Quickstart

What you will build

This guide covers the minimum setup required to:

1. obtain a Nosmai license key
2. add the SDK to an application
3. request the required permissions
4. initialize Nosmai
5. display a live camera preview
6. apply a simple built-in effect

Choose the section for your platform. The platform guides provide the complete production setup, lifecycle handling, camera controls, and error handling.

Before you start

Create a project

Open the Nosmai Console, sign in, and create a project for the application.

Use the exact application identifier that will be present in the installed app:

Copy the license key issued for the project. Nosmai license keys use the following format:

NOSMAI-<project-key>

Do not use a key issued for a different package name, bundle identifier, or platform.

Use a physical device

Use an arm64 iPhone or an arm64-v8a Android device. A simulator or emulator can help with layout development, but it is not a reliable environment for camera effects, face tracking, recording, or performance testing.

Keep the first launch online

The SDK verifies the license with the Nosmai service. Keep the test device connected to the internet during the first successful launch.

Flutter

Flutter is the shortest path to a complete cross-platform preview because NosmaiCameraPreview owns the native camera view on both platforms.

1. Add the package

The Flutter plugin, example application, and release history are available in the Nosmai Flutter SDK repository.

Add the current package to pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  nosmai_camera_sdk: ^3.0.6

Run:

flutter pub get

2. Configure iOS

The Flutter plugin resolves the native NosmaiCameraSDK dependency through CocoaPods. Do not copy an iOS framework into the Flutter application manually.

Set the minimum iOS version in the application Podfile:

platform :ios, '15.0'

Install the native pod and open the generated workspace when working in Xcode:

cd ios
pod install --repo-update

Add the required permission descriptions:

<key>NSCameraUsageDescription</key>
<string>This app uses the camera for real-time filters and effects.</string>
<key>NSMicrophoneUsageDescription</key>
<string>This app uses the microphone when recording video or streaming.</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>This app saves captured photos and videos to your library.</string>

Camera permission is required for preview. Microphone permission is only required when audio is recorded or streamed. Photo library permission is only required when the app saves media to the user's library.

3. Configure Android

The proprietary Android SDK is distributed separately and is not included in the pub.dev package.

1. Download nosmai-sdk-3.0.1.aar and SHA256SUMS from the Android SDK v3.0.1 release.
2. Run shasum -a 256 -c SHA256SUMS in the download directory.
3. Rename the verified AAR to nosmai-release.aar.
4. Place it at android/app/libs/nosmai-release.aar.

Add the local AAR repository to the Flutter application's Android project:

allprojects {
    repositories {
        google()
        mavenCentral()
        flatDir { dirs "${rootProject.projectDir}/app/libs" }
    }
}

Add the AAR to the application module:

dependencies {
    implementation files('libs/nosmai-release.aar')
}

android {
    defaultConfig {
        minSdk 21

        ndk {
            abiFilters "arm64-v8a"
        }
    }
}

Add the required permissions:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.CAMERA" />
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    <uses-permission android:name="android.permission.INTERNET" />

    <application>
        ...
    </application>
</manifest>

The Flutter Dart package and native Android AAR are versioned separately. Flutter package 3.0.6 is compatible with Android native SDK 3.0.1.

4. Initialize the SDK

Initialize once before opening a camera screen:

import 'package:flutter/material.dart';
import 'package:nosmai_camera_sdk/nosmai_camera_sdk.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  final initialized = await NosmaiFlutter.initialize(
    'NOSMAI-YOUR-LICENSE-KEY',
  );

  if (!initialized) {
    throw StateError('Nosmai SDK initialization failed');
  }

  runApp(const MyApp());
}

Do not initialize Nosmai every time a widget rebuilds. Initialize it once at application startup or through a single application-level service.

5. Display the camera

import 'package:flutter/material.dart';
import 'package:nosmai_camera_sdk/nosmai_camera_sdk.dart';

