DEV Community: Team Banuba

Flutter Video Editor in 6 Steps: Banuba SDK Setup, Entry Screens and Export

Team Banuba — Tue, 03 Nov 2026 13:35:51 +0000

A Flutter video editor built on Banuba's ve_sdk_flutter plugin is one Dart call that opens a native recording and editing screen and returns the exported file paths to your code. The setup is six steps: pin the package, configure iOS, configure Android, launch the editor, pick an entry screen, and set the export.

Banuba Video Editor SDK is a production-ready mobile video editing engine for iOS, Android, Flutter and React Native. We build it, so this guide uses our plugin, and the comparison near the end also covers the open-source Flutter packages we do not sell.

What do you need before you add a video editor to Flutter?

You need four things:

A license token. Banuba issues it with a 14-day free trial of the Video Editor SDK, and the plugin's pub.dev page says no credit card information is needed. Without a token, every call fails with an error code you will meet in Step 4.
A Flutter toolchain at or above the plugin's floor. The pub.dev page lists Dart 3.3.0, Flutter 3.19.2, Android 8.0+ and iOS 15.0+.
Native tools for both platforms. Our requirements pages list Kotlin 2.1+ or Java 17, the Camera 2 API and OpenGL ES 3.0 on Android, and Swift 5.9, Xcode 26.0 and iOS 15.0 on Apple devices.
Physical devices. Our Android requirements mark x86-64 as limited support and x86 as not supported, so an emulator image is a weak place to judge the editor.

Step 1: How do you install the Flutter video editor plugin?

Add the package with the version pinned:

dependencies:
  ve_sdk_flutter: 0.48.1

Then run flutter pub get. The ve_sdk_flutter package depends only on flutter and plugin_platform_interface, so it does not pull a media library into your Dart dependency tree. The media engine arrives through CocoaPods and Gradle in the next two steps.

Pin the exact version on purpose, and read the changelog rather than the version number. Some releases track native SDK versions: 0.43.0 supports Video Editor 1.52.0 and 0.44.0 supports 1.53.0, so a minor bump can change native behavior under the same Dart code. Others touch nothing functional at all, which is what 0.48.0 and 0.48.1 did, updating the package description, repository link, topics and homepage.

Step 2: What does iOS need?

Two edits. First, add Banuba's spec repositories at the top of ios/Podfile, as the plugin integration guide shows:

platform :ios, '15.0'

source 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/Banuba/specs.git'
source 'https://github.com/sdk-banuba/banuba-sdk-podspecs.git'

Second, add the four usage descriptions to ios/Runner/Info.plist:

<key>NSAppleMusicUsageDescription</key>
<string>This app requires access to the media library</string>
<key>NSCameraUsageDescription</key>
<string>This app requires access to the camera.</string>
<key>NSMicrophoneUsageDescription</key>
<string>This app requires access to the microphone.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>This app requires access to the photo library.</string>

Run pod install inside ios, then select your Development Team under Signing & Capabilities. Replace the sample strings with wording that tells your users why you need each permission.

Step 3: What does Android need, and how do you keep the APK small?

On Android, the size decision is the main one. Our documentation gives these additions to your app's download size, and we did not re-measure them for this article:

What you ship	Android	iOS
Core editor	25 MB	14 MB
Full bundle	45 MB	45 MB
Editor with face AR features	45 to 90 MB	45 to 140 MB

Two switches move you between those rows.

Turn off face AR if you do not need masks. Add ENABLE_FACE_AR=false to android/gradle.properties, and this line to the Podfile:

ENV['ENABLE_FACE_AR'] = 'false'

Filter processor architectures. The integration guide notes that each architecture adds megabytes. Ship ARM only:

ndk {
    abiFilters 'armeabi-v7a', 'arm64-v8a'
}

Upload an Android App Bundle as well. Our Android docs state that with a bundle, the per-device library comes out 24 to 26 MB smaller than the documented figure, because Google Play serves each device only its own architecture.

Step 4: How do you open the video editor from Dart?

This is a complete lib/main.dart. One button opens the camera screen, and the result or the error comes back to the same widget:

import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:ve_sdk_flutter/errors.dart';
import 'package:ve_sdk_flutter/export_data.dart';
import 'package:ve_sdk_flutter/export_result.dart';
import 'package:ve_sdk_flutter/features_config.dart';
import 'package:ve_sdk_flutter/ve_sdk_flutter.dart';

// Passed at build time: flutter run --dart-define=BANUBA_TOKEN=your_token
const _licenseToken = String.fromEnvironment('BANUBA_TOKEN');

void main() => runApp(const MaterialApp(home: EditorLauncher()));

class EditorLauncher extends StatefulWidget {
  const EditorLauncher({super.key});

  @override
  State<EditorLauncher> createState() => _EditorLauncherState();
}

class _EditorLauncherState extends State<EditorLauncher> {
  final _veSdk = VeSdkFlutter();
  String _status = 'No clip yet';

  // Step 6: a 720p file in H.264 plus a file at device-chosen quality
  static const _exportData = ExportData(exportedVideos: [
    ExportedVideo(
      fileName: 'clip_720p',
      videoResolution: VideoResolution.hd720p,
      useHevcIfPossible: false,
    ),
    ExportedVideo(
      fileName: 'clip_auto',
      videoResolution: VideoResolution.auto,
    ),
  ]);

  Future<void> _openEditor() async {
    final config = FeaturesConfigBuilder().build();
    try {
      final ExportResult? result = await _veSdk.openCameraScreen(
        _licenseToken,
        config,
        exportData: _exportData,
      );
      if (!mounted) return;
      setState(() {
        _status = result == null
            ? 'Editor closed before export'
            : 'Exported: ${result.videoSources.join(', ')}';
      });
    } on PlatformException catch (e) {
      if (!mounted) return;
      setState(() => _status = _describe(e));
    }
  }

  String _describe(PlatformException e) {
    switch (e.code) {
      case errCodeSdkNotInitialized:
        return 'License token is empty or invalid';
      case errCodeSdkLicenseRevoked:
        return 'License revoked or expired';
      case errCodeMissingHost:
        return 'No Activity or ViewController to show the editor';
      case errCodeInvalidParams:
        return 'The editor received invalid input';
      case errCodeMissingExportResult:
        return 'The editor could not export the video';
      default:
        return 'Error ${e.code}: ${e.message}';
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Column(
          mainAxisSize: MainAxisSize.min,
          children: [
            Text(_status),
            const SizedBox(height: 16),
            ElevatedButton(
              onPressed: _openEditor,
              child: const Text('Open video editor'),
            ),
          ],
        ),
      ),
    );
  }
}

openCameraScreen returns Future<ExportResult?>. A null result means the user closed the editor without exporting, so a user who backs out halfway still leaves your screen with a defined status.

The plugin defines five error codes in errors.dart. The three below are the ones that stop a first run, and a fourth failure mode after them throws nothing at all.

ERR_SDK_NOT_INITIALIZED

The plugin's comment on this code reads: "Error occurs when the sdk cannot be initialized with provided license token: invalid, empty". With the snippet above, it usually means the app was started without --dart-define=BANUBA_TOKEN=..., so the constant is an empty string.

ERR_SDK_LICENSE_REVOKED

The license has been revoked, and the plugin's own comment says to contact Banuba. In the integration sample, the same code also covers an expired license, which is what a finished 14-day trial looks like from Dart.

ERR_MISSING_HOST

The editor is a native screen, so it needs an Activity on Android or a ViewController on iOS to present from. This code means none was available, which points at calling the plugin before the first frame has rendered, for example from main() or initState().

"New UI is not available from Trimmer screen"

This one is not an error code, and that is what makes it expensive to debug. FeaturesConfigBuilder sets enableEditorV2 to true by default, and with the new UI enabled the plugin refuses the trimmer entry point: it writes that line to the debug console and returns null without throwing.

From the snippet above, the only thing you see is "Editor closed before export", as though the user had backed out. If you want openTrimmerScreen, turn the new UI off for that call:

final config = FeaturesConfigBuilder()
    .enableEditorV2(false)
    .build();

Step 5: Which entry screen should the editor open with?

