From 9f77416ae3d7efd9390d3678c9d030099e4b765b Mon Sep 17 00:00:00 2001
From: Ryan Gaus <rsg1egoman@gmail.com>
Date: Fri, 10 Oct 2025 16:19:44 -0400
Subject: [PATCH 01/19] fix: don't reset isFirstFrame on background transformer
 destroy

This was being set as part of
https://github.com/livekit/track-processors-js/pull/96 to try to avoid a
longer gray flash, but inadvertently this being reset on destroy meant
that if a track processor was reused with multiple cycles of
init/destroy, it would get preserved even though all the mediapipe setup
logic that was happening during the gray flash wouldn't get rerun.
---
 src/transformers/BackgroundTransformer.ts | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/transformers/BackgroundTransformer.ts b/src/transformers/BackgroundTransformer.ts
index 313cc19..b36b5c5 100644
--- a/src/transformers/BackgroundTransformer.ts
+++ b/src/transformers/BackgroundTransformer.ts
@@ -94,7 +94,6 @@ export default class BackgroundProcessor extends VideoTransformer<BackgroundOpti
     await super.destroy();
     await this.imageSegmenter?.close();
     this.backgroundImageAndPath = null;
-    this.isFirstFrame = true;
   }
 
   async loadAndSetBackground(path: string) {

From c52bff6a7084d280540839cfddbbddd88d83fa59 Mon Sep 17 00:00:00 2001
From: Ryan Gaus <rsg1egoman@gmail.com>
Date: Mon, 13 Oct 2025 10:04:05 -0400
Subject: [PATCH 02/19] feat: ensure that track processor enabled button is
 always disabled when disconnecting

---
 example/sample.ts | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/example/sample.ts b/example/sample.ts
index 86ad3a3..8a1e028 100644
--- a/example/sample.ts
+++ b/example/sample.ts
@@ -716,11 +716,12 @@ function updateButtonsForPublishState() {
 }
 
 function updateTrackProcessorModeButtons() {
+  const toggleTrackProcessorButtonEnabled = currentRoom?.state === ConnectionState.Connected;
   if (state.isBackgroundProcessorEnabled) {
-    setButtonState('toggle-track-processor', 'Remove Track Processor', false, false);
+    setButtonState('toggle-track-processor', 'Remove Track Processor', false, !toggleTrackProcessorButtonEnabled);
     $('track-processor-modes').style.display = 'block';
   } else {
-    setButtonState('toggle-track-processor', 'Insert Track Processor', false, false);
+    setButtonState('toggle-track-processor', 'Insert Track Processor', false, !toggleTrackProcessorButtonEnabled);
     $('track-processor-modes').style.display = 'none';
   }
 

From 38bba10e83d5ad2bab3e2ce40d31ddb620881897 Mon Sep 17 00:00:00 2001
From: Ryan Gaus <rsg1egoman@gmail.com>
Date: Mon, 13 Oct 2025 10:05:16 -0400
Subject: [PATCH 03/19] feat: add ability to change initial track mode in demo

---
 example/index.html | 13 +++++++++++--
 example/sample.ts  |  9 ++++++---
 2 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/example/index.html b/example/index.html
index 36718f3..c9278de 100644
--- a/example/index.html
+++ b/example/index.html
@@ -96,16 +96,25 @@ <h2>LiveKit track processor sample</h2>
               </button>
 
               <div class="card mt-1 mb-1 mx-n2 p-2">
-                <div>
+                <div class="d-flex align-items-center justify-content-between">
                   <button
                     id="toggle-track-processor"
-                    class="btn btn-secondary"
+                    class="btn btn-secondary mr-2"
                     disabled
                     type="button"
                     onclick="appActions.toggleTrackProcessorEnabled()"
                   >
                     Insert Track Processor
                   </button>
+
+                  <div id="initial-mode-wrapper" style="display: none;">
+                    <span class="text-secondary">Initial mode:</span>
+                    <select class="custom-select" id="initial-mode-select" style="width: 200px;">
+                      <option value="disabled">Disabled</option>
+                      <option value="background-blur">Blur</option>
+                      <option value="virtual-background">Virtual Background</option>
+                    </select>
+                  </div>
                 </div>
 
                 <div id="track-processor-modes" style="display: none;">
diff --git a/example/sample.ts b/example/sample.ts
index 8a1e028..a8a206f 100644
--- a/example/sample.ts
+++ b/example/sample.ts
@@ -254,10 +254,11 @@ const appActions = {
       if (state.isBackgroundProcessorEnabled) {
         await camTrack.stopProcessor();
         state.isBackgroundProcessorEnabled = false;
+        $("initial-mode-wrapper").style.display = 'block';
       } else {
-        await state.backgroundProcessor.switchTo({ mode: 'disabled' });
-        state.isBackgroundProcessorEnabled = true;
-        await camTrack.setProcessor(state.backgroundProcessor);
+        $("initial-mode-wrapper").style.display = 'none';
+        const initialMode = $<HTMLSelectElement>("initial-mode-select").value as BackgroundProcessorOptions['mode'];
+        appActions.switchBackgroundMode(initialMode ?? 'disabled');
       }
     } catch (e: any) {
       appendLog(`ERROR: ${e.message}`);
@@ -655,6 +656,8 @@ function setButtonsForState(connected: boolean) {
 
   toRemove.forEach((id) => $(id)?.removeAttribute('disabled'));
   toAdd.forEach((id) => $(id)?.setAttribute('disabled', 'true'));
+
+  $("initial-mode-wrapper").style.display = connected ? 'block' : 'none';
 }
 
 const elementMapping: { [k: string]: MediaDeviceKind } = {

From 0759f27f22c07d42a6687fb866219bf47cd020c5 Mon Sep 17 00:00:00 2001
From: Ryan Gaus <rsg1egoman@gmail.com>
Date: Mon, 13 Oct 2025 10:08:42 -0400
Subject: [PATCH 04/19] feat: add special error case handling for
 `InvalidStateError` in ProcessorWrapper pipeline

This always happens at the end of processing a stream
---
 src/ProcessorWrapper.ts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/ProcessorWrapper.ts b/src/ProcessorWrapper.ts
index 76a01ca..656c9a8 100644
--- a/src/ProcessorWrapper.ts
+++ b/src/ProcessorWrapper.ts
@@ -185,6 +185,8 @@ export default class ProcessorWrapper<
       .catch((e) => {
         if (e instanceof DOMException && e.name === 'AbortError') {
           this.log.log('stream processor path aborted');
+        } else if (e instanceof DOMException && e.name === 'InvalidStateError' && e.message === 'Stream closed') {
+          this.log.log('stream processor underlying stream closed');
         } else {
           this.log.error('error when trying to pipe', e);
           this.destroy(symbol);

From d00fdba64a5a28a2622f7bce28fa88d44d32e63f Mon Sep 17 00:00:00 2001
From: Ryan Gaus <rsg1egoman@gmail.com>
Date: Mon, 13 Oct 2025 10:11:36 -0400
Subject: [PATCH 05/19] feat: add track transformer destroy options with
 willRestart to hint that a restart is imminent

---
 src/ProcessorWrapper.ts                   | 11 +++++++----
 src/transformers/BackgroundTransformer.ts | 10 +++++++---
 src/transformers/VideoTransformer.ts      |  2 +-
 src/transformers/types.ts                 | 19 +++++++++++--------
 4 files changed, 26 insertions(+), 16 deletions(-)

diff --git a/src/ProcessorWrapper.ts b/src/ProcessorWrapper.ts
index 656c9a8..eefe285 100644
--- a/src/ProcessorWrapper.ts
+++ b/src/ProcessorWrapper.ts
@@ -1,8 +1,9 @@
 import { type ProcessorOptions, type Track, type TrackProcessor } from 'livekit-client';
-import { TrackTransformer } from './transformers';
+import { TrackTransformer, TrackTransformerDestroyOptions } from './transformers';
 import { createCanvas, waitForTrackResolution } from './utils';
 import { LoggerNames, getLogger } from './logger';
 
+
 export interface ProcessorWrapperOptions {
   /**
    * Maximum frame rate for fallback canvas.captureStream implementation
@@ -351,7 +352,7 @@ export default class ProcessorWrapper<
   }
 
   async restart(opts: ProcessorOptions<Track.Kind>): Promise<void> {
-    await this.destroy();
+    await this.destroy(undefined, { willRestart: true });
     await this.init(opts);
   }
 
@@ -364,11 +365,12 @@ export default class ProcessorWrapper<
     await this.transformer.update(options[0]);
   }
 
-  async destroy(symbol?: Symbol) {
+  async destroy(symbol?: Symbol, transformerDestroyOptions: TrackTransformerDestroyOptions = { willRestart: false }) {
     if (symbol && this.symbol !== symbol) {
       // If the symbol is provided, we only destroy if it matches the current symbol
       return;
     }
+
     if (this.useStreamFallback) {
       this.processingEnabled = false;
       if (this.animationFrameId) {
@@ -383,6 +385,7 @@ export default class ProcessorWrapper<
       await this.processor?.writableControl?.close();
       this.trackGenerator?.stop();
     }
-    await this.transformer.destroy();
+
+    await this.transformer.destroy(transformerDestroyOptions);
   }
 }
diff --git a/src/transformers/BackgroundTransformer.ts b/src/transformers/BackgroundTransformer.ts
index b36b5c5..3861871 100644
--- a/src/transformers/BackgroundTransformer.ts
+++ b/src/transformers/BackgroundTransformer.ts
@@ -2,7 +2,7 @@ import * as vision from '@mediapipe/tasks-vision';
 import { getLogger, LoggerNames } from '../logger';
 import { dependencies } from '../../package.json';
 import VideoTransformer from './VideoTransformer';
-import { VideoTransformerInitOptions } from './types';
+import { TrackTransformerDestroyOptions, VideoTransformerInitOptions } from './types';
 
 export type SegmenterOptions = Partial<vision.ImageSegmenterOptions['baseOptions']>;
 
@@ -90,10 +90,14 @@ export default class BackgroundProcessor extends VideoTransformer<BackgroundOpti
     this.gl?.setBackgroundDisabled(this.options.backgroundDisabled ?? false);
   }
 
-  async destroy() {
-    await super.destroy();
+  async destroy(options: TrackTransformerDestroyOptions) {
+    await super.destroy(options);
     await this.imageSegmenter?.close();
     this.backgroundImageAndPath = null;
+
+    if (!options.willRestart) {
+      this.isFirstFrame = true;
+    }
   }
 
   async loadAndSetBackground(path: string) {
diff --git a/src/transformers/VideoTransformer.ts b/src/transformers/VideoTransformer.ts
index ab8799e..46a9956 100644
--- a/src/transformers/VideoTransformer.ts
+++ b/src/transformers/VideoTransformer.ts
@@ -50,7 +50,7 @@ export default abstract class VideoTransformer<Options extends Record<string, un
     this.isDisabled = false;
   }
 
-  async destroy() {
+  async destroy(_options: TrackTransformerDestroyOptions) {
     this.isDisabled = true;
     this.canvas = undefined;
     this.gl?.cleanup();
diff --git a/src/transformers/types.ts b/src/transformers/types.ts
index 181e1d5..27672d2 100644
--- a/src/transformers/types.ts
+++ b/src/transformers/types.ts
@@ -10,9 +10,9 @@ export interface VideoTransformerInitOptions extends TrackTransformerInitOptions
 export interface AudioTransformerInitOptions extends TrackTransformerInitOptions {}
 
 export interface VideoTrackTransformer<Options extends Record<string, unknown>>
-  extends BaseTrackTransformer<VideoTransformerInitOptions, VideoFrame> {
+  extends BaseTrackTransformer<VideoTransformerInitOptions, VideoFrame, TrackTransformerDestroyOptions> {
   init: (options: VideoTransformerInitOptions) => void;
-  destroy: () => void;
+  destroy: (options: TrackTransformerDestroyOptions) => void;
   restart: (options: VideoTransformerInitOptions) => void;
   transform: (frame: VideoFrame, controller: TransformStreamDefaultController) => void;
   transformer?: TransformStream;
@@ -20,26 +20,29 @@ export interface VideoTrackTransformer<Options extends Record<string, unknown>>
 }
 
 export interface AudioTrackTransformer<Options extends Record<string, unknown>>
-  extends BaseTrackTransformer<AudioTransformerInitOptions, AudioData> {
+  extends BaseTrackTransformer<AudioTransformerInitOptions, AudioData, TrackTransformerDestroyOptions> {
   init: (options: AudioTransformerInitOptions) => void;
-  destroy: () => void;
+  destroy: (options: TrackTransformerDestroyOptions) => void;
   restart: (options: AudioTransformerInitOptions) => void;
   transform: (frame: AudioData, controller: TransformStreamDefaultController) => void;
   transformer?: TransformStream;
   update: (options: Options) => void;
 }
 
+export type TrackTransformerDestroyOptions = { willRestart: boolean };
+
 export type TrackTransformer<Options extends Record<string, unknown>> =
   | VideoTrackTransformer<Options>
   | AudioTrackTransformer<Options>;
 
 export interface BaseTrackTransformer<
-  T extends TrackTransformerInitOptions,
+  InitOpts extends TrackTransformerInitOptions,
   DataType extends VideoFrame | AudioData,
+  DestroyOpts extends TrackTransformerDestroyOptions = TrackTransformerDestroyOptions,
 > {
-  init: (options: T) => void;
-  destroy: () => void;
-  restart: (options: T) => void;
+  init: (options: InitOpts) => void;
+  destroy: (options: DestroyOpts) => void;
+  restart: (options: InitOpts) => void;
   transform: (frame: DataType, controller: TransformStreamDefaultController) => void;
   transformer?: TransformStream;
 }

From 6f1d1f3a63db7769420a6769756f217d23106a4f Mon Sep 17 00:00:00 2001
From: Ryan Gaus <rsg1egoman@gmail.com>
Date: Mon, 13 Oct 2025 10:12:31 -0400
Subject: [PATCH 06/19] feat: store lastTrackTransformerDestroyOptions to avoid
 more calls to this.destroy using a different value

---
 src/ProcessorWrapper.ts | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/ProcessorWrapper.ts b/src/ProcessorWrapper.ts
index eefe285..d036b93 100644
--- a/src/ProcessorWrapper.ts
+++ b/src/ProcessorWrapper.ts
@@ -86,6 +86,8 @@ export default class ProcessorWrapper<
 
   private log = getLogger(LoggerNames.ProcessorWrapper);
 
+  private lastTrackTransformerDestroyOptions: TrackTransformerDestroyOptions = { willRestart: false };
+
   constructor(
     transformer: Transformer,
     name: string,
@@ -181,7 +183,7 @@ export default class ProcessorWrapper<
     pipedStream
       .pipeTo(this.trackGenerator.writable)
       // destroy processor if stream finishes
-      .then(() => this.destroy(symbol))
+      .then(() => this.destroy(symbol, this.lastTrackTransformerDestroyOptions))
       // destroy processor if stream errors - unless it's an abort error
       .catch((e) => {
         if (e instanceof DOMException && e.name === 'AbortError') {
@@ -366,6 +368,7 @@ export default class ProcessorWrapper<
   }
 
   async destroy(symbol?: Symbol, transformerDestroyOptions: TrackTransformerDestroyOptions = { willRestart: false }) {
+    this.lastTrackTransformerDestroyOptions = transformerDestroyOptions;
     if (symbol && this.symbol !== symbol) {
       // If the symbol is provided, we only destroy if it matches the current symbol
       return;

From fc0ce336a147707886793fd70f67f681e1974184 Mon Sep 17 00:00:00 2001
From: Ryan Gaus <rsg1egoman@gmail.com>
Date: Mon, 13 Oct 2025 12:07:58 -0400
Subject: [PATCH 07/19] feat: get rid of lastTrackTransformerDestroyOptions and
 symbol logic

---
 src/ProcessorWrapper.ts                   | 35 ++++++++++++-----------
 src/transformers/BackgroundTransformer.ts |  2 ++
 src/transformers/VideoTransformer.ts      |  2 +-
 3 files changed, 22 insertions(+), 17 deletions(-)

diff --git a/src/ProcessorWrapper.ts b/src/ProcessorWrapper.ts
index d036b93..24d4f78 100644
--- a/src/ProcessorWrapper.ts
+++ b/src/ProcessorWrapper.ts
@@ -82,11 +82,9 @@ export default class ProcessorWrapper<
   // FPS control for fallback implementation
   private maxFps: number;
 
-  private symbol?: Symbol;
-
   private log = getLogger(LoggerNames.ProcessorWrapper);
 
-  private lastTrackTransformerDestroyOptions: TrackTransformerDestroyOptions = { willRestart: false };
+  // private lastTrackTransformerDestroyOptions: TrackTransformerDestroyOptions = { willRestart: false };
 
   constructor(
     transformer: Transformer,
@@ -149,6 +147,7 @@ export default class ProcessorWrapper<
   }
 
   async init(opts: ProcessorOptions<Track.Kind>): Promise<void> {
+    console.log('.. INIT');
     await this.setup(opts);
 
     if (!this.canvas) {
@@ -177,13 +176,15 @@ export default class ProcessorWrapper<
     const readableStream = this.processor.readable;
     const pipedStream = readableStream.pipeThrough(this.transformer!.transformer!);
 
-    const symbol = Symbol('stream');
-    this.symbol = symbol;
-
     pipedStream
       .pipeTo(this.trackGenerator.writable)
       // destroy processor if stream finishes
-      .then(() => this.destroy(symbol, this.lastTrackTransformerDestroyOptions))
+      .then(async () => {
+        // this.lastTrackTransformerDestroyOptions = { willRestart: true };
+        await this.cleanup();
+        console.log('.. PIPED STREAM CLEANUP', { willRestart: true });
+        await this.transformer.destroy({ willRestart: true });
+      })
       // destroy processor if stream errors - unless it's an abort error
       .catch((e) => {
         if (e instanceof DOMException && e.name === 'AbortError') {
@@ -192,7 +193,7 @@ export default class ProcessorWrapper<
           this.log.log('stream processor underlying stream closed');
         } else {
           this.log.error('error when trying to pipe', e);
-          this.destroy(symbol);
+          this.destroy();
         }
       });
 
@@ -354,7 +355,8 @@ export default class ProcessorWrapper<
   }
 
   async restart(opts: ProcessorOptions<Track.Kind>): Promise<void> {
-    await this.destroy(undefined, { willRestart: true });
+    console.log('.. RESTART');
+    await this.destroy({ willRestart: true });
     await this.init(opts);
   }
 
@@ -367,13 +369,7 @@ export default class ProcessorWrapper<
     await this.transformer.update(options[0]);
   }
 
-  async destroy(symbol?: Symbol, transformerDestroyOptions: TrackTransformerDestroyOptions = { willRestart: false }) {
-    this.lastTrackTransformerDestroyOptions = transformerDestroyOptions;
-    if (symbol && this.symbol !== symbol) {
-      // If the symbol is provided, we only destroy if it matches the current symbol
-      return;
-    }
-
+  async cleanup() {
     if (this.useStreamFallback) {
       this.processingEnabled = false;
       if (this.animationFrameId) {
@@ -384,11 +380,18 @@ export default class ProcessorWrapper<
         this.displayCanvas.parentNode.removeChild(this.displayCanvas);
       }
       this.capturedStream?.getTracks().forEach((track) => track.stop());
+      // await this.transformer.destroy(this.lastTrackTransformerDestroyOptions);
     } else {
+      // NOTE: closing writableControl below 
       await this.processor?.writableControl?.close();
       this.trackGenerator?.stop();
     }
+  }
 
+  async destroy(transformerDestroyOptions: TrackTransformerDestroyOptions = { willRestart: false }) {
+    // this.lastTrackTransformerDestroyOptions = transformerDestroyOptions;
+    await this.cleanup();
+    console.log('.. REGULAR DESTROY', transformerDestroyOptions);
     await this.transformer.destroy(transformerDestroyOptions);
   }
 }
diff --git a/src/transformers/BackgroundTransformer.ts b/src/transformers/BackgroundTransformer.ts
index 3861871..e2cd602 100644
--- a/src/transformers/BackgroundTransformer.ts
+++ b/src/transformers/BackgroundTransformer.ts
@@ -95,6 +95,8 @@ export default class BackgroundProcessor extends VideoTransformer<BackgroundOpti
     await this.imageSegmenter?.close();
     this.backgroundImageAndPath = null;
 
+    console.log('WILL RESTART', options);
+    // debugger;
     if (!options.willRestart) {
       this.isFirstFrame = true;
     }
diff --git a/src/transformers/VideoTransformer.ts b/src/transformers/VideoTransformer.ts
index 46a9956..bb9165f 100644
--- a/src/transformers/VideoTransformer.ts
+++ b/src/transformers/VideoTransformer.ts
@@ -1,6 +1,6 @@
 import { createCanvas } from '../utils';
 import { setupWebGL } from '../webgl/index';
-import { VideoTrackTransformer, VideoTransformerInitOptions } from './types';
+import { TrackTransformerDestroyOptions, VideoTrackTransformer, VideoTransformerInitOptions } from './types';
 
 export default abstract class VideoTransformer<Options extends Record<string, unknown>>
   implements VideoTrackTransformer<Options>

From 4bff928744dbd85c45c854a23fefe20f42e117ab Mon Sep 17 00:00:00 2001
From: Ryan Gaus <rsg1egoman@gmail.com>
Date: Mon, 13 Oct 2025 12:13:33 -0400
Subject: [PATCH 08/19] feat: add lifecyclestate for deduplicating destroy
 events

Ensure you can't destroy a ProcessorWrapper when it is already destroyed.
---
 src/ProcessorWrapper.ts | 23 ++++++++++++++++-------
 1 file changed, 16 insertions(+), 7 deletions(-)

diff --git a/src/ProcessorWrapper.ts b/src/ProcessorWrapper.ts
index 24d4f78..0dafbb1 100644
--- a/src/ProcessorWrapper.ts
+++ b/src/ProcessorWrapper.ts
@@ -3,6 +3,7 @@ import { TrackTransformer, TrackTransformerDestroyOptions } from './transformers
 import { createCanvas, waitForTrackResolution } from './utils';
 import { LoggerNames, getLogger } from './logger';
 
+type ProcessorWrapperLifecycleState = 'idle' | 'initialized' | 'destroying' | 'destroyed';
 
 export interface ProcessorWrapperOptions {
   /**
@@ -84,7 +85,7 @@ export default class ProcessorWrapper<
 
   private log = getLogger(LoggerNames.ProcessorWrapper);
 
-  // private lastTrackTransformerDestroyOptions: TrackTransformerDestroyOptions = { willRestart: false };
+  private lifecycleState: ProcessorWrapperLifecycleState = 'idle';
 
   constructor(
     transformer: Transformer,
@@ -164,6 +165,7 @@ export default class ProcessorWrapper<
     } else {
       this.initStreamProcessorPath();
     }
+    this.lifecycleState = 'initialized';
   }
 
   private initStreamProcessorPath() {
@@ -180,10 +182,13 @@ export default class ProcessorWrapper<
       .pipeTo(this.trackGenerator.writable)
       // destroy processor if stream finishes
       .then(async () => {
-        // this.lastTrackTransformerDestroyOptions = { willRestart: true };
-        await this.cleanup();
-        console.log('.. PIPED STREAM CLEANUP', { willRestart: true });
-        await this.transformer.destroy({ willRestart: true });
+        if (this.lifecycleState === 'initialized') {
+          this.lifecycleState = 'destroying';
+          await this.cleanup();
+          console.log('.. PIPED STREAM CLEANUP', { willRestart: true });
+          await this.transformer.destroy({ willRestart: true });
+          this.lifecycleState = 'destroyed';
+        }
       })
       // destroy processor if stream errors - unless it's an abort error
       .catch((e) => {
@@ -380,7 +385,6 @@ export default class ProcessorWrapper<
         this.displayCanvas.parentNode.removeChild(this.displayCanvas);
       }
       this.capturedStream?.getTracks().forEach((track) => track.stop());
-      // await this.transformer.destroy(this.lastTrackTransformerDestroyOptions);
     } else {
       // NOTE: closing writableControl below 
       await this.processor?.writableControl?.close();
@@ -389,9 +393,14 @@ export default class ProcessorWrapper<
   }
 
   async destroy(transformerDestroyOptions: TrackTransformerDestroyOptions = { willRestart: false }) {
-    // this.lastTrackTransformerDestroyOptions = transformerDestroyOptions;
+    if (this.lifecycleState !== 'initialized') {
+      return;
+    }
+
+    this.lifecycleState = 'destroying';
     await this.cleanup();
     console.log('.. REGULAR DESTROY', transformerDestroyOptions);
     await this.transformer.destroy(transformerDestroyOptions);
+    this.lifecycleState = 'destroyed';
   }
 }

From 15ad53aef0f32c3aa9396b38d700c3feb6aad750 Mon Sep 17 00:00:00 2001
From: Ryan Gaus <rsg1egoman@gmail.com>
Date: Mon, 13 Oct 2025 12:20:00 -0400
Subject: [PATCH 09/19] refactor: get rid of this.cleanup, I think I don't need
 it anymore

---
 src/ProcessorWrapper.ts | 26 ++++++++------------------
 1 file changed, 8 insertions(+), 18 deletions(-)

diff --git a/src/ProcessorWrapper.ts b/src/ProcessorWrapper.ts
index 0dafbb1..040f290 100644
--- a/src/ProcessorWrapper.ts
+++ b/src/ProcessorWrapper.ts
@@ -181,15 +181,7 @@ export default class ProcessorWrapper<
     pipedStream
       .pipeTo(this.trackGenerator.writable)
       // destroy processor if stream finishes
-      .then(async () => {
-        if (this.lifecycleState === 'initialized') {
-          this.lifecycleState = 'destroying';
-          await this.cleanup();
-          console.log('.. PIPED STREAM CLEANUP', { willRestart: true });
-          await this.transformer.destroy({ willRestart: true });
-          this.lifecycleState = 'destroyed';
-        }
-      })
+      .then(() => this.destroy({ willRestart: true }))
       // destroy processor if stream errors - unless it's an abort error
       .catch((e) => {
         if (e instanceof DOMException && e.name === 'AbortError') {
@@ -374,7 +366,13 @@ export default class ProcessorWrapper<
     await this.transformer.update(options[0]);
   }
 
-  async cleanup() {
+  async destroy(transformerDestroyOptions: TrackTransformerDestroyOptions = { willRestart: false }) {
+    if (this.lifecycleState !== 'initialized') {
+      return;
+    }
+
+    this.lifecycleState = 'destroying';
+
     if (this.useStreamFallback) {
       this.processingEnabled = false;
       if (this.animationFrameId) {
@@ -390,15 +388,7 @@ export default class ProcessorWrapper<
       await this.processor?.writableControl?.close();
       this.trackGenerator?.stop();
     }
-  }
 
-  async destroy(transformerDestroyOptions: TrackTransformerDestroyOptions = { willRestart: false }) {
-    if (this.lifecycleState !== 'initialized') {
-      return;
-    }
-
-    this.lifecycleState = 'destroying';
-    await this.cleanup();
     console.log('.. REGULAR DESTROY', transformerDestroyOptions);
     await this.transformer.destroy(transformerDestroyOptions);
     this.lifecycleState = 'destroyed';

From 8352d14bd7a257967cea814776a7fc6378ac166e Mon Sep 17 00:00:00 2001
From: Ryan Gaus <rsg1egoman@gmail.com>
Date: Mon, 13 Oct 2025 12:49:46 -0400
Subject: [PATCH 10/19] feat: add media exhausted state

---
 src/ProcessorWrapper.ts | 47 +++++++++++++++++++++++++++++------------
 1 file changed, 34 insertions(+), 13 deletions(-)

diff --git a/src/ProcessorWrapper.ts b/src/ProcessorWrapper.ts
index 040f290..49d9027 100644
--- a/src/ProcessorWrapper.ts
+++ b/src/ProcessorWrapper.ts
@@ -3,7 +3,7 @@ import { TrackTransformer, TrackTransformerDestroyOptions } from './transformers
 import { createCanvas, waitForTrackResolution } from './utils';
 import { LoggerNames, getLogger } from './logger';
 
-type ProcessorWrapperLifecycleState = 'idle' | 'initialized' | 'destroying' | 'destroyed';
+type ProcessorWrapperLifecycleState = 'idle' | 'initializing' | 'running' | 'media-exhausted' | 'destroying' | 'destroyed';
 
 export interface ProcessorWrapperOptions {
   /**
@@ -149,6 +149,7 @@ export default class ProcessorWrapper<
 
   async init(opts: ProcessorOptions<Track.Kind>): Promise<void> {
     console.log('.. INIT');
+    this.lifecycleState = 'initializing';
     await this.setup(opts);
 
     if (!this.canvas) {
@@ -165,7 +166,7 @@ export default class ProcessorWrapper<
     } else {
       this.initStreamProcessorPath();
     }
-    this.lifecycleState = 'initialized';
+    this.lifecycleState = 'running';
   }
 
   private initStreamProcessorPath() {
@@ -180,8 +181,8 @@ export default class ProcessorWrapper<
 
     pipedStream
       .pipeTo(this.trackGenerator.writable)
-      // destroy processor if stream finishes
-      .then(() => this.destroy({ willRestart: true }))
+      // if stream finishes, the media to process is exhausted
+      .then(() => this.handleMediaExhausted())
       // destroy processor if stream errors - unless it's an abort error
       .catch((e) => {
         if (e instanceof DOMException && e.name === 'AbortError') {
@@ -244,6 +245,7 @@ export default class ProcessorWrapper<
 
   private startRenderLoop() {
     if (!this.sourceDummy || !(this.sourceDummy instanceof HTMLVideoElement)) {
+      this.handleMediaExhausted();
       return;
     }
 
@@ -260,12 +262,15 @@ export default class ProcessorWrapper<
     let frameCount = 0;
     let lastFpsLog = 0;
 
+    let captured = (window as any).a;
+
     const renderLoop = () => {
       if (
         !this.processingEnabled ||
         !this.sourceDummy ||
         !(this.sourceDummy instanceof HTMLVideoElement)
       ) {
+        this.handleMediaExhausted();
         return;
       }
 
@@ -366,13 +371,15 @@ export default class ProcessorWrapper<
     await this.transformer.update(options[0]);
   }
 
-  async destroy(transformerDestroyOptions: TrackTransformerDestroyOptions = { willRestart: false }) {
-    if (this.lifecycleState !== 'initialized') {
-      return;
-    }
-
-    this.lifecycleState = 'destroying';
+  /** Called if the media pipeline no longer can read frames to process from the source media */
+  private async handleMediaExhausted() {
+    console.log('.. MEDIA EXHAUSTED');
+    this.lifecycleState = 'media-exhausted'
+    await this.cleanup();
+  }
 
+  /** Tears down the media stack logic initialized in initStreamProcessorPath / initFallbackPath */
+  private async cleanup() {
     if (this.useStreamFallback) {
       this.processingEnabled = false;
       if (this.animationFrameId) {
@@ -388,9 +395,23 @@ export default class ProcessorWrapper<
       await this.processor?.writableControl?.close();
       this.trackGenerator?.stop();
     }
+  }
+
+  async destroy(transformerDestroyOptions: TrackTransformerDestroyOptions = { willRestart: false }) {
+    console.log('.. DESTROY', this.lifecycleState);
+    switch (this.lifecycleState) {
+      case 'running':
+      case 'media-exhausted':
+        this.lifecycleState = 'destroying';
 
-    console.log('.. REGULAR DESTROY', transformerDestroyOptions);
-    await this.transformer.destroy(transformerDestroyOptions);
-    this.lifecycleState = 'destroyed';
+        await this.cleanup();
+
+        await this.transformer.destroy(transformerDestroyOptions);
+        this.lifecycleState = 'destroyed';
+        break;
+
+      default:
+        break;
+    }
   }
 }

From 40715618549d7e513cc4974010f4763082cb269e Mon Sep 17 00:00:00 2001
From: Ryan Gaus <rsg1egoman@gmail.com>
Date: Mon, 13 Oct 2025 13:07:04 -0400
Subject: [PATCH 11/19] refactor: convert console.logs into log.debugs

---
 src/ProcessorWrapper.ts | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

diff --git a/src/ProcessorWrapper.ts b/src/ProcessorWrapper.ts
index 49d9027..54535f8 100644
--- a/src/ProcessorWrapper.ts
+++ b/src/ProcessorWrapper.ts
@@ -148,7 +148,7 @@ export default class ProcessorWrapper<
   }
 
   async init(opts: ProcessorOptions<Track.Kind>): Promise<void> {
-    console.log('.. INIT');
+    this.log.debug('Init called');
     this.lifecycleState = 'initializing';
     await this.setup(opts);
 
@@ -262,8 +262,6 @@ export default class ProcessorWrapper<
     let frameCount = 0;
     let lastFpsLog = 0;
 
-    let captured = (window as any).a;
-
     const renderLoop = () => {
       if (
         !this.processingEnabled ||
@@ -357,7 +355,7 @@ export default class ProcessorWrapper<
   }
 
   async restart(opts: ProcessorOptions<Track.Kind>): Promise<void> {
-    console.log('.. RESTART');
+    this.log.debug('Restart called');
     await this.destroy({ willRestart: true });
     await this.init(opts);
   }
@@ -373,7 +371,7 @@ export default class ProcessorWrapper<
 
   /** Called if the media pipeline no longer can read frames to process from the source media */
   private async handleMediaExhausted() {
-    console.log('.. MEDIA EXHAUSTED');
+    this.log.debug('Media was exhausted from source');
     this.lifecycleState = 'media-exhausted'
     await this.cleanup();
   }
@@ -398,7 +396,7 @@ export default class ProcessorWrapper<
   }
 
   async destroy(transformerDestroyOptions: TrackTransformerDestroyOptions = { willRestart: false }) {
-    console.log('.. DESTROY', this.lifecycleState);
+    this.log.debug(`Destroy called - lifecycleState=${this.lifecycleState}, transformerDestroyOptions=${JSON.stringify(transformerDestroyOptions)}`);
     switch (this.lifecycleState) {
       case 'running':
       case 'media-exhausted':

From 80aae2dc9910ccba157f5daf190bfa78700b6403 Mon Sep 17 00:00:00 2001
From: Ryan Gaus <rsg1egoman@gmail.com>
Date: Mon, 13 Oct 2025 13:08:15 -0400
Subject: [PATCH 12/19] refactor: remove unused method parameter

---
 src/transformers/VideoTransformer.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/transformers/VideoTransformer.ts b/src/transformers/VideoTransformer.ts
index bb9165f..ab8799e 100644
--- a/src/transformers/VideoTransformer.ts
+++ b/src/transformers/VideoTransformer.ts
@@ -1,6 +1,6 @@
 import { createCanvas } from '../utils';
 import { setupWebGL } from '../webgl/index';
-import { TrackTransformerDestroyOptions, VideoTrackTransformer, VideoTransformerInitOptions } from './types';
+import { VideoTrackTransformer, VideoTransformerInitOptions } from './types';
 
 export default abstract class VideoTransformer<Options extends Record<string, unknown>>
   implements VideoTrackTransformer<Options>
@@ -50,7 +50,7 @@ export default abstract class VideoTransformer<Options extends Record<string, un
     this.isDisabled = false;
   }
 
-  async destroy(_options: TrackTransformerDestroyOptions) {
+  async destroy() {
     this.isDisabled = true;
     this.canvas = undefined;
     this.gl?.cleanup();

From b0e5fa179c8babcef6f4c9750e8825bb758d18df Mon Sep 17 00:00:00 2001
From: Ryan Gaus <rsg1egoman@gmail.com>
Date: Mon, 13 Oct 2025 13:12:22 -0400
Subject: [PATCH 13/19] feat: add handleMediaExhausted call when stream
 processor stream closes

---
 src/ProcessorWrapper.ts | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/src/ProcessorWrapper.ts b/src/ProcessorWrapper.ts
index 54535f8..66e2cfa 100644
--- a/src/ProcessorWrapper.ts
+++ b/src/ProcessorWrapper.ts
@@ -189,6 +189,7 @@ export default class ProcessorWrapper<
           this.log.log('stream processor path aborted');
         } else if (e instanceof DOMException && e.name === 'InvalidStateError' && e.message === 'Stream closed') {
           this.log.log('stream processor underlying stream closed');
+          this.handleMediaExhausted();
         } else {
           this.log.error('error when trying to pipe', e);
           this.destroy();
@@ -372,6 +373,9 @@ export default class ProcessorWrapper<
   /** Called if the media pipeline no longer can read frames to process from the source media */
   private async handleMediaExhausted() {
     this.log.debug('Media was exhausted from source');
+    if (this.lifecycleState !== 'running') {
+      return;
+    }
     this.lifecycleState = 'media-exhausted'
     await this.cleanup();
   }
@@ -383,6 +387,7 @@ export default class ProcessorWrapper<
       if (this.animationFrameId) {
         cancelAnimationFrame(this.animationFrameId);
         this.animationFrameId = undefined;
+        this.lifecycleState = 'media-exhausted';
       }
       if (this.displayCanvas && this.displayCanvas.parentNode) {
         this.displayCanvas.parentNode.removeChild(this.displayCanvas);

From a7d842ece63d2b52f04d41ca7046f209194450f2 Mon Sep 17 00:00:00 2001
From: Ryan Gaus <rsg1egoman@gmail.com>
Date: Mon, 13 Oct 2025 13:16:41 -0400
Subject: [PATCH 14/19] docs: add better comment describing complex logic

---
 src/ProcessorWrapper.ts | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/ProcessorWrapper.ts b/src/ProcessorWrapper.ts
index 66e2cfa..378bd8e 100644
--- a/src/ProcessorWrapper.ts
+++ b/src/ProcessorWrapper.ts
@@ -394,7 +394,8 @@ export default class ProcessorWrapper<
       }
       this.capturedStream?.getTracks().forEach((track) => track.stop());
     } else {
-      // NOTE: closing writableControl below 
+      // NOTE: closing writableControl below terminates the stream in initStreamProcessorPath /
+      // calls the .then(...) which calls this.handleMediaExhausted
       await this.processor?.writableControl?.close();
       this.trackGenerator?.stop();
     }

From 68ddfee138b67ef812ebdb43eb6718da2fd467fb Mon Sep 17 00:00:00 2001
From: Ryan Gaus <rsg1egoman@gmail.com>
Date: Mon, 13 Oct 2025 13:18:53 -0400
Subject: [PATCH 15/19] fix: remove media exhausted assign

---
 src/ProcessorWrapper.ts | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/ProcessorWrapper.ts b/src/ProcessorWrapper.ts
index 378bd8e..3a5407e 100644
--- a/src/ProcessorWrapper.ts
+++ b/src/ProcessorWrapper.ts
@@ -387,7 +387,6 @@ export default class ProcessorWrapper<
       if (this.animationFrameId) {
         cancelAnimationFrame(this.animationFrameId);
         this.animationFrameId = undefined;
-        this.lifecycleState = 'media-exhausted';
       }
       if (this.displayCanvas && this.displayCanvas.parentNode) {
         this.displayCanvas.parentNode.removeChild(this.displayCanvas);

From 45879a68f7a6068ce7eba160466d84ea27d23175 Mon Sep 17 00:00:00 2001
From: Ryan Gaus <rsg1egoman@gmail.com>
Date: Mon, 13 Oct 2025 13:24:54 -0400
Subject: [PATCH 16/19] fix: make TrackTransformerDestroyOptions optional to be
 backwards compatible

---
 src/transformers/BackgroundTransformer.ts | 8 +++-----
 src/transformers/types.ts                 | 2 +-
 2 files changed, 4 insertions(+), 6 deletions(-)

diff --git a/src/transformers/BackgroundTransformer.ts b/src/transformers/BackgroundTransformer.ts
index e2cd602..6e6f615 100644
--- a/src/transformers/BackgroundTransformer.ts
+++ b/src/transformers/BackgroundTransformer.ts
@@ -90,14 +90,12 @@ export default class BackgroundProcessor extends VideoTransformer<BackgroundOpti
     this.gl?.setBackgroundDisabled(this.options.backgroundDisabled ?? false);
   }
 
-  async destroy(options: TrackTransformerDestroyOptions) {
-    await super.destroy(options);
+  async destroy(options?: TrackTransformerDestroyOptions) {
+    await super.destroy();
     await this.imageSegmenter?.close();
     this.backgroundImageAndPath = null;
 
-    console.log('WILL RESTART', options);
-    // debugger;
-    if (!options.willRestart) {
+    if (!options?.willRestart) {
       this.isFirstFrame = true;
     }
   }
diff --git a/src/transformers/types.ts b/src/transformers/types.ts
index 27672d2..87e04f9 100644
--- a/src/transformers/types.ts
+++ b/src/transformers/types.ts
@@ -12,7 +12,7 @@ export interface AudioTransformerInitOptions extends TrackTransformerInitOptions
 export interface VideoTrackTransformer<Options extends Record<string, unknown>>
   extends BaseTrackTransformer<VideoTransformerInitOptions, VideoFrame, TrackTransformerDestroyOptions> {
   init: (options: VideoTransformerInitOptions) => void;
-  destroy: (options: TrackTransformerDestroyOptions) => void;
+  destroy: (options?: TrackTransformerDestroyOptions) => void;
   restart: (options: VideoTransformerInitOptions) => void;
   transform: (frame: VideoFrame, controller: TransformStreamDefaultController) => void;
   transformer?: TransformStream;

From 82f0f2df1431f2f7b8e65f4eca44fa2621352947 Mon Sep 17 00:00:00 2001
From: Ryan Gaus <rsg1egoman@gmail.com>
Date: Mon, 13 Oct 2025 13:47:42 -0400
Subject: [PATCH 17/19] refactor: rename willRestart -> willProcessorRestart

---
 src/ProcessorWrapper.ts                   | 4 ++--
 src/transformers/BackgroundTransformer.ts | 2 +-
 src/transformers/types.ts                 | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/ProcessorWrapper.ts b/src/ProcessorWrapper.ts
index 3a5407e..b778f37 100644
--- a/src/ProcessorWrapper.ts
+++ b/src/ProcessorWrapper.ts
@@ -357,7 +357,7 @@ export default class ProcessorWrapper<
 
   async restart(opts: ProcessorOptions<Track.Kind>): Promise<void> {
     this.log.debug('Restart called');
-    await this.destroy({ willRestart: true });
+    await this.destroy({ willProcessorRestart: true });
     await this.init(opts);
   }
 
@@ -400,7 +400,7 @@ export default class ProcessorWrapper<
     }
   }
 
-  async destroy(transformerDestroyOptions: TrackTransformerDestroyOptions = { willRestart: false }) {
+  async destroy(transformerDestroyOptions: TrackTransformerDestroyOptions = { willProcessorRestart: false }) {
     this.log.debug(`Destroy called - lifecycleState=${this.lifecycleState}, transformerDestroyOptions=${JSON.stringify(transformerDestroyOptions)}`);
     switch (this.lifecycleState) {
       case 'running':
diff --git a/src/transformers/BackgroundTransformer.ts b/src/transformers/BackgroundTransformer.ts
index 6e6f615..67ded07 100644
--- a/src/transformers/BackgroundTransformer.ts
+++ b/src/transformers/BackgroundTransformer.ts
@@ -95,7 +95,7 @@ export default class BackgroundProcessor extends VideoTransformer<BackgroundOpti
     await this.imageSegmenter?.close();
     this.backgroundImageAndPath = null;
 
-    if (!options?.willRestart) {
+    if (!options?.willProcessorRestart) {
       this.isFirstFrame = true;
     }
   }
diff --git a/src/transformers/types.ts b/src/transformers/types.ts
index 87e04f9..21f5202 100644
--- a/src/transformers/types.ts
+++ b/src/transformers/types.ts
@@ -29,7 +29,7 @@ export interface AudioTrackTransformer<Options extends Record<string, unknown>>
   update: (options: Options) => void;
 }
 
-export type TrackTransformerDestroyOptions = { willRestart: boolean };
+export type TrackTransformerDestroyOptions = { willProcessorRestart: boolean };
 
 export type TrackTransformer<Options extends Record<string, unknown>> =
   | VideoTrackTransformer<Options>

From 9658ec019ac1bc6759f97ab441d7ba299721823d Mon Sep 17 00:00:00 2001
From: Ryan Gaus <rsg1egoman@gmail.com>
Date: Mon, 13 Oct 2025 14:43:43 -0400
Subject: [PATCH 18/19] docs(changeset): Fix a "black screen flash" which
 occurs sometimes when restarting the processor wrapper

---
 .changeset/open-candles-talk.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/open-candles-talk.md

diff --git a/.changeset/open-candles-talk.md b/.changeset/open-candles-talk.md
new file mode 100644
index 0000000..ec0b627
--- /dev/null
+++ b/.changeset/open-candles-talk.md
@@ -0,0 +1,5 @@
+---
+'@livekit/track-processors': patch
+---
+
+Fix a "black screen flash" which occurs sometimes when restarting the processor wrapper

From 367d72afb6c030da79569804fdb0db5f75d1f8dc Mon Sep 17 00:00:00 2001
From: Ryan Gaus <rsg1egoman@gmail.com>
Date: Wed, 22 Oct 2025 10:34:36 -0400
Subject: [PATCH 19/19] fix: avoid calling switchBackgroundMode since it has
 its own error handling / finally state setting logic

---
 example/sample.ts | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/example/sample.ts b/example/sample.ts
index a8a206f..8b61483 100644
--- a/example/sample.ts
+++ b/example/sample.ts
@@ -258,7 +258,21 @@ const appActions = {
       } else {
         $("initial-mode-wrapper").style.display = 'none';
         const initialMode = $<HTMLSelectElement>("initial-mode-select").value as BackgroundProcessorOptions['mode'];
-        appActions.switchBackgroundMode(initialMode ?? 'disabled');
+
+        switch (initialMode) {
+          case 'disabled':
+            await state.backgroundProcessor.switchTo({ mode: 'disabled' });
+            break;
+          case 'virtual-background':
+            await state.backgroundProcessor.switchTo({ mode: 'virtual-background', imagePath: IMAGE_PATH });
+            break;
+          case 'background-blur':
+            await state.backgroundProcessor.switchTo({ mode: 'background-blur' });
+            break;
+        }
+
+        state.isBackgroundProcessorEnabled = true;
+        await camTrack.setProcessor(state.backgroundProcessor);
       }
     } catch (e: any) {
       appendLog(`ERROR: ${e.message}`);