Prerequisites

A Flutter project using Flutter 3.22 or later and Dart 3 or later
Nosmai Effects installed for Flutter
A physical arm64 iOS device or arm64-v8a Android device
A Nosmai licence key for the selected native app
Camera usage descriptions and native manifest permissions

1. Add the packages

flutter pub add nosmai_effects_sdk:^1.0.2
flutter pub add permission_handler

The Android host must also contain the verified native 3.0.4 AAR at android/app/libs/nosmai-release.aar. The iOS plugin resolves NosmaiCameraSDK ~> 3.0.4 through CocoaPods.

2. Add camera permission configuration

Android manifest:

<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.INTERNET" />

iOS Info.plist:

<key>NSCameraUsageDescription</key>
<string>This app uses the camera for real-time filters and effects.</string>

3. Initialize Nosmai once

Request camera permission, select the platform key, and initialize before opening the camera screen:

final permission = await Permission.camera.request();
if (!permission.isGranted) {
  throw StateError('Camera permission was denied');
}

final licenseKey = Platform.isAndroid
    ? const String.fromEnvironment('NOSMAI_ANDROID_LICENSE_KEY')
    : const String.fromEnvironment('NOSMAI_IOS_LICENSE_KEY');

final initialized = await NosmaiFlutter.initialize(licenseKey);
if (!initialized) {
  throw StateError('Nosmai initialization failed');
}

Run this from the application startup flow, not from a widget build method.

4. Add the camera preview

Use one preview widget on the camera screen:

NosmaiCameraPreview(
  onInitialized: () async {
    await NosmaiFlutter.instance.applySkinSmoothing(0.4);
  },
  onError: (error) {
    debugPrint('Nosmai preview error: $error');
  },
)

NosmaiCameraPreview owns the native preview lifecycle and forwards taps to an active interactive game by default. Do not mount two camera previews at once.

5. Run on a physical device

Android:

flutter run \
  --dart-define=NOSMAI_ANDROID_LICENSE_KEY=NOSMAI-YOUR-ANDROID-KEY

iOS:

flutter run \
  --dart-define=NOSMAI_IOS_LICENSE_KEY=NOSMAI-YOUR-IOS-KEY

Select a physical device before running either command.

Package example app

For a complete runnable implementation, open the Flutter package example app. It demonstrates the packaged camera screen and the broader SDK controls. Add the verified native Android AAR and your own app-bound licence keys before running it on a physical device.

Verify it worked

You should see the live camera preview, the status Camera ready with skin smoothing, and a visible smoothing change at level 0.4. The preview targets 30 FPS under supported device and effect conditions.

Move the app to the background and return once. The preview should resume without creating a second camera session.

Common errors

Error	Cause	Fix
`Camera permission is required to use this feature. Please grant permission in your device settings.`	Camera access was denied	Enable camera access in system settings, then reopen the screen
`SDK not initialized. Please initialize the SDK first.`	Preview or effect code ran before successful initialization	Await `NosmaiFlutter.initialize` and mount the preview only when it returns `true`
`Invalid license key. Please check your license.`	Key, platform, or app identity was rejected	Check the full key and the registered package name or bundle identifier
`Could not find :nosmai-release:`	Android native AAR is missing	Put the verified file at `android/app/libs/nosmai-release.aar` and link it in the app module
Preview is black after navigation	Another camera controller still owns the device or the preview was duplicated	Dispose the previous camera screen and keep one active `NosmaiCameraPreview`

Flutter quickstart