VeSdkFlutter in 0.48.1 exposes eight entry points. Each takes the token and a FeaturesConfig, and each returns the same ExportResult:

Method	Extra input	Starts the user on
`openCameraScreen`	none	Recording
`openPipScreen`	one video path	Picture-in-picture over an existing clip
`openTrimmerScreen`	list of video paths	Trimming the clips you pass
`openEditorScreen`	list of video paths	The editing timeline
`openAiClippingScreen`	none	AI clipping, starting from the gallery
`openTemplatesScreen`	none	Video templates
`openDraftsScreen`	none	Saved drafts
`openGalleryScreen`	none	The media gallery

openPipScreen takes one video path on top of the token and config, and openTrimmerScreen and openEditorScreen take a list of paths, which you get from a picker such as image_picker. The other five need nothing else.

Two things in the 0.48.1 source are worth knowing before you build on this table. openTrimmerScreen is the one that returns null under the default config, as described above. And openEditorScreen accepts an optional trackData argument that goes nowhere: the plugin serializes track data and sends it to the native side from its internal open method, but the editor entry point does not forward the argument to it. Passing a track there is a silent no-op today, so preload audio another way until a release says otherwise.

Each screen is trimmed through FeaturesConfigBuilder. Setting supportsBeauty and supportsMasks to false in CameraConfig removes the beauty and mask controls from the camera, and supportsVoiceOver: false in EditorConfig removes voice-over, which our docs mark as Android only.

Step 6: How do you control the exported file?

Without ExportData, the plugin exports one video at auto quality, which our docs describe as chosen from the device's hardware. With it, you name each file and pick a VideoResolution. The enum has nine values: seven resolutions from vga360p through vga480p, qhd540p, hd720p, fhd1080p and qhd1440p to uhd2160p, plus auto and original.

The file type differs by platform. Our docs state that the video is exported as .mp4 on Android and .mov on iOS, so do not hard-code an extension when you upload.

Three settings change what lands on disk:

useHevcIfPossible: false switches the file to H.264 (AVC), for upload or playback pipelines that expect AVC.
Watermark(imagePath: 'assets/watermark.png', alignment: WatermarkAlignment.bottomRight) adds your logo. Our docs state that no watermark is added by default.
Each ExportedVideo entry produces its own file, so two entries mean two encodes on the user's phone.

The result carries more than video paths. ExportResult also returns previewFilePath, metaFilePath and audioMeta, and the plugin's example describes the meta file as short data used in the exported video. To play the exported file inside your own screen, the official video_player plugin is enough.

Encoding time depends on the phone, so measure the export on the slowest Android model you support. Our video editor SDK performance benchmark shows how results spread across devices.

Which Flutter video editor route fits your app?

Video editing in Flutter has four realistic routes, and each is the right call for some team.

Question	Banuba plugin (ve_sdk_flutter 0.48.1)	Banuba integration sample	video_editor 3.0.0	ffmpeg_kit_flutter
What it is	Ready editor UI behind one Dart call	Full app source using a platform channel	Dart widgets for trim, crop, rotate and cover	FFmpeg and FFprobe command runner
Editing UI	Included, native screens	Included, editable native code	You assemble it from widgets	None
Export	Included, mp4 or mov	Included	Builds FFmpeg commands, does not export	Any FFmpeg command you write
Access	Trial token on request	Trial token on request	Open	Open
License	Commercial	Commercial	MIT	LGPL 3.0 by default, some packages GPL v3.0
Maintenance state	Released against current native SDK versions	Tracks the plugin	Latest release is 3.0.0, no release since	Upstream FFmpegKit retired; successor and community forks exist

Four ways to read that table:

Fastest to a complete editor: the Banuba plugin. Recording, timeline, effects and export arrive behind the call in Step 4.
Most control over native behavior: the Banuba integration sample. The Flutter integration sample on GitHub ships the app source, so your team can change the native layer rather than wait for a plugin release.
Cost and UI ownership: video_editor. It is free under MIT and every widget is yours to style. You still need an export path, because its README says the library does not handle exportation.
Raw codec control: the FFmpeg route. No other option lets you write arbitrary FFmpeg commands, and the licensing is the thing to settle first, since the default build is LGPL 3.0 and some variants are GPL v3.0.

The FFmpeg route needs one more sentence, because the package most guides still point at is not where the work happens now. The upstream project posted a retirement notice in July 2026 stating that FFmpegKit has been officially retired, and names FFmpegKitNext as the actively maintained continuation, distributed as source only, alongside community-maintained forks published for Android, Flutter and React Native through the usual package managers. A team going this way is picking a fork and a build process, not just adding a dependency.

One more limit of our own: the Banuba editor does not run on the web, so a Flutter web target needs a different route for that platform.

Why use Banuba for a Flutter video editor?

Banuba Video Editor SDK covers recording, a multi-track timeline, effects, AI clipping, AI subtitles and export in one plugin. Our docs state that it works offline and does not send, store or process user information. They also publish agent skills for Claude Code, Codex and Qwen Code, plus an LLM-friendly documentation file for AI-assisted coding.

It does not hand you Dart widgets to restyle line by line. The screens are native, and you shape them through FeaturesConfig, so a team that wants a pixel-level custom UI in Flutter is better served by video_editor plus its own export path.

For the native side of the same editor, see our walkthrough of integrating the iOS video editor SDK in Swift. For other vendors, our comparison of five video editor SDKs for social apps puts Banuba next to the alternatives, and the original Flutter guide on our blog covers the feature list in more depth.

Six steps take a Flutter app from pubspec to an exported clip

Pin ve_sdk_flutter at 0.48.1, add the Podfile sources and permissions, set the Android size switches, and call one open...Screen method from a mounted widget. Then decide the export: which resolutions, which codec, and whether a watermark goes on.

Check the size table in Step 3 and the four failure modes in Step 4 before the first device run. Three of them throw, and the fourth returns null and looks like a user walking away.

FAQ

Is the Banuba Flutter video editor free?

The Banuba Flutter video editor is free for a 14-day trial with the full feature set, and the plugin's pub.dev page says no credit card information is needed. Production use needs a commercial Banuba license.

Does the Banuba Flutter video editor work offline?

Yes. Banuba's documentation states that the Video Editor SDK works offline and does not send, store or process user information.

Does the Banuba Video Editor SDK support Flutter web?

No. The Banuba Video Editor SDK runs on iOS and Android, and pub.dev lists only those two platforms for ve_sdk_flutter.

How do I fix ERR_SDK_NOT_INITIALIZED in the Banuba Flutter plugin?

The Banuba plugin returns ERR_SDK_NOT_INITIALIZED when the license token is empty or invalid. Check that the token reaches the call, for example that you passed --dart-define=BANUBA_TOKEN=... when you started the app.

Why does openTrimmerScreen return null in the Banuba Flutter plugin?

Because the new editor UI is on by default. FeaturesConfigBuilder sets enableEditorV2 to true, and the plugin blocks the trimmer entry point under it, logging "New UI is not available from Trimmer screen" and returning null rather than throwing. Call .enableEditorV2(false) on the builder if you need that screen.

How much does the Banuba video editor add to a Flutter app's size?

Banuba documents 25 MB on Android and 14 MB on iOS for the core editor, 45 MB for the full bundle, and 45 to 90 MB on Android or 45 to 140 MB on iOS with face AR. Turning face AR off and filtering architectures moves a build toward the core figures.

Face AR SDK Integration on Android and iOS: 6 Steps From Token to First Effect

Team Banuba — Wed, 14 Oct 2026 13:37:46 +0000

Adding face AR to an existing mobile app is a six-step integration that touches two code files per platform, plus your build files. Banuba Face AR SDK is a real-time, on-device face tracking and AR effects SDK. Per Banuba's own technical specification it tracks a single face at 30 FPS on the Android High, iOS Mid and iOS High device tiers and at 25 FPS on Android Low, within a head-angle range of 80 degrees. The full table is in step 6.

The six steps are: get a client token, add the SDK packages, initialize once at app start, connect the camera to a player and an output view, load an effect, and handle the lifecycle. This guide is for a mobile developer who already ships an Android or iOS app and wants a face filter running in the camera view. The code below is taken from the official Banuba sample repositories for Android and iOS, so every call is one you can open and run. We build the SDK, and every figure named below comes from our own documentation; this guide contains no benchmark of our own.

