@jadujoel/web-audio-clip-node 0.1.7 → 0.1.8

package/examples/streaming/opus-worker-common.ts

@@ -0,0 +1,278 @@
+import { estimateTotalSamplesFromContentLength } from "./src/streamTimeline";
+import { resampleChannel } from "./worker-utils";
+
+export const OPUS_SAMPLE_RATE = 48_000;
+
+const textDecoder = new TextDecoder();
+
+export interface OpusHead {
+	channels: number;
+	preSkip: number;
+	description: Uint8Array<ArrayBufferLike>;
+}
+
+export function parseOpusHead(packet: Uint8Array): OpusHead | null {
+	if (packet.length < 19) return null;
+	const magic = textDecoder.decode(packet.slice(0, 8));
+	if (magic !== "OpusHead") return null;
+	const channels = packet[9] ?? 0;
+	const preSkip = (packet[10] ?? 0) | ((packet[11] ?? 0) << 8);
+	return {
+		channels,
+		preSkip,
+		description: packet,
+	};
+}
+
+export function createFallbackOpusHead(channels: number): OpusHead {
+	const description = new Uint8Array(19);
+	description.set(new TextEncoder().encode("OpusHead"), 0);
+	description[8] = 1;
+	description[9] = channels;
+	return {
+		channels,
+		preSkip: 0,
+		description,
+	};
+}
+
+interface StreamingOpusDecoderOptions {
+	processorPort: MessagePort;
+	targetSampleRate: number;
+	postMessage: (message: unknown) => void;
+}
+
+export class StreamingOpusDecoder {
+	private readonly processorPort: MessagePort;
+	private readonly targetSampleRate: number;
+	private readonly postMessage: (message: unknown) => void;
+	private readonly decoder: AudioDecoder;
+	private totalBytes: number | null = null;
+	private samplesDecodedCount = 0;
+	private didSendMeta = false;
+	private initialized = false;
+	private configured = false;
+	private decodedAnyPacket = false;
+	private streamChannels = 2;
+	private preSkipSourceSamples = 0;
+	private preSkipTargetSamples = 0;
+	private samplesSkipped = 0;
+	private allowTimestampProbe = false;
+	private preSkipProbeDone = false;
+	private shouldApplyPreSkip = true;
+	private lastConfig: {
+		codec: string;
+		sampleRate: number;
+		numberOfChannels: number;
+		descriptionLength: number;
+	} | null = null;
+
+	constructor({
+		processorPort,
+		targetSampleRate,
+		postMessage,
+	}: StreamingOpusDecoderOptions) {
+		this.processorPort = processorPort;
+		this.targetSampleRate = targetSampleRate;
+		this.postMessage = postMessage;
+		this.decoder = new AudioDecoder({
+			output: this.handleOutput,
+			error: (error: DOMException) => {
+				this.postMessage({
+					type: "error",
+					message: this.lastConfig == null
+						? error.message
+						: `${error.message} (${JSON.stringify({
+							configured: this.configured,
+							decodedAnyPacket: this.decodedAnyPacket,
+							config: this.lastConfig,
+						})})`,
+				});
+			},
+		});
+	}
+
+	setTotalBytes(totalBytes: number | null) {
+		this.totalBytes = totalBytes;
+	}
+
+	async configure(head: OpusHead, bitstreamFormat: "ogg" | "opus") {
+		if (head.channels <= 0) {
+			throw new Error("Opus stream contains invalid channel count");
+		}
+		this.streamChannels = head.channels;
+		this.preSkipSourceSamples = head.preSkip;
+		const dstRate = this.targetSampleRate > 0
+			? this.targetSampleRate
+			: OPUS_SAMPLE_RATE;
+		this.preSkipTargetSamples = Math.round(
+			(this.preSkipSourceSamples / OPUS_SAMPLE_RATE) * dstRate,
+		);
+		this.allowTimestampProbe = bitstreamFormat === "ogg";
+		this.preSkipProbeDone = false;
+		this.shouldApplyPreSkip = true;
+		const config: AudioDecoderConfig = {
+			codec: "opus",
+			sampleRate: OPUS_SAMPLE_RATE,
+			numberOfChannels: head.channels,
+			description: head.description,
+		};
+		this.lastConfig = {
+			codec: config.codec,
+			sampleRate: config.sampleRate,
+			numberOfChannels: config.numberOfChannels,
+			descriptionLength: head.description.length,
+		};
+		const support = await AudioDecoder.isConfigSupported(config);
+		if (!support.supported) {
+			throw new Error(
+				`Unsupported Opus decoder config: ${JSON.stringify({
+					codec: config.codec,
+					sampleRate: config.sampleRate,
+					numberOfChannels: config.numberOfChannels,
+					descriptionLength: head.description.length,
+				})}`,
+			);
+		}
+		this.decoder.configure(config);
+		this.configured = true;
+	}
+
+	decodePacket(packet: Uint8Array, timestampUs: number) {
+		if (!this.configured) {
+			throw new Error("Decoder is not configured for Opus stream");
+		}
+		this.decoder.decode(
+			new EncodedAudioChunk({
+				type: "key",
+				timestamp: timestampUs,
+				data: packet,
+			}),
+		);
+		this.decodedAnyPacket = true;
+	}
+
+	async flush() {
+		await this.decoder.flush();
+	}
+
+	close() {
+		try {
+			this.decoder.close();
+		} catch {
+			// already closed
+		}
+	}
+
+	get samplesDecoded() {
+		return this.samplesDecodedCount;
+	}
+
+	get channels() {
+		return this.streamChannels;
+	}
+
+	get hasConfiguredDecoder() {
+		return this.configured;
+	}
+
+	get hasDecodedPackets() {
+		return this.decodedAnyPacket;
+	}
+
+	private readonly handleOutput = (audioData: AudioData) => {
+		const numFrames = audioData.numberOfFrames;
+		const numChannels = audioData.numberOfChannels;
+		const srcRate = audioData.sampleRate;
+		const dstRate = this.targetSampleRate > 0 ? this.targetSampleRate : srcRate;
+		if (this.allowTimestampProbe && !this.preSkipProbeDone) {
+			const preSkipUs = Math.round(
+				(this.preSkipSourceSamples / OPUS_SAMPLE_RATE) * 1_000_000,
+			);
+			if (audioData.timestamp >= preSkipUs && preSkipUs > 0) {
+				this.shouldApplyPreSkip = false;
+			}
+			this.preSkipProbeDone = true;
+		}
+
+		const channelData: Float32Array[] = [];
+		for (let ch = 0; ch < numChannels; ch++) {
+			const raw = new Float32Array(numFrames);
+			audioData.copyTo(raw, { planeIndex: ch, format: "f32-planar" });
+			channelData.push(resampleChannel(raw, srcRate, dstRate));
+		}
+		audioData.close();
+
+		let resampledFrames = channelData[0]?.length ?? 0;
+		if (
+			this.shouldApplyPreSkip &&
+			this.samplesSkipped < this.preSkipTargetSamples &&
+			resampledFrames > 0
+		) {
+			const toSkip = Math.min(
+				this.preSkipTargetSamples - this.samplesSkipped,
+				resampledFrames,
+			);
+			this.samplesSkipped += toSkip;
+			if (toSkip === resampledFrames) {
+				return;
+			}
+			for (let ch = 0; ch < channelData.length; ch++) {
+				channelData[ch] = channelData[ch].subarray(toSkip);
+			}
+			resampledFrames = channelData[0]?.length ?? 0;
+		}
+
+		if (!this.didSendMeta) {
+			this.didSendMeta = true;
+			const estimatedTotalSamples = estimateTotalSamplesFromContentLength({
+				totalBytes: this.totalBytes,
+				bitrate: null,
+				sourceSampleRate: OPUS_SAMPLE_RATE,
+				targetSampleRate: dstRate,
+			});
+			this.postMessage({
+				type: "streamMeta",
+				estimatedTotalSamples,
+				sampleRate: dstRate,
+				channels: numChannels,
+				isEstimate: true,
+			});
+		}
+
+		if (!this.initialized) {
+			this.initialized = true;
+			const estimatedTotalSamples = estimateTotalSamplesFromContentLength({
+				totalBytes: this.totalBytes,
+				bitrate: null,
+				sourceSampleRate: OPUS_SAMPLE_RATE,
+				targetSampleRate: dstRate,
+			});
+			this.processorPort.postMessage({
+				type: "bufferInit",
+				data: {
+					channels: numChannels,
+					totalLength: estimatedTotalSamples ?? 0,
+					streaming: true,
+				},
+			});
+			this.postMessage({
+				type: "info",
+				sampleRate: srcRate,
+				channels: numChannels,
+			});
+		}
+
+		if (resampledFrames > 0) {
+			this.processorPort.postMessage({
+				type: "bufferRange",
+				data: {
+					startSample: this.samplesDecodedCount,
+					channelData,
+				},
+			});
+			this.samplesDecodedCount += resampledFrames;
+			this.postMessage({ type: "decoded", samplesDecoded: this.samplesDecodedCount });
+		}
+	};
+}

