@stream-io/video-filters-web 0.8.7 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 This file was generated using [@jscutlery/semver](https://github.com/jscutlery/semver).
 
+## [0.9.0](https://github.com/GetStream/stream-video-js/compare/@stream-io/video-filters-web-0.8.7...@stream-io/video-filters-web-0.9.0) (2026-09-04)
+
+### Features
+
+- **video-filters-web:** apply background filter changes without re-registering the filter ([#2403](https://github.com/GetStream/stream-video-js/issues/2403)) ([4fbb30a](https://github.com/GetStream/stream-video-js/commit/4fbb30a640f87a61d400179b24f844b04f2f3bd5))
+
 ## [0.8.7](https://github.com/GetStream/stream-video-js/compare/@stream-io/video-filters-web-0.8.6...@stream-io/video-filters-web-0.8.7) (2026-08-28)
 
 ### Performance Improvements

package/README.md

@@ -43,10 +43,47 @@ const processor = new VirtualBackground(
 // 4. Start the processor and use the processed track
 const processedTrack = await processor.start();
 
-// 5. Stop the processor
+// 5. Change the effect at any time, without restarting the track
+await processor.updateOptions({
+  backgroundFilter: 'blur',
+  backgroundBlurLevel: 'high',
+});
+
+// 6. Stop the processor
 processor.stop();
 ```
 
+### Updating the effect
+
+`updateOptions` changes the background effect of a running processor. The new
+effect is applied on the next frame - the input track, renderer and segmenter
+are preserved, so there is no interruption and the processed track doesn't
+need to be re-published.
+
+```typescript
+// switch between blur levels
+await processor.updateOptions({
+  backgroundFilter: 'blur',
+  backgroundBlurLevel: 3,
+});
+
+// switch to an image background
+await processor.updateOptions({
+  backgroundFilter: 'image',
+  backgroundImage: 'https://example.com/background.jpg',
+});
+```
+
+Notes:
+
+- `updateOptions` replaces the effect options, so always pass the complete
+  set you want applied.
+- `basePath` and `modelPath` are fixed for the lifetime of the processor;
+  changing the model requires a new instance.
+- When several updates overlap, the last one wins.
+- If the background image fails to load, the promise rejects and the current
+  background keeps rendering.
+
 ## Known limitations
 
 - This library only works in a modern desktop browser that supports WebAssembly SIMD and WebGL.

package/dist/esm/src/VirtualBackground.js

@@ -22,6 +22,28 @@ class VirtualBackground extends BaseVideoProcessor {
         super(track, hooks);
         this.options = options;
     }
+    async updateOptions(options) {
+        const { basePath, modelPath } = this.options;
+        const previous = this.options;
+        const next = { basePath, modelPath, ...options };
+        this.options = next;
+        try {
+            const opts = await this.initializeSegmenterOptions();
+            if (this.options === next) {
+                const previousMedia = this.opts?.backgroundSource?.media;
+                this.opts = opts;
+                if (previousMedia instanceof ImageBitmap &&
+                    previousMedia !== opts.backgroundSource?.media) {
+                    previousMedia.close();
+                }
+            }
+        }
+        catch (error) {
+            if (this.options === next)
+                this.options = previous;
+            throw error;
+        }
+    }
     async initialize() {
         this.webGlRenderer = new WebGLRenderer(this.canvas);
         await this.initializeSegmenter();
@@ -112,6 +134,9 @@ class VirtualBackground extends BaseVideoProcessor {
     async loadBackground(url) {
         if (!url)
             return null;
+        const current = this.opts?.backgroundSource;
+        if (current?.url === url)
+            return current;
         const result = await fetch(url, { signal: this.abortController.signal });
         if (!result.ok) {
             throw new Error(`[virtual-background] Failed to load background image: ${result.status} ${result.statusText}`);

package/dist/esm/src/VirtualBackground.js.map

@@ -1 +1 @@
-{"version":3,"file":"VirtualBackground.js","sources":["../../../../../src/VirtualBackground.ts"],"sourcesContent":["import {\n  BACKGROUND_BLUR_MAP,\n  BackgroundOptions,\n  SegmenterOptions,\n  VideoTrackProcessorHooks,\n} from './types';\nimport { FilesetResolver, ImageSegmenter } from '@mediapipe/tasks-vision';\nimport { WebGLRenderer } from './WebGLRenderer';\nimport { packageName, version } from './version';\nimport { BaseVideoProcessor } from './BaseVideoProcessor';\n\n/**\n * Wraps a video MediaStreamTrack in a real-time processing pipeline.\n * Incoming frames are processed through a transformer and re-emitted\n * on a new MediaStreamVideoTrack for downstream consumption.\n */\nexport class VirtualBackground extends BaseVideoProcessor {\n  private segmenter: ImageSegmenter | null = null;\n  private isSegmenterReady = false;\n  private webGlRenderer!: WebGLRenderer;\n\n  private opts!: SegmenterOptions;\n\n  private latestCategoryMask: WebGLTexture | undefined = undefined;\n  private latestConfidenceMask: WebGLTexture | undefined = undefined;\n  private lastFrameTime = -1;\n\n  constructor(\n    track: MediaStreamVideoTrack,\n    private readonly options: BackgroundOptions = {},\n    hooks: VideoTrackProcessorHooks = {},\n  ) {\n    super(track, hooks);\n  }\n\n  protected async initialize(): Promise<void> {\n    this.webGlRenderer = new WebGLRenderer(this.canvas);\n\n    await this.initializeSegmenter();\n  }\n\n  private async initializeSegmenter() {\n    try {\n      this.opts = await this.initializeSegmenterOptions();\n\n      const basePath =\n        this.options.basePath ||\n        `https://unpkg.com/${packageName}@${version}/mediapipe`;\n\n      const model =\n        this.options.modelPath ||\n        `${basePath}/models/selfie_segmenter_landscape.tflite`;\n\n      const fileset = await FilesetResolver.forVisionTasks(`${basePath}/wasm`);\n\n      this.segmenter = await ImageSegmenter.createFromOptions(fileset, {\n        baseOptions: { modelAssetPath: model, delegate: 'GPU' },\n        runningMode: 'VIDEO',\n        outputCategoryMask: true,\n        outputConfidenceMasks: true,\n        canvas: this.canvas,\n      });\n\n      this.isSegmenterReady = true;\n    } catch (error) {\n      this.isSegmenterReady = false;\n      this.hooks.onError?.(error);\n      throw error;\n    }\n  }\n\n  protected async transform(frame: VideoFrame): Promise<VideoFrame> {\n    const currentTime = frame.timestamp;\n    const hasNewFrame = currentTime - this.lastFrameTime > 1_000;\n    this.lastFrameTime = currentTime;\n\n    if (hasNewFrame && this.isSegmenterReady && this.segmenter) {\n      const start = performance.now();\n\n      await this.runSegmentation(frame);\n\n      this.webGlRenderer.render(\n        frame,\n        this.opts,\n        this.latestCategoryMask,\n        this.latestConfidenceMask,\n      );\n\n      this.updateStats(performance.now() - start);\n    }\n\n    return new VideoFrame(this.canvas, { timestamp: frame.timestamp });\n  }\n\n  private async runSegmentation(frame: VideoFrame): Promise<void> {\n    if (!this.segmenter) return;\n\n    return new Promise<void>((resolve) => {\n      const timestamp = Math.floor(performance.now());\n      this.segmenter!.segmentForVideo(frame, timestamp, (result) => {\n        try {\n          this.latestCategoryMask = result.categoryMask?.getAsWebGLTexture();\n          this.latestConfidenceMask =\n            result.confidenceMasks?.[0]?.getAsWebGLTexture();\n        } catch (err) {\n          console.error('[virtual-background] segmentation error:', err);\n          this.hooks.onError?.(err);\n        } finally {\n          result.close();\n          resolve();\n        }\n      });\n    });\n  }\n\n  private async initializeSegmenterOptions(): Promise<SegmenterOptions> {\n    const isSelfieMode = this.options.modelPath\n      ? this.options.modelPath.includes('selfie_segmenter')\n      : true;\n\n    if (this.options.backgroundFilter === 'image') {\n      const source = await this.loadBackground(this.options.backgroundImage);\n      return {\n        backgroundSource: source,\n        bgBlur: 0,\n        bgBlurRadius: 0,\n        isSelfieMode,\n        segmentationOptions: this.options.segmentationOptions,\n      };\n    }\n\n    const blurLevel = this.options.backgroundBlurLevel;\n    const strength =\n      typeof blurLevel === 'string'\n        ? BACKGROUND_BLUR_MAP[blurLevel]\n        : Math.round(blurLevel ?? 5);\n\n    return {\n      backgroundSource: undefined,\n      bgBlur: Math.min(strength * 1.5, 20),\n      bgBlurRadius: Math.min(strength, 10),\n      isSelfieMode,\n      segmentationOptions: this.options.segmentationOptions,\n    };\n  }\n\n  private async loadBackground(url?: string) {\n    if (!url) return null;\n    const result = await fetch(url, { signal: this.abortController.signal });\n    if (!result.ok) {\n      throw new Error(\n        `[virtual-background] Failed to load background image: ${result.status} ${result.statusText}`,\n      );\n    }\n\n    return {\n      type: 'image',\n      media: await createImageBitmap(await result.blob()),\n      url,\n    };\n  }\n\n  protected onFlush(): void {\n    this.destroySegmenter();\n  }\n\n  protected onStop(): void {\n    this.webGlRenderer?.close();\n    this.destroySegmenter();\n  }\n\n  private destroySegmenter() {\n    this.segmenter?.close();\n    this.segmenter = null;\n    this.isSegmenterReady = false;\n  }\n\n  protected get processorName() {\n    return 'background-processor';\n  }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"VirtualBackground.js","sources":["../../../../../src/VirtualBackground.ts"],"sourcesContent":["import {\n  BACKGROUND_BLUR_MAP,\n  BackgroundEffectOptions,\n  BackgroundOptions,\n  SegmenterOptions,\n  VideoTrackProcessorHooks,\n} from './types';\nimport { FilesetResolver, ImageSegmenter } from '@mediapipe/tasks-vision';\nimport { WebGLRenderer } from './WebGLRenderer';\nimport { packageName, version } from './version';\nimport { BaseVideoProcessor } from './BaseVideoProcessor';\n\n/**\n * Wraps a video MediaStreamTrack in a real-time processing pipeline.\n * Incoming frames are processed through a transformer and re-emitted\n * on a new MediaStreamVideoTrack for downstream consumption.\n */\nexport class VirtualBackground extends BaseVideoProcessor {\n  private segmenter: ImageSegmenter | null = null;\n  private isSegmenterReady = false;\n  private webGlRenderer!: WebGLRenderer;\n\n  private opts!: SegmenterOptions;\n\n  private latestCategoryMask: WebGLTexture | undefined = undefined;\n  private latestConfidenceMask: WebGLTexture | undefined = undefined;\n  private lastFrameTime = -1;\n\n  constructor(\n    track: MediaStreamVideoTrack,\n    private options: BackgroundOptions = {},\n    hooks: VideoTrackProcessorHooks = {},\n  ) {\n    super(track, hooks);\n  }\n\n  async updateOptions(options: BackgroundEffectOptions): Promise<void> {\n    const { basePath, modelPath } = this.options;\n    const previous = this.options;\n    const next = { basePath, modelPath, ...options };\n    this.options = next;\n    try {\n      const opts = await this.initializeSegmenterOptions();\n      if (this.options === next) {\n        const previousMedia = this.opts?.backgroundSource?.media;\n        this.opts = opts;\n        if (\n          previousMedia instanceof ImageBitmap &&\n          previousMedia !== opts.backgroundSource?.media\n        ) {\n          previousMedia.close();\n        }\n      }\n    } catch (error) {\n      if (this.options === next) this.options = previous;\n      throw error;\n    }\n  }\n\n  protected async initialize(): Promise<void> {\n    this.webGlRenderer = new WebGLRenderer(this.canvas);\n\n    await this.initializeSegmenter();\n  }\n\n  private async initializeSegmenter() {\n    try {\n      this.opts = await this.initializeSegmenterOptions();\n\n      const basePath =\n        this.options.basePath ||\n        `https://unpkg.com/${packageName}@${version}/mediapipe`;\n\n      const model =\n        this.options.modelPath ||\n        `${basePath}/models/selfie_segmenter_landscape.tflite`;\n\n      const fileset = await FilesetResolver.forVisionTasks(`${basePath}/wasm`);\n\n      this.segmenter = await ImageSegmenter.createFromOptions(fileset, {\n        baseOptions: { modelAssetPath: model, delegate: 'GPU' },\n        runningMode: 'VIDEO',\n        outputCategoryMask: true,\n        outputConfidenceMasks: true,\n        canvas: this.canvas,\n      });\n\n      this.isSegmenterReady = true;\n    } catch (error) {\n      this.isSegmenterReady = false;\n      this.hooks.onError?.(error);\n      throw error;\n    }\n  }\n\n  protected async transform(frame: VideoFrame): Promise<VideoFrame> {\n    const currentTime = frame.timestamp;\n    const hasNewFrame = currentTime - this.lastFrameTime > 1_000;\n    this.lastFrameTime = currentTime;\n\n    if (hasNewFrame && this.isSegmenterReady && this.segmenter) {\n      const start = performance.now();\n\n      await this.runSegmentation(frame);\n\n      this.webGlRenderer.render(\n        frame,\n        this.opts,\n        this.latestCategoryMask,\n        this.latestConfidenceMask,\n      );\n\n      this.updateStats(performance.now() - start);\n    }\n\n    return new VideoFrame(this.canvas, { timestamp: frame.timestamp });\n  }\n\n  private async runSegmentation(frame: VideoFrame): Promise<void> {\n    if (!this.segmenter) return;\n\n    return new Promise<void>((resolve) => {\n      const timestamp = Math.floor(performance.now());\n      this.segmenter!.segmentForVideo(frame, timestamp, (result) => {\n        try {\n          this.latestCategoryMask = result.categoryMask?.getAsWebGLTexture();\n          this.latestConfidenceMask =\n            result.confidenceMasks?.[0]?.getAsWebGLTexture();\n        } catch (err) {\n          console.error('[virtual-background] segmentation error:', err);\n          this.hooks.onError?.(err);\n        } finally {\n          result.close();\n          resolve();\n        }\n      });\n    });\n  }\n\n  private async initializeSegmenterOptions(): Promise<SegmenterOptions> {\n    const isSelfieMode = this.options.modelPath\n      ? this.options.modelPath.includes('selfie_segmenter')\n      : true;\n\n    if (this.options.backgroundFilter === 'image') {\n      const source = await this.loadBackground(this.options.backgroundImage);\n      return {\n        backgroundSource: source,\n        bgBlur: 0,\n        bgBlurRadius: 0,\n        isSelfieMode,\n        segmentationOptions: this.options.segmentationOptions,\n      };\n    }\n\n    const blurLevel = this.options.backgroundBlurLevel;\n    const strength =\n      typeof blurLevel === 'string'\n        ? BACKGROUND_BLUR_MAP[blurLevel]\n        : Math.round(blurLevel ?? 5);\n\n    return {\n      backgroundSource: undefined,\n      bgBlur: Math.min(strength * 1.5, 20),\n      bgBlurRadius: Math.min(strength, 10),\n      isSelfieMode,\n      segmentationOptions: this.options.segmentationOptions,\n    };\n  }\n\n  private async loadBackground(url?: string) {\n    if (!url) return null;\n\n    const current = this.opts?.backgroundSource;\n    if (current?.url === url) return current;\n\n    const result = await fetch(url, { signal: this.abortController.signal });\n    if (!result.ok) {\n      throw new Error(\n        `[virtual-background] Failed to load background image: ${result.status} ${result.statusText}`,\n      );\n    }\n\n    return {\n      type: 'image',\n      media: await createImageBitmap(await result.blob()),\n      url,\n    };\n  }\n\n  protected onFlush(): void {\n    this.destroySegmenter();\n  }\n\n  protected onStop(): void {\n    this.webGlRenderer?.close();\n    this.destroySegmenter();\n  }\n\n  private destroySegmenter() {\n    this.segmenter?.close();\n    this.segmenter = null;\n    this.isSegmenterReady = false;\n  }\n\n  protected get processorName() {\n    return 'background-processor';\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/src/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sources":["../../../../../src/types.ts"],"sourcesContent":["export type BackgroundSource = {\n  type: string;\n  media?: ImageBitmap | ReadableStream;\n  url: string;\n  video?: HTMLVideoElement;\n  track?: MediaStreamTrack;\n};\nexport type BackgroundFilter = 'blur' | 'image';\nexport type BackgroundBlurLevel = 'low' | 'medium' | 'high' | number;\n\n/**\n * Options for controlling the segmentation mask smoothing.\n * These values are passed to the WebGL shader that blends\n * consecutive segmentation masks over time.\n */\nexport interface SegmentationOptions {\n  /**\n   * Controls how fast the mask adapts to new segmentation results.\n   * Higher values make the mask react faster but may cause flickering.\n   * Lower values produce smoother transitions but increase latency.\n   * Value should be between 0 and 1.\n   * @default 0.8\n   */\n  smoothingFactor?: number;\n\n  /**\n   * Lower edge of the smoothstep function applied to the confidence mask.\n   * Confidence values below this are mapped to 0 (background).\n   * Value should be between 0 and 1, and less than smoothstepMax.\n   * @default 0.6\n   */\n  smoothstepMin?: number;\n\n  /**\n   * Upper edge of the smoothstep function applied to the confidence mask.\n   * Confidence values above this are mapped to 1 (foreground).\n   * Value should be between 0 and 1, and greater than smoothstepMin.\n   * @default 0.9\n   */\n  smoothstepMax?: number;\n}\n\nexport interface SegmenterOptions {\n  backgroundSource?: BackgroundSource | null;\n  bgBlur: number;\n  bgBlurRadius: number;\n  isSelfieMode: boolean;\n  segmentationOptions?: SegmentationOptions;\n}\n/**\n * Static configuration for the processor, defining which background\n * effect should be applied and how it should behave.\n */\nexport interface BackgroundOptions {\n  basePath?: string;\n  modelPath?: string;\n  backgroundFilter?: BackgroundFilter;\n  backgroundBlurLevel?: BackgroundBlurLevel;\n  backgroundImage?: string | undefined;\n  segmentationOptions?: SegmentationOptions;\n}\n\n/**\n * Performance statistics for video processing.\n */\nexport interface PerformanceStats {\n  delay: number;\n  fps: number;\n  timestamp: number;\n}\n\n/**\n * Runtime hooks for handling lifecycle or error events.\n */\nexport interface VideoTrackProcessorHooks {\n  onError?: (error: unknown) => void;\n  onStats?: (stats: PerformanceStats) => void;\n}\n\n/**\n * Maps blur level to blur strength values.\n */\nexport const BACKGROUND_BLUR_MAP: Record<'low' | 'medium' | 'high', number> = {\n  low: 3,\n  medium: 5,\n  high: 7,\n};\n"],"names":[],"mappings":"AA+EA;;AAEG;AACI,MAAM,mBAAmB,GAA8C;AAC5E,IAAA,GAAG,EAAE,CAAC;AACN,IAAA,MAAM,EAAE,CAAC;AACT,IAAA,IAAI,EAAE,CAAC;;;;;"}
+{"version":3,"file":"types.js","sources":["../../../../../src/types.ts"],"sourcesContent":["export type BackgroundSource = {\n  type: string;\n  media?: ImageBitmap | ReadableStream;\n  url: string;\n  video?: HTMLVideoElement;\n  track?: MediaStreamTrack;\n};\nexport type BackgroundFilter = 'blur' | 'image';\nexport type BackgroundBlurLevel = 'low' | 'medium' | 'high' | number;\n\n/**\n * Options for controlling the segmentation mask smoothing.\n * These values are passed to the WebGL shader that blends\n * consecutive segmentation masks over time.\n */\nexport interface SegmentationOptions {\n  /**\n   * Controls how fast the mask adapts to new segmentation results.\n   * Higher values make the mask react faster but may cause flickering.\n   * Lower values produce smoother transitions but increase latency.\n   * Value should be between 0 and 1.\n   * @default 0.8\n   */\n  smoothingFactor?: number;\n\n  /**\n   * Lower edge of the smoothstep function applied to the confidence mask.\n   * Confidence values below this are mapped to 0 (background).\n   * Value should be between 0 and 1, and less than smoothstepMax.\n   * @default 0.6\n   */\n  smoothstepMin?: number;\n\n  /**\n   * Upper edge of the smoothstep function applied to the confidence mask.\n   * Confidence values above this are mapped to 1 (foreground).\n   * Value should be between 0 and 1, and greater than smoothstepMin.\n   * @default 0.9\n   */\n  smoothstepMax?: number;\n}\n\nexport interface SegmenterOptions {\n  backgroundSource?: BackgroundSource | null;\n  bgBlur: number;\n  bgBlurRadius: number;\n  isSelfieMode: boolean;\n  segmentationOptions?: SegmentationOptions;\n}\nexport interface BackgroundEffectOptions {\n  backgroundFilter?: BackgroundFilter;\n  backgroundBlurLevel?: BackgroundBlurLevel;\n  backgroundImage?: string | undefined;\n  segmentationOptions?: SegmentationOptions;\n}\n\n/**\n * Static configuration for the processor, defining which background\n * effect should be applied and how it should behave.\n */\nexport interface BackgroundOptions extends BackgroundEffectOptions {\n  basePath?: string;\n  modelPath?: string;\n}\n\n/**\n * Performance statistics for video processing.\n */\nexport interface PerformanceStats {\n  delay: number;\n  fps: number;\n  timestamp: number;\n}\n\n/**\n * Runtime hooks for handling lifecycle or error events.\n */\nexport interface VideoTrackProcessorHooks {\n  onError?: (error: unknown) => void;\n  onStats?: (stats: PerformanceStats) => void;\n}\n\n/**\n * Maps blur level to blur strength values.\n */\nexport const BACKGROUND_BLUR_MAP: Record<'low' | 'medium' | 'high', number> = {\n  low: 3,\n  medium: 5,\n  high: 7,\n};\n"],"names":[],"mappings":"AAkFA;;AAEG;AACI,MAAM,mBAAmB,GAA8C;AAC5E,IAAA,GAAG,EAAE,CAAC;AACN,IAAA,MAAM,EAAE,CAAC;AACT,IAAA,IAAI,EAAE,CAAC;;;;;"}

package/dist/esm/src/version.js

@@ -1,4 +1,4 @@
-const version = "0.8.7";
+const version = "0.9.0";
 const packageName = "@stream-io/video-filters-web";
 
 export { packageName, version };

package/dist/index.cjs.js

@@ -1561,7 +1561,7 @@ const createTFLiteSIMDModule = (__Module) => {
   return __Module.ready;
 };
 
-const version = "0.8.7";
+const version = "0.9.0";
 const packageName = "@stream-io/video-filters-web";
 
 // @ts-expect-error - module is not declared
@@ -2593,6 +2593,28 @@ class VirtualBackground extends BaseVideoProcessor {
         super(track, hooks);
         this.options = options;
     }
+    async updateOptions(options) {
+        const { basePath, modelPath } = this.options;
+        const previous = this.options;
+        const next = { basePath, modelPath, ...options };
+        this.options = next;
+        try {
+            const opts = await this.initializeSegmenterOptions();
+            if (this.options === next) {
+                const previousMedia = this.opts?.backgroundSource?.media;
+                this.opts = opts;
+                if (previousMedia instanceof ImageBitmap &&
+                    previousMedia !== opts.backgroundSource?.media) {
+                    previousMedia.close();
+                }
+            }
+        }
+        catch (error) {
+            if (this.options === next)
+                this.options = previous;
+            throw error;
+        }
+    }
     async initialize() {
         this.webGlRenderer = new WebGLRenderer(this.canvas);
         await this.initializeSegmenter();
@@ -2683,6 +2705,9 @@ class VirtualBackground extends BaseVideoProcessor {
     async loadBackground(url) {
         if (!url)
             return null;
+        const current = this.opts?.backgroundSource;
+        if (current?.url === url)
+            return current;
         const result = await fetch(url, { signal: this.abortController.signal });
         if (!result.ok) {
             throw new Error(`[virtual-background] Failed to load background image: ${result.status} ${result.statusText}`);