# Install for Web

> Add the authorized Web 0.2.0 preview package and confirm camera, secure-context, WebGL2, WebAssembly, and Web Crypto support.

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

Product: Nosmai Effects
Group: get-started
Source: https://nosmai.com/docs/effects/installation/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:

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

The package name used by application imports is:

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

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

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

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

Do not deploy the camera experience over plain HTTP.

## Check WebGL2 before startup

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

```ts
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](/docs/effects/quickstart/web/) to create the canvas, verify
the licence, start the camera, and apply a compatible `.nosmai` package.

## Common errors

| Error | Cause | Fix |
| --- | --- | --- |
| `Cannot find package '@nosmai/web-sdk'` | Authorized archive was not installed in this project | Install the supplied `0.2.0` archive and refresh the lockfile |
| `UNSUPPORTED_BROWSER` | Required browser APIs are unavailable | Use a supported modern browser and a secure context |
| `WEBGL_UNAVAILABLE` | WebGL2 context creation failed | Enable hardware acceleration or use a compatible browser and GPU |
| `CAMERA_PERMISSION` | User, browser policy, or iframe policy denied camera access | Grant camera access and add `allow="camera"` for an iframe |
| `PACKAGE_FETCH_FAILED` | Package URL is blocked, missing, or outside Content Security Policy | Verify the URL, response, CORS headers, and `connect-src` policy |

## Next steps

- [Add real-time camera effects to a Web app](/docs/effects/quickstart/web/)
- [Get and apply a licence key](/docs/effects/license-key/)
- [Check Web preview capabilities](/docs/effects/platform-support/)
- [Understand filters and authored effects](/docs/effects/concepts/filters-and-effects/)

## References

- [Nosmai Effects](/docs/effects/)
- [Nosmai Effects product page](https://nosmai.com/effects/)
- [Nosmai Effects pricing](https://nosmai.com/effects/#pricing)