What do you need before you add a face AR SDK to an app?

Four things, and all of them are checkable before you write a line.

A device and OS floor. Banuba Face AR SDK supports Android from 8.0 (API level 26) and iOS from 13.0, and needs OpenGL ES 3.0 or higher on any mobile platform, per the system requirements.
A camera. The iOS sample opens the front camera at the 1280x720 preset.
A language. The SDK exposes Kotlin and Java on Android, Swift and Objective-C on iOS.
A client token, which is step 1. One decision belongs here rather than later. If your app also targets Flutter or React Native, the same SDK ships as Banuba-maintained plugins, and our earlier walkthrough on adding AR features to a React Native app covers that path. This guide stays native.

Step 1: Get a client token and decide where it lives

Banuba Face AR SDK does nothing without a token. There are two kinds, per the token management page: a demo token for the trial, valid for 14 days and activating all SDK features, and a commercial token issued after payment, valid for the prepaid period and activating the features in your license. You request the demo token through the form on the Face AR SDK page.

The decision at this step is storage. Banuba recommends storing the token on your server, because it makes renewal faster. If the token is compiled into the app, every renewal means a new build submitted to the App Store or Google Play.

Where this step fails: an expired token. Banuba documents three states. While the token is valid, the SDK works as expected. For one month after expiry, the SDK works but shows a Banuba watermark. After that month, the functionality stops while the rest of your app keeps running. A demo token in a live app hits the first of those states 14 days after you got it, which is why the docs say not to ship one.

Step 2: Add the SDK packages, and only the ones you need

Banuba Face AR SDK is split into packages, and your app pulls the ones its features need. Three rules from the installation page decide the step.

First, the API package is always required. On Android that is com.banuba.sdk:sdk_api, on iOS it is BNBSdkApi. Second, face tracking lives in its own package, face_tracker on Android and BNBFaceTracker on iOS, and the docs say to include it whenever you deal with tracking. Third, every package must be the same version. Banuba warns that packages of different versions, even minor ones, may conflict or work incorrectly together.

On Android, add the Banuba Maven repository in settings.gradle.kts:

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven {
            name = "BanubaMaven"
            url = uri("https://nexus.banuba.net/repository/maven-releases")
        }
    }
}

Then declare the packages. Note the underscores in the artifact names and the exact version string:

val bnbVersion = "1.18.5"

dependencies {
    // Always required
    api("com.banuba.sdk:sdk_api:$bnbVersion")
    // Face tracking is used in most effects
    api("com.banuba.sdk:face_tracker:$bnbVersion")

    // Add only what your effects actually use:
    // api("com.banuba.sdk:background:$bnbVersion")   // background replacement
    // api("com.banuba.sdk:makeup:$bnbVersion")       // makeup
    // api("com.banuba.sdk:eyes:$bnbVersion")         // eye effects
    // api("com.banuba.sdk:lips:$bnbVersion")         // lipstick
    // api("com.banuba.sdk:hair:$bnbVersion")         // hair color
    // api("com.banuba.sdk:skin:$bnbVersion")         // skin retouch
}

Pin the version rather than writing 1.18.+. A dynamic version resolves at build time, so two machines, or the same machine a week apart, can end up on different patch releases. That is the exact situation the docs warn about when they say every package must be on the same version.

For a face filter alone, sdk_api plus face_tracker is the whole list. The banuba_sdk package depends on everything, and the docs describe it as the choice when you do not care about size.

On iOS, add the Swift Package Manager packages through File > Add Package Dependencies, starting with https://github.com/sdk-banuba/BNBSdkApi, and add the feature packages from the sdk-banuba repositories at the same version. CocoaPods is also supported through a custom repository listed in the podspecs repo.

Where this step fails: a feature that renders wrong or not at all. The installation page says to read the application logs in that case to find which package is missing. The second failure is a version mismatch between two packages, which the same page says can break features without an obvious error.

Step 3: Initialize the SDK once at app start

Initialization is a single call with the token, placed in the application class so it runs once before any camera screen opens.

Android, from the sample's Application.kt:

import com.banuba.sdk.manager.BanubaSdkManager

const val BANUBA_CLIENT_TOKEN = <#Place your token here#>

class Application : android.app.Application() {
    override fun onCreate() {
        super.onCreate()
        BanubaSdkManager.initialize(this, BANUBA_CLIENT_TOKEN)
    }
}

iOS, from the sample's AppDelegate.swift. The resourcePath array tells the SDK where to look for effects, and the sample points it at an effects folder inside the app bundle and at the bundle root:

import UIKit
import BNBSdkApi

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    var banubaClientToken: String = <#Place your token here#>
    var window: UIWindow?

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        BanubaSdkManager.initialize(
            resourcePath: [
                Bundle.main.bundlePath + "/effects",
                Bundle.main.bundlePath
            ],
            clientTokenString: banubaClientToken
        )
        return true
    }
}

The <#Place your token here#> placeholder is literally what the samples ship, and neither file compiles until you replace it. Put in the value from step 1, or the call that fetches it from your server.

Step 4: Connect the camera, the player and the output view

This is the step that turns the SDK on. Three objects do the work on both platforms: a camera device that produces frames, a Player that runs the pipeline, and an output that displays the result. The pattern is player.use(input, output), then play().

Android, from the sample's MainActivity.kt, trimmed to the pipeline:

import android.os.Bundle
import android.view.SurfaceView
import com.banuba.sdk.input.CameraDevice
import com.banuba.sdk.input.CameraInput
import com.banuba.sdk.output.SurfaceOutput
import com.banuba.sdk.player.Player

class MainActivity : BaseActivity(R.layout.main) {

    private val surfaceView by lazy(LazyThreadSafetyMode.NONE) {
        findViewById<SurfaceView>(R.id.surfaceView)
    }

    // The player executes the main pipeline
    private val player by lazy(LazyThreadSafetyMode.NONE) { Player() }

    // This camera device will pass frames to the CameraInput
    private val cameraDevice by lazy(LazyThreadSafetyMode.NONE) {
        CameraDevice(requireNotNull(this.applicationContext), this@MainActivity)
    }

    // The result will be displayed on the surface
    private val surfaceOutput by lazy(LazyThreadSafetyMode.NONE) {
        SurfaceOutput(surfaceView.holder)
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // Set where the player takes input frames from and where it displays the result
        player.use(CameraInput(cameraDevice), surfaceOutput)
    }
}

iOS, from the sample's ViewController.swift. The output here is an EffectPlayerView placed in the storyboard:

import UIKit
import BNBSdkApi
import BNBSdkCore

class ViewController: UIViewController {
    // Output surface for the Player
    @IBOutlet weak var effectView: EffectPlayerView!

    // Input stream for the Player
    private let cameraDevice = CameraDevice(
        cameraMode: .FrontCameraSession,
        captureSessionPreset: .hd1280x720
    )

    // Player processes frames from the input and renders them into the outputs
    private var player: Player?

    // Current effect
    private var effect: BNBEffect?

    override func viewDidLoad() {
        super.viewDidLoad()
        player = Player()
        player?.use(input: Camera(cameraDevice: cameraDevice))
        player?.use(outputs: [effectView])
        player?.play()
        effect = player?.load(effect: "TrollGrandma")
        cameraDevice.start()
    }
}

Where this step fails: a black view. On Android, nothing is drawn until cameraDevice.start() and player.play() have both run, and in the sample those calls sit in the lifecycle methods shown in step 6, not in onCreate. On iOS the sample starts the camera as the last line of viewDidLoad, after play() and after the effect load.

Step 5: Load an effect

An effect is a folder. Per the effect structure docs, only config.json is mandatory inside it, and the other files are images, shaders, videos and a config.js script that the effect refers to. The samples ship an effect named TrollGrandma in an effects folder, and both platforms load it by name.

Android loads asynchronously, and passing an empty string unloads:

companion object {
    private const val MASK_NAME = "effects/TrollGrandma"
}

