[SDK] Capture local media ahead of the join and hand it to the participation

A lobby captures the microphone and the camera on the browser's devices
alone, with `createLocalMedia`, so that any backend can take them over:
`LocalMedia` hands out the same `LocalAudioMediaTrack` and
`LocalVideoMediaTrack` a call renders, with mute, device and facing
switches and the host's `VideoProcessor` run on the preview. Given to
`join` as `publish`, the tracks are moved rather than shared: the
publisher takes them over as it starts publishing, their lobby objects
are finished, and the LiveKit backend adopts the device tracks as its
own and the processor with its running output, so the join captures
nothing and initialises nothing again.

Also here, found on the way: a track already on the requested device is
left alone (LiveKit would restart it, always on Firefox, which echoes no
device id in `getConstraints()`), identical captures in flight are
coalesced (React's strict mode mounts twice), and every operation on a
processor takes its turn, since a stopped track tears its processor down
without waiting for the next track's init.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

sdk/SdkArchitecture.md

@@ -126,10 +126,15 @@ probe that decides whether the service that issued the token can take over the
 delayed leave, which picks the delayed leave timings the join uses. The join
 waits for the publisher to hold its token, so that the LiveKit room exists
 before a subscriber, who lacks the permission to create it, asks for a token
-of its own. Until `join()` the tracks exist but their upstream is paused: a host
-can show a preview without anyone hearing it. The upstream flows exactly while the
-membership is `joined`: a sync outage pauses it, and `leave()` pauses it for good
-and sends the leave.
+of its own. The tracks are created once the membership is `joined`, with their
+upstream paused until then. A lobby that wants them earlier captures them with
+`createLocalMedia`, on the browser's devices alone so that any backend fits, and
+hands the media to `join()` as `publish`: the tracks are moved, not shared — they
+leave the lobby's `tracks$`, their objects are finished, and the backend
+publishes the very same device tracks and the processor already running on them,
+so nothing is captured or initialised again at the join. The upstream flows
+exactly while the membership is `joined`: a sync outage pauses it, and `leave()`
+pauses it for good and sends the leave.
 
 ## Vocabulary
 

sdk/index.ts

@@ -61,8 +61,8 @@ export {
   createLivekitBackend,
   type LivekitBackendOptions,
 } from "./src/media-backend/livekit/LivekitBackend";
-// For a host that creates LiveKit tracks itself, such as a preview before joining
-export { convertToLivekitProcessor } from "./src/media-backend/livekit/videoProcessor";
+// Tracks for a lobby, captured ahead of the join and handed to it
+export { createLocalMedia } from "./src/LocalMedia";
 // For a developer panel to check a transport before using it
 export {
   getSFUConfig as authenticateWithTransport,

sdk/src/LocalMedia.test.ts

@@ -0,0 +1,237 @@
+/*
+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 { beforeAll, describe, expect, it, vi } from "vitest";
+
+import { createLocalMedia, type GetUserMedia } from "./LocalMedia";
+import { type LocalVideoMediaTrack, type VideoProcessor } from "./media-api";
+
+describe("createLocalMedia", () => {
+  it("opens the microphone and the camera in one request", async () => {
+    const getUserMedia = fakeGetUserMedia();
+    const media = createLocalMedia(getUserMedia);
+
+    const tracks = await media.capture([
+      { source: "microphone", deviceId: "mic" },
+      {
+        source: "camera",
+        capture: { resolution: { width: 640, height: 480 } },
+      },
+    ]);
+
+    expect(getUserMedia).toHaveBeenCalledExactlyOnceWith({
+      audio: { deviceId: "mic" },
+      video: { width: 640, height: 480, frameRate: undefined },
+    });
+    expect(tracks.map((t) => t.source)).toEqual(["microphone", "camera"]);
+    expect(media.tracks$.value).toEqual(tracks);
+    expect(media.requests.map((r) => r.source)).toEqual([
+      "microphone",
+      "camera",
+    ]);
+  });
+
+  it("joins an identical capture still in flight rather than opening the devices again", async () => {
+    const getUserMedia = fakeGetUserMedia();
+    const media = createLocalMedia(getUserMedia);
+    const requests = [{ source: "camera" as const }];
+
+    const [first, second] = await Promise.all([
+      media.capture(requests),
+      media.capture(requests),
+    ]);
+
+    expect(getUserMedia).toHaveBeenCalledOnce();
+    expect(second).toEqual(first);
+    expect(media.tracks$.value).toEqual(first);
+  });
+
+  it("shows the processor's output, initialised once", async () => {
+    const processor = fakeProcessor();
+    const media = createLocalMedia(fakeGetUserMedia());
+    const [camera] = await media.capture([{ source: "camera", processor }]);
+    const element = document.createElement("video");
+
+    camera.attach(element);
+
+    expect(processor.init).toHaveBeenCalledOnce();
+    expect(tracksOn(element)).toEqual([processor.output]);
+  });
+
+  it("hands the tracks over as they are: no second capture, no second init", async () => {
+    const getUserMedia = fakeGetUserMedia();
+    const processor = fakeProcessor();
+    const media = createLocalMedia(getUserMedia);
+    const [microphone, camera] = await media.capture([
+      { source: "microphone" },
+      { source: "camera", processor },
+    ]);
+
+    const taken = media.takeTracks();
+
+    expect(taken.get("microphone")?.track).toBe(trackBehind(microphone));
+    expect(taken.get("camera")).toEqual({
+      track: trackBehind(camera),
+      constraints: {},
+      muted: false,
+      processor: { processor, processedTrack: processor.output },
+    });
+    expect(media.tracks$.value).toEqual([]);
+    expect(getUserMedia).toHaveBeenCalledOnce();
+    expect(processor.init).toHaveBeenCalledOnce();
+    expect(processor.destroy).not.toHaveBeenCalled();
+    media.stop();
+    expect(taken.get("camera")!.track.stop).not.toHaveBeenCalled();
+  });
+
+  it("finishes a handed-over track", async () => {
+    const media = createLocalMedia(fakeGetUserMedia());
+    const [camera] = await media.capture([{ source: "camera" }]);
+    const element = document.createElement("video");
+    camera.attach(element);
+
+    media.takeTracks();
+
+    expect(element.srcObject).toBeNull();
+    await expect(camera.setEnabled(false)).rejects.toThrow("handed over");
+    expect(() => camera.attach(element)).toThrow("handed over");
+  });
+
+  it("mutes by disabling the track and hands the mute over", async () => {
+    const media = createLocalMedia(fakeGetUserMedia());
+    const [microphone] = await media.capture([{ source: "microphone" }]);
+
+    await expect(microphone.setEnabled(false)).resolves.toBe(false);
+
+    expect(microphone.muted$.value).toBe(true);
+    expect(trackBehind(microphone).enabled).toBe(false);
+    expect(media.takeTracks().get("microphone")?.muted).toBe(true);
+  });
+
+  it("switches the device by opening it anew", async () => {
+    const getUserMedia = fakeGetUserMedia();
+    const processor = fakeProcessor();
+    const media = createLocalMedia(getUserMedia);
+    const [camera] = await media.capture([{ source: "camera", processor }]);
+    const first = trackBehind(camera);
+    const element = document.createElement("video");
+    camera.attach(element);
+
+    await camera.setDevice("other");
+
+    expect(getUserMedia).toHaveBeenLastCalledWith({
+      video: { deviceId: "other" },
+    });
+    expect(first.stop).toHaveBeenCalled();
+    expect(processor.restart).toHaveBeenCalledOnce();
+    const [restartedOn, input] = vi.mocked(processor.restart).mock.calls[0];
+    expect(restartedOn).not.toBe(first);
+    expect(input).toBe(vi.mocked(processor.init).mock.calls[0][1]);
+    expect(tracksOn(element)).toEqual([processor.output]);
+    expect(media.takeTracks().get("camera")?.constraints).toEqual({
+      deviceId: "other",
+    });
+  });
+
+  it("reports the facing mode and switches it", async () => {
+    const getUserMedia = fakeGetUserMedia({ facingMode: "user" });
+    const media = createLocalMedia(getUserMedia);
+    const [camera] = (await media.capture([{ source: "camera" }])) as [
+      LocalVideoMediaTrack,
+    ];
+    expect(camera.facingMode$.value).toBe("user");
+
+    await camera.switchFacingMode();
+
+    expect(getUserMedia).toHaveBeenLastCalledWith({
+      video: { facingMode: "environment" },
+    });
+  });
+
+  it("releases one device and stops the rest", async () => {
+    const media = createLocalMedia(fakeGetUserMedia());
+    const [microphone, camera] = await media.capture([
+      { source: "microphone" },
+      { source: "camera" },
+    ]);
+
+    media.release("camera");
+    expect(trackBehind(camera).stop).toHaveBeenCalled();
+    expect(media.tracks$.value).toEqual([microphone]);
+
+    media.stop();
+    expect(trackBehind(microphone).stop).toHaveBeenCalled();
+    expect(media.tracks$.value).toEqual([]);
+  });
+
+  it("refuses a screen share", async () => {
+    const media = createLocalMedia(fakeGetUserMedia());
+    await expect(media.capture([{ source: "screenShare" }])).rejects.toThrow(
+      "screen share",
+    );
+  });
+});
+
+class FakeMediaStream {
+  public constructor(private readonly tracks: MediaStreamTrack[]) {}
+  public getTracks(): MediaStreamTrack[] {
+    return this.tracks;
+  }
+}
+
+beforeAll(() => {
+  globalThis.MediaStream = FakeMediaStream as unknown as typeof MediaStream;
+});
+
+let nextId = 0;
+const tracksById = new Map<string, MediaStreamTrack>();
+
+function fakeTrack(
+  kind: "audio" | "video",
+  settings: MediaTrackSettings = {},
+): MediaStreamTrack {
+  const track = {
+    kind,
+    id: `${kind}-${nextId++}`,
+    enabled: true,
+    stop: vi.fn(),
+    getSettings: () => settings,
+  } as unknown as MediaStreamTrack;
+  tracksById.set(track.id, track);
+  return track;
+}
+
+function fakeGetUserMedia(videoSettings?: MediaTrackSettings): GetUserMedia {
+  return vi.fn(async (constraints: MediaStreamConstraints) => {
+    const tracks: MediaStreamTrack[] = [];
+    if (constraints.audio) tracks.push(fakeTrack("audio"));
+    if (constraints.video) tracks.push(fakeTrack("video", videoSettings));
+    return Promise.resolve(
+      new FakeMediaStream(tracks) as unknown as MediaStream,
+    );
+  });
+}
+
+function fakeProcessor(): VideoProcessor & { output: MediaStreamTrack } {
+  const output = fakeTrack("video");
+  return {
+    name: "blur",
+    output,
+    init: vi.fn(async () => Promise.resolve(output)),
+    restart: vi.fn(async () => Promise.resolve(output)),
+    destroy: vi.fn(async () => Promise.resolve()),
+  };
+}
+
+/** The device's track, which a media track was created on and keeps the id of. */
+function trackBehind(mediaTrack: { id: string }): MediaStreamTrack {
+  return tracksById.get(mediaTrack.id)!;
+}
+
+function tracksOn(element: HTMLMediaElement): MediaStreamTrack[] {
+  return (element.srcObject as unknown as FakeMediaStream).getTracks();
+}

sdk/src/LocalMedia.ts

@@ -0,0 +1,335 @@
+/*
+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 { BehaviorSubject, type Observable, of } from "rxjs";
+
+import { MatrixRTCError } from "./errors";
+import {
+  type HandedOverTrack,
+  type LocalAudioMediaTrack,
+  type LocalMedia,
+  type LocalVideoMediaTrack,
+  type MediaSource,
+  type MediaStreamStats,
+  type PublishRequest,
+  type VideoProcessor,
+} from "./media-api";
+import { constant } from "./reactive/Behavior";
+import { inTurn } from "./utils/processorTurns";
+
+type Source = "microphone" | "camera";
+type Request = Extract<PublishRequest, { source: Source }>;
+export type GetUserMedia = (
+  constraints: MediaStreamConstraints,
+) => Promise<MediaStream>;
+
+/**
+ * Local media on the browser's devices alone, for a lobby ahead of a join:
+ * no backend is involved, so whichever backend joins can take the tracks
+ * over. Activity and level are not measured; stats are none.
+ */
+export function createLocalMedia(
+  getUserMedia: GetUserMedia = async (constraints) =>
+    navigator.mediaDevices.getUserMedia(constraints),
+): LocalMedia {
+  const capturedTracks = new Map<Source, CapturedTrack>();
+  const requests = new Map<Source, Request>();
+  const tracks$ = new BehaviorSubject<
+    (LocalAudioMediaTrack | LocalVideoMediaTrack)[]
+  >([]);
+  const publishCapturedTracks = (): void =>
+    tracks$.next(
+      [...capturedTracks.values()].map(({ mediaTrack }) => mediaTrack),
+    );
+
+  // A second identical capture while the first is open joins it: a host that
+  // mounts twice (React's strict mode) must not open the devices twice and
+  // replace the tracks it is already showing
+  const pending = new Map<
+    string,
+    Promise<(LocalAudioMediaTrack | LocalVideoMediaTrack)[]>
+  >();
+  const capture = async (
+    wanted: PublishRequest[],
+  ): Promise<(LocalAudioMediaTrack | LocalVideoMediaTrack)[]> => {
+    const key = JSON.stringify(
+      wanted.map((request) => ({ ...request, processor: undefined })),
+    );
+    const running = pending.get(key);
+    if (running) return running;
+    const started = captureNow(wanted).finally(() => pending.delete(key));
+    pending.set(key, started);
+    return started;
+  };
+
+  const captureNow = async (
+    wanted: PublishRequest[],
+  ): Promise<(LocalAudioMediaTrack | LocalVideoMediaTrack)[]> => {
+    const bySource = new Map<Source, Request>();
+    for (const request of wanted) {
+      if (request.source === "screenShare")
+        throw new MatrixRTCError(
+          "A screen share cannot be captured ahead of a join",
+        );
+      bySource.set(request.source, request);
+    }
+    const constraints: MediaStreamConstraints = {};
+    for (const request of bySource.values())
+      constraints[request.source === "microphone" ? "audio" : "video"] =
+        trackConstraints(request);
+    const stream = await getUserMedia(constraints);
+    const captured: CapturedTrack[] = [];
+    for (const track of stream.getTracks()) {
+      const source: Source = track.kind === "audio" ? "microphone" : "camera";
+      const request = bySource.get(source)!;
+      capturedTracks.get(source)?.stop();
+      const captured_ = new CapturedTrack(
+        source,
+        track,
+        trackConstraints(request),
+        getUserMedia,
+      );
+      capturedTracks.set(source, captured_);
+      requests.set(source, request);
+      if (request.source === "camera" && request.processor)
+        await captured_.setProcessor(request.processor);
+      captured.push(captured_);
+    }
+    publishCapturedTracks();
+    return captured.map(({ mediaTrack }) => mediaTrack);
+  };
+
+  const release = (source: MediaSource): void => {
+    if (source !== "microphone" && source !== "camera") return;
+    capturedTracks.get(source)?.stop();
+    capturedTracks.delete(source);
+    publishCapturedTracks();
+  };
+
+  const stop = (): void => {
+    for (const track of capturedTracks.values()) track.stop();
+    capturedTracks.clear();
+    publishCapturedTracks();
+  };
+
+  const takeTracks = (): Map<Source, HandedOverTrack> => {
+    const taken = new Map<Source, HandedOverTrack>();
+    for (const [source, track] of capturedTracks)
+      taken.set(source, track.handOver());
+    capturedTracks.clear();
+    publishCapturedTracks();
+    return taken;
+  };
+
+  return {
+    get requests(): PublishRequest[] {
+      return [...requests.values()];
+    },
+    tracks$,
+    capture,
+    release,
+    stop,
+    takeTracks,
+  };
+}
+
+/** The constraints a request means to the browser. */
+function trackConstraints(request: Request): MediaTrackConstraints {
+  const device = request.deviceId && { deviceId: request.deviceId };
+  if (request.source === "microphone") return { ...device, ...request.capture };
+  const resolution = request.capture?.resolution;
+  return {
+    ...device,
+    ...(resolution && {
+      width: resolution.width,
+      height: resolution.height,
+      frameRate: resolution.frameRate,
+    }),
+  };
+}
+
+/**
+ * Internal Class that is the owner of the tracks.
+ * Will get stored in `capturedTracks` of `createLocalMedia`.
+ * To the outside this class will return the `LocalMedia` interface.
+ */
+class CapturedTrack {
+  public readonly mediaTrack: LocalAudioMediaTrack | LocalVideoMediaTrack;
+  private readonly muted$ = new BehaviorSubject(false);
+  private readonly facingMode$: BehaviorSubject<
+    "user" | "environment" | undefined
+  >;
+  private readonly elements = new Set<HTMLMediaElement>();
+  private processor: HandedOverTrack["processor"];
+  /** What the processor reads frames from; a processor needs a playing element. */
+  private processorInput?: HTMLVideoElement;
+  private finished = false;
+
+  public constructor(
+    public readonly source: Source,
+    private track: MediaStreamTrack,
+    private constraints: MediaTrackConstraints,
+    private readonly getUserMedia: GetUserMedia,
+  ) {
+    this.facingMode$ = new BehaviorSubject(facingModeOf(track));
+    this.mediaTrack = this.asMediaTrack();
+  }
+
+  public handOver(): HandedOverTrack {
+    const { track, processor } = this;
+    // The device actually in use, so that a backend asked for it again
+    // recognises it rather than restarting the track
+    const { deviceId } = track.getSettings();
+    const constraints = { ...this.constraints, ...(deviceId && { deviceId }) };
+    this.finish();
+    return { track, constraints, muted: this.muted$.value, processor };
+  }
+
+  public stop(): void {
+    const { processor } = this;
+    if (processor)
+      void inTurn(processor.processor, async () =>
+        processor.processor.destroy(),
+      );
+    this.processor?.processedTrack.stop();
+    this.track.stop();
+    this.finish();
+  }
+
+  public async setProcessor(
+    processor: VideoProcessor | undefined,
+  ): Promise<void> {
+    this.live();
+    if (processor === this.processor?.processor) return;
+    const previous = this.processor?.processor;
+    if (previous) await inTurn(previous, async () => previous.destroy());
+    this.processor = processor && {
+      processor,
+      processedTrack: await inTurn(processor, async () =>
+        processor.init(this.track, this.input()),
+      ),
+    };
+    this.show();
+  }
+
+  private input(): HTMLVideoElement {
+    this.processorInput ??= document.createElement("video");
+    this.processorInput.muted = true;
+    this.processorInput.playsInline = true;
+    play(this.processorInput, this.track);
+    return this.processorInput;
+  }
+
+  private finish(): void {
+    this.finished = true;
+    for (const element of this.elements) element.srcObject = null;
+    this.elements.clear();
+  }
+
+  private live(): void {
+    if (this.finished)
+      throw new MatrixRTCError(
+        `The ${this.source} was handed over to a participation`,
+      );
+  }
+
+  private shown(): MediaStreamTrack {
+    return this.processor?.processedTrack ?? this.track;
+  }
+
+  private show(): void {
+    for (const element of this.elements) play(element, this.shown());
+  }
+
+  private async reacquire(constraints: MediaTrackConstraints): Promise<void> {
+    this.live();
+    this.constraints = { ...this.constraints, ...constraints };
+    const stream = await this.getUserMedia({
+      [this.track.kind]: this.constraints,
+    });
+    this.track.stop();
+    this.track = stream.getTracks()[0];
+    this.track.enabled = !this.muted$.value;
+    const { processor } = this;
+    if (processor)
+      processor.processedTrack = await inTurn(processor.processor, async () =>
+        processor.processor.restart(this.track, this.input()),
+      );
+    this.facingMode$.next(facingModeOf(this.track));
+    this.show();
+  }
+
+  private asMediaTrack(): LocalAudioMediaTrack | LocalVideoMediaTrack {
+    const base = {
+      source: this.source,
+      id: this.track.id,
+      muted$: this.muted$,
+      // Nothing leaves the device before the track is published, so there is
+      // nothing unencrypted to report
+      encrypted: true,
+      stats$: (): Observable<MediaStreamStats> => of(undefined),
+      attach: (element: HTMLMediaElement): void => {
+        this.live();
+        this.elements.add(element);
+        play(element, this.shown());
+      },
+      detach: (element: HTMLMediaElement): void => {
+        if (this.elements.delete(element)) element.srcObject = null;
+      },
+      setEnabled: async (enabled: boolean): Promise<boolean> => {
+        this.live();
+        this.track.enabled = enabled;
+        this.muted$.next(!enabled);
+        return Promise.resolve(enabled);
+      },
+      setDevice: async (deviceId: string): Promise<void> => {
+        if (this.track.getSettings().deviceId === deviceId) return;
+        await this.reacquire({ deviceId });
+      },
+    };
+    if (this.source === "microphone")
+      return {
+        ...base,
+        kind: "audio",
+        isActive$: constant(false),
+        audioLevel$: constant(0),
+        setAudioContext: () => {},
+        setVolume: () => {},
+      };
+    return {
+      ...base,
+      kind: "video",
+      facingMode$: this.facingMode$,
+      switchFacingMode: async () => {
+        const facingMode = this.facingMode$.value;
+        if (facingMode === undefined) return;
+        await this.reacquire({
+          facingMode: facingMode === "user" ? "environment" : "user",
+        });
+        return this.track.getSettings().deviceId;
+      },
+      setProcessor: async (processor) => this.setProcessor(processor),
+    };
+  }
+}
+
+function play(element: HTMLMediaElement, track: MediaStreamTrack): void {
+  element.srcObject = new MediaStream([track]);
+  // Autoplay is not a given for a stream set after mount; a test DOM returns
+  // nothing from play
+  const playing = element.play() as Promise<void> | undefined;
+  playing?.catch(() => undefined);
+}
+
+function facingModeOf(
+  track: MediaStreamTrack,
+): "user" | "environment" | undefined {
+  const { facingMode } = track.getSettings();
+  return facingMode === "user" || facingMode === "environment"
+    ? facingMode
+    : undefined;
+}

sdk/src/api.ts

@@ -20,6 +20,7 @@ import { type Observable } from "rxjs";
 import { type Behavior } from "./reactive/Behavior";
 import {
   type LocalAudioMediaTrack,
+  type LocalMedia,
   type LocalMemberMedia,
   type LocalVideoMediaTrack,
   type MediaSource,
@@ -84,12 +85,15 @@ export interface RTCSlot {
 
 export interface RTCParticipationOptions {
   /**
-   * Published at the join; `publish` on the participation adds to it from then
-   * on. Kept as an option, rather than only the method, because the LiveKit
-   * backend reads the initial requests to build the room's default capture
-   * options before the first connection exists.
+   * What the local member publishes at the join: requests the SDK captures
+   * itself, or the media a lobby captured ahead of the join, which the
+   * participation takes over (its tracks leave `media.tracks$`) and publishes
+   * in place of capturing. `publish` on the participation adds to either from
+   * then on. Kept as an option, rather than only the method, because the
+   * LiveKit backend reads it to build the room's default capture options
+   * before the first connection exists.
    */
-  publish: PublishRequest[];
+  publish: PublishRequest[] | LocalMedia;
   /**
    * LEGACY
    *

sdk/src/media-api.ts

@@ -185,3 +185,45 @@ export interface MemberMedia {
 export interface LocalMemberMedia extends MemberMedia {
   tracks$: Behavior<(LocalAudioMediaTrack | LocalVideoMediaTrack)[] | null>;
 }
+
+/**
+ * Tracks captured ahead of a join, for a lobby: the same local tracks a
+ * participation hands out, on nothing but the browser's devices, so they fit
+ * whichever backend joins. Handed to `join` as `publish`, they are moved once
+ * the participation publishes them: they leave `tracks$`, their objects are
+ * finished (controls reject, elements detached), and the same devices come
+ * back under `localMember$.tracks$` as new objects. `stop` releases only what
+ * was not moved; `capture` works again afterwards.
+ */
+export interface LocalMedia {
+  /** What was captured with, one per source; a join reads its defaults from here. */
+  readonly requests: PublishRequest[];
+  tracks$: Behavior<(LocalAudioMediaTrack | LocalVideoMediaTrack)[]>;
+  /**
+   * Opens the devices, in one permission prompt where the browser asks for
+   * one. Rejects where a device cannot be opened, having opened none of them.
+   * A source captured already is replaced.
+   */
+  capture(
+    requests: PublishRequest[],
+  ): Promise<(LocalAudioMediaTrack | LocalVideoMediaTrack)[]>;
+  /** Closes the device behind a source; nothing where it was not captured. */
+  release(source: MediaSource): void;
+  /** Closes every device still held. */
+  stop(): void;
+  /**
+   * For a media backend, as it starts publishing: moves every track out,
+   * finishing its object here. Not for a host; the participation calls it.
+   */
+  takeTracks(): Map<"microphone" | "camera", HandedOverTrack>;
+}
+
+/** One track as a backend receives it: the device's own track and what runs on it. */
+export interface HandedOverTrack {
+  track: MediaStreamTrack;
+  /** What it was opened with, for a backend that restarts it. */
+  constraints: MediaTrackConstraints;
+  muted: boolean;
+  /** Where a processor runs: it and its output, to adopt rather than initialise again. */
+  processor?: { processor: VideoProcessor; processedTrack: MediaStreamTrack };
+}

sdk/src/media-backend/api.ts

@@ -20,6 +20,7 @@ import { type Observable } from "rxjs";
 import { type ResolvedTransport, type RTCMember } from "../api";
 import {
   type LocalAudioMediaTrack,
+  type LocalMedia,
   type LocalMemberMedia,
   type LocalVideoMediaTrack,
   type MediaSource,
@@ -56,8 +57,8 @@ export interface MediaBackendContext {
   /** The slot the session is in, `application#id`; a token is issued for it. */
   slotId: string;
   ownMembershipIdentity: CallMembershipIdentityParts;
-  /** What the local member publishes at the join. */
-  publish: PublishRequest[];
+  /** What the local member publishes at the join: requests, or a lobby's media. */
+  publish: PublishRequest[] | LocalMedia;
   encryptionSystem: EncryptionSystem;
   /**
    * Every media key the session knows: the current ones replayed on

sdk/src/media-backend/livekit/LivekitBackend.ts

@@ -92,7 +92,7 @@ export function createLivekitBackend(
     roomId,
     slotId,
     ownMembershipIdentity,
-    publish,
+    publish: requestsOrMedia,
     encryptionSystem,
     mediaKeys$,
     timings,
@@ -101,6 +101,9 @@ export function createLivekitBackend(
   { client, mediaQuality }: LivekitBackendOptions,
 ): MediaBackend {
   const logger = parentLogger.getChild("[LivekitBackend]");
+  const [publish, media] = Array.isArray(requestsOrMedia)
+    ? [requestsOrMedia, undefined]
+    : [requestsOrMedia.requests, requestsOrMedia];
   const keyProvider = createKeyProvider(encryptionSystem, mediaKeys$, logger);
   const transports = createTransportRegistry(scope);
   const localTransport$ = new BehaviorSubject<TransportLocator | null>(null);
@@ -137,6 +140,7 @@ export function createLivekitBackend(
     connectionMap$,
     localTransport$,
     publish,
+    media,
     audioOutputDeviceId$,
     encryptionSystem,
     logger,

sdk/src/media-backend/livekit/LivekitMediaTrack.test.ts

@@ -205,7 +205,11 @@ describe("createLivekitMediaTrack", () => {
     await expect(track.setEnabled(false)).resolves.toBe(false);
     expect(setEnabled).toHaveBeenCalledWith("microphone", false);
     await track.setDevice("mic-2");
-    expect(switchActiveDevice).toHaveBeenCalledWith("audioinput", "mic-2");
+    expect(switchActiveDevice).toHaveBeenCalledWith(
+      "audioinput",
+      "mic-2",
+      false,
+    );
   });
 });
 

sdk/src/media-backend/livekit/LivekitMediaTrack.ts

@@ -50,7 +50,10 @@ import {
   type VideoMediaTrack,
 } from "../../media-api";
 import { MatrixRTCError } from "../../errors";
-import { convertToLivekitProcessor } from "./videoProcessor";
+import {
+  convertToLivekitProcessor,
+  type LivekitProcessor,
+} from "./videoProcessor";
 
 export const mediaSources: Record<Track.Source, MediaSource> = {
   [Track.Source.Microphone]: "microphone",
@@ -197,9 +200,19 @@ export function createLocalLivekitMediaTrack(
     setDevice: async (deviceId: string): Promise<void> => {
       if (base.source !== "microphone" && base.source !== "camera")
         throw new MatrixRTCError(`A ${base.source} track has no device`);
+      // LiveKit decides whether to restart by the constraints it keeps, which
+      // a browser that does not echo the device id back (Firefox) leaves
+      // without one; a track already on the device is left alone here
+      const current = publication.track;
+      if (
+        current instanceof LocalTrack &&
+        current.mediaStreamTrack.getSettings().deviceId === deviceId
+      )
+        return;
       await room.switchActiveDevice(
         base.kind === "audio" ? "audioinput" : "videoinput",
         deviceId,
+        false,
       );
     },
   };
@@ -230,9 +243,11 @@ export function createLocalLivekitMediaTrack(
       const track = videoTrack();
       // A processor cannot be built on a track that has already ended
       if (!track || track.mediaStreamTrack.readyState === "ended") return;
+      const current = track.getProcessor() as LivekitProcessor | undefined;
+      if (processor === current?.source) return;
       if (processor)
         await track.setProcessor(convertToLivekitProcessor(processor));
-      else if (track.getProcessor()) await track.stopProcessor();
+      else if (current) await track.stopProcessor();
     },
   };
 }

sdk/src/media-backend/livekit/LocalMedia.ts

@@ -27,6 +27,7 @@ import {
 
 import {
   type LocalAudioMediaTrack,
+  type LocalMedia,
   type LocalVideoMediaTrack,
   type MediaSource,
   type PublishRequest,
@@ -57,6 +58,8 @@ interface Props {
   /** The transport we publish on; null until the session has found it. */
   localTransport$: Behavior<TransportLocator | null>;
   publish: PublishRequest[];
+  /** Tracks the host captured ahead of the join; the publisher takes them over. */
+  media?: LocalMedia;
   /** Read by the connection factory for the rooms it creates from now on. */
   audioOutputDeviceId$: BehaviorSubject<string | undefined>;
   encryptionSystem: EncryptionSystem;
@@ -79,6 +82,7 @@ export function createLivekitLocalMedia({
   connectionMap$,
   localTransport$,
   publish: initialRequests,
+  media,
   audioOutputDeviceId$,
   encryptionSystem,
   logger: parentLogger,
@@ -119,6 +123,7 @@ export function createLivekitLocalMedia({
       connection.livekitRoom,
       desired,
       logger.getChild(`[Publisher ${JSON.stringify(connection.transport)}]`),
+      media,
     );
     publisher$.next(publisher);
     return Promise.resolve(async (): Promise<void> => {

sdk/src/media-backend/livekit/Publisher.test.ts

@@ -11,16 +11,32 @@ import {
   LocalParticipant,
   type LocalTrack,
   type LocalTrackPublication,
+  LocalVideoTrack,
   ParticipantEvent,
   type Room as LivekitRoom,
   Track,
+  type TrackPublishOptions,
 } from "livekit-client";
 import { logger } from "matrix-js-sdk/lib/logger";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from "vitest";
 
-import { type PublishRequest } from "../../media-api";
+import {
+  type HandedOverTrack,
+  type LocalMedia,
+  type PublishRequest,
+  type VideoProcessor,
+} from "../../media-api";
 import { flushPromises } from "../../utils/test";
 import { type DesiredMedia, Publisher } from "./Publisher";
+import { type LivekitProcessor } from "./videoProcessor";
 
 describe("Publisher", () => {
   describe("setAudioOutputDevice", () => {
@@ -327,6 +343,143 @@ function fakeRoom(
   return { room, switchActiveDevice };
 }
 
+// A lobby's tracks come as the device's own MediaStreamTracks; LiveKit's
+// track classes are real here so that what is published is what LiveKit will
+// restart and stop as its own
+describe("adopting a lobby's tracks", () => {
+  // LiveKit wraps every track in a MediaStream, which jsdom does not have
+  beforeAll(() => {
+    globalThis.MediaStream = class {
+      public constructor(private readonly tracks: MediaStreamTrack[]) {}
+      public getTracks(): MediaStreamTrack[] {
+        return this.tracks;
+      }
+    } as unknown as typeof MediaStream;
+  });
+
+  function setup(
+    source: "microphone" | "camera",
+    handed: HandedOverTrack,
+  ): { participant: LocalParticipant; publisher: Publisher } {
+    const participant = fakeLocalParticipant(async () => Promise.resolve());
+    const room = {
+      options: {},
+      setE2EEEnabled: () => undefined,
+      localParticipant: participant,
+    } as unknown as LivekitRoom;
+    const desired: DesiredMedia = new Map([
+      [source, { request: { source }, enabled: true }],
+    ]);
+    const media = {
+      takeTracks: () => new Map([[source, handed]]),
+    } as unknown as LocalMedia;
+    const publisher = new Publisher(room, desired, logger, media);
+    return { participant, publisher };
+  }
+
+  it("publishes the lobby's track as its own rather than capturing", async () => {
+    const handed = handedOver("video");
+    const { participant, publisher } = setup("camera", handed);
+
+    publisher.start();
+    await flushPromises();
+
+    expect(participant.createTracks).not.toHaveBeenCalled();
+    const [published, options] = vi.mocked(participant.publishTrack).mock
+      .calls[0] as [LocalVideoTrack, TrackPublishOptions];
+    expect(published).toBeInstanceOf(LocalVideoTrack);
+    expect(published.mediaStreamTrack).toBe(handed.track);
+    expect(published.isUserProvided).toBe(false);
+    expect(options.source).toBe(Track.Source.Camera);
+  });
+
+  it("adopts the processor's output without initialising it again", async () => {
+    const setProcessor = vi
+      .spyOn(LocalVideoTrack.prototype, "setProcessor")
+      .mockResolvedValue(undefined);
+    const processor = {
+      name: "blur",
+      init: vi.fn(),
+      restart: vi.fn(),
+      destroy: vi.fn(),
+    } as unknown as VideoProcessor;
+    const processedTrack = fakeMediaStreamTrack("video");
+    const handed = handedOver("video", {
+      processor: { processor, processedTrack },
+    });
+    const { publisher } = setup("camera", handed);
+
+    publisher.start();
+    await flushPromises();
+
+    const adapter = setProcessor.mock.calls[0][0] as LivekitProcessor;
+    await adapter.init({ kind: Track.Kind.Video, track: handed.track });
+    expect(adapter.processedTrack).toBe(processedTrack);
+    expect(adapter.source).toBe(processor);
+    expect(processor.init).not.toHaveBeenCalled();
+    setProcessor.mockRestore();
+  });
+
+  // A development build mounts, unmounts and mounts the call again: the first
+  // publisher must not have taken the tracks the second one needs
+  it("leaves the lobby's tracks alone until it starts", async () => {
+    const participant = fakeLocalParticipant(async () => Promise.resolve());
+    const room = {
+      options: {},
+      setE2EEEnabled: () => undefined,
+      localParticipant: participant,
+    } as unknown as LivekitRoom;
+    const takeTracks = vi.fn(() => new Map());
+    const media = { takeTracks } as unknown as LocalMedia;
+
+    const publisher = new Publisher(room, new Map(), logger, media);
+    await publisher.destroy();
+
+    expect(takeTracks).not.toHaveBeenCalled();
+  });
+
+  it("joins muted where the lobby muted", async () => {
+    const { participant, publisher } = setup(
+      "microphone",
+      handedOver("audio", { muted: true }),
+    );
+
+    publisher.start();
+    await flushPromises();
+
+    const [published] = vi.mocked(participant.publishTrack).mock.calls[0];
+    expect((published as LocalTrack).isMuted).toBe(true);
+  });
+});
+
+function fakeMediaStreamTrack(kind: "audio" | "video"): MediaStreamTrack {
+  return {
+    kind,
+    id: `${kind}-track`,
+    label: "",
+    enabled: true,
+    readyState: "live",
+    getSettings: () => ({}),
+    getConstraints: () => ({}),
+    getCapabilities: () => ({}),
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+    stop: vi.fn(),
+  } as unknown as MediaStreamTrack;
+}
+
+function handedOver(
+  kind: "audio" | "video",
+  extra: Partial<HandedOverTrack> = {},
+): HandedOverTrack {
+  return {
+    track: fakeMediaStreamTrack(kind),
+    constraints: { deviceId: "lobby" },
+    muted: false,
+    ...extra,
+  };
+}
+
 function fakeLocalTrack(source: Track.Source): LocalTrack {
   const state = { isMuted: false, isUpstreamPaused: false };
   const track = {

sdk/src/media-backend/livekit/Publisher.ts

@@ -6,15 +6,23 @@ Please see LICENSE in the repository root for full details.
 */
 
 import {
+  LocalAudioTrack,
   type LocalTrackPublication,
+  LocalVideoTrack,
   ParticipantEvent,
   type Room as LivekitRoom,
   type Track,
 } from "livekit-client";
 import { type Logger } from "matrix-js-sdk/lib/logger";
 
-import { type MediaSource, type PublishRequest } from "../../media-api";
+import {
+  type HandedOverTrack,
+  type LocalMedia,
+  type MediaSource,
+  type PublishRequest,
+} from "../../media-api";
 import { livekitSources, mediaSources } from "./LivekitMediaTrack";
+import { convertToLivekitProcessor } from "./videoProcessor";
 import {
   audioCaptureOptions,
   screenShareCaptureOptions,
@@ -31,6 +39,9 @@ export interface DesiredPublication {
 
 export type DesiredMedia = Map<MediaSource, DesiredPublication>;
 
+/** A lobby's tracks, moved out of its media, until each is published. */
+export type HandedOverTracks = ReturnType<LocalMedia["takeTracks"]>;
+
 /**
  * Publishes the local media on one LiveKit room, following the host's
  * requests.
@@ -46,10 +57,19 @@ export class Publisher {
   public started = false;
   private readonly room: LivekitRoom;
 
+  /** A lobby's tracks, taken over at `start`; each leaves the map as it is published. */
+  private captured: HandedOverTracks = new Map();
+
+  /**
+   * @param media - What a lobby opened ahead of the join, published in place
+   * of capturing. Taken over only at `start`, so that a publisher torn down
+   * before it publishes leaves the tracks to the next one.
+   */
   public constructor(
     room: LivekitRoom,
     private readonly desired: DesiredMedia,
     private readonly logger: Logger,
+    private readonly media?: LocalMedia,
   ) {
     this.room = room;
     room.setE2EEEnabled(room.options.e2ee !== undefined)?.catch((e: Error) => {
@@ -79,33 +99,86 @@ export class Publisher {
   public start(): void {
     if (this.started) return;
     this.started = true;
+    this.captured = this.media?.takeTracks() ?? new Map();
+    // A track muted in the lobby joins muted
+    for (const [source, { muted }] of this.captured) {
+      const wanted = this.desired.get(source);
+      if (wanted && muted) wanted.enabled = false;
+    }
     const requests = [...this.desired.values()]
-      .filter(({ enabled }) => enabled)
+      .filter(
+        ({ request, enabled }) => enabled || this.hasCaptured(request.source),
+      )
       .map(({ request }) => request);
-    const sources = new Set(requests.map((request) => request.source));
+    const toCapture = new Set(
+      requests
+        .map((request) => request.source)
+        .filter((source) => !this.hasCaptured(source)),
+    );
     // Microphone and camera in one call so that the browser asks for
     // permission once; the room defaults carry their options. LiveKit
     // resolves these once the track is published, which may block on the
     // connection; LocalTrackPublished is what tells us a track exists.
-    if (sources.has("microphone") && sources.has("camera"))
+    const captureBoth = toCapture.has("microphone") && toCapture.has("camera");
+    if (captureBoth)
       void this.room.localParticipant.enableCameraAndMicrophone();
     for (const request of requests)
       if (
         request.source === "screenShare" ||
-        !(sources.has("microphone") && sources.has("camera"))
+        this.hasCaptured(request.source) ||
+        !captureBoth
       )
         this.publish(request).catch((e) => {
           this.logger.error(`Failed to publish the ${request.source}`, e);
         });
   }
 
+  private hasCaptured(source: MediaSource): boolean {
+    return (
+      (source === "microphone" || source === "camera") &&
+      this.captured.has(source)
+    );
+  }
+
+  private takeCaptured(request: PublishRequest): HandedOverTrack | undefined {
+    if (request.source === "screenShare") return undefined;
+    const track = this.captured.get(request.source);
+    this.captured.delete(request.source);
+    return track;
+  }
+
+  /** A lobby's track as if this participant had captured it: LiveKit restarts and stops it as its own. */
+  private async adopt(
+    { track, constraints, muted, processor }: HandedOverTrack,
+    request: PublishRequest,
+  ): Promise<LocalTrackPublication> {
+    const local =
+      track.kind === "audio"
+        ? new LocalAudioTrack(track, constraints, false)
+        : new LocalVideoTrack(track, constraints, false);
+    if (muted) await local.mute();
+    if (processor && local instanceof LocalVideoTrack)
+      await local.setProcessor(
+        convertToLivekitProcessor(
+          processor.processor,
+          processor.processedTrack,
+        ),
+      );
+    return this.room.localParticipant.publishTrack(local, {
+      source: livekitSources[request.source],
+      ...(request.source === "camera" && videoPublishOptions(request.capture)),
+    });
+  }
+
   /** Publishes one request and resolves with its publication once LiveKit has it. */
   public async publish(
     request: PublishRequest,
   ): Promise<LocalTrackPublication | undefined> {
     const participant = this.room.localParticipant;
     let publication: LocalTrackPublication | undefined;
-    if (request.source === "microphone")
+    const captured = this.takeCaptured(request);
+    if (captured) publication = await this.adopt(captured, request);
+    else if (request.source === "microphone")
       publication = await participant.setMicrophoneEnabled(
         true,
         audioCaptureOptions(request),

sdk/src/media-backend/livekit/videoProcessor.test.ts

@@ -47,4 +47,29 @@ describe("convertToLivekitProcessor", () => {
     await adapter.destroy();
     expect(processor.destroy).toHaveBeenCalled();
   });
+
+  // A stopped track tears its processor down without waiting, while the track
+  // replacing it initialises the same one
+  it("runs a destroy and the next init on one processor in turn, across adapters", async () => {
+    const processor = fakeProcessor();
+    let finishDestroy = (): void => {};
+    vi.mocked(processor.destroy).mockImplementation(
+      async () =>
+        new Promise<void>((resolve) => {
+          finishDestroy = resolve;
+        }),
+    );
+    const previous = convertToLivekitProcessor(processor);
+    const next = convertToLivekitProcessor(processor);
+
+    const destroying = previous.destroy();
+    const initialising = next.init(options);
+    await Promise.resolve();
+    expect(processor.init).not.toHaveBeenCalled();
+
+    finishDestroy();
+    await Promise.all([destroying, initialising]);
+    expect(processor.init).toHaveBeenCalledOnce();
+    expect(next.processedTrack).toBe(processed);
+  });
 });

sdk/src/media-backend/livekit/videoProcessor.ts

@@ -8,27 +8,42 @@ Please see LICENSE in the repository root for full details.
 import { type Track, type TrackProcessor } from "livekit-client";
 
 import { type VideoProcessor } from "../../media-api";
+import { inTurn } from "../../utils/processorTurns";
+
+export interface LivekitProcessor extends TrackProcessor<Track.Kind.Video> {
+  /** The processor this adapts, so that setting the same one again is a no-op. */
+  source: VideoProcessor;
+}
 
 /**
  * A `VideoProcessor` as livekit-client wants it. LiveKit reads the processed
  * track off the processor after `init` and `restart` rather than taking it as
- * their result, so the adapter keeps it there.
+ * their result, so the adapter keeps it there. A processor a lobby already
+ * runs on the track is adopted with its output, `running`, so that the join
+ * does not initialise it again. Every step takes its turn on the processor,
+ * which a stopped track tears down without waiting for the next one's init.
  */
 export function convertToLivekitProcessor(
   processor: VideoProcessor,
-): TrackProcessor<Track.Kind.Video> {
-  const adapter: TrackProcessor<Track.Kind.Video> = {
+  running?: MediaStreamTrack,
+): LivekitProcessor {
+  const adapter: LivekitProcessor = {
     name: processor.name,
-    init: async (opts) => {
-      adapter.processedTrack = await processor.init(opts.track, opts.element);
-    },
-    restart: async (opts) => {
-      adapter.processedTrack = await processor.restart(
-        opts.track,
-        opts.element,
-      );
-    },
-    destroy: async () => processor.destroy(),
+    source: processor,
+    init: async (opts) =>
+      inTurn(processor, async () => {
+        adapter.processedTrack =
+          running ?? (await processor.init(opts.track, opts.element));
+        running = undefined;
+      }),
+    restart: async (opts) =>
+      inTurn(processor, async () => {
+        adapter.processedTrack = await processor.restart(
+          opts.track,
+          opts.element,
+        );
+      }),
+    destroy: async () => inTurn(processor, async () => processor.destroy()),
   };
   return adapter;
 }

sdk/src/utils/processorTurns.ts

@@ -0,0 +1,26 @@
+/*
+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 { type VideoProcessor } from "../media-api";
+
+const turns = new WeakMap<VideoProcessor, Promise<unknown>>();
+
+/**
+ * One operation at a time on a processor. A host shares one across the
+ * tracks it captures and publishes, and a second init while the first still
+ * loads its model, or a destroy while an init runs, leaves it broken: the
+ * backend's own locking is per track, and a track that is stopped tears its
+ * processor down without waiting.
+ */
+export async function inTurn<T>(
+  processor: VideoProcessor,
+  run: () => Promise<T>,
+): Promise<T> {
+  const turn = (turns.get(processor) ?? Promise.resolve()).then(run, run);
+  turns.set(processor, turn);
+  return turn;
+}