# Longpipe — full documentation

> Open-source SDK for real-time video effects in the browser: virtual backgrounds,
> background blur, portrait matting, face touch-up, auto-reframe, and microphone
> noise removal. WebGPU with a WebGL2 fallback. MIT licensed. npm: `longpipe`.

Source: https://github.com/sb2702/longpipe
Docs site: https://longpipe.dev/docs
Index: https://longpipe.dev/llms.txt
Generated from the site's own docs sources at build time.

## Contents

1. Longpipe docs — https://longpipe.dev/docs
2. Getting started — https://longpipe.dev/docs/getting-started
3. API reference — https://longpipe.dev/docs/api
4. Architecture — https://longpipe.dev/docs/architecture
5. Backgrounds — https://longpipe.dev/docs/backgrounds
6. Touch-up — https://longpipe.dev/docs/touchup
7. Auto-reframe — https://longpipe.dev/docs/reframe
8. Audio denoise — https://longpipe.dev/docs/audio
9. Presets & autotune — https://longpipe.dev/docs/presets
10. Model layer — https://longpipe.dev/docs/model-layer
11. Self-hosting weights — https://longpipe.dev/docs/self-hosting

---


<!-- source: https://longpipe.dev/docs -->

# Longpipe

Open-source video effects SDK for the browser. Real-time virtual backgrounds, face touch-up, auto-reframe and mic noise removal on WebGPU with a WebGL2 fallback.

## What it does

Wraps neural matting + compositing into a single class. Hand it a `MediaStream`, get a `MediaStream` back with the effects applied. Runs in a worker by default; audio passes through unchanged unless you ask for denoising.

Backgrounds, touch-up and auto-reframe all ride a **single shared encoder pass** — enabling a second effect doesn't cost a second inference. Audio denoise runs in a parallel `AudioWorklet`, off the GPU entirely.

## Quick links