// Inside onCreate, on a button:
var shouldApply = false
showMaskButton.setOnClickListener {
    shouldApply = !shouldApply
    showMaskButton.text = if (shouldApply) "Hide mask" else "Show mask"
    // The mask is loaded asynchronously and applied
    player.loadAsync(if (shouldApply) MASK_NAME else "")
}

iOS loads synchronously with player?.load(effect: "TrollGrandma"), as shown in step 4.

Note the asymmetry in those two strings, because it is a common first bug. Android passes the path effects/TrollGrandma relative to assets. iOS passes the bare name TrollGrandma, because the effects folder is already in the resourcePath array you set in step 3. Copying the Android constant into the iOS project gives you a silent no-op.

The decision at this step is where effects come from. You can write the folder yourself starting from a blank config.json, build one in Banuba Studio, or buy one from the Banuba Asset Store. Which packages the effect needs comes back to step 2: a 3D mask needs face tracking only, while lipstick needs the lips package.

Where this step fails: the effect loads and nothing changes on screen, or part of it is missing. That is the missing-package symptom from step 2, and the logs name the package.

Step 6: Handle permissions, the lifecycle and the device you did not test on

The sample activity extends a BaseActivity that requests CAMERA and RECORD_AUDIO at onStart and finishes the activity if either is denied. Your app already has a permission flow, so the point is only that the camera device must not start before the grant.

The lifecycle calls in the Android sample are the part most ports drop. Each object is started, paused and closed in order:

override fun onStart() {
    super.onStart()
    // We start the camera and then the player starts taking frames
    cameraDevice.start()
}

override fun onResume() {
    super.onResume()
    player.play()
}

override fun onPause() {
    super.onPause()
    // Pause the player when the activity is inactive
    player.pause()
}

override fun onStop() {
    // After this, the camera stops capturing frames and transmitting them to the player
    cameraDevice.stop()
    super.onStop()
}

override fun onDestroy() {
    // After you are done using the player, free all resources by calling close()
    cameraDevice.close()
    surfaceOutput.close()
    player.close()
    super.onDestroy()
}

The three close() calls in onDestroy are what the sample's own comment calls mandatory. A user who backgrounds the app without pressing anything goes through onPause and onStop, so the camera is released by that path too.

The last decision is the device you test on. Banuba's technical specification publishes face tracking figures per device tier, measured under fixed lab conditions, and names no handsets:

Tier, per Banuba's specification	Single face, FPS	Max angle, degrees	Max distance, cm	5 faces, FPS
Android Low	25	80	170	22
Android High	30	80	180	27
iOS Mid	30	80	230	30
iOS High	30	80	230	30

Banuba produced these figures in its own lab, and no third party has repeated them. In text: single-face tracking holds 25 FPS on the Android Low tier and 30 FPS on Android High and both iOS tiers. The maximum tracking angle is 80 degrees on every tier. The maximum tracking distance is 170 cm on Android Low, 180 cm on Android High and 230 cm on both iOS tiers. With five faces in frame, Android Low drops to 22 FPS, Android High to 27, and both iOS tiers stay at 30. The specification lists five as the maximum number of faces tracked with acceptable quality on most devices.

So the low-tier Android handset is the one that shows the gap between your first effect and the spec sheet. Run the effect you intend to ship on one before you decide the effect is done, and if you want a device list to start from, our tested guide to AR SDKs on Android and iOS names the handsets we used.

Six steps, two code files per platform, one device to test on

The integration touches two code files per platform, plus your build files: an application class that initializes the SDK with the token, and a camera screen that connects a camera device to a Player and an output view, then loads an effect by folder name.

The costs sit at the edges. Token storage decides whether a renewal is a server change or a store submission. Package selection decides app size and whether a feature silently lacks its neural network. The lifecycle block decides whether the camera is released when the user leaves. And the Android Low tier, at 25 FPS single-face and 22 FPS with five faces in Banuba's own figures, is the device that tells you whether the effect is finished.

FAQ

Where is the Banuba Face AR SDK documentation for Android and iOS integration?

Banuba publishes the integration docs per platform under one Getting Started page, with Android, iOS, Web, Flutter, React Native and Desktop tabs, and the installation page lists every Banuba Face AR SDK package with what it provides. The same docs ship an LLM-friendly llms-full.txt file for AI-assisted setup.

Where are the Banuba Face AR SDK code samples?

Banuba keeps platform-specific sample projects on GitHub. The Android and iOS repositories linked in this guide hold the camera sample used above, and Banuba also publishes quickstart repositories for Flutter, React Native, Web, Unity and desktop.

What happens when the Banuba Face AR SDK token expires?

For one month after expiry, Banuba Face AR SDK keeps working but displays a Banuba watermark. After that month the SDK functionality stops while the rest of the app works normally. The token cannot be extended; you request a new one and update it in the app, which is why Banuba recommends storing it on a server.

Banuba SDK watermark appeared after the trial, what do I do?

A watermark after the trial means the 14-day demo token of Banuba Face AR SDK has expired. Request a commercial token, or a renewed demo token if you have not finished evaluating, and replace the value you pass to BanubaSdkManager.initialize.

Does Banuba Face AR SDK have Flutter and React Native plugins?

Yes. Banuba maintains the Banuba Face AR SDK Flutter plugin on pub.dev and the React Native plugin on npm, and both sit on the same SDK as the native Android and iOS integration shown here.

6 Routes for Adding a Video Editing SDK to an iOS App and Where Each Breaks

Team Banuba — Wed, 14 Oct 2026 08:37:14 +0000

A video editing SDK for iOS is a packaged framework that hands your app a timeline, effects and export so your team does not assemble them from AVFoundation primitives. Six routes are realistic on iOS today, and the right one depends on a single input: the list of things your editor must do on day one.

The routes fail at different points, from a portrait-only system view to a license that only arrives after a sales call. Banuba sells one of the SDKs compared below, the Banuba Video Editor SDK, and it gets the same treatment as the rest, including the jobs it cannot do and the toolchain it forces on your build machine.

Step 1: List what the editor has to do

Before comparing anything, collect four inputs.

Your deployment floor and toolchain. The minimum iOS version you ship and the Xcode version your CI runs. One SDK below requires Xcode 26.0, which in turn requires a recent macOS, so check your build machines before your deployment target.
Your feature tier. Sort the plan into one of four buckets: (a) trim, join and export; (b) a timeline UI with text, music and filters; (c) camera-time effects such as face masks, beauty or background replacement applied while recording; (d) the same editor on Android, in a browser or on a server.
Your oldest supported device. Step 5 times exports on it.
Who signs contracts. Two of the routes cannot be prototyped until someone talks to sales.

Tier (a) has two no-cost answers; tiers (b) to (d) are where licensed SDKs come in.

Step 2: Choose a video editing SDK route (or none)

Route	Product compared	Access and availability	iOS install path (per vendor docs)	App size added (vendor-published)	Trial (vendor terms)	Where it breaks
UIVideoEditorController	Apple's system trim view in UIKit	Free, first-party	Part of UIKit	Ships with iOS	Not applicable	Portrait only; no subclassing or overlay views
AVFoundation	Apple's media framework	Free, first-party	Part of the iOS SDK	Ships with iOS	Not applicable	No editor UI, no face AR, beauty, background removal or captions
Banuba Video Editor SDK	Native editor with UI plus Face AR	Open sample on GitHub; trial token on request, then license	CocoaPods 1.12.1+ or SPM; iOS 15.0+, Swift 5.9+, Xcode 26.0+	14 MB core, 45 MB full bundle	14 days, all features	Requires Xcode 26 on your build machines; no browser editor, no headless server render, no pro multi-track or HDR export
IMG.LY Video Editor SDK (CE.SDK)	Cross-platform editor engine	Sales-gated custom quote	CocoaPods, `pod 'IMGLYUI'`	Not published	30 days, full access	Each platform licensed separately; no face AR or beauty in documented features
Meishe StreamingSDK + EffectSDK	Pro editing and effects engine	Login-gated download, contact sales	Objective-C against `NvsStreamingContext`	Not published	Trial authorization, watermarked output	Per-app license file bound to bundle ID; media must be transcoded to its own m3u8
Picsart Editor SDK	Web editor embed	CDN script tag; no iOS package	None documented	Not applicable	Not evaluated	Desktop browsers only; WebView unsupported