package/examples/streaming/package.json

@@ -7,6 +7,14 @@
     "dev": "bun run build:worker && bun index.html"
   },
   "dependencies": {
-    "@jadujoel/web-audio-clip-node": "file:../.."
+    "@jadujoel/web-audio-clip-node": "file:../..",
+    "react": "^19",
+    "react-dom": "^19",
+    "zustand": "^5"
+  },
+  "devDependencies": {
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "opus-decoder": "0.7.11"
   }
 }

package/examples/streaming/raw-opus-framed-decode-worker.ts

@@ -0,0 +1,148 @@
+// Raw Opus Decode Worker — runs fetch → framed raw Opus packet parse → AudioDecoder off the main thread.
+// Expected transport format:
+// - 8-byte magic: FROPUS01
+// - 4-byte little-endian OpusHead packet length
+// - OpusHead packet bytes
+// - repeated 4-byte little-endian packet length + Opus packet bytes
+
+// @ts-expect-error redeclare self as DedicatedWorkerGlobalScope
+declare const self: DedicatedWorkerGlobalScope;
+
+import { createFramedRawOpusStreamState, parseFramedRawOpusStream } from "./framed-raw-opus";
+import {
+	StreamingOpusDecoder,
+	OPUS_SAMPLE_RATE,
+} from "./opus-worker-common";
+import {
+	concat,
+	createThrottleStream,
+} from "./worker-utils";
+
+let abortController: AbortController | null = null;
+
+self.onmessage = (ev: MessageEvent) => {
+	const { type } = ev.data;
+	if (type === "init") {
+		const { port, url, throttle, targetSampleRate } = ev.data as {
+			port: MessagePort;
+			url: string;
+			throttle?: number;
+			targetSampleRate?: number;
+		};
+		abortController = new AbortController();
+		startStreaming(port, url, abortController.signal, throttle ?? 0, targetSampleRate ?? 0);
+	} else if (type === "abort") {
+		abortController?.abort();
+	}
+};
+
+async function startStreaming(
+	processorPort: MessagePort,
+	url: string,
+	signal: AbortSignal,
+	throttle: number,
+	targetSampleRate: number,
+) {
+	let totalBytes: number | null = null;
+	let bytesReceived = 0;
+	let leftover: Uint8Array<ArrayBufferLike> = new Uint8Array(0);
+	let packetTimestampUs = 0;
+	const parserState = createFramedRawOpusStreamState();
+	const streamDecoder = new StreamingOpusDecoder({
+		processorPort,
+		targetSampleRate,
+		postMessage: (message) => self.postMessage(message),
+	});
+
+	try {
+		const response = await fetch(url, { signal });
+		if (!response.ok) {
+			self.postMessage({
+				type: "error",
+				message: `Fetch failed: ${response.status} ${response.statusText}`,
+			});
+			return;
+		}
+		if (!response.body) {
+			self.postMessage({ type: "error", message: "Response has no body" });
+			return;
+		}
+
+		const contentLength = response.headers.get("content-length");
+		totalBytes = contentLength ? Number.parseInt(contentLength, 10) : null;
+		streamDecoder.setTotalBytes(totalBytes);
+
+		const body = throttle > 0
+			? response.body.pipeThrough(createThrottleStream(throttle))
+			: response.body;
+		const reader = body.getReader();
+
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+
+			bytesReceived += value.length;
+			self.postMessage({ type: "progress", bytesReceived, totalBytes });
+
+			const combined = leftover.length > 0 ? concat(leftover, value) : value;
+			const parsed = parseFramedRawOpusStream(combined, parserState);
+			leftover = parsed.leftover;
+
+			if (parsed.head != null && !streamDecoder.hasConfiguredDecoder) {
+				await streamDecoder.configure(parsed.head, "opus");
+			}
+
+			for (const packet of parsed.packets) {
+				streamDecoder.decodePacket(packet, packetTimestampUs);
+				packetTimestampUs += 1;
+			}
+		}
+
+		if (leftover.length > 0) {
+			const parsed = parseFramedRawOpusStream(leftover, parserState);
+			if (parsed.leftover.length > 0) {
+				throw new Error("Framed raw Opus stream ended with a partial packet");
+			}
+			if (parsed.head != null && !streamDecoder.hasConfiguredDecoder) {
+				await streamDecoder.configure(parsed.head, "opus");
+			}
+			for (const packet of parsed.packets) {
+				streamDecoder.decodePacket(packet, packetTimestampUs);
+				packetTimestampUs += 1;
+			}
+		}
+
+		if (streamDecoder.hasConfiguredDecoder && streamDecoder.hasDecodedPackets) {
+			await streamDecoder.flush();
+		} else {
+			self.postMessage({
+				type: "error",
+				message: "No framed raw Opus packets found in the stream",
+			});
+			return;
+		}
+
+		processorPort.postMessage({
+			type: "bufferEnd",
+			data: { totalLength: streamDecoder.samplesDecoded },
+		});
+		self.postMessage({
+			type: "done",
+			samplesDecoded: streamDecoder.samplesDecoded,
+			sampleRate: OPUS_SAMPLE_RATE,
+			channels: streamDecoder.channels,
+		});
+	} catch (e: unknown) {
+		if (e instanceof DOMException && e.name === "AbortError") {
+			self.postMessage({ type: "aborted" });
+		} else {
+			self.postMessage({
+				type: "error",
+				message: e instanceof Error ? e.message : String(e),
+			});
+		}
+	} finally {
+		streamDecoder.close();
+		processorPort.close();
+	}
+}