- [Getting started](https://longpipe.dev/docs/getting-started) — install + your first effect
- [API reference](https://longpipe.dev/docs/api) — `EffectsPipeline` options
- [Architecture](https://longpipe.dev/docs/architecture) — one encoder, many heads
- [Backgrounds](https://longpipe.dev/docs/backgrounds) — accepted background formats
- [Touch-up](https://longpipe.dev/docs/touchup) — skin smoothing
- [Auto-reframe](https://longpipe.dev/docs/reframe) — automatic subject framing
- [Audio denoise](https://longpipe.dev/docs/audio) — real-time mic noise removal
- [Presets & autotune](https://longpipe.dev/docs/presets) — model size knobs
- [Model layer](https://longpipe.dev/docs/model-layer) — run the model without the pipeline
- [Self-hosting weights](https://longpipe.dev/docs/self-hosting) — point at your own CDN

## For LLMs and agents

The docs are published as plain markdown, no HTML parsing needed:

- [`/llms.txt`](/llms.txt) — index of every page, with a summary of what Longpipe is
- [`/llms-full.txt`](/llms-full.txt) — all documentation concatenated into one file

Both are generated from these same pages at build time, so they can't drift.

## Status

Early but functional, and under active development — published on npm, with real-time matting that benchmarks well against MediaPipe and frame-to-frame temporal stability from an optical-flow head. Backgrounds, touch-up, multi-face support, auto-reframe and audio denoise all ship today; AR effects and lighting correction are still planned. Expect API changes between versions, and rough edges. Issues + PRs welcome on [GitHub](https://github.com/sb2702/longpipe).

---


<!-- source: https://longpipe.dev/docs/getting-started -->

# Getting started

## Install

```bash
npm install longpipe
```

That's it — model weights stream from `cdn.longpipe.dev` on first init, so no extra setup. (If you'd rather host weights yourself, see [Self-hosting weights](https://longpipe.dev/docs/self-hosting).)

## Your first effect

```js
import { EffectsPipeline } from 'longpipe'

// Get any MediaStream — webcam, captureStream(), getDisplayMedia(), whatever
const camera = await navigator.mediaDevices.getUserMedia({ video: true })

const pipeline = new EffectsPipeline(camera, {
  background: 'blur',  // 'blur' | 'none' | image URL | ImageBitmap | { color: '#0a3' } | ...
})

// pipeline.stream is a MediaStream — use it anywhere you'd use the original
videoElement.srcObject = pipeline.stream
await pipeline.ready
```

## What's happening

1. The constructor returns synchronously. `pipeline.stream` is available immediately and emits passthrough until init completes.
2. The SDK spawns a worker, picks the best model preset for your GPU (autotune), fetches weights, and starts compositing.
3. `await pipeline.ready` resolves when the first composited frame lands.

## Next steps

- Pick a [background](https://longpipe.dev/docs/backgrounds) other than blur
- Look at the full [API reference](https://longpipe.dev/docs/api)
- Tune [presets](https://longpipe.dev/docs/presets) if autotune isn't picking what you want

---


<!-- source: https://longpipe.dev/docs/api -->

# API reference

## `EffectsPipeline`

The single public class. Hand it a `MediaStream`, get a `MediaStream` back with the effect applied. The pipeline owns its own worker, weight loading, autotune, frame transport selection, audio passthrough, and adaptive preset swaps — designed so you don't have to wire any of that yourself.

Construction returns synchronously: `pipeline.stream` is wired immediately and emits the unprocessed input until the model is ready (~1–3s on cold start, depending on hardware). Use `await pipeline.ready` if you want to wait for the effect to actually be live before consuming the output.

```ts
const pipeline = new EffectsPipeline(inputStream, options?)
```

## Constructor parameters

### `inputStream`

**Type:** `MediaStream` &nbsp;·&nbsp; **Required**

Any video stream — webcam from `getUserMedia()`, screen capture from `getDisplayMedia()`, or a captured stream from a `<video>` or `<canvas>` element via `.captureStream()`. Audio tracks are passed through unchanged by default; pass `audio: 'drop'` to strip them, or `audio: 'denoise'` to clean them (see [Audio denoise](https://longpipe.dev/docs/audio)).

### `options`

**Type:** `PipelineOptions` &nbsp;·&nbsp; Optional

Shape:

```ts
interface PipelineOptions {
  background?:        BackgroundInput              // default: 'blur'
  touchup?:           TouchupOptions               // default: off
  reframe?:           boolean | ReframeOptions     // default: off
  preset?:            PresetName | ManualPreset    // default: 'auto'
  weightsBaseUrl?:    string                       // default: cdn.longpipe.dev/.../v/0.0.5/
  audio?:             'passthrough' | 'drop' | 'denoise' | { denoise: DenoiseOptions }   // default: 'passthrough'
  enabled?:           boolean                      // default: true
  outputResolution?:  { w: number, h: number }     // default: input track size
  adaptive?:          boolean                      // default: true
  onReady?:           () => void
  onError?:           (err: PipelineError) => void
}
```

Each property in detail:

#### `background`

**Type:** `BackgroundInput` · **Default:** `'blur'`

**Blur**

To add a blur, you can either set background to `'blur'` to use default blur settings, 

```ts
{
  background:  'blur'
}
```

or you can specify an object

```ts
{
  background: {
    blur: {
      strength?: number //0 to 1
    }
  }
}
```

**Image**

You can set `background` to a url, an `ImageBitmap` or an `<img>` element

```ts
{
  background: string | HTMLImageElement | ImageBitmap
}
```
**Video**

You can also set a video background by specifying a video url, or a `<video>` element, which will play in a loop with each frame being set as the background as the video plays in a loop.

```ts
{
  background: string | HTMLVideoElement
}
```

Swappable at runtime via `pipeline.setBackground(...)` — no flicker, no re-init. See [Backgrounds](https://longpipe.dev/docs/backgrounds) for the full input surface.

#### `touchup`

**Type:** `TouchupOptions` · **Default:** `off`

Skin smoothing. Composes with the background rather than replacing it — both ride the same encoder pass, so enabling it adds the landmark model and the smoothing passes, not a second inference.

```ts
new EffectsPipeline(stream, { background: 'blur', touchup: true })
new EffectsPipeline(stream, { touchup: { strength: 0.4, style: 'bilateral' } })
```

`strength` (0–1, default `0.6`) is the knob to expose to users. `amount`, `detail` and `style` tune the look. Smooths every face in frame (up to four, on `medium` and above).

Needs three extra files from `weightsBaseUrl` on first enable — see [Touch-up](https://longpipe.dev/docs/touchup).

#### `reframe`

**Type:** `boolean | ReframeOptions` · **Default:** `off`

Crop and zoom so the subject is framed — "centre stage". Needs no extra assets or model; it rides the face keypoints the network already produces.

```ts
new EffectsPipeline(stream, { reframe: true })              // auto-follow
new EffectsPipeline(stream, { reframe: { auto: false } })   // solve once, then freeze
```

`auto: true` (default) follows the subject with a deadband — hold, deliberate move, hold. `auto: false` is manual: it frames once and holds until you call `pipeline.reframe()`, which is the mode for a reframe button in your own UI.

Applies to you, not to a virtual background. See [Auto-reframe](https://longpipe.dev/docs/reframe).

#### `preset`

**Type:** `'auto' | 'fast' | 'balanced' | 'quality'` · **Default:** `'auto'`

Model size selection. `'auto'` runs an init-time microbenchmark and picks the largest preset whose per-frame model cost fits the frame budget (~half a 30fps frame) on the user's hardware; while in `'auto'` mode the adaptive controller (see below) can swap up or down at runtime. Explicit choices — `'fast'`, `'balanced'`, `'quality'` — are always respected and never auto-overridden. Pass a `ManualPreset` object to pin a specific model + dtype + resolution combination. See [Presets & autotune](https://longpipe.dev/docs/presets).

#### `weightsBaseUrl`

**Type:** `string` · **Default:** `cdn.longpipe.dev/...`

Where the SDK fetches model weight files. The default points at a public, versioned CDN (`https://cdn.longpipe.dev/models/v/0.0.5/`) — fine for prototyping. Override to self-host: offline use, locked-down corporate networks, or to avoid the public CDN dependency. The SDK fetches files of the form `model_${preset}.bin`. See [Self-hosting weights](https://longpipe.dev/docs/self-hosting).

#### `audio`

**Type:** `'passthrough' | 'drop' | 'denoise' | { denoise: DenoiseOptions }` · **Default:** `'passthrough'`

Controls the output stream's audio. `'passthrough'` forwards the input's audio tracks unmodified — useful for video-call scenarios where audio is part of the same stream. `'drop'` strips audio, useful when you only care about the video (e.g., screen recording, frame export, server-side processing). `'denoise'` runs the input microphone through the real-time speech denoiser — a separate `AudioWorklet` pipeline, independent of the video work — and outputs the cleaned track; pass `{ denoise: { model, postFilterBeta, gruLeak, enabled } }` to configure it. See [Audio denoise](https://longpipe.dev/docs/audio).

#### `enabled`

**Type:** `boolean` · **Default:** `true`

Whether the effect is active. `false` makes the pipeline emit the raw input stream verbatim — no model load, no inference, no compositing. Toggle at runtime via `pipeline.setEnabled(true | false)` — cheap to re-enable since the worker stays alive.

#### `outputResolution`

**Type:** `{ w: number, h: number }` · **Default:** `input track size`

Dimensions of the output canvas. By default matches the input video track's intrinsic size — preserves aspect ratio and avoids pointless rescale. Falls back to 1280×720 if the track hasn't reported its size yet. Set explicitly to force a specific output dimension regardless of input.

#### `adaptive`

**Type:** `boolean` · **Default:** `true`

Whether the SDK auto-adjusts the preset at runtime when conditions change. **Only applies when `preset: 'auto'`** — explicit preset choices are always respected. When enabled, downgrades to a smaller preset if framerate drops below target, and upgrades when `modelMs` shows consistent headroom (WebGPU only — WebGL upgrades are too expensive to swap live).

#### `onReady`

 void">

Fires once after the first composited frame lands. Equivalent to `await pipeline.ready` resolving — pick whichever pattern fits your code. Fires exactly once per pipeline lifetime.

#### `onError`

 void">

Fires for **async / runtime** errors after the constructor returns: weight 404, GPU context loss (`webglcontextlost` or `device.lost`), worker crashes, adaptive preset swap failures, runtime background-resolution errors. **Synchronous construction errors** (no input video track, transport setup throws) propagate out of `new EffectsPipeline(...)` directly — wrap construction in try/catch if you want one handler for both.

## Properties

- **`pipeline.stream: MediaStream`** — the output stream. Available synchronously; emits passthrough video until the effect is live.
- **`pipeline.ready: Promise<void>`** — resolves when the worker emits its first composited frame. Optional to await.

## Methods

- **`pipeline.setBackground(bg: BackgroundInput): Promise<void>`** — swap the background at runtime. Same input shape as the option. No flicker, no re-init.
- **`pipeline.setEnabled(enabled: boolean): void`** — toggle the effect. `false` puts the pipeline in passthrough mode.
- **`pipeline.setTouchup(opts: TouchupOptions | null): Promise<void>`** — enable, update or disable skin smoothing at runtime. `null` disables. First call fetches the landmark assets; later calls are instant, so it's safe on a slider. See [Touch-up](https://longpipe.dev/docs/touchup).
- **`pipeline.setReframe(cfg: boolean | ReframeOptions | null): Promise<void>`** — enable, update or disable auto-reframe. `null` (or `false`) disables. No fetch. See [Auto-reframe](https://longpipe.dev/docs/reframe).
- **`pipeline.reframe(): Promise<void>`** — recompute the frame now and hold it. The manual-mode entry point — wire it to a "reframe" button. A no-op in `auto` mode, where the camera already follows.
- **`pipeline.setDenoise(input: boolean | DenoiseOptions): void`** — toggle or reconfigure audio denoise at runtime. `false` = passthrough; an object updates the DFN params live. Only effective when `audio: 'denoise'` was set at construction. See [Audio denoise](https://longpipe.dev/docs/audio).
- **`pipeline.getAudioStats(): AudioStats | null`** — current denoise telemetry (model, per-hop p50/p95 ms, buffered latency, sample rate). `null` when denoise isn't active.
- **`pipeline.setPreset(preset: PresetName | ManualPreset): void`** — manually swap presets. Disables the adaptive controller.
- **`pipeline.getStats(): Promise<PipelineStats>`** — runtime counters (model time, fps, current preset, etc). Single postMessage round-trip.
- **`pipeline.attachPreview(canvas: HTMLCanvasElement): void`** — attach a second canvas for previewing candidate effects. See [Preview](#preview).
- **`pipeline.setPreview({ background, fps? }): Promise<void>`** — render a candidate effect to the preview canvas. See [Preview](#preview).
- **`pipeline.clearPreview(): void`** — stop previewing.
- **`pipeline.destroy(): void`** — terminates the worker and releases GPU resources. The pipeline is not reusable after destroy.

## Preview

Show a user what a candidate effect would look like — e.g. while they browse a background menu — **without** changing the effect on the outgoing stream. The main output keeps its currently-applied background; a second canvas renders the candidate. The network and matte are computed once and shared between the two, so previewing adds only a second composite (not a second inference).

```ts
// 1. Attach a canvas you own. Called ONCE — control is transferred to the
//    worker, so the element can't be drawn to by the page afterward. The
//    worker sizes the backing to the output resolution; CSS-scale it for display.
pipeline.attachPreview(document.querySelector('#preview'))

// 2. Preview a candidate. `background` is the identical wide surface as the
//    main effect (keyword, URL, ImageBitmap, { color }, { blur }, …). 'none'
//    previews the no-effect (raw) option. fps throttles the preview (default 15;
//    the main output stays the priority).
await pipeline.setPreview({ background: 'https://example.com/beach.jpg', fps: 15 })

// 3. Stop previewing (the canvas freezes on its last frame — hide it in your UI).
pipeline.clearPreview()
```

To **apply** a previewed candidate to the outgoing stream, just call `pipeline.setBackground(sameInput)` — there's no separate "commit" call.

The preview canvas is local display only; it is not a `MediaStream` and is not transmitted. On WebGPU it composites directly to your canvas; on WebGL2 it's presented via a per-frame snapshot of the render canvas (a little more expensive, which is why preview is throttled).

## Error handling

`onError` and `pipeline.ready` rejection both fire for async errors after the constructor returns:

- **Init failures** — weight fetch 404, `normalizeBackground` URL fetch fail, worker init exception.
- **GPU context loss** — WebGL `webglcontextlost` event, WebGPU `device.lost` promise.
- **Worker uncaught failures** — pipe broken, command threw.
- **Adaptive swap failures** — marked `recoverable: true` on the error; pipeline keeps running on the prior preset.
- **Runtime background errors** — e.g., `setBackground()` called with an invalid URL.

`onError` does **not** fire for synchronous constructor errors — those propagate out of `new EffectsPipeline(...)` directly. Wrap in try/catch if you want a single handler for both.

---


<!-- source: https://longpipe.dev/docs/architecture -->

# Architecture

You don't need any of this to use Longpipe. It's here because the design is the reason the SDK is fast, and because "how does enabling three effects not cost three models?" is a fair question.

## One encoder, many heads

Longpipe is a **hydranet**: a single EfficientNet-Lite-derived encoder runs once per frame, and several small decoders read from it.

```
             video frame
                  │
        ┌─────────▼─────────┐
        │   shared encoder  │   ← runs once
        └─────────┬─────────┘
        ┌─────┬───┴───┬──────┐
        ▼     ▼       ▼      ▼
     matte  face    optical  (future
            keypts   flow     heads)
        │     │        │
        ▼     ▼        ▼
   background  touch-up   temporal
    / blur     reframe    stability
```

The consequence is the one that matters in practice: **enabling a second effect doesn't cost a second inference.** Backgrounds use the matte. Auto-reframe uses the face keypoints. Touch-up uses the keypoints plus a separate landmark model on a small face crop. Temporal stability uses the flow head. Every one of those reads from an encoder pass that was already happening.

The exceptions are honest ones. Touch-up runs a second, small network — a 478-point landmark regressor — on a 256×256 face crop, once per face. And audio denoise isn't part of this graph at all (see below).

## Base network + wrapper

Each preset is a composition of two pieces, not one monolithic network:

- The **base network** runs at a low internal resolution (128×80 up to 320×192, depending on preset). This is where the encoder and the heads live — it's the expensive part, so it runs small.
- The **U-Net wrapper** takes the full-resolution frame, strides it down to feed the base, then upsamples the base's output back up while re-injecting high-resolution detail. This is what recovers hair and edge detail that a low-res matte alone would lose.

So a preset's "output resolution" and its "base resolution" are genuinely different numbers, and the gap between them is the wrapper's job. See [Presets & autotune](https://longpipe.dev/docs/presets) for the table.

Three base networks back the five presets — `xs`/`small` share one, `medium`/`large` share another, `xl` has its own — differing in wrapper variant, resolution, and frame cadence.

## Temporal stability

Per-frame matting flickers. A matte that is *consistently* slightly wrong looks far better in video than one that is inconsistently right, so temporal stability is treated as a first-class output rather than a post-hoc smoothing filter.

A small optical-flow head rides the encoder's cached features and predicts backward flow. Each frame, the previous matte is warped along that flow to line up with the current frame, then blended with the fresh prediction through a gate that backs off where the flow is unreliable (fast motion, occlusion seams). Face keypoints get the identical treatment, which is what keeps the touch-up and reframe boxes from jittering.

On presets that skip frames, the same machinery does double duty: a skipped frame doesn't reuse a stale matte, it warps the last one forward to where the subject is now.

## Frame skipping ≠ dropping frames

Smaller presets run the model on every second or third frame. **Compositing still runs on every frame** — the background, blur, or touch-up is applied to every single frame you get out. Only the model re-run is gated, and the matte in between is flow-warped rather than frozen. The output is always at full source framerate.

## Fully-GPU, zero-copy

Every model in the video path is hand-written WGSL (WebGPU) and GLSL (WebGL2) shaders — no general-purpose inference runtime, no ONNX graph interpreter. Frames enter as GPU textures and never leave the GPU: no readback to JavaScript, no CPU↔GPU round trip per frame, no intermediate `ImageData`.

Two backends, one interface. WebGPU is used when available; WebGL2 is a full fallback, not a degraded mode. The model code is identical across both — only the shader implementations differ.

The effects themselves compose as a chain of GPU passes ending in exactly one compositor, which is why touch-up and a virtual background can both be on without either one round-tripping through the other.

## Worker by default

All model and render work happens in a dedicated `Web Worker`. The main thread holds a thin shim that owns capability detection, transport setup, audio, and the public API. Your app's main thread stays free for your app.

Getting frames in and out of that worker is the messiest part of doing this in a browser, because the available APIs differ per browser. Longpipe probes at runtime and picks the best available path on each side — `MediaStreamTrackProcessor`/`MediaStreamTrackGenerator` where supported, a transferred-canvas capture path, or an `ImageBitmap` shuttle as the universal fallback. Chromium, Firefox, and Safari each end up on a different combination. None of it is configurable and none of it is visible to you: you hand in a `MediaStream` and get a `MediaStream` back.

## Adapting to the device

Longpipe ships five presets rather than one model, and picks between them at runtime.

At init, an autotune step microbenchmarks candidate presets on the actual device — using correctly-shaped zero-filled weights, since GPU cost is driven by tensor shapes rather than values — so it can choose *before* downloading any weights. It then fetches only the preset it picked.

At runtime, an adaptive controller watches framerate and model time, and swaps presets when the device's situation changes (another tab starts hammering the GPU, a laptop drops to battery saver). Both are on by default under `preset: 'auto'` and both are fully overridable. See [Presets & autotune](https://longpipe.dev/docs/presets).

## Audio is a separate pipeline

Audio denoise shares nothing with the above. It runs as WebAssembly in an `AudioWorklet` on the audio render thread — no GPU, no worker, no interaction with the video model. It has its own three-model lineup and its own init-time probe to pick between them.

The two pipelines meet only at the end, where the cleaned audio track and the processed video track are assembled into the output `MediaStream`. That means denoise adds no load to the video pipeline, and a heavy video preset doesn't put your audio at risk. See [Audio denoise](https://longpipe.dev/docs/audio).

## Where this is going

The hydranet framing is a bet: the encoder is the asset, and new effects should arrive as new heads on it rather than as new models. Auto-reframe is the cleanest example so far — it shipped needing no new weights and no new inference at all, because the keypoints it needs were already being produced for something else.

AR effects and lighting correction are the next heads. See the [roadmap](https://github.com/sb2702/longpipe#roadmap).

---


<!-- source: https://longpipe.dev/docs/backgrounds -->

# Backgrounds

The `background` option accepts a wide input surface. Same input shape works at construction or runtime via `pipeline.setBackground(...)`.

## Keyword

```js
new EffectsPipeline(stream, { background: 'blur' })
new EffectsPipeline(stream, { background: 'none' })   // passthrough
```

## Image URL

```js
new EffectsPipeline(stream, {
  background: 'https://example.com/beach.jpg',
})
```

The SDK fetches and decodes to an `ImageBitmap` on the main thread before init.

## Pre-resolved bitmap or element

```js
const bitmap = await createImageBitmap(myImg)
new EffectsPipeline(stream, { background: bitmap })

// Or pass an <img> element directly
new EffectsPipeline(stream, { background: document.querySelector('img') })
```

## Structured forms

```js
new EffectsPipeline(stream, { background: { blur: { strength: 0.5 } } })   // strength: 0–1
new EffectsPipeline(stream, { background: { color: '#0a3322' } })
new EffectsPipeline(stream, { background: { image: 'https://example.com/beach.jpg' } })
```

## Swapping at runtime

```js
pipeline.setBackground('blur')
pipeline.setBackground({ color: '#000' })
pipeline.setBackground(otherBitmap)
```

No re-init, no flicker. Internally the compositor swaps its reference texture.

## Previewing a background

The same input surface works for previewing a candidate effect on a second canvas before applying it (e.g. browsing a background menu): `pipeline.setPreview({ background })` takes the identical types. See [Preview](https://longpipe.dev/docs/api#preview).

## Performance note

`'blur'` is meaningfully slower than image / solid color — extra blur pyramid passes. If you're benchmarking or showing perf-sensitive demos, default to image or color. Functional demos where perf isn't the message can use blur freely.

---


<!-- source: https://longpipe.dev/docs/touchup -->

# Touch-up

Skin smoothing, the beauty-filter effect every conferencing app ships. Off by default.

```js
new EffectsPipeline(stream, { touchup: true })
```

That's the whole thing if you don't care how it works. Everything below is for when you do.

## It runs in parallel with backgrounds

Touch-up and the background are **not** alternatives — they compose:

```js
new EffectsPipeline(stream, {
  background: 'blur',
  touchup: { strength: 0.4 },
})
```

Both ride the **same encoder pass**. The face keypoints come from a second head on the network that's already running for the matte, so enabling touch-up doesn't add an inference — it adds the landmark model and the smoothing passes. Nothing about the background changes.

## Options

```js
new EffectsPipeline(stream, {
  touchup: {
    strength: 0.6,
    amount: 8,
    detail: 0.35,
    style: 'freq-sep',
  },
})
```

#### `strength`

**Type:** `number` · **Default:** `0.6`

How much of the smoothed result is blended over the original, `0`–`1`. `0` is a no-op; `1` is the full effect. This is the knob to put in front of users — it's the only one most people want.

#### `amount`

**Type:** `number` · **Default:** `8`

Smoothing radius, in atlas pixels. Higher removes more; too high and skin goes plastic.

#### `detail`

**Type:** `number` · **Default:** `0.35`

How much high-frequency texture — pores, stubble — survives the smoothing, `0`–`1`. This is what keeps a face looking like skin rather than a mannequin. Only applies to `'freq-sep'`; ignored by `'bilateral'`.

#### `style`

**Type:** `'freq-sep' | 'bilateral'` · **Default:** `'freq-sep'`

Which filter does the smoothing.

**`'freq-sep'`** — frequency separation. Splits the face into a low-frequency band (blurred) and a high-frequency band (texture), smooths the first, and adds the second back scaled by `detail`. Softens tone and blotchiness while keeping pores. The default, and the better choice for most video.

**`'bilateral'`** — a single edge-preserving pass. Stronger on blemishes and hard edges, at the cost of a more processed look. `detail` does nothing here.

Both cost about the same. It's a look preference, not a performance trade — which is why it's yours to expose rather than ours to pick.

## Runtime control

```js
await pipeline.setTouchup({ strength: 0.8 })   // enable, or update params live
await pipeline.setTouchup(null)                // disable
```

The first call fetches the landmark assets (see below); later calls reuse them, so parameter changes are instant. Safe to wire straight to a slider.

## Multiple faces

Everyone in frame gets smoothed — up to **four faces**, on the `medium`, `large` and `xl` presets. `small` and `xs` decode keypoints on a coarser grid that can't reliably separate a second face, so they smooth one.

You don't configure this and there's no per-face API. The cost is near-flat in the number of faces: they share a single atlas, so the smoothing passes run once regardless.

## Extra assets

Touch-up needs three files beyond the model weights, fetched from `weightsBaseUrl` on first enable:

| File | What it is |
| --- | --- |
| `model_landmark_mesh.bin` | the 478-point face landmark model (`.f16.bin` used when available) |
| `face_topology.json` | the canonical face mesh |
| `weight_mask.png` | which regions get smoothed, and how much |

If you're [self-hosting weights](https://longpipe.dev/docs/self-hosting), these need to sit alongside `model_*.bin` or touch-up will fail to enable. On the default CDN they're already there.

## Performance

The landmark model runs once per face, every frame. On a single face that's the common case and it's modest; four faces cost four runs. The smoothing itself is a fixed cost.

If you're tight on budget, `strength` is free to lower but the model still runs — to actually reclaim the time, call `setTouchup(null)`.

## Requirements

Touch-up needs face-capable model weights. Every current preset has them, so this only bites if you're self-hosting an older weight set — in which case the SDK logs a warning and leaves the effect off rather than failing your pipeline.

---


<!-- source: https://longpipe.dev/docs/reframe -->

# Auto-reframe

Crop and zoom the output so the subject is better framed — the "centre stage" behaviour from Meet, Zoom and Teams. Off by default.

```js
new EffectsPipeline(stream, { reframe: true })
```

It needs no extra assets and no extra model. It rides the face keypoints the network already produces for the matte, so turning it on costs a crop, not an inference.

## Auto vs manual

Two modes, because apps ship both.

**`auto`** (the default) — the frame follows the subject. It holds still, makes a deliberate move when they've actually gone somewhere, then holds again. It is not a continuous tracker; continuous tracking reads as swimming, because a head moves constantly even when a person doesn't.

```js
new EffectsPipeline(stream, { reframe: true })       // auto, all defaults
```

**`manual`** — solve the frame once, then freeze. Nothing moves until you ask. This is the mode for a "reframe" button in your own UI:

```js
new EffectsPipeline(stream, { reframe: { auto: false } })

// later, from your button:
await pipeline.reframe()
```

It reframes once when enabled, then holds. `pipeline.reframe()` recomputes and freezes again. In `auto` the camera already follows, so the method does nothing there.

## Options

```js
new EffectsPipeline(stream, {
  reframe: {
    zoom: 1.35,
    gravity: 0.5,
    margin: 0.04,
    auto: { deadband: 0.09, ease: 0.07 },
  },
})
```

Anything you leave out takes its default.

#### `zoom`

**Type:** `number` · **Default:** `1.35`

How tight the crop is — `1` is the full frame, `1.35` shows ~74% of it. This is the *requested* zoom, not a guarantee: it relaxes toward `1` as needed to keep the subject framed (see below).

#### `gravity`

**Type:** `number` · **Default:** `0.5`

How hard the subject pulls the crop toward itself, `0`–`1`. At `0` the frame never moves. At `1` the subject is centred exactly. The default deliberately sits in between — the crop moves *toward* you without centring you, which is what the commercial implementations do and what stops the effect feeling like a machine locking on.

#### `margin`

**Type:** `number` · **Default:** `0.04`

Keep-out space around the subject's face, as a fraction of the frame. Larger values give a roomier crop and make the no-op case (below) trigger sooner.

#### `auto`

**Type:** `boolean | { deadband?, ease? }` · **Default:** `true`

`true` (default) tracks; `false` is manual. Pass an object to tune the tracking — the two knobs only exist here because they describe how the frame *moves*, and in manual it doesn't.

**`deadband`** (default `0.09`) — how far the ideal frame must drift before the camera bothers moving. Bigger is lazier and steadier.

**`ease`** (default `0.07`) — how quickly it closes the gap once it starts moving, per frame. Bigger is snappier; too big and it snaps.

## Why it sometimes does nothing

If you sit in the far corner of frame, auto-reframe will do nothing at all. That's correct, and it's the same thing the commercial implementations do.

The crop has to stay inside the frame *and* contain the subject. For someone hard against an edge, containing them needs a crop about the size of the whole frame — which is to say, no reframe. There's no special case for it; it falls out of the two constraints. As you move back toward the middle, the crop tightens again on its own.

## It doesn't move your background

The reframe applies to **you**, not to a virtual background:

```js
new EffectsPipeline(stream, {
  background: 'https://example.com/office.jpg',
  reframe: true,
})
```

The office stays put while you zoom — it's a backdrop behind you, not part of the shot. A **blurred** background is different: that *is* your real room, so it reframes with you. Neither needs configuring.

Touch-up composes with reframe too; all three effects run together off the one encoder pass.

## Which face

Auto-reframe frames **one** subject: the largest face, i.e. the person closest to the camera. The choice is sticky — a second person has to be decisively closer, not marginally, before the camera hands over. Two people sitting side by side won't make it flip back and forth.

This is the opposite of [touch-up](https://longpipe.dev/docs/touchup), which smooths everyone. Framing is a choice about *whose* shot it is; smoothing isn't.

## Runtime control

```js
await pipeline.setReframe(true)                    // enable, all defaults
await pipeline.setReframe({ zoom: 1.6 })           // enable, tighter
await pipeline.setReframe({ auto: false })         // manual mode
await pipeline.reframe()                           // manual: solve now
await pipeline.setReframe(null)                    // disable
```

No fetch, so enabling is instant.

## Requirements

Auto-reframe needs face-capable model weights. Every current preset has them; if you're [self-hosting](https://longpipe.dev/docs/self-hosting) an older weight set the SDK logs a warning and leaves the effect off rather than failing your pipeline.

---


<!-- source: https://longpipe.dev/docs/audio -->

# Audio denoise

Real-time speech denoising — suppress background noise (keyboards, fans, traffic, room hum) from a microphone while keeping the speaker's voice clean.

It runs as a **separate pipeline** from the video effect: an `AudioWorklet` on the audio render thread, in parallel with the GPU video work. The two share nothing but the output `MediaStream`, so denoise adds no load to the video pipeline.

## Hear it

The same ~10-second clip — a noisy microphone recording, then cleaned by each model. Headphones recommended.

**Noisy input**

[audio sample: https://longpipe.dev/audio/noisy.mp3]

**DFN3 — `dfn` (high)**

[audio sample: https://longpipe.dev/audio/dfn.mp3]

**DFN3 int8 — `dfnint8` (mid)**

[audio sample: https://longpipe.dev/audio/dfn_int8.mp3]

**RNNoise — `rnnoise` (low)**

[audio sample: https://longpipe.dev/audio/rnnoise.mp3]

## Enabling it

Pass `audio: 'denoise'`. The input stream's microphone track is denoised in place; `pipeline.stream` carries the cleaned audio track.

```js
const stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true })

const pipeline = new EffectsPipeline(stream, {
  background: 'blur',
  audio: 'denoise',
})

videoEl.srcObject = pipeline.stream   // denoised audio + processed video
```

`pipeline.ready` resolves on the first video frame and does **not** wait on audio — the mic passes through until the denoiser has loaded (a beat after init), then switches over automatically.

## Models

Three models cover the hardware range. The default, `'auto'`, runs a tiny **weight-free probe** at init: it times the real network on the user's device *without* downloading the multi-MB weights, then picks the best fit and downloads only that one.

| `model`     | tier | what it is |
|-------------|------|------------|
| `'dfn'`     | high | DeepFilterNet3, full f32 — best quality |
| `'dfnint8'` | mid  | DeepFilterNet3 with int8 GRUs — smaller download, faster on weak hardware |
| `'rnnoise'` | low  | classic RNNoise — tiny, and the fallback where wasm SIMD isn't available |

The two DeepFilterNet models are Longpipe's hand-written WebAssembly port of [DeepFilterNet3](https://github.com/Rikorose/DeepFilterNet); RNNoise is [Xiph's RNNoise](https://github.com/xiph/rnnoise).

Force a specific model (or tier shorthand) to skip the probe:

```js
new EffectsPipeline(stream, { audio: { denoise: { model: 'dfn' } } })    // explicit model
new EffectsPipeline(stream, { audio: { denoise: { model: 'high' } } })   // tier: high | mid | low
```

## Options

```ts
interface DenoiseOptions {
  model?:          'auto' | 'high' | 'mid' | 'low' | 'rnnoise' | 'dfn' | 'dfnint8'  // default 'auto'
  postFilterBeta?: number    // DFN post-filter — extra suppression of residual noise (default 0.03)
  gruLeak?:        number     // DFN recurrent-state drift bound (default 0.995)
  enabled?:        boolean    // start denoising vs. passthrough (default true)
}
```

`postFilterBeta` and `gruLeak` tune the DeepFilterNet models (`'dfn'` / `'dfnint8'`) only; RNNoise ignores them.

## Runtime control

```js
pipeline.setDenoise(false)                      // passthrough — stop denoising (cheap to re-enable)
pipeline.setDenoise(true)                       // resume
pipeline.setDenoise({ postFilterBeta: 0.05 })   // tune DFN params live
```

Inspect what's running and how it performs:

```js
const s = pipeline.getAudioStats()
// { model: 'dfn', p50Ms: 0.4, p95Ms: 0.6, latencyMs: 12.5, sampleRate: 48000, active: true }
```

`p50Ms` / `p95Ms` are per-hop compute time (the budget is one 2.67 ms audio render quantum); `latencyMs` is the buffering the denoiser adds.

## Sample rate

The models run at 48 kHz. If the browser gives the `AudioContext` a different rate, the SDK resamples in and out automatically — you don't need to do anything. `getAudioStats().sampleRate` reflects the actual context rate.

## Notes

- Denoise needs an **audio track** in the input — request `audio: true` in `getUserMedia`. With no audio track it's a no-op (a recoverable `onError` with `source: 'audio'`).
- The DeepFilterNet models need **wasm SIMD** (every current browser has it); on a rare device without it, `'auto'` falls back to RNNoise.
- This cleans *your* mic for **outbound** audio — in a call you send `pipeline.stream` to the other participant, whose playback is what they hear. If you monitor your own denoised audio locally, route it low-latency and use headphones (playing your live mic back is a feedback loop, the same as any mic monitor).

---


<!-- source: https://longpipe.dev/docs/presets -->

# Presets & autotune

Longpipe ships five model presets covering different speed/quality tradeoffs. The default (`'auto'`) picks one for the user's hardware automatically. All five get frame-to-frame stability from an optical-flow head that rides the same encoder pass.

## The presets

| Preset | Output resolution | Base resolution | Base network | Frame cadence | Named shortcut |
|---|---|---|---|---|---|
| `xs` | 384×240 | 128×80 | Small | 1-in-3 frames | `fast` |
| `small` | 384×224 | 192×112 | Small | 1-in-2 frames | — |
| `medium` | 512×320 | 256×160 | Large | 1-in-2 frames | `balanced` |
| `large` | 640×400 | 256×160 | Large | every frame | — |
| `xl` | 1280×768 | 320×192 | XL | every frame | `quality` |

**Output resolution** is where the matte is produced and composited (the network's refinement input); **base resolution** is what the encoder runs at internally (the wrapper strides the input down to it). **Frame cadence** is how often the model re-runs — skipped frames reuse the previous matte while still compositing every frame, so a `1-in-2` preset costs roughly half the per-source-frame inference of an every-frame one.

`large` is the design reference tier; the others sit around it as cheaper/heavier variants. Weights are f16 on hardware that supports it (most WebGPU + WebGL2), f32 otherwise — the runtime decides, regardless of preset. All tiers are trained on the same data and exported with the same op fusions. See `MODEL_PLAN.md` in the repo for architecture details.

The three named shortcuts — `'fast'`, `'balanced'`, `'quality'` — map to `xs`, `medium`, `xl` respectively.

## Autotune (`preset: 'auto'`)

On init, the worker microbenchmarks the candidate presets on the real device and picks the largest one whose measured per-frame model cost fits the frame budget — roughly half of a 30fps source frame (~16 ms; WebGL is more conservative, since it has no live upgrade path). The benchmark uses zero-filled weights of the correct shapes (GPU cost is shape-driven), so it runs before any weights are fetched.

Autotune runs once at startup and adds a small amount to init time for the sweep.

> **Audio denoise auto-selects separately.** `preset` and autotune here govern the *video* model only. When `audio: 'denoise'` is set, the denoiser runs its own analogous weight-free probe at init — timing the denoise network on the device (no weights downloaded) to pick `dfn` / `dfnint8` / `rnnoise` — independent of the video preset. See [Audio denoise → Models](https://longpipe.dev/docs/audio#models).

## Adaptive (runtime)

When `preset: 'auto'` and `adaptive: true` (the default), Longpipe also adjusts at runtime:

- **Downgrade** if the actual framerate drops below the target (typically because another tab started doing heavy work, the user plugged into a battery-saver power plan, etc.).
- **Upgrade** if `modelMs` shows consistent headroom (WebGPU only — WebGL upgrades are too expensive to be worth doing live).

Disable with `adaptive: false`.

## Pinning a preset

```js
new EffectsPipeline(stream, { preset: 'large' })  // disables autotune & adaptive
new EffectsPipeline(stream, { preset: 'auto', adaptive: false })  // autotune once, then stay
```

---


<!-- source: https://longpipe.dev/docs/model-layer -->

# Running the model without the pipeline

[`EffectsPipeline`](https://longpipe.dev/docs/api) is the supported path for almost everyone: it owns the worker, weight fetching, autotune, per-browser frame transport, and adaptive preset swaps. If you hand it a `MediaStream` and want a `MediaStream` back, use it and skip this page.

This page is for the cases where the pipeline's shape is wrong for you:

- You already have frames — a `<canvas>` render loop, decoded `VideoFrame`s from WebCodecs, still images, a file being processed offline.
- You want the **alpha matte as data**, not a composited canvas.
- You want to own the worker, the frame scheduling, or the transport yourself.
- You're doing something offline — batch-processing images, generating training data, running a research comparison — where a 30fps real-time pipeline is the wrong tool.

Everything here is a supported public API, exported from a separate entry point:

```js
import { WebGPUBackend, TierModel, TIER_CONFIG, loadWeightsFromBinary } from 'longpipe/model'
```

> **Why a separate entry point?** `longpipe/model` includes both backends, and the WebGL2 backend is ~114KB of GLSL. The main `longpipe` entry carries its backends inside an inlined worker, so exporting these from `'longpipe'` would charge every `EffectsPipeline` user for code they never touch. Importing from `'longpipe'` costs exactly what it did before this entry point existed.

## The three pieces

The model layer is deliberately small. There are only three things to understand.

**A backend** wraps WebGPU or WebGL2 and owns a canvas, a dtype, tensor allocation, and the op library. `WebGPUBackend` and `WebGLBackend` implement the identical `Backend` interface — model code never knows which one it's running on.

**`TierModel`** is the matting network: a base network plus a U-Net wrapper. It's constructed with an input tensor and weights, wires its whole compute graph at construction, and pre-allocates every intermediate buffer. `run()` takes no arguments and allocates nothing.

**`TIER_CONFIG`** says *which* base network and wrapper each tier uses, and at what resolutions. The `.bin` file carries only weights — the architecture is code. This is why loading a tier takes a config lookup rather than a model-format parser.

## Minimal example: frame in, alpha matte out

```js
import { WebGPUBackend, TierModel, TIER_CONFIG, loadWeightsFromBinary } from 'longpipe/model'

const TIER = 'large'
const cfg  = TIER_CONFIG[TIER]              // { base, wrapper, canvasRes, baseRes }

// 1. Backend. A canvas is required even if you never present to it —
//    both backends are built around one. Any offscreen canvas will do.
const backend = await WebGPUBackend.create({
  canvas: new OffscreenCanvas(cfg.canvasRes.w, cfg.canvasRes.h),
  dtype:  'f32',                            // or 'f16' — see Precision below
})

// 2. Weights. One fetch, parsed into a nested object of typed-array views.
const buf = await fetch(`https://cdn.longpipe.dev/models/v/0.0.5/model_${TIER}.bin`)
  .then(r => r.arrayBuffer())
const w = loadWeightsFromBinary(buf)        // { base, wrapper, flow?, face? }

// 3. Input op — ingests an ImageBitmap or VideoFrame and bilinearly
//    resamples it to the tier's canvas resolution.
const input = backend.ops.Input(cfg.canvasRes.h, cfg.canvasRes.w)

// 4. The model. Graph is wired here; nothing is allocated during run().
const model = new TierModel(
  backend, input.output, w.base, w.wrapper, cfg.wrapper, cfg.base,
)

// 5. Per frame:
input.setSource(frame)                      // ImageBitmap | VideoFrame
input.run()
model.run()

// 6. The matte. model.output is a 4-channel tensor; alpha is channel 0.
const data = await backend.readback(model.output)
const alpha = data.filter((_, i) => i % 4 === 0)   // one float per pixel, 0–1
```

That's the whole thing. No worker, no `MediaStream`, no transport negotiation.

### Choosing a backend

```js
import { WebGPUBackend, WebGLBackend } from 'longpipe/model'

const backend = await WebGPUBackend.isAvailable()
  ? await WebGPUBackend.create({ canvas, dtype })
  : await WebGLBackend.create({ canvas, dtype })
```

`isAvailable()` does a real adapter request, not just a `navigator.gpu` check — the two disagree often enough to matter.

## Compositing too: `RenderOp`

If you want the finished picture rather than the matte, `RenderOp` orchestrates network → alpha upscale → composite, and presents to the backend's canvas.

```js
import { RenderOp } from 'longpipe/model'

const renderOp = new RenderOp(backend)
renderOp.attachNetwork(model, input, {
  upscaler:   'bilinear',                   // or 'bicubic'
  background: { mode: 'blur', sigma: 8 },   // or { mode: 'solid', color: [r,g,b] }
                                            // or { mode: 'image', image: tensor }
})

// Per frame — RenderOp fans the source out to both the display and network paths:
renderOp.setSource(frame)
renderOp.run()
// backend.canvas now holds the composited frame
```

Note `setSource` goes on the `RenderOp`, not the input op, once a network is attached — it drives the display path (at canvas resolution) and the network path (at the tier's resolution) from the same frame.

Colors in `{ mode: 'solid' }` are `[r, g, b]` in the 0–1 range, not 0–255.

### Splitting model and display work

`RenderOp.run()` is `runModel()` + `runDisplay()`. Calling them separately is how frame skipping works: run the model every Nth frame, composite every frame against whatever alpha is current.

```js
renderOp.setSource(frame)
if (frameIndex % 2 === 0) renderOp.runModel()   // network + alpha upscale
renderOp.runDisplay()                            // display refresh + composite
```

The alpha tensor persists between model runs, so the skipped frames still composite correctly — they just use a matte that's one frame old. This is exactly what the pipeline does for the `xs`, `small` and `medium` presets.

## Resolutions

Two numbers per tier, and they are not the same thing:

- **`canvasRes`** — the network's *input* resolution and the alpha *output* resolution. This is what you size the `Input` op to.
- **`baseRes`** — what the base network runs at internally. The wrapper strides `canvasRes` down to it and upsamples the result back. You never construct anything at this resolution; it's informational.

```js
TIER_CONFIG.large        // { canvasRes: { w: 640, h: 400 }, baseRes: { w: 256, h: 160 }, ... }
```

The `Input` op **stretches** to the target resolution — it does not preserve aspect ratio. If your source aspect doesn't match the tier's, crop before ingesting or the matte will be distorted:

```js
// cover-style centre crop to the tier's aspect, at native resolution
const aspect = cfg.canvasRes.w / cfg.canvasRes.h
const srcAspect = img.width / img.height
const [sw, sh] = srcAspect > aspect
  ? [Math.round(img.height * aspect), img.height]
  : [img.width, Math.round(img.width / aspect)]
const cropped = await createImageBitmap(
  img, Math.round((img.width - sw) / 2), Math.round((img.height - sh) / 2), sw, sh,
)
```

## Precision

`dtype: 'f16'` roughly halves memory traffic and is meaningfully faster on most hardware. On WebGPU it requires the adapter's `shader-f16` feature, and `create()` **throws** if you ask for it without support — check first:

```js
const dtype = await WebGPUBackend.hasF16Support() ? 'f16' : 'f32'
```

Weights come in both forms: `model_large.bin` and `model_large.f16.bin`. They're interchangeable — a backend converts at upload time if the file's precision doesn't match its own — so fetching the matching file is a download-size optimization, not a correctness requirement.

## What you give up

The pipeline layer is not just a convenience wrapper. Driving the model directly means these are now yours to handle:

- **Temporal stability.** The flow head, warping, and the gated stabilizer live in the pipeline's renderer, not in `TierModel`. A bare `TierModel` is a **per-frame** model — run it on video and you'll see the frame-to-frame flicker the pipeline exists partly to remove.
- **Preset selection.** No autotune, no adaptive downgrade. You pick a tier and live with it.
- **The worker.** `TierModel` runs wherever you construct it. On the main thread, that's your frame budget.
- **Transport.** No `MediaStreamTrackProcessor` negotiation, no bitmap shuttle, no per-browser path selection.
- **Face effects.** Touch-up and auto-reframe are renderer-level compositions over the face head, not part of `TierModel`.

If you need any of those, you probably want the pipeline.

## Performance notes

**Build the graph once.** Constructing a `TierModel` compiles shaders and allocates every buffer. Do it at init and reuse it — never per frame. `run()` is allocation-free by design.

**`readback()` is a synchronization point.** It's a genuine async buffer map on WebGPU, but on WebGL2 it's a **blocking** `gl.readPixels`. Reading the matte back every frame will stall a WebGL2 render loop. If you're compositing on the GPU anyway, use `RenderOp` and never read back at all.

**Use `sync()` for timing.** `run()` only enqueues GPU commands, so `performance.now()` around it measures CPU dispatch, not GPU work. `await backend.sync()` is a cheap barrier that doesn't transfer data.

```js
const t0 = performance.now()
model.run()
await backend.sync()
const ms = performance.now() - t0
```

**Clean up with `backend.destroy()`** when you're done — it releases GPU resources.

## A working reference

`sdk/demo/main.ts` in the repo is a complete single-frame version of everything above — backend selection, weight fetch with `.f16.bin` fallback, aspect cropping, `TierModel` construction, `RenderOp` compositing, and timing. It's the file this page was written from.

---


<!-- source: https://longpipe.dev/docs/self-hosting -->

# Self-hosting weights

By default Longpipe fetches weights from `https://cdn.longpipe.dev/models/v/0.0.5/`. To host them yourself — for offline use, locked-down corporate networks, or just to avoid the public CDN dependency — point `weightsBaseUrl` at your own host.

```js
new EffectsPipeline(stream, {
  weightsBaseUrl: 'https://cdn.example.com/longpipe/v0.0.5/',
})
```

## What to host

The SDK fetches files of the form `model_${preset}.bin` (and `.f16.bin` for fp16-capable hardware). The full set is in [`weights/`](https://github.com/sb2702/longpipe/tree/main/weights) on GitHub. Download those and host them at the URL you set.

If you use [touch-up](https://longpipe.dev/docs/touchup), three more files must sit alongside them — they're fetched from the same base URL the first time the effect is enabled:

- `model_landmark_mesh.bin` (and `.f16.bin`)
- `face_topology.json`
- `weight_mask.png`

Miss these and matting still works, but enabling touch-up fails. [Auto-reframe](https://longpipe.dev/docs/reframe) needs nothing extra.

## CORS

Browsers require the weight host to send `Access-Control-Allow-Origin: *` (or your specific origin). The SDK uses `fetch()` with default CORS mode.

## Versioning

The default URL is versioned in the path (`/v/0.0.5/`) so SDK upgrades that change weight shapes can move to a new prefix without breaking older SDKs in the wild. Mirror that pattern when self-hosting if you want to stay in sync with future SDK versions.