Skip to content

armgit / Piik

Public Imported from GitHub
0

Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。

36.3 KB
Raw Blame
import type { CopyKey } from "../ui/copy";
import { INPUT_CHANNEL } from "../remote-control/input-route";
import type { IceConfig, SignalPayload } from "../../shared/protocol";
import { createOpaqueId } from "../lib/opaque-id";
import { waitForConnectionOperation } from "./connection-operation";
import type { BrowserEncodingPool, BrowserPooledSender } from "../media/browser-encoding-pool";
import { BrowserEncodingOutput, encodedStreams, supportsBrowserEncoding } from "../media/browser-encoding-output";
import { debugError, debugEvent } from "../lib/debug";
import { debugTrack, observeDebugConnection } from "../lib/debug-webrtc";
import {
  applyVideoCaptureProfile,
  configureAudioSender,
  configureVideoSender,
  needsStartupVideoProfile,
  screenAudioBitrate,
  audioSenderCeiling,
  audioQualitySettingsEqual,
  STARTUP_VIDEO_ENCODED_FRAMES,
  startupVideoProfile,
  videoQualitySettingsEqual,
  type AudioSenderParameterReadback,
  type QualityProfile,
} from "../media/quality";
import { cloneSenderVideoTrack, stopSenderVideoTrack } from "../media/sender-video-track";
import { retireSenderQualityEvidence } from "../media/sender-quality-evidence";
import { EMPTY_METRICS, type PeerSnapshot } from "../types";
import {
  captureMetrics,
  collectConnectionMetrics,
  createStatsAccumulator,
} from "./stats";
import {
  applyVideoCodecPreference,
  normalizeVideoOfferSdp,
  type BrowserVideoCodecPreference,
  VP8_ONLY_VIDEO_CODEC,
} from "./video-codec";
import {
  addRemoteIceCandidate,
  iceServersWithNatPrediction,
  natPredictionSurveyUrls,
  NatPredictionCandidateEmitter,
  type SignalCandidate,
} from "./nat-prediction";

const MAX_PENDING_CANDIDATES = 64;
// An audio-direction change must not wait forever for a lost SDP answer.
// Initial acquisition and ICE restart keep their existing route/recovery owners.
export const RENEGOTIATION_ANSWER_TIMEOUT_MS = 15_000;
type PeerIceConfig = Pick<RTCConfiguration, "iceServers"> & {
  natPredictionStunUrls?: readonly string[];
};

export interface HostPeerEvents {
  sendSignal: (peerId: string, payload: SignalPayload) => boolean;
  onUpdate: (snapshot: PeerSnapshot) => void;
  onInputChannel?: (channel: RTCDataChannel, connection: RTCPeerConnection) => void;
}

/** Common lifecycle contract for Browser and native Host direct edges. */
export interface HostMediaPeer {
  readonly peerId: string;
  readonly connectionId: string;
  start(): Promise<boolean>;
  acceptSignal(payload: SignalPayload): Promise<void>;
  restartIce(): Promise<boolean>;
  isConnected(): boolean;
  getSnapshot(): PeerSnapshot;
  updateIceConfig(iceConfig: IceConfig): void;
  updateProfile(profile: QualityProfile): Promise<boolean>;
  updateCaptureProfile(profile: QualityProfile): Promise<boolean>;
  setPaused(paused: boolean): void;
  replaceStream(stream: MediaStream): Promise<boolean>;
  dispose(): void;
}

export class HostPeer {
  readonly connectionId: string;

  private readonly connection: RTCPeerConnection;
  private readonly pendingCandidates: SignalCandidate[] = [];
  private readonly natPredictionEnabled: boolean;
  private readonly localIceCandidates: NatPredictionCandidateEmitter;
  private statsAccumulator = createStatsAccumulator();
  private senderVideoTrack: MediaStreamTrack | null;
  private replacementVideoTrack: MediaStreamTrack | null = null;
  private replacementAudioTrack: MediaStreamTrack | null = null;
  private videoSender: RTCRtpSender | null = null;
  private pooledVideo: BrowserPooledSender | null = null;
  private encodedOutput: BrowserEncodingOutput | null = null;
  private readonly encodedStreamsEnabled: boolean;
  private audioTransceiver: RTCRtpTransceiver | null = null;
  private audioSender: RTCRtpSender | null = null;
  private statsTimer: number | null = null;
  private statsInFlight = false;
  private statsSamplingBlocked = false;
  private appliedVideoProfile: QualityProfile | null = null;
  private appliedAudioBitrate: number | null = null;
  private appliedAudioSenderParameters:
    | AudioSenderParameterReadback
    | null = null;
  private readonly lifetime = new AbortController();
  private readonly releaseDebug: () => void;
  private get disposed(): boolean { return this.lifetime.signal.aborted; }
  private profileRevision = 0;
  private negotiationEpoch = 0;
  private ordinaryAnswerEpoch: number | null = null;
  private answerTimer: number | null = null;
  private pendingNegotiation = false;
  private senderMutationTail: Promise<void> = Promise.resolve();
  private negotiationTail: Promise<void> = Promise.resolve();
  private startupVideoProfilePending: boolean;
  // RTP frame counts can survive replaceTrack; 0 suits a fresh sender, while
  // a replacement needs a valid current-track sample to establish its baseline.
  private startupFramesBaseline: number | null = 0;
  private connectedOnce = false;
  private awaitingReconnect = false;
  private paused = false;
  private snapshot: PeerSnapshot;

