Effects Flutter
Effects / Reference / API reference / Flutter
Updated August 22, 2026

Look up the nosmai_effects_sdk 1.0.3 preview widget, lifecycle, effects, Cloud Filters, beauty, media, and output APIs.

Entry points

APIPurpose
NosmaiFlutter.initialize(licenseKey)Initializes the native SDK once and returns whether startup was accepted
NosmaiFlutter.instanceShared operational API after initialization
NosmaiCameraPreviewNative camera preview for processed camera output
NosmaiFilterPreviewManaged filter thumbnail with loading/error placeholders and available preview caching
NosmaiCameraPreviewControllerReinitializes an attached preview when explicit recovery is required
NosmaiCameraLifecycleMixinCoordinates 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

APIUse
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.

APIContract
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, isHairColoringActiveControls 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() returns NosmaiRecordingResult with the finalized path, duration in seconds, size in bytes, and success/error state. See Recording configuration.
  • capturePhoto returns 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.

References

Nosmai

An AR and AI company. Founded on the idea that the next decade of software will be visual, and that the tools for it should be within reach of anyone building.

Newsletter

Product updates and release notes. No spam.

© 2026 nosmai, inc · all rights reserved