Attach background effects through one switchable pipeline

- One pipeline, shared by the pre-join preview and the call, attached the
  first time an effect is wanted and never detached after; turning blur
  off switches it to a disabled mode in place. Main dropped the processor
  whenever blur went off, and a pipeline taken off the camera is destroyed
  and re-primed, so each time blur came back one unprocessed frame went
  out. Built once, the priming frame is spent once.
- Still driven by the existing blur setting: nothing a user sees changes.
- Its logic is BackgroundEffects in src/state/, which the provider only
  builds, so the tests drive it without rendering anything.
- Disabled drops the blur radius too. The SDK's disabled mode keeps it,
  and with a radius every frame is still segmented and thrown away; with
  neither a radius nor a picture, frames pass untouched.
- Switches run one at a time and skip any overtaken, so an earlier,
  slower switch can't land after a later choice.
- Builds, rebuilds and teardowns of the pipeline run one at a time
  (OneStepPipeline). The preview's and the call's tracks attach and stop
  it independently, and the SDK's wrapper holds one track's streams: two
  builds at once overwrite each other's, and a stop during a build does
  nothing.
- Every camera track starts with the pipeline on: the room's capture
  defaults follow it, and a camera turned off before the first effect is
  replaced on turning it on, since a stopped track can't take one. One
  attached after publishing lets the room through while it is built.
- BlurBackgroundTransformer becomes BackgroundEffectTransformer: it also
  sits disabled, and its init applies that state as the SDK's would.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

src/livekit/TrackProcessorContext.tsx

@@ -1,12 +1,13 @@
 /*
 Copyright 2024-2025 New Vector Ltd.
+Copyright 2026 Element Creations Ltd.
 
 SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
 Please see LICENSE in the repository root for full details.
 */
 
 import {
-  ProcessorWrapper,
+  type ProcessorWrapper,
   supportsBackgroundProcessors as supportsBackgroundProcessorsLivekitSdk,
   type BackgroundOptions,
 } from "@livekit/track-processors";
@@ -16,21 +17,20 @@ import {
   type JSX,
   use,
   useEffect,
-  useMemo,
+  useState,
 } from "react";
 import { type LocalVideoTrack } from "livekit-client";
 import { logger } from "matrix-js-sdk/lib/logger";
 import { combineLatest } from "rxjs";
 
-import {
-  backgroundBlur as backgroundBlurSettings,
-  useSetting,
-} from "../settings/settings";
-import { BlurBackgroundTransformer } from "./BlurBackgroundTransformer";
+import { backgroundBlur as backgroundBlurSettings } from "../settings/settings";
+import { BackgroundEffectTransformer } from "./BackgroundEffectTransformer";
+import { OneStepPipeline } from "./OneStepPipeline";
 import { type Behavior } from "../state/Behavior";
-import { type ObservableScope } from "../state/ObservableScope";
+import { ObservableScope } from "../state/ObservableScope";
+import { BackgroundEffects } from "../state/BackgroundEffects";
+import { useBehavior } from "../useBehavior";
 import { platform } from "../Platform";
-import { useValueBehavior } from "../useValueBehavior";
 
 //TODO-MULTI-SFU: This is not yet fully there.
 // it is a combination of exposing observable and react hooks.
@@ -41,19 +41,21 @@ export type ProcessorState = {
   processor: undefined | ProcessorWrapper<BackgroundOptions>;
 };
 
-const ProcessorContext = createContext<ProcessorState | undefined>(undefined);
+const ProcessorContext = createContext<BackgroundEffects | undefined>(
+  undefined,
+);
 
 export function useTrackProcessor(): ProcessorState {
-  const state = use(ProcessorContext);
-  if (state === undefined)
-    throw new Error(
-      "useTrackProcessor must be used within a ProcessorProvider",
-    );
-  return state;
+  return useBehavior(useTrackProcessorState$());
 }
 
 export function useTrackProcessorState$(): Behavior<ProcessorState> {
-  return useValueBehavior(useTrackProcessor());
+  const effects = use(ProcessorContext);
+  if (effects === undefined)
+    throw new Error(
+      "useTrackProcessor must be used within a ProcessorProvider",
+    );
+  return effects.state$;
 }
 
 /**
@@ -73,8 +75,13 @@ export function applyProcessor(
       logger.debug("Not attaching video processor to an ended track");
       return;
     }
+    const track = videoTrack.mediaStreamTrack;
     videoTrack.setProcessor(processor).catch((e) => {
-      logger.warn("Failed to attach video processor", e);
+      // The pipeline builds one track at a time, so a track can end while its
+      // build waits a turn. The camera's next track attaches it again.
+      if (track.readyState === "ended")
+        logger.debug("Video processor not attached: the track ended first");
+      else logger.warn("Failed to attach video processor", e);
     });
   }
   if (!processor && videoTrack.getProcessor()) {
@@ -120,26 +127,22 @@ function supportsBackgroundProcessors(): boolean {
 }
 
 export const ProcessorProvider: FC<Props> = ({ children }) => {
-  // The setting the user wants to have
-  const [blurActivated] = useSetting(backgroundBlurSettings);
-  const supported = useMemo(() => supportsBackgroundProcessors(), []);
-  const blur = useMemo(
-    () =>
-      new ProcessorWrapper(
-        new BlurBackgroundTransformer({ blurRadius: 15 }),
-        "background-blur",
-      ),
-    [],
-  );
+  const [effects, setEffects] = useState<BackgroundEffects | null>(null);
+  useEffect(() => {
+    const scope = new ObservableScope();
+    setEffects(
+      new BackgroundEffects(scope, {
+        supported: supportsBackgroundProcessors(),
+        blur$: backgroundBlurSettings.value$,
+        pipeline: new OneStepPipeline(
+          new BackgroundEffectTransformer({ backgroundDisabled: true }),
+          "background-effect",
+        ),
+      }),
+    );
+    return (): void => scope.end();
+  }, []);
 
-  // This is the actual state exposed through the context
-  const processorState = useMemo(
-    () => ({
-      supported,
-      processor: supported && blurActivated ? blur : undefined,
-    }),
-    [supported, blurActivated, blur],
-  );
-
-  return <ProcessorContext value={processorState}>{children}</ProcessorContext>;
+  if (effects === null) return null;
+  return <ProcessorContext value={effects}>{children}</ProcessorContext>;
 };