  constructor(
    readonly peerId: string,
    iceConfig: PeerIceConfig,
    private stream: MediaStream,
    private desiredProfile: QualityProfile,
    private readonly events: HostPeerEvents,
    private readonly videoCodec: BrowserVideoCodecPreference =
      VP8_ONLY_VIDEO_CODEC,
    connectionId = createOpaqueId(),
    natPredictionEnabled = false,
    private readonly videoPool: BrowserEncodingPool | null = null,
  ) {
    this.connectionId = connectionId;
    this.natPredictionEnabled = natPredictionEnabled;
    const sourceVideoTrack = stream.getVideoTracks()[0] ?? null;
    this.paused = sourceVideoTrack?.enabled === false;
    this.senderVideoTrack = sourceVideoTrack
      ? this.cloneVideoTrack(sourceVideoTrack)
      : null;
    this.startupVideoProfilePending = needsStartupVideoProfile(desiredProfile);
    this.encodedStreamsEnabled = !!videoPool && supportsBrowserEncoding();
    let allocatedConnection: RTCPeerConnection | null = null;
    try {
      this.connection = allocatedConnection = new RTCPeerConnection({
        ...(this.encodedStreamsEnabled ? { encodedInsertableStreams: true } : {}),
        iceServers: iceServersWithNatPrediction(
          iceConfig.iceServers,
          this.natPredictionEnabled,
          iceConfig.natPredictionStunUrls,
        ),
      });
      if (events.onInputChannel) events.onInputChannel(this.connection.createDataChannel(INPUT_CHANNEL), this.connection);
    } catch (error) {
      allocatedConnection?.close();
      stopSenderVideoTrack(this.senderVideoTrack);
      throw error;
    }
    this.releaseDebug = observeDebugConnection(this.connection, { connectionId, peerId, role: "send" });
    this.localIceCandidates = new NatPredictionCandidateEmitter(
      this.natPredictionEnabled,
      (candidate) => this.sendIceCandidate(candidate),
      natPredictionSurveyUrls(
        iceConfig.iceServers,
        iceConfig.natPredictionStunUrls,
      ),
    );
    this.snapshot = {
      peerId,
      connectionId: this.connectionId,
      connectionState: this.connection.connectionState,
      iceConnectionState: this.connection.iceConnectionState,
      metrics: { ...EMPTY_METRICS },
      error: null,
      senderParameters: null,
      audioSenderParameters: null,
    };
    this.bindConnectionEvents();
  }

  async start(): Promise<boolean> {
    const videoTrack = this.senderVideoTrack;
    if (!videoTrack) {
      this.setError(null, "host.capture.noSource");
      return false;
    }
    const audioTrack = this.stream.getAudioTracks()[0] ?? null;
    const videoTransceiver = this.connection.addTransceiver(videoTrack, {
      direction: "sendonly",
      streams: [this.stream],
    });
    if (!applyVideoCodecPreference(videoTransceiver, this.videoCodec)) {
      this.setError(null, "host.err.codecUnsupported");
      return false;
    }
    this.videoSender = videoTransceiver.sender;
    if (this.encodedStreamsEnabled) {
      this.encodedOutput = new BrowserEncodingOutput(this.videoSender, () => {
        this.fail();
      }, { connectionId: this.connectionId, peerId: this.peerId });
      this.encodedOutput.setPaused(this.paused);
    }
    this.attachVideoPool(this.stream.getVideoTracks()[0]!);
    this.audioTransceiver = this.connection.addTransceiver(audioTrack ?? "audio", {
      direction: audioTrack ? "sendonly" : "inactive",
      streams: [this.stream],
    });
    this.audioSender = this.audioTransceiver.sender;
    if (this.encodedStreamsEnabled) {
      // The connection flag also owns audio, including a later source with audio.
      const audio = encodedStreams(this.audioSender);
      void audio.readable.pipeTo(audio.writable).catch((error) => this.fail(error));
    }
    await this.enqueueSenderMutation(async () => {
      if (this.disposed || !this.videoSender || !this.audioSender) {
        return false;
      }
      return this.configureSender(this.videoSender, this.audioSender, {
        profile: startupVideoProfile(this.desiredProfile),
        profileRevision: this.profileRevision,
        video: true,
        audio: true,
      });
    });
    if (!(await this.createOffer()) || this.disposed) {
      return false;
    }
    this.statsTimer = window.setInterval(() => {
      void this.updateStats();
    }, 2_000);
    this.emit();
    return true;
  }

