Introduction

What is Nosmai Effects?

Nosmai Effects is a camera SDK for adding real-time visual effects to mobile applications. It processes camera frames on the device and displays the result in a live preview. The same processed output can also be used for photos, video recording, and live streaming.

The SDK handles the difficult parts of a camera effects experience, including:

real-time frame processing
GPU-accelerated rendering
face detection and face tracking
filter and effect management
beauty and makeup placement
background segmentation and replacement
camera lifecycle management
processed output for recording and live streaming

Your application remains responsible for its screens, buttons, navigation, product rules, and user experience. Nosmai provides the camera and effects capabilities that those screens control.

What you can build

Capability	Examples
Camera preview	Front and back camera preview with real-time processing
Color filters	LUT looks, brightness, contrast, hue, saturation, RGB, and white balance
Beauty	Skin smoothing, skin whitening, sharpening, and teeth whitening
Makeup	Lipstick, eyeshadow, blusher, eyelashes, and eyebrows
Face shaping	Face slimming, eye size, nose, chin, jaw, lips, forehead, and brow controls
Eye effects	Eye color adjustment and face-tracked eye effects
AR effects	Face masks, stickers, particles, animated overlays, and 3D content
Backgrounds	Blur, solid color, image, video, and packaged background effects
Capture	Photos and videos with active effects included
Live streaming	Processed camera output for services such as Agora
Cloud filters	Browse, download, cache, and apply filters without shipping every filter inside the app

How the SDK is used

A basic Nosmai integration has four steps:

Create a project and license key in the Nosmai Console.
Add the Nosmai SDK package for your platform.
Initialize the SDK and show the camera preview.
Apply a built-in feature or a .nosmai filter.

The SDK automatically handles face detection when an active feature needs it. An application does not need to start a separate face detector before applying lipstick, face shaping, or a face-tracked effect.

Two types of visual features

Nosmai provides built-in features and external .nosmai packages.

Built-in features

Built-in features are part of the SDK and are controlled through direct methods. They are suitable for settings that an application wants to adjust continuously with sliders, buttons, or saved presets.

Examples include:

skin smoothing
skin whitening
lipstick
eyeshadow
blusher
eyelashes
eyebrows
face shaping
eye color
brightness and contrast

External `.nosmai` packages

A .nosmai package is a protected filter file that contains the resources and instructions for one visual experience. The application passes the package path to applyEffect, and the SDK reads the package type and applies it correctly.

The supported package types are:

Type	Intended use
`filter`	Color grading, LUT effects, and full-frame visual filters
`effect`	AR effects, face masks, stickers, particles, and 3D content
`beauty_effect`	Packaged makeup and face-mesh beauty effects
`background`	Packaged background replacement effects

Applications do not need separate apply methods for these four package types. Use applyEffect for all of them.

Local and cloud filters

Filters can reach the application in two ways.

Local filters

Local filters are included in the application bundle. They are available immediately and do not require a download before use.

Use local filters when:

a filter is required for the first camera session
the application must work without a network connection
the filter library is small
a specific branded effect must always be available

Cloud filters

Cloud filters are listed through the Nosmai cloud catalog and downloaded when required. Once downloaded, a cloud filter is stored locally and uses the same applyEffect method as a bundled filter.

Use cloud filters when:

the filter library is large
new filters must be published without releasing a new application version
filters are seasonal or temporary
reducing the initial application download size is important

Cloud catalog requests and downloads need a network connection. Applying an already downloaded filter does not upload camera frames.

On-device processing

Camera frame processing happens on the user's device. The SDK uses device hardware acceleration where available to keep the preview responsive.

This provides three important benefits:

Privacy: camera frames do not need to be uploaded for filters, beauty, face tracking, or background processing.
Low latency: the effect is rendered directly on the device, without waiting for a response from a remote image-processing service.
Predictable operation: active effects can continue to work when the network is unavailable, subject to license validation and any assets that still need to be downloaded.

[!NOTE] The license service and cloud filter catalog use the network. This is separate from camera frame processing. Nosmai does not need to upload every camera frame to apply an effect.

Supported platforms

Platform	Current package	Minimum requirement
iOS	`NosmaiCameraSDK` 3.0.0	iOS 15.0+, physical arm64 device
Android	Nosmai Android AAR 3.0.1	Android API 21+, arm64-v8a device
Flutter	`nosmai_camera_sdk` 3.0.6	Flutter 3.22+, iOS 15.0+ or Android API 21+

The current release is intended for physical mobile devices. Camera processing and device hardware acceleration should be tested on real iOS and Android devices before release.

The iOS release is a dynamic nosmai.framework, distributed through the NosmaiCameraSDK CocoaPod and as a verified ZIP from GitHub. The Flutter package resolves this iOS pod automatically. On Android, Flutter applications must download the proprietary AAR separately and add it to the application module. The AAR is intentionally not included in the pub.dev archive.

React Native and Web are not part of the current SDK documentation set. They should only be documented when an officially supported package is available.

Official SDK repositories

Use the official repositories for package releases, example applications, change history, and platform-specific issue reports:

Platform	Repository
Android	nosmai/camera-sdk-android
iOS	nosmai/camera-sdk-ios
Flutter	nosmai/nosmai_camera_sdk_flutter

Always use the documentation that matches the installed SDK version. A repository default branch or older README may describe a previous release.

Performance expectations

Actual frame rate depends on:

device GPU and processor
camera resolution
target frame rate
number and complexity of active features
face detection requirements
background segmentation
recording or live streaming at the same time
device temperature and power-saving state

Nosmai is designed for real-time use, but applications should still test low-end and high-end target devices. A stable 30 FPS experience is often a better default than requesting 60 FPS on hardware that cannot sustain it.

What the SDK does not decide

Nosmai provides camera and effects technology. Your application still decides:

which filters are shown to each user
whether a feature is free or paid
which effect is selected by default
when recording starts and stops
how captured media is stored or uploaded
how live-stream access is authenticated
how camera and microphone permissions are explained
how failures are presented to the user

Before continuing

You will need:

a Nosmai account
a project in the Nosmai Console
a valid license key for the application
the final Android package name or iOS bundle identifier
a physical supported device
camera permission
microphone permission if the application records audio or streams with audio
internet access for initial license verification

Continue with the Quickstart to install the SDK and display your first camera preview.

Use Releases and compatibility when selecting native and Flutter versions for a production application.