@pexip/media-processor 20.3.5 → 21.0.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 21.0.0
+
+### Major Changes
+
+- 3963c2e: Post-processing the segmentation mask
+
+  - Add downsampling post-processing
+  - Refine mask boundaries for more edge snappy
+  - Reduce the gaps between the segmented areas
+  - Add bystander removal
+
+### Minor Changes
+
+- 4cc4701: WebGPU implementation improvements:
+
+  - Port WebGL2 post-processing steps to WebGPU, matching mask/edge quality and
+    performance
+  - Implement compute-based separable joint bilateral filter for mask refinement
+  - Add compute tent blur for edge feathering, using single half-float channel
+    for mask
+  - Introduce downsample/upsample and dual filter blur in compute for optimized
+    background effects
+  - Cache pipelines and textures to reduce per-frame allocation overhead
+  - Use `r16float` mask storage when available for efficiency
+  - Improve blend quality with smoothstep edge softening
+  - Integrate light wrap and H.264 noise stabilization into compositing
+
+### Patch Changes
+
+- 24bc717: Fix added noise YUV->RBG negative value issue
+- 872971f: Mark `excludeBystanders` related params as `@experimental`:
+  `personCenter`, `morphErodeRadiusPx`, `morphPass`, and `morphDilateRadiusPx`
+- 2e895ac: Add add an `@experimental` tag for `excludeBystanders`
+- 4eaf9d7: Use the correct region to apply noise
+- Updated dependencies [1fff975]
+- Updated dependencies [3963c2e]
+- Updated dependencies [762ebd2]
+  - @pexip/utils@17.2.0
+
 ## 20.3.5
 
 ### Patch Changes

package/api-docs/README.mdx

@@ -211,7 +211,7 @@ A library for media analysis using Web APIs.
 | [ProcessorProcessOptions](interfaces/ProcessorProcessOptions.mdx) | - |
 | [ProcessWorkerDebugMessage](interfaces/ProcessWorkerDebugMessage.mdx) | - |
 | [ProcessorEvent](interfaces/ProcessorEvent.mdx) | - |
-| [RendererOptions](interfaces/RendererOptions.mdx) | - |
+| [RendererOptions](interfaces/RendererOptions.mdx) | Options controlling the rendering and effects for person/background segmentation. All values are stable per-frame and can be safely updated in real-time. |
 | [Renderer](interfaces/Renderer.mdx) | - |
 | [RenderEventHandlers](interfaces/RenderEventHandlers.mdx) | - |
 | [SegmentationModelAsset](interfaces/SegmentationModelAsset.mdx) | Segmentation model asset that can be used to load a segmentation model. |
@@ -219,6 +219,9 @@ A library for media analysis using Web APIs.
 | [SegmenterOptions](interfaces/SegmenterOptions.mdx) | - |
 | [SegmentationSmoothingConfig](interfaces/SegmentationSmoothingConfig.mdx) | - |
 | [MPMask](interfaces/MPMask.mdx) | Wrapper for a mask produced by a Segmentation Task. |
+| [Stats](interfaces/Stats.mdx) | - |
+| [Weights](interfaces/Weights.mdx) | - |
+| [SelectionOptions](interfaces/SelectionOptions.mdx) | - |
 | [Benchmark](interfaces/Benchmark.mdx) | - |
 | [Point](interfaces/Point.mdx) | Interface for Point consist of coordinates x and y |
 | [Size](interfaces/Size.mdx) | - |
@@ -245,7 +248,7 @@ A library for media analysis using Web APIs.
 | [BackgroundImage](interfaces/BackgroundImage.mdx) | - |
 | [Segmenter](interfaces/Segmenter.mdx) | - |
 | [Detector](interfaces/Detector.mdx) | - |
-| [SegmentationParams](interfaces/SegmentationParams.mdx) | - |
+| [SegmentationParams](interfaces/SegmentationParams.mdx) | Options controlling the rendering and effects for person/background segmentation. All values are stable per-frame and can be safely updated in real-time. |
 | [VideoProcessor](interfaces/VideoProcessor.mdx) | - |
 
 ## Type Aliases
@@ -268,6 +271,7 @@ A library for media analysis using Web APIs.
 | [ExtractMessageEventType](type-aliases/ExtractMessageEventType.mdx) | - |
 | [IncludeMessageEventDataType](type-aliases/IncludeMessageEventDataType.mdx) | - |
 | [TupleOf](type-aliases/TupleOf.mdx) | From https://github.com/Microsoft/TypeScript/issues/26223#issuecomment-674500430 |