  async replaceStream(nextStream: MediaStream): Promise<boolean> {
    const nextSourceVideoTrack = nextStream.getVideoTracks()[0];
    if (this.disposed || !nextSourceVideoTrack) {
      return false;
    }

    return this.enqueueSenderMutation(async () => {
      const videoSender = this.videoSender;
      const audioSender = this.audioSender;
      const audioTransceiver = this.audioTransceiver;
      const previousVideoTrack = this.senderVideoTrack;
      if (
        this.disposed ||
        !videoSender ||
        !audioSender ||
        !audioTransceiver ||
        !previousVideoTrack
      ) {
        return false;
      }

      const videoChanged = this.stream.getVideoTracks()[0] !== nextSourceVideoTrack;
      const nextVideoTrack = videoChanged ? this.cloneVideoTrack(nextSourceVideoTrack) : previousVideoTrack;
      let retainedNextVideoTrack = false;
      const nextAudioTrack = nextStream.getAudioTracks()[0] ?? null;
      const nextAudioDirection = nextAudioTrack ? "sendonly" : "inactive";
      const audioDirectionChanged =
        audioTransceiver.direction !== nextAudioDirection;
      const previousAudioDirection = audioTransceiver.direction;
      this.replacementVideoTrack = nextVideoTrack;
      this.replacementAudioTrack = nextAudioTrack;
      this.applyPausedState(nextVideoTrack, nextAudioTrack);
      const previousAudioTrack = audioSender.track;
      if (videoChanged) {
        this.statsSamplingBlocked = true;
        this.statsAccumulator = createStatsAccumulator();
      }

      try {
        try {
          if (videoChanged) await this.waitForOperation(() => videoSender.replaceTrack(nextVideoTrack));
          await this.waitForOperation(() => audioSender.replaceTrack(nextAudioTrack));
          if (nextVideoTrack.readyState === "ended") throw new Error("Replacement video track ended");
          if (audioDirectionChanged) {
            audioTransceiver.direction = nextAudioDirection;
          }
        } catch (error) {
          if (this.disposed) return false;
          const [videoRollback] = await Promise.allSettled([
            videoChanged ? this.waitForOperation(() => videoSender.replaceTrack(previousVideoTrack)) : Promise.resolve(),
            this.waitForOperation(() => audioSender.replaceTrack(previousAudioTrack)),
          ]);
          if (this.disposed) return false;
          if (audioDirectionChanged) {
            audioTransceiver.direction = previousAudioDirection;
          }
          if (videoRollback.status === "rejected") {
            this.fail(videoRollback.reason);
          }
          this.setError(error, "host.fail.source");
          return false;
        }

        if (this.disposed) {
          return false;
        }
        this.applyPausedState(nextVideoTrack, nextAudioTrack);
        this.senderVideoTrack = nextVideoTrack;
        this.stream = nextStream;
        retainedNextVideoTrack = true;
        if (videoChanged) {
          this.pooledVideo?.dispose();
          this.pooledVideo = null;
          this.attachVideoPool(nextSourceVideoTrack);
          if (previousVideoTrack !== this.encodedOutput?.track) stopSenderVideoTrack(previousVideoTrack);
          this.startupVideoProfilePending = needsStartupVideoProfile(this.desiredProfile);
          this.startupFramesBaseline = null;
          this.snapshot = { ...this.snapshot, metrics: { ...EMPTY_METRICS } };
        }
        await this.configureSender(videoSender, audioSender, {
          profile: startupVideoProfile(this.desiredProfile),
          profileRevision: this.profileRevision,
          video: videoChanged && this.connection.connectionState === "connected",
          audio: true,
        });
        if (this.disposed) return false;
        this.snapshot = { ...this.snapshot, error: null };
        this.emit();
        return !audioDirectionChanged || (await this.createOffer());
      } finally {
        if (videoChanged && !retainedNextVideoTrack) {
          stopSenderVideoTrack(nextVideoTrack);
        }
        if (this.replacementVideoTrack === nextVideoTrack) {
          this.replacementVideoTrack = null;
          this.replacementAudioTrack = null;
        }
        if (videoChanged) {
          this.statsAccumulator = createStatsAccumulator();
          this.statsSamplingBlocked = false;
        }
      }
    });
  }