Figures come from each vendor's own documentation as read in September 2026. Vendor pages change, so anything that decides a build (price, size, trial terms, license mechanics) should come from the vendor in writing.

UIVideoEditorController

Apple's system interface for trimming and re-encoding a recorded movie, free and first-party. The UIKit reference lists its limits: portrait mode only, no subclassing, a private view hierarchy, no overlay views, and availability only on devices that support video recording. It wins on effort, with zero UI code for trimming.

AVFoundation

AVFoundation is first-party, costs nothing and sits in the iOS SDK, with compositions, tracks and export sessions as building blocks. It wins on cost and dependency count. It has no editor UI and no face AR, beauty, background removal or automatic captions.

Banuba Video Editor SDK

A native iOS editor with its own UI, installed via CocoaPods or Swift Package Manager. The Video Editor SDK page lists transitions, an audio editor, text and GIFs, LUT color filters, templates, and Face AR with face filters and green screen background subtraction. Access starts with a 14-day trial token covering all features, then a license priced on monthly active users with no per-developer-seat fees and no public price list. Of the three licensed SDKs, it is the only one with a published size.

Two boundaries worth knowing before you add the pod. It does not cover browser editing, headless server rendering, or pro multi-track and HDR work. And it requires Xcode 26.0 or newer, which is the strictest toolchain requirement of the six routes and the one most likely to stop a prototype on day one, since it rules out build machines on an older macOS.

IMG.LY Video Editor SDK

Built on the CE.SDK engine, the IMG.LY video SDK runs on iOS, Android, web, React Native, Flutter, Electron, macOS and Mac Catalyst, plus a Node.js headless renderer. It handles MP4, WebM and MOV, and IMG.LY states GDPR compliance and SOC 2 Type II certification. Access is a custom quote metered by MAU, with each platform licensed separately and AI plugin usage billed by the model providers. It wins on platform reach and on trial length. Face AR and beauty are absent from its documented features, and it does not publish an SDK size.

Meishe StreamingSDK

Meishe pairs StreamingSDK with EffectSDK. It wins on editing depth: multi-track timelines, nestable sub-timelines, 4K editing, 8K image processing, HDR export with HLG or ST2084 curves, and 106- or 240-point face landmark models. Its access is the heaviest here: login-gated downloads, contact-sales pricing with no published figure, a per-app license bound to your bundle ID, a watermark until authorization, and 4K licensed separately. No SDK size is published.

Picsart Editor SDK

A web embed loaded by a CDN script tag, for desktop browsers only. Mobile browsers are not officially supported and WebView is explicitly unsupported, which rules out wrapping it in an iOS app. It also lacks real-time editing, allows one source video per project, and caps output at 1080p and 10 minutes. We did not evaluate its signup terms because it has no iOS path.

Step 3: How to trim and export a video with AVFoundation

For tier (a), this is the whole job. The function loads a clip, clamps the end time to the asset's duration, exports the range as MP4 at the highest-quality preset, and throws on each failure path.

Two export paths appear below, behind an availability check. The newer export(to:as:) is cleaner, and the completion-handler path is what runs on an iOS 15 deployment target. Confirm the exact availability badge on Apple's AVAssetExportSession reference against the SDK you build with, and delete the branch if your floor is above it.

import AVFoundation

enum TrimExportError: Error {
    case sessionUnavailable
    case mp4NotSupported
    case exportFailed
}

func trimAndExport(source: URL,
                   from startSeconds: Double,
                   to endSeconds: Double,
                   output: URL) async throws {

    let asset = AVURLAsset(url: source)
    let duration = try await asset.load(.duration)

    let start = CMTime(seconds: startSeconds, preferredTimescale: 600)
    let end = CMTimeMinimum(CMTime(seconds: endSeconds, preferredTimescale: 600), duration)

    guard let session = AVAssetExportSession(
        asset: asset,
        presetName: AVAssetExportPresetHighestQuality
    ) else {
        throw TrimExportError.sessionUnavailable
    }

    guard session.supportedFileTypes.contains(.mp4) else {
        throw TrimExportError.mp4NotSupported
    }

    session.timeRange = CMTimeRange(start: start, end: end)

    // Start from an empty destination path.
    try? FileManager.default.removeItem(at: output)

    if #available(iOS 18.0, *) {
        try await session.export(to: output, as: .mp4)
    } else {
        session.outputURL = output
        session.outputFileType = .mp4

        await withCheckedContinuation { continuation in
            session.exportAsynchronously {
                continuation.resume()
            }
        }

        switch session.status {
        case .completed:
            break
        case .cancelled:
            throw CancellationError()
        default:
            throw session.error ?? TrimExportError.exportFailed
        }
    }
}

// Caller
Task {
    do {
        try await trimAndExport(source: inputURL, from: 2, to: 12, output: outputURL)
        print("Export finished: \(outputURL.path)")
    } catch {
        print("Export failed: \(error.localizedDescription)")
    }
}

inputURL and outputURL are your own file URLs.

The export session comes back nil

The initializer is failable. Before blaming the file, call AVAssetExportSession.determineCompatibility(ofExportPreset:with:outputFileType:completionHandler:) with your asset and preset; Apple provides it for this check.

The export throws on the MP4 file type

Apple documents that the export throws when the file type is missing from supportedFileTypes. The guard in the snippet reports that case as its own error.

The export throws after the user leaves the screen

Apple's documentation says the export also ends on cancellation, and that cancelling the parent Task cancels it. If the task is tied to a view's lifetime, dismissing the view ends the export. The legacy branch surfaces the same case as a CancellationError.

Past this point, a timeline UI, filter previews and face effects during recording are yours to write.

Step 4: How to integrate a video editor SDK for iOS

Banuba: install, permissions, license check

The iOS requirements page sets the floor, and the integration guide walks through five tasks:

Add the pods with CocoaPods 1.12.1 or newer, or the packages with Swift Package Manager.
Add four usage strings to Info.plist: NSCameraUsageDescription, NSMicrophoneUsageDescription, NSPhotoLibraryUsageDescription and NSAppleMusicUsageDescription (media library).
Create a module class that builds a VideoEditorConfig.
Create BanubaVideoEditor with your license token.
Call getLicenseState and open the editor only when it reports a valid license.

Check the Xcode version on your build machines before step 1. The requirements page lists Xcode 26.0 or newer, and a CI image or a developer laptop on an older macOS will not get there with a pod install.

Banuba documents integration "in as little as 8 minutes"; that is our own claim, and the runnable ve-sdk-ios-integration-sample is how to test it on your machine. Teams using Claude Code, Codex or Qwen Code can install Banuba's agent skills and let the coding agent perform these steps.

BanubaVideoEditor returns nil

Per the docs, the initializer returns nil when the token is incorrect, for example empty or truncated. Check how the token reaches the binary first.

The editor opens to a "Video content unavailable" screen

The docs state this appears when the SDK starts with a revoked or expired license. The getLicenseState check in task 5 catches it before the user does.

IMG.LY: one pod, several licenses

On iOS, IMG.LY installs with pod 'IMGLYUI' via CocoaPods. The planning work is the license count, since iOS, Android, web and desktop are each licensed separately.

Meishe: license file before first frame

Meishe's iOS integration is written in Objective-C against NvsStreamingContext. Download requires a login, and output stays watermarked until the per-app license, bound to your bundle ID, is authorized. Media must also go via Meishe's transcoding service into its proprietary m3u8 format before it can sit on a track, so plan that step into your import flow.

Questions to ask about any client-side license token

The license token ships inside your app, so ask every vendor, including us:

How is the token scoped to the bundle ID, and what does the SDK do when the bundle ID differs?
What happens if someone lifts the token from the binary and ships it in another app?
How does revocation work, how fast does it reach installed apps, and what does the end user see?
Does license validation need a network call, and what does the SDK do offline?

Get the answers in writing.

Step 5: Measure before you commit

Three numbers settle most decisions, and each has to come from your own build.

Binary size delta

Archive the app with and without the SDK and compare. Banuba's requirements docs publish 14 MB for the core editor and 45 MB for the full bundle. IMG.LY and Meishe do not publish a size, so the archive diff is your only number for them.

Export wall-clock on your oldest device

