Prerequisites
- A Flutter project using Flutter 3.29 or later and Dart 3 or later
- Nosmai Effects installed for Flutter
- A physical arm64 iOS device, or an Android device that supports
arm64-v8aorarmeabi-v7a - 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:^2.0.2 flutter pub add permission_handler
The Flutter 2.0.2 plugin resolves the verified Android 3.0.7 AAR from the official GitHub release and resolves NosmaiCameraSDK 3.0.7 through CocoaPods. Do not add a second manual AAR or framework copy.
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 {
final nosmai = NosmaiFlutter.instance;
final prepared = await nosmai.prepareBeautyFilters();
if (prepared) {
await nosmai.applySkinSmoothing(0.4);
}
},
onError: (error) {
debugPrint('Nosmai preview error: $error');
},
)
NosmaiCameraPreview owns the native preview lifecycle. 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 your own app-bound licence keys before running it on a physical device.
Verify it worked
You should see the live camera preview and a visible smoothing change at level 0.4. Any on-screen status label is part of your application's UI, not created by these snippets. 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 com.nosmai:nosmai-sdk:3.0.7 | Gradle could not reach the official release repository and the AAR was not cached | Restore access to GitHub Releases, then refresh Gradle dependencies |
| 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 |
Next steps
- Apply a beauty filter in Flutter
- Replace the background in Flutter
- Download a Cloud Filter in Flutter
- Stream processed frames with Agora in Flutter