  updateProfile(profile: QualityProfile): Promise<boolean> {
    return this.updateOwnedProfile(profile, false);
  }

  updateCaptureProfile(profile: QualityProfile): Promise<boolean> {
    return this.updateOwnedProfile(profile, true);
  }

  setPaused(paused: boolean): void {
    this.paused = paused;
    this.encodedOutput?.setPaused(paused);
    this.pooledVideo?.setPaused(paused);
    this.applyPausedState(this.senderVideoTrack, this.audioSender?.track ?? null);
    this.applyPausedState(this.replacementVideoTrack, this.replacementAudioTrack);
  }

  private applyPausedState(
    videoTrack: MediaStreamTrack | null,
    audioTrack: MediaStreamTrack | null,
  ): void {
    if (videoTrack) videoTrack.enabled = !this.paused;
    if (audioTrack) audioTrack.enabled = !this.paused;
  }

  private updateOwnedProfile(
    profile: QualityProfile,
    updateCaptureConstraints: boolean,
  ): Promise<boolean> {
    if (this.disposed) {
      return Promise.resolve(false);
    }
    if (!needsStartupVideoProfile(profile)) {
      this.startupVideoProfilePending = false;
    }
    const effectiveVideoProfile = this.startupVideoProfilePending
      ? startupVideoProfile(profile)
      : profile;
    const changed =
      !videoQualitySettingsEqual(this.desiredProfile, profile) ||
      !audioQualitySettingsEqual(this.desiredProfile, profile);
    this.desiredProfile = profile;
    // Connection recovery replays the same intent, not a new user mutation.
    const requestedRevision = changed ? ++this.profileRevision : this.profileRevision;
    return this.enqueueSenderMutation(async () => {
      const videoSender = this.videoSender;
      const audioSender = this.audioSender;
      const videoTrack = this.senderVideoTrack;
      if (
        this.disposed ||
        !videoSender ||
        !audioSender ||
        !videoTrack ||
        requestedRevision !== this.profileRevision
      ) {
        return false;
      }
      if (updateCaptureConstraints && videoTrack !== this.encodedOutput?.track) {
        try {
          await this.waitForOperation(() => applyVideoCaptureProfile(videoTrack, profile));
        } catch (error) {
          if (this.disposed) return false;
          throw error;
        }
        if (
          this.disposed ||
          this.senderVideoTrack !== videoTrack ||
          requestedRevision !== this.profileRevision
        ) {
          return false;
        }
      }
      const updateVideo =
        this.connection.connectionState === "connected" &&
        (this.appliedVideoProfile === null ||
          !videoQualitySettingsEqual(
            this.appliedVideoProfile,
            effectiveVideoProfile,
          ));
      const updateAudio =
        this.appliedAudioBitrate !==
          screenAudioBitrate(profile.maxAudioBitrate);
      if (!updateVideo && !updateAudio) {
        return true;
      }
      if (
        !(await this.configureSender(videoSender, audioSender, {
          profile: effectiveVideoProfile,
          profileRevision: requestedRevision,
          video: updateVideo,
          audio: updateAudio,
        }))
      ) {
        return false;
      }
      if (this.disposed || requestedRevision !== this.profileRevision) {
        return false;
      }
      if (updateVideo) {
        this.statsAccumulator = createStatsAccumulator();
      }
      this.snapshot = { ...this.snapshot, error: null };
      this.emit();
      return true;
    });
  }

  async acceptSignal(payload: SignalPayload): Promise<void> {
    if (this.disposed || payload.connectionId !== this.connectionId || payload.kind === "punch") {
      return;
    }

    try {
      if (payload.kind === "description") {
        if (payload.description.type !== "answer") {
          return;
        }
        await this.enqueueNegotiation(() => this.acceptAnswer(payload));
      } else {
        await this.enqueueNegotiation(async () => {
          if (this.disposed) return;
          // Native trickle events may precede a restart answer. The retained
          // remote description still belongs to the previous ICE generation.
          if (this.ordinaryAnswerEpoch !== null || !this.connection.remoteDescription) {
            if (this.pendingCandidates.length < MAX_PENDING_CANDIDATES) {
              this.pendingCandidates.push(payload.candidate);
            }
          } else {
            await this.waitForOperation(() => addRemoteIceCandidate(this.connection, payload.candidate));
          }
        });
      }
    } catch (error) {
      this.setError(error, "host.err.createConnection");
    }
  }