+| [OptionalKeys](type-aliases/OptionalKeys.mdx) | - |
 | [Canvas](type-aliases/Canvas.mdx) | - |
 | [Unsubscribe](type-aliases/Unsubscribe.mdx) | Unsubscribe the subscription |
 | [AudioBufferFloats](type-aliases/AudioBufferFloats.mdx) | Same as [AudioBuffer](https://developer.mozilla.org/en-US/docs/Web/API/AudioBuffer) Or the return from [AnalyserNode.getFloatFrequencyData()](https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode/getFloatFrequencyData) |
@@ -312,12 +316,28 @@ A library for media analysis using Web APIs.
 
 | Variable | Description |
 | ------ | ------ |
-| [PROCESSING\_WIDTH](variables/PROCESSING_WIDTH.mdx) | - |
-| [PROCESSING\_HEIGHT](variables/PROCESSING_HEIGHT.mdx) | - |
-| [FOREGROUND\_THRESHOLD](variables/FOREGROUND_THRESHOLD.mdx) | - |
+| [getCanvasRenderingContext2D](variables/getCanvasRenderingContext2D.mdx) | - |
+| [getImageSize](variables/getImageSize.mdx) | - |
 | [BACKGROUND\_BLUR\_AMOUNT](variables/BACKGROUND_BLUR_AMOUNT.mdx) | - |
+| [BACKGROUND\_THRESHOLD](variables/BACKGROUND_THRESHOLD.mdx) | - |
+| [DOWN\_SAMPLE\_FACTOR](variables/DOWN_SAMPLE_FACTOR.mdx) | - |
 | [EDGE\_BLUR\_AMOUNT](variables/EDGE_BLUR_AMOUNT.mdx) | - |
+| [EXCLUDE\_BYSTANDERS](variables/EXCLUDE_BYSTANDERS.mdx) | - |
+| [FOREGROUND\_THRESHOLD](variables/FOREGROUND_THRESHOLD.mdx) | - |
+| [LIGHT\_WRAP\_BLUR\_AMOUNT](variables/LIGHT_WRAP_BLUR_AMOUNT.mdx) | - |
+| [LIGHT\_WRAP\_EDGE\_BAND](variables/LIGHT_WRAP_EDGE_BAND.mdx) | - |
+| [LIGHT\_WRAP\_INTENSITY](variables/LIGHT_WRAP_INTENSITY.mdx) | - |
+| [LIGHT\_WRAP\_TIGHTNESS](variables/LIGHT_WRAP_TIGHTNESS.mdx) | - |
 | [MASK\_COMBINE\_RATIO](variables/MASK_COMBINE_RATIO.mdx) | - |
+| [MORPH\_DILATE\_RADIUS\_PX](variables/MORPH_DILATE_RADIUS_PX.mdx) | - |
+| [MORPH\_ERODE\_RADIUS\_PX](variables/MORPH_ERODE_RADIUS_PX.mdx) | - |
+| [MORPH\_PASS](variables/MORPH_PASS.mdx) | - |
+| [PERSON\_CENTER](variables/PERSON_CENTER.mdx) | - |
+| [PROCESSING\_HEIGHT](variables/PROCESSING_HEIGHT.mdx) | - |
+| [PROCESSING\_WIDTH](variables/PROCESSING_WIDTH.mdx) | - |
+| [SIGMA\_RANGE](variables/SIGMA_RANGE.mdx) | - |
+| [SIGMA\_SPACE](variables/SIGMA_SPACE.mdx) | - |
+| [STRONG\_EDGE\_BLUR\_AMOUNT](variables/STRONG_EDGE_BLUR_AMOUNT.mdx) | - |
 | [PROCESS\_STATUS](variables/PROCESS_STATUS.mdx) | Process status |
 | [RENDER\_EFFECT](variables/RENDER_EFFECT.mdx) | - |
 | [RENDER\_BACKEND](variables/RENDER_BACKEND.mdx) | - |
@@ -348,6 +368,10 @@ A library for media analysis using Web APIs.
 
 | Function | Description |
 | ------ | ------ |
+| [nearestPowerOfTwo](functions/nearestPowerOfTwo.mdx) | Coerce any positive number to the nearest power of two within [minPow, maxPow] Example: nearestPowerOfTwo(13) => 16; nearestPowerOfTwo(3.2) => 4 |
+| [iou](functions/iou.mdx) | Intersection over Union (IoU), how much two masks overlap as a fraction of either's total. 1.0 = perfect match, 0 = no overlap. Used for stable, robust tracking of the main person between frames, especially with bystander removal and temporal instance switching. |
+| [labelComponents](functions/labelComponents.mdx) | - |
+| [scoreComponent](functions/scoreComponent.mdx) | - |
 | [createAudioContext](functions/createAudioContext.mdx) | A function to create `AudioContext` using constructor or factory function depends on the browser supports |
 | [resumeAudioOnInterruption](functions/resumeAudioOnInterruption.mdx) | Resume the stream whenever interrupted |
 | [resumeAudioOnUnmute](functions/resumeAudioOnUnmute.mdx) | Resume the AudioContext whenever the source track is unmuted |
@@ -366,7 +390,8 @@ A library for media analysis using Web APIs.
 | [createChannelMergerGraphNode](functions/createChannelMergerGraphNode.mdx) | Create a ChannelMergerNode |
 | [createAudioGraph](functions/createAudioGraph.mdx) | Accepts AudioNodeInitConnections to build the audio graph within a signal audio context |
 | [createAudioGraphProxy](functions/createAudioGraphProxy.mdx) | - |
-| [createBenchmark](functions/createBenchmark.mdx) | - |
+| [createBenchmark](functions/createBenchmark.mdx) | Creates a benchmarking utility for measuring frame durations and calculating frames per second (FPS). |
+| [createWindowedStats](functions/createWindowedStats.mdx) | - |
 | [sum](functions/sum.mdx) | Sum an array of numbers |
 | [avg](functions/avg.mdx) | Average an array of numbers |
 | [pow](functions/pow.mdx) | pow function from Math in functional form `number -> number -> number` |
@@ -400,6 +425,8 @@ A library for media analysis using Web APIs.
 | [createSegmenter](functions/createSegmenter.mdx) | - |
 | [isRenderEffects](functions/isRenderEffects.mdx) | - |
 | [createCanvas](functions/createCanvas.mdx) | Create a Canvas element with provided width and height |
+| [setVideoElementSrc](functions/setVideoElementSrc.mdx) | - |
+| [playVideo](functions/playVideo.mdx) | - |
 | [createFrameCallbackRequest](functions/createFrameCallbackRequest.mdx) | Create a callback loop for video frame processing using `requestVideoFrameCallback` under-the-hood when available otherwise our fallback implementation based on `setTimeout`. |
 | [createVideoProcessor](functions/createVideoProcessor.mdx) | - |
 | [createVideoTrackProcessor](functions/createVideoTrackProcessor.mdx) | Video track processor using MediaStreamTrackProcessor API |

package/api-docs/functions/createBenchmark.mdx

@@ -1,14 +1,26 @@
 ```ts
-function createBenchmark(clock, __namedParameters): Benchmark;
+function createBenchmark(clock, options): Benchmark;
 ```
 
+Creates a benchmarking utility for measuring frame durations and calculating frames per second (FPS).
+
 ## Parameters
 
-| Parameter | Type | Default value |
-| ------ | ------ | ------ |
-| `clock` | [`Clock`](../interfaces/Clock.mdx) | `performance` |
-| `__namedParameters` | `BenchmarkOptions` | `{}` |
+| Parameter | Type | Default value | Description |
+| ------ | ------ | ------ | ------ |
+| `clock` | [`Clock`](../interfaces/Clock.mdx) | `performance` | An object with a `now()` method returning the current timestamp (in milliseconds). Defaults to `window.performance`. |
+| `options` | `BenchmarkOptions` | `{}` | Optional configuration options for the benchmark utility. |
 
 ## Returns
 
 [`Benchmark`](../interfaces/Benchmark.mdx)
+
+An object with methods to start/end frame measurements, reset the benchmark, and calculate current FPS.
+
+## Remarks
+
+This function is designed for performance measurement in animation or game loops.
+It records frame start/end times, ignores an initial warmup period, utilizes a circular buffer
+to average recent frame durations, and computes a smoothed FPS value on demand.
+The calculation may only occur if sufficient samples have been gathered and the minimum interval between
+calculations has elapsed.

package/api-docs/functions/createWindowedStats.mdx

@@ -0,0 +1,23 @@
+```ts
+function createWindowedStats(windowSize): object;
+```
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `windowSize` | `number` |
+
+## Returns
+
+`object`
+
+| Name | Type |
+| ------ | ------ |
+| `add()` | (`value`) => `void` |
+| `get mean` | `number` |
+| `get variance` | `number` |
+| `get stddev` | `number` |
+| `get stdError` | `number` |
+| `get count` | `number` |
+| `clear()` | () => `void` |

package/api-docs/functions/iou.mdx

@@ -0,0 +1,19 @@
+```ts
+function iou(a, b): number;
+```
+
+Intersection over Union (IoU), how much two masks overlap as a fraction of either's total.
+1.0 = perfect match, 0 = no overlap.
+Used for stable, robust tracking of the main person between frames,
+especially with bystander removal and temporal instance switching.
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `a` | `Uint8Array` |
+| `b` | `Uint8Array` |
+
+## Returns
+
+`number`

package/api-docs/functions/labelComponents.mdx

@@ -0,0 +1,20 @@
+```ts
+function labelComponents(
+   input, 
+   labels, 
+   width, 
+height): Map<number, Stats>;
+```
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `input` | `Uint8Array` |
+| `labels` | `Int32Array` |
+| `width` | `number` |
+| `height` | `number` |
+
+## Returns
+
+`Map`\<`number`, [`Stats`](../interfaces/Stats.mdx)\>

package/api-docs/functions/nearestPowerOfTwo.mdx

@@ -0,0 +1,21 @@
+```ts
+function nearestPowerOfTwo(
+   n, 
+   minPow?, 
+   maxPow?): number;
+```
+
+Coerce any positive number to the nearest power of two within [minPow, maxPow]
+Example: nearestPowerOfTwo(13) => 16; nearestPowerOfTwo(3.2) => 4
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `n` | `number` |
+| `minPow?` | `number` |
+| `maxPow?` | `number` |
+
+## Returns
+
+`number`

package/api-docs/functions/playVideo.mdx

@@ -0,0 +1,16 @@
+```ts
+function playVideo(video, __namedParameters): Promise<void>;
+```
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `video` | `HTMLVideoElement` |
+| `__namedParameters` | \{ `setTimeout?`: (`handler`, `timeout?`, ...`arguments`) => `number` & (`handler`, `timeout?`, ...`arguments`) => `number`; `clearTimeout?`: (`id`) => `void` & (`id`) => `void`; \} |
+| `__namedParameters.setTimeout?` | (`handler`, `timeout?`, ...`arguments`) => `number` & (`handler`, `timeout?`, ...`arguments`) => `number` |
+| `__namedParameters.clearTimeout?` | (`id`) => `void` & (`id`) => `void` |
+
+## Returns
+
+`Promise`\<`void`\>

package/api-docs/functions/scoreComponent.mdx

@@ -0,0 +1,22 @@
+```ts
+function scoreComponent(
+   stats, 
+   overlap, 
+   weights, 
+   width, 
+   height): number;
+```
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `stats` | [`Stats`](../interfaces/Stats.mdx) |
+| `overlap` | `number` |
+| `weights` | [`SelectionOptions`](../interfaces/SelectionOptions.mdx) |
+| `width` | `number` |
+| `height` | `number` |
+
+## Returns
+
+`number`

package/api-docs/functions/setVideoElementSrc.mdx

@@ -0,0 +1,14 @@
+```ts
+function setVideoElementSrc(video, src): void;
+```
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `video` | `HTMLVideoElement` |
+| `src` | `MediaProvider` |
+
+## Returns
+
+`void`

package/api-docs/interfaces/Benchmark.mdx

@@ -24,6 +24,18 @@ end(): void;
 
 ***
 
+### reset()
+
+```ts
+reset(): void;
+```
+
+#### Returns
+
+`void`
+
+***
+
 ### calculateFps()
 
 ```ts

package/api-docs/interfaces/RendererOptions.mdx

@@ -1,15 +1,32 @@
+Options controlling the rendering and effects for person/background segmentation.
+All values are stable per-frame and can be safely updated in real-time.
+
 ## Extended by
 
 - [`SegmentationParams`](SegmentationParams.mdx)
 
 ## Properties
 
-| Property | Type | Default value | Description |
-| ------ | ------ | ------ | ------ |
-| <a id="backgroundimageurl"></a> `backgroundImageUrl` | `string` | `undefined` | - |
-| <a id="foregroundthreshold"></a> `foregroundThreshold` | `number` | `undefined` | Confident score threshold to be considered as the foreground between 0 and 1 |
-| <a id="backgroundbluramount"></a> `backgroundBlurAmount` | `number` | `undefined` | Between 0 and 10 |
-| <a id="edgebluramount"></a> `edgeBlurAmount` | `number` | `3` | Range in between 0 and 20 |
-| <a id="maskcombineratio"></a> `maskCombineRatio` | `number` | `undefined` | The ratio used for smoothing the mask between 0 and 1 |
-| <a id="effects"></a> `effects` | `"blur"` \| `"none"` \| `"overlay"` | `undefined` | Effects |
-| <a id="backend"></a> `backend` | `"webgl"` \| `"webgpu"` | `undefined` | Backend to render background effects |
+| Property | Type | Description |
+| ------ | ------ | ------ |
+| <a id="backgroundimageurl"></a> `backgroundImageUrl` | `string` | URL or Data URI for the virtual background image (used in "overlay" effect). |
+| <a id="backgroundbluramount"></a> `backgroundBlurAmount` | `number` | Amount of background blur (radius in px): [0,9]. Recommend: 3–6 for portraits. Higher may be slow and over-blurred. **Default** `3` |
+| <a id="edgebluramount"></a> `edgeBlurAmount` | `number` | Edge blur for mask boundary antialiasing (radius in px): [0,9]. Small values (1–5) smooth mask stair-steps; large values soften edges more visibly. **Default** `4` |
+| <a id="effects"></a> `effects` | `"blur"` \| `"none"` \| `"overlay"` | Effects to apply: "none", "blur", or "overlay". "blur" = background blur. "overlay" = replace BG with backgroundImageUrl. |
+| <a id="backend"></a> `backend` | `"webgl"` \| `"webgpu"` | Backend to render background effects |
+| <a id="foregroundthreshold"></a> `foregroundThreshold` | `number` | [0,1] Upper mask confidence: all mask pixels >= this are considered definite foreground. Adjust to make mask edges tighter or more permissive for foreground inclusion. Example: 0.8 ("mask > 0.8 = sure foreground"). Must always be >= backgroundThreshold. **Default** `0.85` |
+| <a id="backgroundthreshold"></a> `backgroundThreshold` | `number` | [0,1] Lower mask confidence: all mask pixels <= this are considered definite background. Adjust to make mask edges tighter or more permissive for background inclusion. Example: 0.3 ("mask < 0.3 = sure background"). **Default** `0.35` |
+| <a id="sigmaspace"></a> `sigmaSpace` | `number` | Bilateral filter: sigma in pixel space for mask edge snapping. Controls the neighborhood/pixel distance—higher is larger window (5–10 typical). **Default** `5` |
+| <a id="sigmarangelo"></a> `sigmaRangeLo` | `number` | Bilateral filter: minimum sigma in color/luma (for mask interiors), [0,1]. Controls how little color difference is needed to cross-mask regions away from edge. Lower = sharper edge preservation in mask interiors. Example: 0.2 **Default** `0.2` |
+| <a id="sigmarangehi"></a> `sigmaRangeHi` | `number` | Bilateral filter: maximum sigma in color/luma (for mask uncertain zones), [0,1]. Controls how much color similarity is required at uncertain/edge mask locations. Higher = more mask smoothing at edges. Example: 0.8 **Default** `0.8` |
+| <a id="maskcombineratio"></a> `maskCombineRatio` | `number` | Ratio for mask smoothing (how much uncertainty enables temporal blend), [0,1]. Higher = more frame-to-frame blending, more stability but more trailing ghosts. Typical: 0.6–0.85. **Default** `0.8` |
+| <a id="excludebystanders"></a> `excludeBystanders` | `boolean` | **`Experimental`** Whether to exclude bystanders/connected people from the output mask. The main person instance (closest to personCenter OR largest blob) is kept in the output mask. All other bystanders/connected people are suppressed (bystander removal). **Default** `false (no bystander removal, all detected people are included in the mask). @experimental This feature is experimental and only works in WebGL backend.` |
+| <a id="personcenter"></a> `personCenter` | \[`number`, `number`\] | **`Experimental`** Person center: normalized (x, y) in [0,1] image coordinates for main subject selection. Used by the CCL/bias filter to select the main person blob. **Default** `[0.5, 0.42] (= center, slightly above vertical midpoint). @experimental This feature is experimental and only works in WebGL backend.` |
+| <a id="morpheroderadiuspx"></a> `morphErodeRadiusPx` | `number` | **`Experimental`** Morphological erosion: radius in pixels [1,12]. Sets kernel size for bridge-breaking. Larger values break thicker bridges but may erode fine details. **Default** `5 @experimental This feature is experimental and only works in WebGL backend.` |
+| <a id="morphpass"></a> `morphPass` | `number` | **`Experimental`** Morphological pass: number of separable passes [1,10]. More passes increase the effective span. **Default** `4 @experimental This feature is experimental and only works in WebGL backend.` |
+| <a id="morphdilateradiuspx"></a> `morphDilateRadiusPx` | `number` | **`Experimental`** Geodesic dilation: radius in pixels [1,12]. Must match erosion for good reconstruction. **Default** `6 @experimental This feature is experimental and only works in WebGL backend.` |
+| <a id="lightwrapintensity"></a> `lightWrapIntensity` | `number` | [0,1] Light wrap amount (halo intensity) at mask edge. Wraps blurred background color just outside the subject edge onto the subject boundary for realism. **Default** `0.8` |
+| <a id="lightwraptightness"></a> `lightWrapTightness` | `number` | [0.5,4.0] Controls power/tightness of the wrap band falloff. Higher = tighter/narrower wrap. **Default** `1.2` |
+| <a id="lightwrapedgeband"></a> `lightWrapEdgeBand` | `number` | Width of the wrap band (feather size, in normalized mask units) between the backgroundThreshold and foregroundThreshold in [0.0, (foregroundThreshold - backgroundThreshold) / 2] Higher = wider soft halo. **Default** `0.25` |
+| <a id="lightwrapbluramount"></a> `lightWrapBlurAmount` | `number` | Blur amount used for background color in the wrap band (units=blur passes). **Default** `1` |
+| <a id="downsamplefactor"></a> `downSampleFactor` | `number` | Downsampling factor for mask/blurring, must be [2,4]. 2 = half resolution, 4 = quarter resolution for faster filtering. Use for performance tuning vs. quality. **Default** `2` |

package/api-docs/interfaces/SegmentationParams.mdx

@@ -1,18 +1,35 @@
+Options controlling the rendering and effects for person/background segmentation.
+All values are stable per-frame and can be safely updated in real-time.
+
 ## Extends
 
 - [`RendererOptions`](RendererOptions.mdx)
 
 ## Properties
 
-| Property | Type | Default value | Description | Inherited from |
-| ------ | ------ | ------ | ------ | ------ |
-| <a id="backgroundimageurl"></a> `backgroundImageUrl` | `string` | `undefined` | - | [`RendererOptions`](RendererOptions.mdx).[`backgroundImageUrl`](RendererOptions.mdx#backgroundimageurl) |
-| <a id="foregroundthreshold"></a> `foregroundThreshold` | `number` | `undefined` | Confident score threshold to be considered as the foreground between 0 and 1 | [`RendererOptions`](RendererOptions.mdx).[`foregroundThreshold`](RendererOptions.mdx#foregroundthreshold) |
-| <a id="backgroundbluramount"></a> `backgroundBlurAmount` | `number` | `undefined` | Between 0 and 10 | [`RendererOptions`](RendererOptions.mdx).[`backgroundBlurAmount`](RendererOptions.mdx#backgroundbluramount) |
-| <a id="edgebluramount"></a> `edgeBlurAmount` | `number` | `3` | Range in between 0 and 20 | [`RendererOptions`](RendererOptions.mdx).[`edgeBlurAmount`](RendererOptions.mdx#edgebluramount) |
-| <a id="maskcombineratio"></a> `maskCombineRatio` | `number` | `undefined` | The ratio used for smoothing the mask between 0 and 1 | [`RendererOptions`](RendererOptions.mdx).[`maskCombineRatio`](RendererOptions.mdx#maskcombineratio) |
-| <a id="effects"></a> `effects` | `"blur"` \| `"none"` \| `"overlay"` | `undefined` | Effects | [`RendererOptions`](RendererOptions.mdx).[`effects`](RendererOptions.mdx#effects) |
-| <a id="backend"></a> `backend` | `"webgl"` \| `"webgpu"` | `undefined` | Backend to render background effects | [`RendererOptions`](RendererOptions.mdx).[`backend`](RendererOptions.mdx#backend) |
-| <a id="segmenter"></a> `segmenter` | [`Segmenter`](Segmenter.mdx) | `undefined` | - | - |
-| <a id="width"></a> `width` | `number` | `undefined` | - | - |
-| <a id="height"></a> `height` | `number` | `undefined` | - | - |
+| Property | Type | Description | Inherited from |
+| ------ | ------ | ------ | ------ |
+| <a id="backgroundimageurl"></a> `backgroundImageUrl` | `string` | URL or Data URI for the virtual background image (used in "overlay" effect). | [`RendererOptions`](RendererOptions.mdx).[`backgroundImageUrl`](RendererOptions.mdx#backgroundimageurl) |
+| <a id="backgroundbluramount"></a> `backgroundBlurAmount` | `number` | Amount of background blur (radius in px): [0,9]. Recommend: 3–6 for portraits. Higher may be slow and over-blurred. **Default** `3` | [`RendererOptions`](RendererOptions.mdx).[`backgroundBlurAmount`](RendererOptions.mdx#backgroundbluramount) |
+| <a id="edgebluramount"></a> `edgeBlurAmount` | `number` | Edge blur for mask boundary antialiasing (radius in px): [0,9]. Small values (1–5) smooth mask stair-steps; large values soften edges more visibly. **Default** `4` | [`RendererOptions`](RendererOptions.mdx).[`edgeBlurAmount`](RendererOptions.mdx#edgebluramount) |
+| <a id="effects"></a> `effects` | `"blur"` \| `"none"` \| `"overlay"` | Effects to apply: "none", "blur", or "overlay". "blur" = background blur. "overlay" = replace BG with backgroundImageUrl. | [`RendererOptions`](RendererOptions.mdx).[`effects`](RendererOptions.mdx#effects) |
+| <a id="backend"></a> `backend` | `"webgl"` \| `"webgpu"` | Backend to render background effects | [`RendererOptions`](RendererOptions.mdx).[`backend`](RendererOptions.mdx#backend) |
+| <a id="foregroundthreshold"></a> `foregroundThreshold` | `number` | [0,1] Upper mask confidence: all mask pixels >= this are considered definite foreground. Adjust to make mask edges tighter or more permissive for foreground inclusion. Example: 0.8 ("mask > 0.8 = sure foreground"). Must always be >= backgroundThreshold. **Default** `0.85` | [`RendererOptions`](RendererOptions.mdx).[`foregroundThreshold`](RendererOptions.mdx#foregroundthreshold) |
+| <a id="backgroundthreshold"></a> `backgroundThreshold` | `number` | [0,1] Lower mask confidence: all mask pixels <= this are considered definite background. Adjust to make mask edges tighter or more permissive for background inclusion. Example: 0.3 ("mask < 0.3 = sure background"). **Default** `0.35` | [`RendererOptions`](RendererOptions.mdx).[`backgroundThreshold`](RendererOptions.mdx#backgroundthreshold) |
+| <a id="sigmaspace"></a> `sigmaSpace` | `number` | Bilateral filter: sigma in pixel space for mask edge snapping. Controls the neighborhood/pixel distance—higher is larger window (5–10 typical). **Default** `5` | [`RendererOptions`](RendererOptions.mdx).[`sigmaSpace`](RendererOptions.mdx#sigmaspace) |
+| <a id="sigmarangelo"></a> `sigmaRangeLo` | `number` | Bilateral filter: minimum sigma in color/luma (for mask interiors), [0,1]. Controls how little color difference is needed to cross-mask regions away from edge. Lower = sharper edge preservation in mask interiors. Example: 0.2 **Default** `0.2` | [`RendererOptions`](RendererOptions.mdx).[`sigmaRangeLo`](RendererOptions.mdx#sigmarangelo) |
+| <a id="sigmarangehi"></a> `sigmaRangeHi` | `number` | Bilateral filter: maximum sigma in color/luma (for mask uncertain zones), [0,1]. Controls how much color similarity is required at uncertain/edge mask locations. Higher = more mask smoothing at edges. Example: 0.8 **Default** `0.8` | [`RendererOptions`](RendererOptions.mdx).[`sigmaRangeHi`](RendererOptions.mdx#sigmarangehi) |
+| <a id="maskcombineratio"></a> `maskCombineRatio` | `number` | Ratio for mask smoothing (how much uncertainty enables temporal blend), [0,1]. Higher = more frame-to-frame blending, more stability but more trailing ghosts. Typical: 0.6–0.85. **Default** `0.8` | [`RendererOptions`](RendererOptions.mdx).[`maskCombineRatio`](RendererOptions.mdx#maskcombineratio) |
+| <a id="excludebystanders"></a> `excludeBystanders` | `boolean` | **`Experimental`** Whether to exclude bystanders/connected people from the output mask. The main person instance (closest to personCenter OR largest blob) is kept in the output mask. All other bystanders/connected people are suppressed (bystander removal). **Default** `false (no bystander removal, all detected people are included in the mask). @experimental This feature is experimental and only works in WebGL backend.` | [`RendererOptions`](RendererOptions.mdx).[`excludeBystanders`](RendererOptions.mdx#excludebystanders) |
+| <a id="personcenter"></a> `personCenter` | \[`number`, `number`\] | **`Experimental`** Person center: normalized (x, y) in [0,1] image coordinates for main subject selection. Used by the CCL/bias filter to select the main person blob. **Default** `[0.5, 0.42] (= center, slightly above vertical midpoint). @experimental This feature is experimental and only works in WebGL backend.` | [`RendererOptions`](RendererOptions.mdx).[`personCenter`](RendererOptions.mdx#personcenter) |
+| <a id="morpheroderadiuspx"></a> `morphErodeRadiusPx` | `number` | **`Experimental`** Morphological erosion: radius in pixels [1,12]. Sets kernel size for bridge-breaking. Larger values break thicker bridges but may erode fine details. **Default** `5 @experimental This feature is experimental and only works in WebGL backend.` | [`RendererOptions`](RendererOptions.mdx).[`morphErodeRadiusPx`](RendererOptions.mdx#morpheroderadiuspx) |
+| <a id="morphpass"></a> `morphPass` | `number` | **`Experimental`** Morphological pass: number of separable passes [1,10]. More passes increase the effective span. **Default** `4 @experimental This feature is experimental and only works in WebGL backend.` | [`RendererOptions`](RendererOptions.mdx).[`morphPass`](RendererOptions.mdx#morphpass) |
+| <a id="morphdilateradiuspx"></a> `morphDilateRadiusPx` | `number` | **`Experimental`** Geodesic dilation: radius in pixels [1,12]. Must match erosion for good reconstruction. **Default** `6 @experimental This feature is experimental and only works in WebGL backend.` | [`RendererOptions`](RendererOptions.mdx).[`morphDilateRadiusPx`](RendererOptions.mdx#morphdilateradiuspx) |
+| <a id="lightwrapintensity"></a> `lightWrapIntensity` | `number` | [0,1] Light wrap amount (halo intensity) at mask edge. Wraps blurred background color just outside the subject edge onto the subject boundary for realism. **Default** `0.8` | [`RendererOptions`](RendererOptions.mdx).[`lightWrapIntensity`](RendererOptions.mdx#lightwrapintensity) |
+| <a id="lightwraptightness"></a> `lightWrapTightness` | `number` | [0.5,4.0] Controls power/tightness of the wrap band falloff. Higher = tighter/narrower wrap. **Default** `1.2` | [`RendererOptions`](RendererOptions.mdx).[`lightWrapTightness`](RendererOptions.mdx#lightwraptightness) |
+| <a id="lightwrapedgeband"></a> `lightWrapEdgeBand` | `number` | Width of the wrap band (feather size, in normalized mask units) between the backgroundThreshold and foregroundThreshold in [0.0, (foregroundThreshold - backgroundThreshold) / 2] Higher = wider soft halo. **Default** `0.25` | [`RendererOptions`](RendererOptions.mdx).[`lightWrapEdgeBand`](RendererOptions.mdx#lightwrapedgeband) |
+| <a id="lightwrapbluramount"></a> `lightWrapBlurAmount` | `number` | Blur amount used for background color in the wrap band (units=blur passes). **Default** `1` | [`RendererOptions`](RendererOptions.mdx).[`lightWrapBlurAmount`](RendererOptions.mdx#lightwrapbluramount) |
+| <a id="downsamplefactor"></a> `downSampleFactor` | `number` | Downsampling factor for mask/blurring, must be [2,4]. 2 = half resolution, 4 = quarter resolution for faster filtering. Use for performance tuning vs. quality. **Default** `2` | [`RendererOptions`](RendererOptions.mdx).[`downSampleFactor`](RendererOptions.mdx#downsamplefactor) |
+| <a id="segmenter"></a> `segmenter` | [`Segmenter`](Segmenter.mdx) | - | - |
+| <a id="width"></a> `width` | `number` | - | - |
+| <a id="height"></a> `height` | `number` | - | - |

package/api-docs/interfaces/SelectionOptions.mdx

@@ -0,0 +1,15 @@
+## Extends
+
+- [`Weights`](Weights.mdx)
+
+## Properties
+
+| Property | Type | Inherited from |
+| ------ | ------ | ------ |
+| <a id="iou"></a> `iou` | `number` | [`Weights`](Weights.mdx).[`iou`](Weights.mdx#iou) |
+| <a id="area"></a> `area` | `number` | [`Weights`](Weights.mdx).[`area`](Weights.mdx#area) |
+| <a id="height"></a> `height` | `number` | [`Weights`](Weights.mdx).[`height`](Weights.mdx#height) |
+| <a id="center"></a> `center` | `number` | [`Weights`](Weights.mdx).[`center`](Weights.mdx#center) |
+| <a id="centerx"></a> `centerX` | `number` | - |
+| <a id="centery"></a> `centerY` | `number` | - |
+| <a id="decay"></a> `decay` | `number` | - |

package/api-docs/interfaces/Stats.mdx

@@ -0,0 +1,11 @@
+## Properties
+
+| Property | Type |
+| ------ | ------ |
+| <a id="sumx"></a> `sumX` | `number` |
+| <a id="sumy"></a> `sumY` | `number` |
+| <a id="count"></a> `count` | `number` |
+| <a id="minx"></a> `minX` | `number` |
+| <a id="maxx"></a> `maxX` | `number` |
+| <a id="miny"></a> `minY` | `number` |
+| <a id="maxy"></a> `maxY` | `number` |

package/api-docs/interfaces/Weights.mdx

@@ -0,0 +1,12 @@
+## Extended by
+
+- [`SelectionOptions`](SelectionOptions.mdx)
+
+## Properties
+
+| Property | Type |
+| ------ | ------ |
+| <a id="iou"></a> `iou` | `number` |
+| <a id="area"></a> `area` | `number` |
+| <a id="height"></a> `height` | `number` |
+| <a id="center"></a> `center` | `number` |

package/api-docs/type-aliases/OptionalKeys.mdx

@@ -0,0 +1,10 @@
+```ts
+type OptionalKeys<T, K> = Omit<T, K> & Partial<Pick<T, K>>;
+```
+
+## Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |
+| `K` *extends* keyof `T` |

package/api-docs/variables/BACKGROUND_THRESHOLD.mdx

@@ -0,0 +1,3 @@
+```ts
+const BACKGROUND_THRESHOLD: 0.35 = 0.35;
+```

package/api-docs/variables/DOWN_SAMPLE_FACTOR.mdx

@@ -0,0 +1,3 @@
+```ts
+const DOWN_SAMPLE_FACTOR: 2 = 2;
+```

package/api-docs/variables/EDGE_BLUR_AMOUNT.mdx

@@ -1,3 +1,3 @@
 ```ts
-const EDGE_BLUR_AMOUNT: 3 = 3;
+const EDGE_BLUR_AMOUNT: 4 = 4;
 ```

package/api-docs/variables/EXCLUDE_BYSTANDERS.mdx

@@ -0,0 +1,3 @@
+```ts
+const EXCLUDE_BYSTANDERS: false = false;
+```

package/api-docs/variables/FOREGROUND_THRESHOLD.mdx

@@ -1,3 +1,3 @@
 ```ts
-const FOREGROUND_THRESHOLD: 0.5 = 0.5;
+const FOREGROUND_THRESHOLD: 0.85 = 0.85;
 ```

package/api-docs/variables/LIGHT_WRAP_BLUR_AMOUNT.mdx

@@ -0,0 +1,3 @@
+```ts
+const LIGHT_WRAP_BLUR_AMOUNT: 1 = 1;
+```

package/api-docs/variables/LIGHT_WRAP_EDGE_BAND.mdx

@@ -0,0 +1,3 @@
+```ts
+const LIGHT_WRAP_EDGE_BAND: 0.25 = 0.25;
+```

package/api-docs/variables/LIGHT_WRAP_INTENSITY.mdx

@@ -0,0 +1,3 @@
+```ts
+const LIGHT_WRAP_INTENSITY: 0.8 = 0.8;
+```

package/api-docs/variables/LIGHT_WRAP_TIGHTNESS.mdx

@@ -0,0 +1,3 @@
+```ts
+const LIGHT_WRAP_TIGHTNESS: 1 = 1;
+```

package/api-docs/variables/MASK_COMBINE_RATIO.mdx

@@ -1,3 +1,3 @@
 ```ts
-const MASK_COMBINE_RATIO: 0.5 = 0.5;
+const MASK_COMBINE_RATIO: 0.8 = 0.8;
 ```

package/api-docs/variables/MORPH_DILATE_RADIUS_PX.mdx

@@ -0,0 +1,3 @@
+```ts
+const MORPH_DILATE_RADIUS_PX: 6 = 6;
+```

package/api-docs/variables/MORPH_ERODE_RADIUS_PX.mdx

@@ -0,0 +1,3 @@
+```ts
+const MORPH_ERODE_RADIUS_PX: 5 = 5;
+```

package/api-docs/variables/MORPH_PASS.mdx

@@ -0,0 +1,3 @@
+```ts
+const MORPH_PASS: 4 = 4;
+```

package/api-docs/variables/PERSON_CENTER.mdx

@@ -0,0 +1,3 @@
+```ts
+const PERSON_CENTER: [number, number];
+```

package/api-docs/variables/SIGMA_RANGE.mdx

@@ -0,0 +1,3 @@
+```ts
+const SIGMA_RANGE: [number, number];
+```

package/api-docs/variables/SIGMA_SPACE.mdx

@@ -0,0 +1,3 @@
+```ts
+const SIGMA_SPACE: 5 = 5;
+```

package/api-docs/variables/STRONG_EDGE_BLUR_AMOUNT.mdx

@@ -0,0 +1,3 @@
+```ts
+const STRONG_EDGE_BLUR_AMOUNT: 2 = 2;
+```

package/api-docs/variables/getCanvasRenderingContext2D.mdx

@@ -0,0 +1,14 @@
+```ts
+const getCanvasRenderingContext2D: (canvas, options?) => OffscreenCanvasRenderingContext2D;
+```
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `canvas` | `OffscreenCanvas` |
+| `options?` | `CanvasRenderingContext2DOptions` |
+
+## Returns
+
+`OffscreenCanvasRenderingContext2D`

package/api-docs/variables/getImageSize.mdx

@@ -0,0 +1,13 @@
+```ts
+const getImageSize: (image) => Size;
+```
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `image` | `CanvasImageSource` |
+
+## Returns
+
+`Size`