Time one fixed clip in each route, the AVFoundation snippet included, on the slowest phone you support.

Trial window

Banuba gives 14 days with all features, IMG.LY 30 days with full access, and Meishe a trial authorization with watermarked output. Plan the test so it fits the shortest window you are using.

For more metrics, there is a list of seven numbers worth measuring inside your own app. If engineering time is the open question, run the build-versus-buy math next to these results.

How to choose between the routes

If you are building a trim-and-share feature, use AVFoundation, or UIVideoEditorController if a portrait system view is acceptable, because both cost nothing and add nothing to your download.
If you are building a creator or social app where face effects run while recording, use the Banuba Video Editor SDK, because the timeline UI and Face AR arrive in one dependency on iOS 15+; confirm your build machines can run Xcode 26 first.
If your editor must also run on the web or render on a server, use IMG.LY, because one engine covers web, mobile and a Node.js renderer; budget for one license per platform.
If you need multi-track timelines, 4K editing or HDR export, use Meishe, because its editing model goes deepest; start the license conversation early, since output stays watermarked until authorization.
If the editor lives only in a desktop browser, Picsart's Editor SDK is the one that fits there; it is not an option for an iOS app.

Where each vendor ranks per criterion is covered in our iOS SDK comparison on the Banuba blog.

Stay on Apple's frameworks until effects or other platforms enter the plan

Tier (a) apps can ship on AVFoundation with the snippet above and no license. Once camera-time effects, a timeline UI, web reach or HDR depth appear on the roadmap, a licensed SDK is the shorter path, and the scenario list names which one. Size and export time measured in your own app confirm it within the trial window.

FAQ

What are the Banuba Video Editor SDK iOS requirements?

iOS 15.0 or newer, Swift 5.9 or newer and Xcode 26.0 or newer, installed through CocoaPods 1.12.1+ or Swift Package Manager. Banuba supports arm64 and arm64e, with limited x86-64 support. The Xcode floor is the one to check first, because it constrains your build machines rather than your users' phones.

Is there a free way to add video editing to an iOS app?

Yes. AVFoundation and UIVideoEditorController cost nothing. Among licensed options, Banuba offers a 14-day trial with all features, IMG.LY 30 days with full access, and Meishe a watermarked trial authorization.

Can the Banuba Video Editor SDK run in a browser or on a server?

No. Banuba covers native iOS and Android plus Flutter and React Native. For browser editing or headless rendering, IMG.LY's CE.SDK is the documented fit.

How is the Banuba Video Editor SDK priced compared with IMG.LY and Meishe?

Banuba prices on monthly active users with no per-developer-seat fees and no public price list. IMG.LY quotes per customer, metered by MAU, with each platform licensed separately. Meishe publishes no price and routes buyers to sales.

Virtual Eyewear Try-On: 4 Jobs Between Frame Photos and Cart

Team Banuba — Mon, 31 Aug 2026 20:44:28 +0000

Putting eyewear try-on on a storefront breaks into four jobs: turning photographs of each frame into a try-on asset, deciding which browsers get the entry point, mounting the widget and choosing what opens it, and connecting the catalog check to the cart events. Three are front-end work. The first is a data pipeline, and it sets the launch date.

The ticket usually arrives with a design attached, a button under the add-to-cart block, and no picture of what sits behind it. The code below uses the Banuba virtual try-on widget because that is what we build, so the attribute and method names are ours, and every fact about them is cited to our own documentation. The four jobs hold for any web try-on engine you mount.

Before you start

Four things belong in hand before the first commit:

An HTTPS origin for every environment the widget runs in, staging included.
A merchant ID issued by Banuba, which the widget uses to load your configuration.
Photographs of every frame in the launch collection, shot to the digitization spec rather than pulled from the web catalog.
A decision about where the entry point lives on the product detail page, since it drives the gating logic in the second job.

Digitizing the frames

Digitization turns photographs of a physical frame into the asset the widget renders on a face, and in the admin dashboard you do it one frame at a time. Per frame you supply a name, a brand picked from the list or created on the spot, a SKU, an optional product page URL, then three images in the try-on model step: left, body and right. A preview renders while the images upload, so a bad set shows itself before you save, as our glasses dashboard guide describes.

Since widget v1.7.0, released 30 April 2026 according to our widget changelog, that processing runs automatically. The consequence lands on whoever owns the photography. Our docs state that photos failing the requirements give a poor result, and that it cannot be repaired afterwards, because nothing about the processing is manual. Treat the photo spec as an input requirement with the same weight as a schema.

Here is the part that reshapes a project plan. The bulk CSV path is makeup only. In our bulk upload template the Category column always takes the value MAKEUP, and the columns after it are Region, Finish, Color as a 6-digit hex, and Coverage, all parameters of a cosmetic product. Frames therefore go in through the Glasses tab individually, and our docs mark that tab Beta. For a catalog of any size that is a data entry line with a person's name on it, and sizing it comes before anyone commits to a launch date.

Production work asks for more than the three try-on images. The commercial list in our knowledge base adds UPC number, a storefront image link, the product page URL, photos from multiple angles, and a 3D model, with frame size where it is known. Collect all of it in the same pass, since walking the collection twice costs the same hours twice.

The decision point is ownership. Someone has to supply the photographs, either merchandising from existing shoots or a studio from a new one, and that answer moves the timeline more than any code in this article does. Pull one frame record out of your PIM as well and see whether the frame size fields exist there at all.

What goes wrong here is scheduling. A team scopes the work as a front-end sprint, then finds in week one that the launch collection has to be entered by hand and reshot on top, because the existing photography was styled for hero banners at an angle the try-on step cannot use.

Deciding which browsers get the button

The try-on button should render off a runtime check rather than a static support table, because camera access has hard requirements a shopper's browser either satisfies or fails. The first is transport. Webcam access needs an HTTPS/TLS connection, so a staging box on plain HTTP fails at the first call and looks exactly like a broken widget; MDN documents the secure context rule behind getUserMedia, which applies to every camera API on the page, ours included.

The second is the engine. Our documented system requirements specify the last 2 Safari major versions, the last 2 iOS major versions, and the last 5 versions of Chrome, Opera, Edge and Samsung Internet. Read that as the set we test against. A version floor describes a population, while the shopper in front of you is one device with one driver and one browser build.

The answer for an individual shopper comes from feature detection at render time:

function cameraIsAvailable() {
  return Boolean(
    window.isSecureContext &&
    navigator.mediaDevices &&
    typeof navigator.mediaDevices.getUserMedia === 'function'
  );
}

const tryOnButton = document.getElementById('open-vto');
tryOnButton.hidden = !cameraIsAvailable();

window.isSecureContext covers transport, navigator.mediaDevices is absent entirely on browsers without media capture, and tryOnButton is the entry point your PDP template renders. The button now appears only where both conditions hold.

Then comes the branch, and both sides are defensible. Hiding the entry point on a failing check keeps the page honest, at the cost of a shopper who never learns the feature exists. Rendering it with a static model photo behind it keeps the feature discoverable. Eyewear weakens that second option in a way a cosmetic shade does not: a frame on a stock model shows how the style reads, while the question that made the shopper tap was how it sits on their own face.

Skip the gate and the failure is uniform. Every shopper sees the button, and the ones on an old in-app browser or an HTTP staging link get a modal that opens onto nothing.

Mounting the widget and picking the trigger

Mounting is two lines of markup, and the judgment call here is what opens the widget afterwards. The bundle loads from a CDN, and the element goes wherever the experience should appear, both covered in our integration guide:

<head>
  <script type="module" src="https://tintvto.com/widget.js"></script>
</head>

That path carries no version segment, so it resolves to the current release. Confirm a pinned URL with your technical manager before production, because a minor release can change behavior on a page you have not deployed to in months.

On a product detail page you want the widget focused on the frame being viewed, which is what the isolated SKU attributes do:

<tint-vto merchant-id="YOUR_MERCHANT_ID" isolated-sku sku="8028997081552"></tint-vto>
<button id="open-vto" data-sku="8028997081552" hidden>Try these on</button>