  async restartIce(): Promise<boolean> {
    return this.enqueueNegotiation(async () => {
      if (
        this.disposed ||
        this.ordinaryAnswerEpoch !== null ||
        this.connection.signalingState !== "stable"
      ) {
        return false;
      }
      return this.createOwnedOffer(true, this.nextNegotiationEpoch());
    });
  }

  isConnected(): boolean {
    return this.connection.connectionState === "connected";
  }

  getSnapshot(): PeerSnapshot {
    return { ...this.snapshot, metrics: { ...this.snapshot.metrics } };
  }

  updateIceConfig(iceConfig: IceConfig): void {
    if (this.disposed) {
      return;
    }
    try {
      this.connection.setConfiguration({
        iceServers: iceServersWithNatPrediction(
          iceConfig.iceServers,
          this.natPredictionEnabled,
          iceConfig.natPredictionStunUrls,
        ),
      });
      this.localIceCandidates.setSurveyUrls(
        natPredictionSurveyUrls(
          iceConfig.iceServers,
          iceConfig.natPredictionStunUrls,
        ),
      );
    } catch (error) {
      this.setError(error, "host.err.createConnection");
    }
  }

  dispose(): void {
    if (this.disposed) {
      return;
    }
    this.releaseDebug();
    this.lifetime.abort();
    retireSenderQualityEvidence(this.connectionId);
    this.nextNegotiationEpoch();
    this.ordinaryAnswerEpoch = null;
    this.pendingNegotiation = false;
    if (this.statsTimer !== null) {
      window.clearInterval(this.statsTimer);
      this.statsTimer = null;
    }
    this.connection.close();
    this.pooledVideo?.dispose();
    this.pooledVideo = null;
    this.encodedOutput?.dispose();
    this.encodedOutput = null;
    this.localIceCandidates.discard();
    stopSenderVideoTrack(this.senderVideoTrack);
    this.senderVideoTrack = null;
    this.audioTransceiver = null;
  }

  private bindConnectionEvents(): void {
    this.connection.addEventListener("icecandidate", (event) => {
      this.localIceCandidates.add(event.candidate);
    });
    this.connection.addEventListener("icegatheringstatechange", () => {
      if (
        this.natPredictionEnabled &&
        this.connection.iceGatheringState === "complete"
      ) {
        this.localIceCandidates.gatheringComplete();
      }
    });
    this.connection.addEventListener("connectionstatechange", () => {
      const state = this.connection.connectionState;
      if (state === "connected") {
        const replayProfile = this.awaitingReconnect;
        this.connectedOnce = true;
        this.awaitingReconnect = false;
        if (replayProfile) {
          this.appliedVideoProfile = null;
          this.appliedAudioBitrate = null;
          this.appliedAudioSenderParameters = null;
        }
        if (replayProfile || !this.startupVideoProfilePending) {
          void this.updateProfile(this.desiredProfile);
        }
      } else if (this.connectedOnce && state !== "closed") {
        this.awaitingReconnect = true;
      }
      this.emit();
    });
    this.connection.addEventListener("iceconnectionstatechange", () => this.emit());
  }

  private cloneVideoTrack(source: MediaStreamTrack): MediaStreamTrack {
    return cloneSenderVideoTrack(source, (track) => {
      if (this.senderVideoTrack === track) this.fail();
    });
  }

