{"version":3,"file":"audio-bus.cjs","names":[],"sources":["../../src/audio/audio-bus.ts"],"sourcesContent":["/**\n * @tempest-limits file-lines — the mixing graph, the per-source handle and the\n * output route are one object's lifetime: the limiter only makes sense after the\n * sum, and the element that carries `setSinkId` is the same one the mix leaves\n * through. Splitting them would hand the caller two halves that are useless apart.\n */\nimport { isAudioOutputSelectionSupported, setAudioOutput } from \"./audio-output\";\n\n/** Default ceiling for a per-source or master gain, as a multiplier. */\nexport const DEFAULT_MAX_GAIN = 3;\n\n/** Shape of the master limiter. Matches `DynamicsCompressorNode`'s params. */\nexport interface LimiterSettings {\n /** dBFS above which the compressor starts working. */\n threshold: number;\n /** dB range over which the curve bends. `0` is a hard knee. */\n knee: number;\n /** Input/output ratio above the threshold. 20 is limiting, not compression. */\n ratio: number;\n /** Seconds to clamp a peak. */\n attack: number;\n /** Seconds to let go. */\n release: number;\n}\n\n/**\n * A limiter, not a compressor: a hard knee at a 20:1 ratio with a 3 ms attack\n * catches the sum before it clips without audibly ducking anything below it.\n */\nconst DEFAULT_LIMITER: LimiterSettings = {\n threshold: -8,\n knee: 0,\n ratio: 20,\n attack: 0.003,\n release: 0.25,\n};\n\n/** Options for {@link createAudioBus}. */\nexport interface AudioBusOptions {\n /** Ceiling for every gain on this bus. Default {@link DEFAULT_MAX_GAIN}. */\n maxGain?: number;\n /** Override the master limiter, or pass `false` to run without one. */\n limiter?: Partial | false;\n /**\n * Reuse an existing `AudioContext` instead of creating one.\n *\n * Browsers cap the number of live contexts (Chrome allows around six), so a\n * page that already has one — a level meter, a player — should hand it over\n * rather than open a second.\n */\n context?: AudioContext;\n}\n\n/** One source attached to the bus. */\nexport interface AudioBusHandle {\n /**\n * Set this source's gain, where `1` is the level it arrived at.\n *\n * Values above `1` are the point of the whole graph: `element.volume` is\n * clamped at `1`, so a quiet talker could only ever be attenuated — the one\n * correction nobody needs.\n */\n setGain: (gain: number) => void;\n /** Current gain, after clamping. */\n readonly gain: number;\n /** Detach this source and release its nodes. The bus stays up. */\n stop: () => void;\n}\n\n/** A running mix. */\nexport interface AudioBus {\n /**\n * Play a stream through the shared mix.\n *\n * @param stream - The stream to play. Only its first audio track is used.\n * @param options - `gain` is the initial multiplier, default `1`.\n * @returns A handle to adjust or detach this source.\n */\n attach: (stream: MediaStream, options?: { gain?: number }) => AudioBusHandle;\n /** Scale every source, on top of its own gain. */\n setMasterGain: (gain: number) => void;\n /** Current master gain, after clamping. */\n readonly masterGain: number;\n /**\n * Route the whole mix to one output device.\n *\n * @param deviceId - Device id from `useMediaDevices().audioOutputs`, or `\"\"`\n * for the system default.\n * @returns `false` when the engine cannot route audio, or the device is gone.\n */\n setOutputDevice: (deviceId: string) => Promise;\n /** Device id the mix is routed to. `\"\"` is the system default. */\n readonly outputDevice: string;\n /**\n * Resume a context the browser started suspended.\n *\n * Autoplay policy suspends a context created outside a user gesture, and a\n * suspended context is silent with no error anywhere. Call this from the\n * click that starts playback.\n */\n resume: () => Promise;\n /**\n * Detach everything and close the context this bus created.\n *\n * Idempotent, and the bus stays callable afterwards: `attach` hands back an\n * inert handle instead of throwing. That is not politeness — creating a node\n * on a closed `AudioContext` throws `InvalidStateError`, and the stream that\n * arrives late is the normal case (a WebRTC `ontrack` firing after the\n * component that owned the bus went away).\n */\n close: () => void;\n /** Whether this browser gave us a Web Audio graph at all. */\n readonly supported: boolean;\n /** Whether this browser can route the mix to a chosen output device. */\n readonly canSelectOutput: boolean;\n}\n\n/**\n * Clamp a gain into `0..max`, treating a non-finite value as unity.\n *\n * `NaN` reaches here from an empty input or a failed parse, and assigning it to\n * an `AudioParam` throws — losing the audio for a typo in a number field.\n */\nfunction clampGain(gain: number, max: number): number {\n if (!Number.isFinite(gain)) return 1;\n return Math.min(max, Math.max(0, gain));\n}\n\n/** The `AudioContext` constructor this engine exposes, prefixed or not. */\nfunction audioContextConstructor(): typeof AudioContext | undefined {\n if (typeof AudioContext !== \"undefined\") return AudioContext;\n return (globalThis as { webkitAudioContext?: typeof AudioContext }).webkitAudioContext;\n}\n\n/** A media element that may support output routing. */\ntype SinkCapableElement = HTMLAudioElement & { setSinkId?: (sinkId: string) => Promise };\n\n/**\n * The stream to feed the graph: just the audio track, when this engine can build\n * one.\n *\n * Isolating the track keeps a camera's video out of the source node. `MediaStream`\n * is missing outside a browser (jsdom, a worker), and there the original stream is\n * the right answer anyway — `createMediaStreamSource` reads its first audio track.\n */\nfunction audioOnly(stream: MediaStream, track: MediaStreamTrack): MediaStream {\n if (typeof MediaStream === \"undefined\") return stream;\n return new MediaStream([track]);\n}\n\n/** Start playback without letting an environment that has no media pipeline throw. */\nfunction playQuietly(element: HTMLAudioElement): void {\n try {\n void element.play?.()?.catch(() => undefined);\n } catch {\n /* jsdom and any engine without a media pipeline — nothing to play anyway */\n }\n}\n\n/**\n * Mix several streams into one output, with gain above 100% and a master limiter.\n *\n * Three things make this a graph instead of a few `