# Flutter quickstart

> Initialize Nosmai Effects, add the camera preview, start processing, and apply a beauty effect in a Flutter app.

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

Product: Nosmai Effects
Group: get-started
Source: https://nosmai.com/docs/effects/quickstart/flutter/

## Prerequisites

- A Flutter project using Flutter 3.22 or later and Dart 3 or later
- [Nosmai Effects installed for Flutter](/docs/effects/installation/flutter/)
- A physical arm64 iOS device or `arm64-v8a` Android device
- A [Nosmai licence key](/docs/effects/license-key/) for the selected native app
- Camera usage descriptions and native manifest permissions

## 1. Add the packages

```sh
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:

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

iOS `Info.plist`:

```xml
<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:

```dart
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:

```dart
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:

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

iOS:

```sh
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](https://github.com/nosmai/nosmai_effects_sdk_flutter/tree/main/example).
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` |

## Next steps

- [Apply a beauty filter in Flutter](/docs/effects/guides/effects/apply-a-beauty-filter/flutter/)
- [Replace the background in Flutter](/docs/effects/guides/background/replace-the-background/flutter/)
- [Download a Cloud Filter in Flutter](/docs/effects/guides/filters/download-a-cloud-filter/flutter/)
- [Stream processed frames with Agora in Flutter](/docs/effects/integrations/agora/flutter/)

## References

- [Flutter installation](/docs/effects/installation/flutter/)
- [Flutter package example app](https://github.com/nosmai/nosmai_effects_sdk_flutter/tree/main/example)
- [Flutter package API](https://pub.dev/documentation/nosmai_effects_sdk/latest/)
- [How the pipeline works](/docs/effects/concepts/how-the-pipeline-works/)
- [Nosmai Effects](https://nosmai.com/effects/)
- [Nosmai Effects pricing](https://nosmai.com/effects/#pricing)