@voltkit-rtc/client 0.2.0

package/src/music.ts

@@ -0,0 +1,200 @@
+/**
+ * Music from inside the page.
+ *
+ * A host who plays a song through their speakers and lets the microphone pick
+ * it up sends the audience a recording of a room: thin, late, and mangled by
+ * the echo canceller, whose whole job is to remove exactly that. The audio
+ * here never leaves the browser as sound. It is taken from the element or
+ * stream that is playing it and published as audio in its own right.
+ */
+
+/** An `<audio>` or `<video>` element, or audio the page already holds. */
+export type MusicInput = HTMLMediaElement | MediaStream | MediaStreamTrack;
+
+export interface MusicOptions {
+  /** 0 to 1. What the audience hears. Default 1. */
+  volume?: number;
+  /**
+   * Whether the host hears it too. Defaults to true for an element -- routing
+   * it for publishing takes it off the speakers, so this puts it back -- and
+   * false for a stream, which is normally audible somewhere already.
+   */
+  monitor?: boolean;
+}
+
+export type TrackSource = 'mic' | 'music' | 'camera' | 'screen';
+
+let shared: AudioContext | null = null;
+/** A media element can be wired to one audio graph, once, for its whole life. */
+const elementNodes = new WeakMap<HTMLMediaElement, MediaElementAudioSourceNode>();
+
+function audioContext(): AudioContext {
+  shared ??= new AudioContext({ latencyHint: 'interactive' });
+  // Browsers start a context suspended until the page has had a user gesture.
+  // Publishing music happens on a click, so this normally just succeeds.
+  if (shared.state === 'suspended') void shared.resume().catch(() => undefined);
+  return shared;
+}
+
+const clamp = (v: number) => Math.min(1, Math.max(0, Number.isFinite(v) ? v : 1));
+
+/**
+ * One piece of music, as a track that can be published and a volume that can
+ * be turned without touching the microphone.
+ */
+export class MusicSource {
+  private readonly ctx = audioContext();
+  private readonly input: AudioNode;
+  private readonly isElement: boolean;
+  /** What is sent. */
+  private readonly level: GainNode;
+  /** What the host hears. */
+  private readonly monitor: GainNode;
+  private readonly out: MediaStreamAudioDestinationNode;
+  private vol: number;
+  private on = true;
+  private closed = false;
+
+  constructor(input: MusicInput, options: MusicOptions = {}) {
+    const ctx = this.ctx;
+    this.isElement = typeof HTMLMediaElement !== 'undefined' && input instanceof HTMLMediaElement;
+    if (this.isElement) {
+      const element = input as HTMLMediaElement;
+      let node = elementNodes.get(element);
+      if (!node) {
+        node = ctx.createMediaElementSource(element);
+        elementNodes.set(element, node);
+      }
+      // It may have been left playing straight to the speakers by an earlier
+      // MusicSource that was closed.
+      try { node.disconnect(); } catch { /* not connected */ }
+      this.input = node;
+    } else {
+      const stream = input instanceof MediaStream ? input : new MediaStream([input as MediaStreamTrack]);
+      if (stream.getAudioTracks().length === 0) throw new Error('the music stream has no audio track');
+      this.input = ctx.createMediaStreamSource(stream);
+    }
+
+    this.vol = clamp(options.volume ?? 1);
+    this.level = ctx.createGain();
+    this.level.gain.value = this.vol;
+    this.monitor = ctx.createGain();
+    this.monitor.gain.value = (options.monitor ?? this.isElement) ? 1 : 0;
+    this.out = ctx.createMediaStreamDestination();
+
+    this.input.connect(this.level);
+    this.level.connect(this.out);
+    this.input.connect(this.monitor);
+    this.monitor.connect(ctx.destination);
+  }
+
+  /** The music as a track. Publish this. */
+  get track(): MediaStreamTrack {
+    return this.out.stream.getAudioTracks()[0]!;
+  }
+
+  /** The music after its volume, for mixing into something else. */
+  get node(): AudioNode {
+    return this.level;
+  }
+
+  get volume(): number {
+    return this.vol;
+  }
+
+  get enabled(): boolean {
+    return this.on;
+  }
+
+  /** 0 to 1. Changes what the audience hears, smoothly, without a click. */
+  setVolume(volume: number): void {
+    this.vol = clamp(volume);
+    if (this.on) this.level.gain.setTargetAtTime(this.vol, this.ctx.currentTime, 0.03);
+  }
+
+  /** Silence the music for the audience without stopping playback. */
+  setEnabled(enabled: boolean): void {
+    this.on = enabled;
+    this.level.gain.setTargetAtTime(enabled ? this.vol : 0, this.ctx.currentTime, 0.03);
+  }
+
+  /** Whether the host hears it locally. */
+  setMonitor(enabled: boolean): void {
+    this.monitor.gain.setTargetAtTime(enabled ? 1 : 0, this.ctx.currentTime, 0.03);
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    try { this.input.disconnect(); } catch { /* already */ }
+    this.level.disconnect();
+    this.monitor.disconnect();
+    this.track.stop();
+    // An element stays wired to the audio graph for good. Hand it back to the
+    // speakers, or it would play in silence from now on.
+    if (this.isElement) this.input.connect(this.ctx.destination);
+  }
+}
+
+/**
+ * Microphone and music as ONE track, for a destination that takes one audio
+ * track -- a broadcast. Each side keeps its own switch.
+ */
+export class AudioMixer {
+  private readonly ctx = audioContext();
+  private readonly out = this.ctx.createMediaStreamDestination();
+  private readonly micGain = this.ctx.createGain();
+  private readonly micNode: MediaStreamAudioSourceNode | null = null;
+  private music: MusicSource | null = null;
+
+  constructor(mic: MediaStreamTrack | null) {
+    if (mic) {
+      this.micNode = this.ctx.createMediaStreamSource(new MediaStream([mic]));
+      this.micNode.connect(this.micGain);
+      this.micGain.connect(this.out);
+    }
+  }
+
+  /** Publish this instead of the microphone. */
+  get track(): MediaStreamTrack {
+    return this.out.stream.getAudioTracks()[0]!;
+  }
+
+  get hasMusic(): boolean {
+    return this.music !== null;
+  }
+
+  get musicEnabled(): boolean {
+    return this.music?.enabled ?? false;
+  }
+
+  setMicEnabled(enabled: boolean): void {
+    this.micGain.gain.setTargetAtTime(enabled ? 1 : 0, this.ctx.currentTime, 0.03);
+  }
+
+  setMusic(input: MusicInput, options?: MusicOptions): void {
+    this.clearMusic();
+    this.music = new MusicSource(input, options);
+    this.music.node.connect(this.out);
+  }
+
+  setMusicEnabled(enabled: boolean): void {
+    this.music?.setEnabled(enabled);
+  }
+
+  setMusicVolume(volume: number): void {
+    this.music?.setVolume(volume);
+  }
+
+  clearMusic(): void {
+    this.music?.close();
+    this.music = null;
+  }
+
+  close(): void {
+    this.clearMusic();
+    this.micNode?.disconnect();
+    this.micGain.disconnect();
+    this.track.stop();
+  }
+}