merchant-id is the identifier Banuba issues you, isolated-sku switches the widget into single product mode, and sku names the frame on this page. The token and sdk-token attributes are documented as deprecated and slated for removal, so check any snippet inherited from an older sample.

That merchant ID ships in your page source and any visitor can read it in devtools, which is normal for a widget that loads its configuration client side and is also the first question a security reviewer will ask. The answer worth having in writing before launch is how the identifier is scoped: which origins it works from, how that list is configured, and what happens when someone copies it onto their own domain. Put those three questions to your technical manager during evaluation rather than the week before release.

Our integration guide documents launch triggers for opening immediately, opening on the window load event, and opening on a customer action. A product detail page wants the third, so that the camera permission prompt follows an explicit tap and reads as an answer to something the shopper asked for.

The camera itself can be declined, and the fallback is two method calls:

<script type="module">
  const widget = document.querySelector('tint-vto');
  const tryOnButton = document.getElementById('open-vto');

  tryOnButton.addEventListener('click', async () => {
    await widget.open();

    const stream = await widget.useWebcam();
    if (!stream) {
      const modelPhoto = await fetch('/media/model-front.webp').then((r) => r.blob());
      await widget.useImage(modelPhoto);
    }
  });
</script>

useWebcam() resolves with the active stream, or with null when the shopper denies access, and useImage() accepts a Blob or File to render on instead. usePhoto() is a deprecated alias of useImage(). On a frames PDP that fallback stays a courtesy, for the fit reason above.

Two things break here in practice. One is the inherited snippet still passing token, which keeps working until the release that removes it. The other is a widget wired to open on page load, which spends the camera prompt before the shopper has expressed any interest and trains them to dismiss it.

Connecting the catalog and the cart

Two wires finish the integration: a catalog check deciding whether the button renders for this frame, and the events keeping the cart in step with the widget. The check is isCustomerSkuExist(customerSkuIds: string[]), which resolves true when every SKU you pass exists in the try-on catalog and can be called before open(), per our widget API reference. Put it in the PDP render path:

<script type="module">
  const widget = document.querySelector('tint-vto');
  const tryOnButton = document.getElementById('open-vto');
  const currentSku = tryOnButton.dataset.sku;

  const isDigitized = await widget.isCustomerSkuExist([currentSku]);
  tryOnButton.hidden = !isDigitized || !cameraIsAvailable();
</script>

currentSku reads the data-sku attribute your template wrote onto the button, and cameraIsAvailable() is the detection function from the previous job, imported from wherever you keep it. A frame with no try-on asset yet never shows a button.

That gate carries more weight for eyewear than for a cosmetic shade, where a missing asset still leaves a swatch and a product photo to look at.

Cart sync runs on the events the widget emits. Attach the listeners once, wherever you mount the element:

const cart = window.storefrontCart; // your own cart module

widget.addEventListener('addToCart', ({ detail }) => cart.add(detail));
widget.addEventListener('removeFromCart', ({ detail }) => cart.remove(detail));
widget.addEventListener('redirectToCart', () => { window.location.href = '/cart'; });

Our API reference documents detail as an array of Product objects on the first two events, and as null on redirectToCart, which fires when the shopper clicks Go to cart. To drive the widget from your own product data instead, applyProduct() takes fully defined product objects and applyProductByCustomerSku() takes your customer facing SKU identifiers.

For device checks, widget v1.7.1 of 18 May 2026 added try-on links and QR codes generated per product or for a whole catalog, per the same changelog. QA becomes scanning a code: open it on the phones your analytics say people shop from, and walk the flow inside the Instagram and Facebook in-app browsers, with no deploy behind any of it. Rendering and camera behavior diverge across handsets much further than a support matrix suggests, which is what our web AR testing kept running into.

The defects to watch for are quiet ones. Leave any of those events unhandled and the cart drifts, so a shopper adds a frame inside the try-on and finds the header count unchanged. Ship a frame to the PDP with a live button before anyone has processed its photos and you get the ungated version of the check above.

What carries over to another engine

Swap the vendor and the identifiers change while the shapes survive. There is always an asset preparation step with a photography spec attached, and it is the long pole. A capability gate follows it, since camera access on the web is conditional everywhere. Then a mount point plus a trigger decision, where the case for the tap is the permission prompt. Last comes the boundary between the try-on surface and your cart, crossed by events one way and product identifiers the other.

Bottom line

The three front-end jobs are a normal week for someone holding the merchant ID and a PDP template. The variable is the photography, and better code will not compress it, because it is bounded by how fast someone shoots frames to spec and enters them one at a time through a Beta tab. So run the estimate in that order: count the frames in the launch collection, find out who is shooting them and whether the UPC and frame size fields exist in your PIM today, and put the code work after that number.

FAQ

What do you upload for each frame?

A name, a brand, a SKU, an optional product page URL, and three images of the frame: left, body and right. Going to production, collect the commercial set in the same pass, which adds UPC number, a storefront image link, photos from multiple angles, a 3D model, and frame size where you have it.

Can frames be bulk imported from a CSV?

No. The bulk upload template is makeup only: its Category field takes the single value MAKEUP and its parameter columns are Region, Finish, Color and Coverage. Frames go in individually through the Glasses tab of the admin dashboard.

Why does the try-on work locally but not on my staging server?

Almost always because staging is served over plain HTTP. Browsers restrict camera access to secure contexts, and localhost counts as one while http://staging.example.com does not. Put a certificate on staging and the same build works.

Does eyewear try-on need a native app?

No. The widget is web based, loads from a CDN script tag, and runs in the browser on desktop and mobile, so no app store release sits in the critical path.

What happens on an unsupported browser?

The widget opens and the camera call fails, which reads to the shopper as a broken page. Hence the feature detection in the second job: the entry point renders only where a secure context and a media devices API are both present.

Which attributes should a new integration use?

merchant-id, plus isolated-sku and sku on a product detail page. token and sdk-token are deprecated and scheduled for removal, and usePhoto() is a deprecated alias of useImage().

6 AR Makeup Try-On Failures a React Storefront Hits in Production

Team Banuba — Wed, 19 Aug 2026 09:37:09 +0000

AR makeup try-on rarely fails in the demo. It fails on the third page load, on a mid-range Android, in the Instagram in-app browser, or on a skin tone nobody on the team has. Six failure modes account for most of it: camera permission handling, double-mounted effects, shade fidelity, frame rate collapse, SKU mapping drift, and mobile browser policy.

Each one below has the same shape: what actually breaks, why React or the mobile browser makes it worse, and the test you can run before a shopper finds it.

The code examples use the Banuba virtual try-on widget because that is what we build, but every test method here is vendor-neutral. If you are integrating a different engine, the checks still apply.

Why does a try-on demo pass and the storefront fail?

A vendor demo runs one product, one browser, one lighting setup, and one face. A storefront runs your whole catalog across every device your analytics has ever seen. The gap between those two is where the six failures live.

It is worth being precise about what a web try-on actually is before testing it. It is a camera stream, a face tracking model, a rendering layer, and a mapping from your SKUs to render parameters. Three of the six failures below are in code you wrote, not in the engine.

1. What happens when the shopper denies camera access?

This is the most common one and the cheapest to fix. getUserMedia can be denied, dismissed, blocked by enterprise policy, or unavailable because the page is not on a secure origin. Per MDN, getUserMedia is only available in a secure context, meaning HTTPS or localhost, so a staging box on plain HTTP will fail every time and look like a bug in the widget.

A try-on with no fallback shows a black rectangle and the shopper leaves the page. A try-on with a fallback shows the product on a model photo and keeps the session alive.

async function openTryOn(widget) {
  await widget.open();

 const stream = await widget.useWebcam();
  if (!stream) {
    // Camera denied, dismissed, or unavailable. Do not leave the modal empty.
    const model = await fetch("/model.webp").then((r) => r.blob());
    await widget.useImage(model);
  }
}

How to test it

In Chrome DevTools, open the three-dot menu, go to More tools, then Sensors, and block camera permission for the origin. Then repeat on plain HTTP. Both paths must render something. Track the denial rate as an event, because if a third of your sessions never get a camera, the fallback image is your real try-on experience and deserves the same design attention.

2. Why does the camera light stay on after the modal closes?

