Background image flickers when loading new image

[lebaudantoine]

Issue: Backgroundf image flickers when loading new image

Description
When loading a new background image in loadAndSetBackground, the currently active background is removed before the new image has been set. This causes a short but noticeable flicker (background disappears briefly, then reappears with the new image).

On my MacBook, the flicker is barely noticeable. However, users with slower CPUs, GPUs, or limited RAM experience a more visible blink that can last up to half a second or longer.

Code Snippet

async loadAndSetBackground(path: string) {
  if (!this.backgroundImageAndPath || this.backgroundImageAndPath?.path !== 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);
    this.backgroundImageAndPath = { imageData, path };
  }
  this.gl?.setBackgroundImage(this.backgroundImageAndPath.imageData);
}

Problem
Even before setBackgroundImage() is called with the new image data, the previously set background seems to be destroyed. Adding a debug stop confirmed that the old background is gone while the new one is still loading.

Enregistrement.de.l.ecran.2025-09-17.a.22.44.38.mov

Expected Behavior

• The old background should remain visible until the new one has been fully loaded.
• Once ready, the new background should smoothly replace the previous one, avoiding any flicker.

[1egoman]

@lebaudantoine Would you be able to verify that after enabling the background image, disabling, and re-enabling, the background image data is cached within the this.backgroundImageAndPath field in the debugger? From your video, it seems like it isn't but that would be good to confirm. If that isn't set, then the background image caching definitely isn't working in your case.

I am not sure exactly how your application works, but if you aren't already, you might consider using the background hot swap functionality that was added to the examples a few months back. More info on this: #94. If I had to guess, it seems like you are adding / fully removing the track processor in your application when enabling a virtual background, which tends to result in this flickering unfortunately because of how the track processor infrastructure was architected (technical details, if you are curious: #96).

The only way I have found to reliably eliminate the flickering in my own tests locally is to enable the track processor on the room when the connection starts, and then dynamically update the track processor's properties using the earlier mentioned approach to enable / disable it. If you can come up with something that works better I'd be interested in hearing about it!

[1egoman]

I think the new updates to the example that have been included as part of #107 should address this, so I am closing this issue. If there's another part of this I missed let me know and I can reopen!