class CameraScreen extends StatelessWidget {
  const CameraScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Stack(
        fit: StackFit.expand,
        children: [
          NosmaiCameraPreview(
            onInitialized: () {
              debugPrint('Nosmai camera is ready');
            },
            onError: (error) {
              debugPrint('Nosmai camera error: $error');
            },
          ),
        ],
      ),
    );
  }
}

NosmaiCameraPreview creates the platform camera view and starts processing when the native preview is ready.

6. Apply a built-in effect

Apply subtle skin smoothing after the camera is ready:

final nosmai = NosmaiFlutter.instance;
await nosmai.applySkinSmoothing(0.4);

Remove built-in beauty effects when required:

await nosmai.removeAllBeautyEffects();

[!NOTE] Built-in effect ranges are documented per method. Do not assume every beauty control uses the same numeric range.

iOS

The iOS SDK provides NosmaiCore as the high-level entry point. It exposes camera and effects objects after initialization.

1. Add the framework

Get the framework, examples, and release information from the Nosmai iOS SDK repository.

The recommended installation uses CocoaPods:

platform :ios, '15.0'

target 'CameraApp' do
  use_frameworks!
  pod 'NosmaiCameraSDK', '3.0.0'
end

Run pod install --repo-update, then open the generated .xcworkspace.

For manual installation, download nosmai.framework.zip and SHA256SUMS from the iOS SDK v3.0.0 release. Verify the archive with shasum -a 256 -c SHA256SUMS, unzip it, add nosmai.framework to the Xcode project, and set it to Embed & Sign for the application target.

Confirm:

• deployment target is iOS 15.0 or later
• the app target includes the framework
• the framework is embedded in the final application
• the target uses a physical arm64 device for camera testing

2. Add permission descriptions

<key>NSCameraUsageDescription</key>
<string>This app uses the camera for real-time filters and effects.</string>
<key>NSMicrophoneUsageDescription</key>
<string>This app uses the microphone when recording video or streaming.</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>This app saves captured photos and videos to your library.</string>

3. Initialize and start the preview

The following Objective-C example creates a preview view, initializes the SDK, attaches the camera, and starts capture:

#import <nosmai/Nosmai.h>

@interface CameraViewController ()
@property(nonatomic, strong) UIView *cameraPreview;
@end

@implementation CameraViewController

- (void)viewDidLoad {
    [super viewDidLoad];

    self.cameraPreview = [[UIView alloc] initWithFrame:self.view.bounds];
    self.cameraPreview.autoresizingMask =
        UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
    [self.view addSubview:self.cameraPreview];

    [[NosmaiCore shared]
        initializeWithAPIKey:@"NOSMAI-YOUR-LICENSE-KEY"
                  completion:^(BOOL success, NSError *error) {
        if (!success) {
            NSLog(@"Nosmai initialization failed: %@", error.localizedDescription);
            return;
        }

        NosmaiCameraConfig *config = [[NosmaiCameraConfig alloc] init];
        config.position = NosmaiCameraPositionFront;
        config.sessionPreset = AVCaptureSessionPresetHigh;
        config.frameRate = 30;

        [[[NosmaiCore shared] camera] updateConfiguration:config];
        [[[NosmaiCore shared] camera] attachToView:self.cameraPreview];

        BOOL started = [[[NosmaiCore shared] camera] startCapture];
        if (!started) {
            NSLog(@"Nosmai camera could not start");
        }
    }];
}

@end

The initialization completion is delivered on the main thread. Attach and start the camera only after initialization succeeds.

4. Apply a built-in effect

NosmaiEffectsEngine *effects = [[NosmaiCore shared] effects];
[effects applySkinSmoothing:0.4f];

Android

The Android SDK provides NosmaiSDK for initialization and processing, NosmaiPreviewView for display, and NosmaiEffects for external .nosmai packages.

The native Android SDK accepts camera frames from the application. The complete sample includes a Camera2 helper that demonstrates the recommended camera connection. Use that helper or connect an existing Camera2 source to NosmaiPreviewView.

1. Add the AAR

Get the AAR, sample application, and release information from the Nosmai Android SDK repository.

Place the supplied Android SDK AAR in:

app/libs/nosmai-sdk-3.0.1.aar