  private attachVideoPool(source: MediaStreamTrack): void {
    const sender = this.videoSender;
    if (!sender || !this.videoPool || !this.encodedOutput) return;
    let binding: BrowserPooledSender | null = null;
    const owns = () => !this.disposed && this.pooledVideo === binding &&
      this.videoSender === sender && this.stream.getVideoTracks()[0] === source;
    const requestKey = () => this.enqueueSenderMutation(async () => {
      if (!owns()) return;
      const request = sender.setParameters as (parameters: RTCRtpSendParameters,
        options: { encodingOptions: Array<{ keyFrame: boolean }> }) => Promise<void>;
      await this.waitForOperation(() => request.call(sender, sender.getParameters(), { encodingOptions: [{ keyFrame: true }] }));
    });
    binding = this.videoPool.create(source, sender, this.connection, this.desiredProfile, this.encodedOutput,
      () => this.enqueueSenderMutation(async () => {
        if (!owns()) return false;
        const previous = this.senderVideoTrack!;
        const next = binding?.carrierScale() === undefined ? this.cloneVideoTrack(source) : this.encodedOutput!.track;
        try {
          this.applyPausedState(next, null);
          // The producer already limits real frames. Filtering its requested
          // canvas clock frames again leaves encoded frames waiting for a tick.
          if (next !== this.encodedOutput?.track) {
            await this.waitForOperation(() => applyVideoCaptureProfile(next, this.desiredProfile));
          }
          if (!owns()) { if (next !== this.encodedOutput?.track) stopSenderVideoTrack(next); return false; }
          if (next !== previous) await this.waitForOperation(() => sender.replaceTrack(next));
          await this.waitForOperation(() => configureVideoSender(sender,
            this.startupVideoProfilePending ? startupVideoProfile(this.desiredProfile) : this.desiredProfile,
            binding?.carrierScale()));
          if (!owns()) throw new DOMException("Retired Browser pool binding", "AbortError");
          if (next.readyState === "ended") throw new Error("Replacement video track ended");
          this.senderVideoTrack = next;
          if (previous !== next && previous !== this.encodedOutput?.track) stopSenderVideoTrack(previous);
          this.statsAccumulator = createStatsAccumulator();
          return true;
        } catch (error) {
          if (!this.disposed && sender.track !== previous) {
            try { await this.waitForOperation(() => sender.replaceTrack(previous)); } catch (rollbackError) { this.fail(rollbackError); }
          }
          if (next !== previous && next !== this.encodedOutput?.track) stopSenderVideoTrack(next);
          if (this.disposed) return false;
          debugError("encoding-pool", "carrier-attachment-failed", error, { connectionId: this.connectionId });
          return false;
        }
      }),
      requestKey,
      () => { if (owns()) this.fail(); });
    this.pooledVideo = binding;
    if (!binding) this.encodedOutput.passthrough(requestKey);
    binding?.setPaused(this.paused);
  }

  private sendIceCandidate(candidate: SignalCandidate | null): void {
    this.events.sendSignal(this.peerId, {
      kind: "candidate",
      connectionId: this.connectionId,
      candidate,
    });
  }

  private waitForOperation<T>(operation: () => Promise<T>): Promise<T> {
    return waitForConnectionOperation(this.lifetime.signal, operation);
  }

  private enqueueSenderMutation<T>(operation: () => Promise<T>): Promise<T> {
    const result = this.senderMutationTail.then(operation);
    this.senderMutationTail = result.then(
      () => undefined,
      () => undefined,
    );
    return result;
  }

  private enqueueNegotiation<T>(operation: () => Promise<T>): Promise<T> {
    const result = this.negotiationTail.then(operation, operation);
    this.negotiationTail = result.then(
      () => undefined,
      () => undefined,
    );
    return result;
  }

  private createOffer(): Promise<boolean> {
    return this.enqueueNegotiation(async () => {
      if (this.disposed) {
        return false;
      }
      // Source/microphone changes may arrive before the current answer. Keep
      // one offer in flight: another offer would let its predecessor's answer
      // consume the newer epoch. The next offer reads the latest transceivers.
      if (this.ordinaryAnswerEpoch !== null) {
        this.pendingNegotiation = true;
        return true;
      }
      return this.createOwnedOffer(false, this.nextNegotiationEpoch());
    });
  }

  private async createOwnedOffer(
    restart: boolean,
    epoch: number,
  ): Promise<boolean> {
    if (!this.ownsLocalOffer(epoch)) {
      return false;
    }
    if (!restart && this.connection.remoteDescription) {
      this.answerTimer = window.setTimeout(() => {
        if (this.ownsLocalOffer(epoch)) this.fail(new Error("SDP renegotiation answer timed out"));
      }, RENEGOTIATION_ANSWER_TIMEOUT_MS);
    }
    try {
      if (restart) {
        this.connection.restartIce();
      }
      const offer = await this.waitForOperation(() => this.connection.createOffer());
      if (!this.ownsLocalOffer(epoch)) {
        return false;
      }
      await this.waitForOperation(() => this.connection.setLocalDescription(offer));
      if (
        !this.ownsLocalOffer(epoch) ||
        !this.connection.localDescription
      ) {
        return false;
      }
      this.ordinaryAnswerEpoch = epoch;
      if (
        !this.events.sendSignal(this.peerId, {
          kind: "description",
          connectionId: this.connectionId,
          description: {
            type: "offer",
            sdp: normalizeVideoOfferSdp(this.connection.localDescription.sdp),
          },
        })
      ) {
        throw new Error("signal send rejected");
      }
      this.snapshot = { ...this.snapshot, error: null };
      this.emit();
      return true;
    } catch (error) {
      if (!this.ownsLocalOffer(epoch)) {
        return false;
      }
      if (this.ordinaryAnswerEpoch === epoch) {
        this.ordinaryAnswerEpoch = null;
      }
      this.clearAnswerTimer();
      this.setError(error, "host.err.createConnection");
      return false;
    }
  }

