From 004bc8d5740ef60d386c06ecf2b211f3b4330f66 Mon Sep 17 00:00:00 2001
From: Ryan Gaus <rsg1egoman@gmail.com>
Date: Thu, 4 Sep 2025 13:28:24 -0400
Subject: [PATCH 1/3] feat: cache background image rather than refetch it every
 time it is enabled

---
 src/transformers/BackgroundTransformer.ts | 29 +++++++++++++----------
 1 file changed, 16 insertions(+), 13 deletions(-)

diff --git a/src/transformers/BackgroundTransformer.ts b/src/transformers/BackgroundTransformer.ts
index 9e2576c..ec48351 100644
--- a/src/transformers/BackgroundTransformer.ts
+++ b/src/transformers/BackgroundTransformer.ts
@@ -36,7 +36,7 @@ export default class BackgroundProcessor extends VideoTransformer<BackgroundOpti
 
   segmentationResults: vision.ImageSegmenterResult | undefined;
 
-  backgroundImage: ImageBitmap | null = null;
+  backgroundImage: HTMLImageElement | null = null;
 
   options: BackgroundOptions;
 
@@ -75,8 +75,8 @@ export default class BackgroundProcessor extends VideoTransformer<BackgroundOpti
     });
 
     // Skip loading the image here if update already loaded the image below
-    if (this.options?.imagePath && !this.backgroundImage) {
-      await this.loadBackground(this.options.imagePath).catch((err) =>
+    if (this.options?.imagePath) {
+      await this.loadAndSetBackground(this.options.imagePath).catch((err) =>
         console.error('Error while loading processor background image: ', err),
       );
     }
@@ -92,16 +92,19 @@ export default class BackgroundProcessor extends VideoTransformer<BackgroundOpti
     this.isFirstFrame = true;
   }
 
-  async loadBackground(path: string) {
-    const img = new Image();
+  async loadAndSetBackground(path: string) {
+    if (!this.backgroundImage || this.backgroundImage.src !== path) {
+      const img = new Image();
 
-    await new Promise((resolve, reject) => {
-      img.crossOrigin = 'Anonymous';
-      img.onload = () => resolve(img);
-      img.onerror = (err) => reject(err);
-      img.src = path;
-    });
-    const imageData = await createImageBitmap(img);
+      await new Promise((resolve, reject) => {
+        img.crossOrigin = 'Anonymous';
+        img.onload = () => resolve(img);
+        img.onerror = (err) => reject(err);
+        img.src = path;
+      });
+      this.backgroundImage = img;
+    }
+    const imageData = await createImageBitmap(this.backgroundImage);
     this.gl?.setBackgroundImage(imageData);
   }
 
@@ -200,7 +203,7 @@ export default class BackgroundProcessor extends VideoTransformer<BackgroundOpti
 
     this.gl?.setBlurRadius(opts.blurRadius ?? null);
     if (opts.imagePath) {
-      await this.loadBackground(opts.imagePath);
+      await this.loadAndSetBackground(opts.imagePath);
     } else {
       this.gl?.setBackgroundImage(null);
     }

From a1b009de15ecec0a0de82a6fe2744040a2493c88 Mon Sep 17 00:00:00 2001
From: Ryan Gaus <rsg1egoman@gmail.com>
Date: Thu, 4 Sep 2025 13:31:11 -0400
Subject: [PATCH 2/3] feat: store imagedata instead of raw image, since
 createImageBitmap is async / could slow down loading more

---
 src/transformers/BackgroundTransformer.ts | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/transformers/BackgroundTransformer.ts b/src/transformers/BackgroundTransformer.ts
index ec48351..00b9ab3 100644
--- a/src/transformers/BackgroundTransformer.ts
+++ b/src/transformers/BackgroundTransformer.ts
@@ -36,7 +36,7 @@ export default class BackgroundProcessor extends VideoTransformer<BackgroundOpti
 
   segmentationResults: vision.ImageSegmenterResult | undefined;
 
-  backgroundImage: HTMLImageElement | null = null;
+  backgroundImageAndPath: { imageData: ImageBitmap, path: string } | null = null;
 
   options: BackgroundOptions;
 
@@ -88,12 +88,12 @@ export default class BackgroundProcessor extends VideoTransformer<BackgroundOpti
   async destroy() {
     await super.destroy();
     await this.imageSegmenter?.close();
-    this.backgroundImage = null;
+    this.backgroundImageAndPath = null;
     this.isFirstFrame = true;
   }
 
   async loadAndSetBackground(path: string) {
-    if (!this.backgroundImage || this.backgroundImage.src !== path) {
+    if (!this.backgroundImageAndPath || this.backgroundImageAndPath?.path !== path) {
       const img = new Image();
 
       await new Promise((resolve, reject) => {
@@ -102,10 +102,10 @@ export default class BackgroundProcessor extends VideoTransformer<BackgroundOpti
         img.onerror = (err) => reject(err);
         img.src = path;
       });
-      this.backgroundImage = img;
+      const imageData = await createImageBitmap(img);
+      this.backgroundImageAndPath = { imageData, path };
     }
-    const imageData = await createImageBitmap(this.backgroundImage);
-    this.gl?.setBackgroundImage(imageData);
+    this.gl?.setBackgroundImage(this.backgroundImageAndPath.imageData);
   }
 
   async transform(frame: VideoFrame, controller: TransformStreamDefaultController<VideoFrame>) {

From e1399c32a880810eeabde277be4f876a9b757584 Mon Sep 17 00:00:00 2001
From: Ryan Gaus <rsg1egoman@gmail.com>
Date: Thu, 4 Sep 2025 13:37:12 -0400
Subject: [PATCH 3/3] docs(changeset): cache background image rather than
 refetch it every time it is enabled

---
 .changeset/legal-kings-fly.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/legal-kings-fly.md

diff --git a/.changeset/legal-kings-fly.md b/.changeset/legal-kings-fly.md
new file mode 100644
index 0000000..c547141
--- /dev/null
+++ b/.changeset/legal-kings-fly.md
@@ -0,0 +1,5 @@
+---
+'@livekit/track-processors': patch
+---
+
+cache background image rather than refetch it every time it is enabled