Download SHA256SUMS with the AAR and verify it before integration:

shasum -a 256 -c SHA256SUMS

Reference it from the application module:

dependencies {
    implementation(files("libs/nosmai-sdk-3.0.1.aar"))
}

The current Android SDK requires:

• minimum API 21
• Java 11 compatibility
• an arm64-v8a device

2. Add permissions

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.CAMERA" />
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    <uses-permission android:name="android.permission.INTERNET" />

    <application>
        ...
    </application>
</manifest>

Request camera permission at runtime before starting the camera. Request microphone permission before recording or streaming audio.

3. Initialize once

Initialize from the application class or another application-level owner:

import android.app.Application;
import com.nosmai.effect.api.NosmaiSDK;

public final class NosmaiApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        NosmaiSDK.initialize(this, "NOSMAI-YOUR-LICENSE-KEY");
    }
}

Register the application class:

<application
    android:name=".NosmaiApplication"
    ...>
</application>

4. Create the processing preview

import android.os.Bundle;
import android.widget.FrameLayout;
import androidx.appcompat.app.AppCompatActivity;
import com.nosmai.effect.api.NosmaiPreviewView;
import com.nosmai.effect.api.NosmaiSDK;

public final class CameraActivity extends AppCompatActivity {
    private NosmaiPreviewView previewView;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_camera);

        FrameLayout container = findViewById(R.id.preview_container);
        previewView = new NosmaiPreviewView(this);
        container.addView(
            previewView,
            new FrameLayout.LayoutParams(
                FrameLayout.LayoutParams.MATCH_PARENT,
                FrameLayout.LayoutParams.MATCH_PARENT
            )
        );

        NosmaiSDK.startProcessing(previewView);

        // Connect Camera2 after camera permission is granted.
        // The Android platform guide contains the complete camera input example.
    }

    @Override
    protected void onResume() {
        super.onResume();
        if (previewView != null) {
            previewView.onResume();
        }
    }

    @Override
    protected void onPause() {
        if (previewView != null) {
            previewView.onPause();
        }
        super.onPause();
    }

    @Override
    protected void onDestroy() {
        // Stop the Camera2 source before stopping Nosmai processing.
        NosmaiSDK.stopProcessing();
        super.onDestroy();
    }
}

Starting processing prepares the preview and effects. The application must then connect its Camera2 source. Do not start more than one camera source for the same preview.

5. Apply a built-in effect

import com.nosmai.effect.api.NosmaiBeauty;

NosmaiBeauty.applySkinSmoothing(0.4f);

Apply a .nosmai package

After the camera preview works, all platforms use one apply method for external packages.

Flutter

final applied = await NosmaiFlutter.instance.applyEffect(filter.path);

iOS

[[[NosmaiCore shared] effects]
    applyEffect:filterPath
      completion:^(BOOL success, NSError *error) {
    if (!success) {
        NSLog(@"Effect failed: %@", error.localizedDescription);
    }
}];

Android

NosmaiEffects.applyEffect(filterPath, new NosmaiEffects.EffectCallback() {
    @Override
    public void onSuccess() {
        // Update the selected state in the application UI.
    }

    @Override
    public void onError(String message) {
        // Show or record the failure.
    }
});

The value passed to applyEffect must identify a valid local .nosmai package. Cloud packages must be downloaded before they can be applied.

Verify the integration

Before adding a large filter library, verify this basic flow:

1. the application starts without an initialization error
2. the operating system asks for camera permission
3. the front camera preview appears
4. the preview orientation is correct
5. the front preview uses the intended mirror setting
6. the built-in test effect changes the preview
7. sending the app to the background releases or pauses the camera
8. returning to the app restores the preview
9. leaving the camera screen turns off the operating system camera indicator

Common first-run problems

Next steps

• Authentication explains license keys, project identity, verification, caching, and production handling.
• Core concepts explains camera input, processing, effect types, built-in beauty, local filters, cloud filters, and output.

The dedicated Android, iOS, and Flutter guides will add complete platform-specific integration, lifecycle, capture, recording, and troubleshooting instructions.