  private async flushCandidates(): Promise<void> {
    const candidates = this.pendingCandidates.splice(0);
    for (const candidate of candidates) {
      await this.waitForOperation(() => addRemoteIceCandidate(this.connection, candidate));
    }
  }

  private async acceptAnswer(
    payload: Extract<SignalPayload, { kind: "description" }>,
  ): Promise<void> {
    const epoch = this.ordinaryAnswerEpoch;
    if (epoch === null || !this.ownsAnswer(epoch)) {
      return;
    }
    try {
      await this.waitForOperation(() => this.connection.setRemoteDescription(payload.description));
      if (!this.ownsAnswer(epoch)) {
        return;
      }
      const audio = this.audioSender;
      if (audio?.track && audioSenderCeiling(audio.getParameters(),
        screenAudioBitrate(this.desiredProfile.maxAudioBitrate)) !== audio.getParameters().encodings[0]?.maxBitrate) {
        // Never await sender work inside negotiation: source replacement can
        // already be waiting for this negotiation queue to finish.
        void this.enqueueSenderMutation(async () => {
          if (this.disposed || !this.videoSender || this.audioSender !== audio) return;
          const revision = this.profileRevision;
          const applied = await this.configureSender(this.videoSender, audio, {
            profile: this.desiredProfile, profileRevision: revision, video: false, audio: true,
          });
          // The negotiated ceiling changed independently of the requested
          // bitrate. Keep the old readback, but let an explicit update retry.
          if (!applied && !this.disposed && revision === this.profileRevision) this.appliedAudioBitrate = null;
        }).catch(error => debugError("webrtc", "audio-parameters-failed", error, { connectionId: this.connectionId }));
      }
      await this.flushCandidates();
      if (this.ownsAnswer(epoch)) {
        this.clearAnswerTimer();
        this.ordinaryAnswerEpoch = null;
        if (this.pendingNegotiation) {
          this.pendingNegotiation = false;
          // Already inside negotiationTail; enqueueing here would deadlock.
          if (!(await this.createOwnedOffer(false, this.nextNegotiationEpoch()))) {
            this.fail();
          }
        }
      }
    } catch (error) {
      if (!this.ownsAnswer(epoch)) {
        return;
      }
      this.fail(error);
    }
  }

  private ownsAnswer(epoch: number): boolean {
    return (
      !this.disposed &&
      epoch === this.negotiationEpoch &&
      this.ordinaryAnswerEpoch === epoch
    );
  }

  private ownsLocalOffer(epoch: number): boolean {
    return !this.disposed && epoch === this.negotiationEpoch;
  }

  private nextNegotiationEpoch(): number {
    this.clearAnswerTimer();
    this.ordinaryAnswerEpoch = null;
    this.negotiationEpoch += 1;
    return this.negotiationEpoch;
  }

  private clearAnswerTimer(): void {
    if (this.answerTimer !== null) window.clearTimeout(this.answerTimer);
    this.answerTimer = null;
  }

  private async updateStats(): Promise<void> {
    if (
      this.disposed ||
      this.connection.connectionState === "closed" ||
      this.statsInFlight ||
      this.statsSamplingBlocked
    ) {
      return;
    }
    const captureTrack = this.senderVideoTrack;
    const captureAudioTrack = this.audioSender?.track ?? null;
    if (
      !captureTrack ||
      this.videoSender?.track !== captureTrack ||
      (this.stream.getAudioTracks()[0] ?? null) !== captureAudioTrack
    ) {
      return;
    }
    this.statsInFlight = true;
    const statsAccumulator = this.statsAccumulator;
    try {
      const metricsPromise = this.waitForOperation(() => collectConnectionMetrics(
        this.connection,
        "send",
        statsAccumulator,
        {
          trackIdentifier: captureTrack.id,
          audioTrackIdentifier: captureAudioTrack?.id ?? null,
        },
      ));
      const capture = captureMetrics(captureTrack);
      debugTrack(captureTrack, { connectionId: this.connectionId, event: "sample" });
      const metrics = { ...(await metricsPromise), ...capture };
      if (
        this.disposed ||
        this.statsSamplingBlocked ||
        this.statsAccumulator !== statsAccumulator ||
        this.senderVideoTrack !== captureTrack ||
        this.videoSender?.track !== captureTrack ||
        (this.audioSender?.track ?? null) !== captureAudioTrack ||
        (this.stream.getAudioTracks()[0] ?? null) !== captureAudioTrack ||
        (metrics.trackIdentifier !== null &&
          metrics.trackIdentifier !== captureTrack.id)
      ) {
        return;
      }
      const encodedFrames = statsAccumulator.frames;
      if (this.startupVideoProfilePending && encodedFrames !== null) {
        if (this.startupFramesBaseline === null) {
          this.startupFramesBaseline = encodedFrames;
        } else if (
          encodedFrames - this.startupFramesBaseline >=
          STARTUP_VIDEO_ENCODED_FRAMES
        ) {
          this.startupVideoProfilePending = false;
          void this.updateProfile(this.desiredProfile);
        }
      }
      const deliveredMetrics = this.pooledVideo?.metrics(metrics) ?? metrics;
      this.snapshot = { ...this.snapshot, metrics: deliveredMetrics };
      this.emit();
    } catch {
      // Stats are observational and must never disrupt a healthy media path.
    } finally {
      this.statsInFlight = false;
    }
  }

