Entry points
| API | Purpose |
|---|---|
NosmaiFlutter.initialize(licenseKey) | Initializes the native SDK once and returns whether startup was accepted |
NosmaiFlutter.instance | Shared operational API after initialization |
NosmaiCameraPreview | Native camera preview for processed camera output |
NosmaiFilterPreview | Managed filter thumbnail with loading/error placeholders and available preview caching |
NosmaiCameraPreviewController | Reinitializes an attached preview when explicit recovery is required |
NosmaiCameraLifecycleMixin | Coordinates cleanup with Flutter application lifecycle |
Camera lifecycle
Use configureCamera, startProcessing, stopProcessing, switchCamera, pauseCamera, resumeCamera, detachCameraView, reinitializePreview, and cleanup. Await asynchronous operations and keep only one mounted preview. NosmaiCameraPreview starts the native view through the supported widget path; do not also create a Flutter camera controller for the same device.
Packages and state
applyEffect(path) is the unified package operation. applyFilter(path) is a filter-specific compatibility surface. Inspect getActiveEffects, getActiveFilterInfo, and getActiveEffectInfo; clear with clearFilter, clearAREffect, removeEffect, removeAllFilters, or clearAll according to the intended scope.
Use getEffectParameters, getEffectParameterValue, setEffectParameter, and setEffectParameterString only with names declared by the active authored package.
Cloud Filters
| API | Use |
|---|---|
getCloudFilters(...) | Fetches the licensed cloud catalog with type and pagination options |
downloadCloudFilter(filterId) | Downloads the selected Cloud Filter and prepares it for use |
removeCloudFilter(filterId) | Removes the downloaded Cloud Filter from SDK-managed storage |
Keep the cloud identifier and use the returned local path for application. The operating system may reclaim cache storage, so handle a missing path by downloading again.
Filter thumbnails
Use NosmaiFilterPreview(filter: filter) to display a local or Cloud Filter catalog item's thumbnail. Configure width, height, fit, alignment, decodeSize, placeholder, and errorBuilder for the picker layout. decodeSize defaults to 256 and is clamped to 64...512 pixels.
The widget loads preview images and can reuse cached or local package previews. It does not download or apply the effect package. Both placeholder callbacks are WidgetBuilder functions receiving only a BuildContext.
See Display catalog thumbnails in the Flutter Cloud Filter guide for the grid example and offline behavior.
Beauty, background, and camera hardware
Call prepareBeautyFilters() from NosmaiCameraPreview.onInitialized before showing or applying beauty controls. It prepares shared native beauty resources without enabling an effect. isBeautyPrepared() reports readiness for the current preview session.
| API | Contract |
|---|---|
setBeautyVisible(visible) / isBeautyVisible() | Hides or restores built-in beauty without clearing configured values. AR packages and backgrounds stay visible. |
applyContourAndHighlighter(contour:, highlighter:) | Independent contour and highlighter strengths from 0.0...2.0. |
applyContourHighlighter(level) | Combined contour and highlighter strength from 0.0...1.0. |
applyFreckles(quantity) | Freckle quantity from 0.0...1.0; pass 0.0 to remove it. |
applyFoundation(shade:, color:, coverage:) / removeFoundation() | Applies a preset or custom colour with coverage from 0.0...1.0. |
applyDarkCircleCorrector(level) | Under-eye correction from 0.0...1.0; pass 0.0 to remove it. |
setHairColor, setHairColorIntensity, removeHairColoring, isHairColoringActive | Controls the optional native hair-colour layer. |
Standard strengths use 0.0...1.0; signed setReshape values use -1.0...1.0; contour, highlighter, lipstick, and blusher support 0.0...2.0. The shared API also exposes colour, makeup, eye-colour, and manual background controls. Check isBeautyFilterEnabled, isCloudFilterEnabled, and isAdvancedFiltersEnabled before presenting gated controls. Flash and torch use hasFlash, hasTorch, mode getters, and mode setters.
Makeup styles and palettes
Use applyLipstick, applyEyeshadow, applyBlusher, applyEyelash, and applyEyebrow with their corresponding Nosmai...Style enums. Coloured layers accept an optional Flutter Color; omit it for the style's native default. Each apply method returns Future<bool>.
Update strength with the matching set...Intensity method and remove the layer with remove.... The state methods are hasLipstick, hasEyeshadow, hasBlusher, hasEyelash, and hasEyebrow. Use removeAllMakeup for all makeup layers. Lipstick and blush accept 0...2; the other layers accept 0...1.
getLipstickColors() returns reference shades with name and normalized r, g, and b fields. See Makeup styles and palettes for the style table, palette conversion, and custom-colour examples.
Face reshaping
setReshape(type: NosmaiReshapeType, value: double) returns Future<void> and clamps strength to -1...1; 0 is neutral. The supported enum values are lip, faceSlim, eye, nose, chin, brow, browThickness, jaw, mouthWidth, and forehead. Set one type to 0 to reset it, or use removeAllMorphing() for the targeted shape reset.
setFaceSlimLevel, setEyeSizeLevel, and setNoseSlimLevel are 0...1 helpers; the other seven signed shape helpers use -1...1. Native names applyFaceSlimming, applyEyeEnlargement, and applyNoseSize are not Flutter methods. See Face reshaping for the exact helper names, directions, UI percentage conversion, and examples.
Runtime face stickers
Use setFaceSticker(imageData, ...) with PNG, JPEG, or animated GIF bytes, or setFaceStickerAsset(assetPath, ...) for an asset declared in pubspec.yaml. Choose a NosmaiFaceStickerAnchor; adjust placement with setFaceStickerPlacement, read state with isFaceStickerActive, and remove the sticker with clearFaceSticker. A face sticker shares the AR overlay slot, so applying another AR effect replaces it.
Eye and hair colouring
setEyeColor(Color, intensity:) and setHairColor(Color, intensity:) return Future<bool>. Intensities use 0...1; update with setEyeColorIntensity or setHairColorIntensity, and remove with removeEyeColoring or removeHairColoring. isHairColoringActive() reports the enabled hair layer; there is no matching dedicated eye-active query in this Dart API. See Eye and hair colouring.
Active effects and events
getActiveEffects() returns NosmaiActiveEffects; subscribe to onActiveEffectsChanged for later snapshots. Package paths can be null even while a built-in sticker or manual beauty is active. Use hasFaceSticker, isArSlotOccupied, hasHairColoring, and effective background fields as appropriate. Snapshots are not licence or face-detection results.
The other public streams are onLicenseStatusChanged, onError, onDownloadProgress, onRecordingProgress, and onGameEvent. Recording progress is elapsed seconds, not completion. Cancel each StreamSubscription on route teardown; do not dispose the shared SDK merely to remove listeners. See Active effects and events.
Media
startRecording()accepts no encoder configuration and returns a Boolean;stopRecording()returnsNosmaiRecordingResultwith the finalized path, duration in seconds, size in bytes, and success/error state. See Recording configuration.capturePhotoreturns a photo result; gallery saves are separate operations returning result maps. Check their results before reporting a persistent save.- Arbitrary OES/I420/pixel-buffer input is not a public Dart API. Use a native provider bridge or adapter; see Off-screen rendering.
Call dispose() on the shared Dart wrapper only when the application no longer needs the SDK process. Ordinary screen navigation should use the documented preview lifecycle instead of repeatedly destroying global state.