This one is specific to React and it is the failure most teams ship without noticing. React 18 in development deliberately mounts, unmounts, and remounts every component. The React documentation is blunt about the reason: Strict Mode calls effects twice so that "bugs caused by missing cleanup logic" surface in development instead of production.

If your effect opens the widget and never releases it, you get two widget instances and two camera streams. In development the symptom is a doubled modal.

In production the symptom is worse: the camera indicator stays lit after the shopper closes the try-on, which reads as spyware and generates support tickets.

import { useEffect, useRef } from "react";
export function TryOn({ merchantId, sku }) {
  const ref = useRef(null);

  useEffect(() => {
    const widget = ref.current;
    let cancelled = false;

    (async () => {
      await widget.open();
      if (cancelled) await widget.close();
    })();

    return () => {
      cancelled = true;
      widget.close();          // release the stream
    };
  }, [sku]);

  return <tint-vto ref={ref} merchant-id={merchantId} isolated-sku sku={sku} />;
}

How to test it

Open the try-on, close it, and watch the browser tab's camera indicator. It must go dark within a second. Then navigate between two product pages five times and confirm you still have exactly one widget instance in the DOM. Run this with Strict Mode on, not off. Turning Strict Mode off to make the double mount go away hides the bug rather than fixing it.

3. Does the shade look right on every skin tone, or only on yours?

This is the failure that costs money rather than support tickets, and it is the hardest to catch because the team testing it is usually not diverse enough to catch it.

The single most common complaint reported by virtual try-on buyers is filed, almost word for word, as "product color not displayed correctly": the shade on screen does not match the shade in the box. A naive color overlay washes out on deep skin and looks artificial on light skin, so the same lipstick reads as two different products depending on who is looking at it.

The fix is not something you test by eye once. Build a fixed test matrix and run it every release. The dermatology standard for this is the Fitzpatrick scale, which defines six skin phototypes, and it gives you a defensible set of rows rather than an arbitrary one.

Written out rather than only in the table: cover all six Fitzpatrick phototypes, four lighting conditions including backlit, at least four finishes including one high-coverage foundation, and both the live webcam path and the uploaded photo path. Twenty-four to forty-eight screenshots per release is a small price against a shade that only works on half your customers.

On the engine side, skin-tone-aware rendering is the specific capability that separates a try-on from a filter. The Banuba virtual try-on widget applies 16 makeup product types with skin-tone-aware application for exactly this reason, and supports 16 or more product categories including eyewear, hair color, contacts, jewelry, and accessories.

Whichever engine you pick, ask for its output across your matrix before you sign, not after.

4. What is your frame rate on the cheapest phone in your analytics?

Real-time face tracking plus rendering is a per-frame GPU and CPU budget. On a flagship phone you will never see the ceiling. On a three-year-old midrange Android the frame rate drops, the render lags behind the face by a few frames, and the try-on stops feeling like a mirror.

Pick a floor and enforce it. A practical one is 24 frames per second sustained over sixty seconds, since that is where motion stops reading as stuttering to most people.

Measure sustained rather than peak, because thermal throttling is what actually gets you: the first ten seconds look fine and second thirty do not.

let frames = 0;
const start = performance.now();

function tick() {
  frames += 1;
  if (performance.now() - start < 60000) requestAnimationFrame(tick);
  else console.log("sustained fps:", frames / 60);
}
requestAnimationFrame(tick);

How to test it

run it on a real device, not the emulator, and not immediately after a charge. Pull the three most common device models out of your analytics and test the slowest one. If you only have flagships in the office, a cheap prepaid Android is the highest-value QA hardware you can buy.

5. Why does one SKU render as a generic tint?

Try-on engines do not render your product. They render the parameters someone mapped to your product: a region, a color, a finish, a coverage level.

When merchandising adds a shade and nobody digitizes it, the try-on either shows nothing or falls back to something approximate, and the shopper sees a color that is not the one on the box.

This is a data integrity problem, so treat it as one. Add a contract test in CI that walks your live catalog and asserts every purchasable SKU exists on the try-on side.

// Fails the build when merchandising adds a SKU that nobody digitized.
const skus = await getPurchasableSkus();          // your catalog
const ok = await widget.isCustomerSkuExist(skus); // try-on catalog
if (!ok) throw new Error("SKU present in catalog but missing from try-on");

That isCustomerSkuExist call is from the Banuba widget API, and most engines expose an equivalent lookup; the open web sample has a minimal page you can diff your own wiring against.

How to test it

Run that check nightly against production data, not just on the fixture set in your test suite. Fixtures never drift. Catalogs always do. Then decide the product behavior for a missing SKU: hiding the try-on button is almost always better than opening a try-on that shows the wrong color.

6. Does it work inside the Instagram browser?

A large share of beauty traffic arrives from social, which means the page opens in an in-app webview rather than Safari or Chrome.

Those webviews have their own camera permission behavior, and iOS has a long-standing quirk that catches teams out: WebKit requires the playsinline attribute on a video element, otherwise the stream takes over the whole screen in fullscreen playback instead of rendering in place.

If you embed the try-on in your own native app rather than the mobile web, the same constraint applies from the other direction. Camera access inside a webview needs a real HTTPS origin, so loading inline HTML without setting a proper base URL will fail even though the identical markup works in a browser tab:

// Android WebView: JS on, and a real HTTPS base URL or the camera never opens.
webView.settings.javaScriptEnabled = true
webView.settings.domStorageEnabled = true
webView.loadDataWithBaseURL("https://shop.example.com/", html, "text/html", "UTF-8", null)

How to test it

Send yourself the product URL through Instagram, Facebook, and TikTok on both iOS and Android, and open it from inside each app. Do not test by pasting the link into Safari. That is a different browser with different rules, and it is not where your traffic is.

What does a release checklist look like?

Pulling the six together, the pre-release pass is short:

Camera denied and plain-HTTP origin both render a fallback, not a black box.
Camera indicator goes dark within a second of closing, with Strict Mode on.
Shade matrix screenshots taken across six phototypes and four lighting setups.
Sustained 24 fps over sixty seconds on the slowest device in your top three.
Nightly SKU contract test green against production catalog data.
Product URL opened from inside Instagram on iOS and Android.

For the integration itself, the reference worth having open alongside the checklist is the widget integration guide, which documents the element, its attributes, and the lifecycle methods used above.

Bottom line

The engineering work in AR makeup try-on has moved. Face tracking and rendering are the vendor's problem now, and a first web integration is realistically a two-week front-end task rather than a computer vision project.

What has not moved is everything around it: permissions, component lifecycle, device spread, catalog integrity, and the browsers your customers actually use.

Those six are yours regardless of which engine you integrate, and they are the difference between a try-on that converts and one that quietly loses sessions. Build the test matrix before the launch, not after the first support ticket.

FAQ

Do I need a native app to run AR makeup try-on?

No. A web-based try-on loads as a script bundle and a custom HTML element on your existing product page, so it runs in the mobile browser without a separate app. A native app can embed the same widget through a webview when you want it inside an existing app experience.

Why does the try-on work on desktop but not on my staging server?

Almost always the secure context rule. Browsers only expose getUserMedia over HTTPS or localhost, so a staging box served over plain HTTP will never get a camera stream no matter how correct the integration is.

How do I test shade accuracy without a diverse test team?

Use a fixed matrix instead of ad hoc checks. Six Fitzpatrick phototypes against four lighting conditions gives you 24 screenshots per finish, which you can collect from a stock photo set for the upload path and from contractors or colleagues for the live path. The point is that it is repeatable between releases.

What frame rate is good enough?

Set a floor rather than chasing a number. Sustained 24 fps over a full minute on your slowest common device is a reasonable bar, because motion below that starts reading as stutter and thermal throttling shows up after the first few seconds.

Can one integration cover more than makeup?

Yes, if the engine supports it. The Banuba widget covers 16 or more product categories including eyewear, hair color, contacts, jewelry, and accessories, so a storefront that integrates for lipstick can enable additional categories later through configuration rather than a second integration.

What breaks most often after launch?

Catalog drift. The integration is static once it ships, but merchandising keeps adding SKUs, and any SKU that is not digitized on the try-on side either disappears or renders approximately. A nightly contract test catches it before a customer does.