Install for Web

Prerequisites

• Node 20.19 or later, or Node 22.12 or later
• A modern ESM-compatible bundler
• HTTPS for deployed environments or localhost for development
• Browser support for camera access, WebGL2, WebAssembly, and Web Crypto
• An authorized nosmai-web-sdk-0.2.0.tgz distribution
• A Web licence key and public verification key supplied for the preview

Install the preview package

Place the authorized archive in a private vendor directory, then install it:

npm install ./vendor/nosmai-web-sdk-0.2.0.tgz

The package name used by application imports is:

import { NosmaiWebSDK } from '@nosmai/web-sdk'

The preview is not a general public npm registry release. Keep its archive and licensed .nosmai assets out of public repositories unless distribution terms explicitly allow them.

Serve optional model assets

Face-aware effects use MediaPipe Face Landmarker. Background packages use a person segmentation model. The SDK can use version-pinned defaults, but self-hosting is preferred when the application has a strict Content Security Policy or needs controlled deployment.

Example public paths:

public/mediapipe/wasm/
public/models/face_landmarker.task
public/models/selfie_segmenter.tflite
public/filters/first-effect.nosmai

Pass these paths when creating the SDK:

const sdk = await NosmaiWebSDK.create({
  canvas,
  faceTracking: {
    wasmRoot: '/mediapipe/wasm',
    modelAssetPath: '/models/face_landmarker.task',
    maxFps: 30,
  },
  segmentation: {
    modelAssetPath: '/models/selfie_segmenter.tflite',
    maxFps: 15,
    temporalBlend: 0.65,
  },
})

Face and segmentation runtimes load only when the active package requires them.

Configure browser security

The document and any embedding iframe must permit camera access. A restrictive Content Security Policy must also allow:

• the application script and worker sources used by the bundler
• connect-src for licence verification and protected package downloads
• model and WASM asset locations
• image and media sources referenced by authored packages

When embedding the camera in an iframe, allow the camera explicitly:

<iframe src="https://camera.example.com" allow="camera"></iframe>

Do not deploy the camera experience over plain HTTP.

Check WebGL2 before startup

const probe = document.createElement('canvas')
const gl = probe.getContext('webgl2')

if (!gl) {
  throw new Error('WEBGL_UNAVAILABLE')
}

The SDK also performs this check and reports a stable error code. Hardware acceleration is recommended. Use sdk.diagnostics to inspect the active GPU renderer and face or segmentation delegate.

Package size

Web bundle impact depends on tree shaking, bundler output, optional MediaPipe runtime, face and segmentation models, and the authored packages shipped by the app. Lazy model loading avoids paying the face or segmentation startup cost for a normal colour effect.

Measure the production JavaScript chunks, cached model assets, and first-effect network request separately.

Verify it worked

Create a compile-only module:

import { NosmaiWebSDK } from '@nosmai/web-sdk'

export function getNosmaiVersion(sdk: NosmaiWebSDK): string {
  return sdk.version
}

Run the production build and confirm TypeScript resolves the import. Continue to the Web quickstart to create the canvas, verify the licence, start the camera, and apply a compatible .nosmai package.

Common errors

Next steps

• Add real-time camera effects to a Web app
• Get and apply a licence key
• Check Web preview capabilities
• Understand filters and authored effects

References

• Nosmai Effects
• Nosmai Effects product page
• Nosmai Effects pricing