# Flutter API reference

> Look up the nosmai_effects_sdk 1.0.2 preview widget, lifecycle, effects, cloud, beauty, media, output, and game APIs.

> For AI agents: the complete documentation index is at https://nosmai.com/llms/effects.txt

Product: Nosmai Effects
Group: reference
Source: https://nosmai.com/docs/effects/reference/api/flutter/

## 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 with optional automatic game-tap forwarding |
| `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.

## Local and Cloud Filters

| API | Use |
| --- | --- |
| `getLocalFilters()` | Returns the installed local catalog |
| `getAllLocalFilters()` | Returns catalogs grouped by local package type |
| `getLocalEffects()` / `getLocalBackgrounds()` / `getLocalBeautyEffects()` / `getLocalGames()` | Returns one typed local subset |
| `getCloudFilters(...)` | Fetches the licensed cloud catalog with type and pagination options |
| `downloadCloudFilter(filterId)` | Downloads or reuses a verified cached package and returns its local path |
| `removeCloudFilter(filterId)` | Removes that cloud package 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.

## Beauty, background, and camera hardware

The shared API exposes beauty, colour, makeup, reshape, 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.

## Games and media

- `isGameReady`, `sendGameTap`, `sendGameInput`, `pauseGame`, `resumeGame`, and
  `restartGame` control an active game.
- `gameEvents`, `licenseStatusStream`, `errorStream`, download progress, and
  recording progress expose asynchronous state.
- `capturePhoto`, `startRecording`, `stopRecording`, and gallery-save helpers
  return typed result models.

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

- [Flutter quickstart](/docs/effects/quickstart/flutter/)
- [Flutter platform guide](/docs/effects/platforms/flutter/)
- [Dart package](https://pub.dev/packages/nosmai_effects_sdk)
- [Flutter example](https://github.com/nosmai/nosmai_effects_sdk_flutter/tree/main/example)