  private setError(error: unknown, key: CopyKey): void {
    if (this.disposed) return;
    debugError("webrtc", "sender-failed", error, { connectionId: this.connectionId, reason: key });
    this.snapshot = { ...this.snapshot, error: { key } };
    this.emit();
  }

  private fail(error?: unknown): void {
    if (this.disposed) return;
    debugError("webrtc", "sender-media-failed", error, { connectionId: this.connectionId });
    this.snapshot = { ...this.snapshot, connectionState: "failed", error: { key: "host.fail.connection" } };
    this.dispose();
    // Expected disposal is silent; terminal media failure must still reach
    // its preparation/recovery owner after owned resources have retired.
    this.events.onUpdate(this.getSnapshot());
  }

  private async configureSender(
    sender: RTCRtpSender,
    audioSender?: RTCRtpSender,
    mutation: {
      profile: QualityProfile;
      profileRevision: number;
      video: boolean;
      audio: boolean;
    } = {
      profile: this.desiredProfile,
      profileRevision: this.profileRevision,
      video: true,
      audio: true,
    },
  ): Promise<boolean> {
    const { profile, profileRevision } = mutation;
    let senderParameters = this.snapshot.senderParameters ?? null;
    let audioSenderParameters = this.appliedAudioSenderParameters;
    let videoSucceeded = true;
    let audioSucceeded = true;

    if (mutation.video) {
      try {
        senderParameters = await this.waitForOperation(() => configureVideoSender(sender, profile, this.pooledVideo?.carrierScale()));
      } catch (error) {
        if (this.disposed) return false;
        videoSucceeded = false;
        debugError("webrtc", "sender-parameters-failed", error, { connectionId: this.connectionId, profileRevision, requested: profile });
      }
    }

    if (
      this.disposed ||
      profileRevision !== this.profileRevision ||
      (mutation.video && this.videoSender !== sender)
    ) {
      return false;
    }

    const pooledVideo = this.pooledVideo;
    if (mutation.video && videoSucceeded && pooledVideo) {
      try { await this.waitForOperation(() => pooledVideo.updateProfile(this.desiredProfile)); }
      catch { videoSucceeded = false; }
    }

    if (mutation.audio && audioSender) {
      if (audioSender.track) {
        try {
          audioSenderParameters = await this.waitForOperation(() => configureAudioSender(
            audioSender,
            screenAudioBitrate(profile.maxAudioBitrate),
          ));
        } catch (error) {
          if (this.disposed) return false;
          audioSucceeded = false;
          debugError("webrtc", "audio-parameters-failed", error, { connectionId: this.connectionId, profileRevision });
        }
      } else {
        audioSenderParameters = null;
      }
    }

    if (
      this.disposed ||
      profileRevision !== this.profileRevision ||
      (mutation.video && this.videoSender !== sender) ||
      (mutation.audio && this.audioSender !== audioSender)
    ) {
      return false;
    }
    debugEvent("webrtc", "sender-parameters", { connectionId: this.connectionId, profileRevision,
      requested: profile, videoSucceeded, audioSucceeded, senderParameters, audioSenderParameters });
    if (mutation.video && videoSucceeded) {
      this.appliedVideoProfile = profile;
    }
    if (mutation.audio && audioSucceeded) {
      this.appliedAudioBitrate = screenAudioBitrate(
        profile.maxAudioBitrate,
      );
      this.appliedAudioSenderParameters = audioSenderParameters;
    }
    this.snapshot = {
      ...this.snapshot,
      senderParameters,
      audioSenderParameters: this.appliedAudioSenderParameters,
    };
    this.emit();
    return videoSucceeded && audioSucceeded;
  }

  private emit(): void {
    if (this.disposed) {
      return;
    }
    this.snapshot = {
      ...this.snapshot,
      connectionState: this.connection.connectionState,
      iceConnectionState: this.connection.iceConnectionState,
    };
    this.events.onUpdate({
      ...this.snapshot,
      metrics: { ...this.snapshot.metrics },
    });
  }
}