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

package/examples/streaming/src/clip-node-lib.ts

@@ -0,0 +1,33 @@
+export {
+	controlDefs,
+	loopControlDefs,
+	transportLinkedControlPairs,
+	loopLinkedControlPairs,
+	getActiveLinkedControls,
+	getLinkedControlPairForControl,
+	getLinkedControlUpdates,
+	isTempoRelativeSnap,
+	remapTempoRelativeValue,
+	ClipNode,
+	float32ArrayFromAudioBuffer,
+	getProcessorBlobUrl,
+	linFromDb,
+} from "../../../src/lib";
+export {
+	ControlSection,
+	DetuneControl,
+	FilterControl,
+	GainControl,
+	PanControl,
+	PlaybackRateControl,
+	PlayheadSlider,
+	useClipControls,
+} from "../../../src/lib-react";
+export type { ControlKey, ClipNodeState, FrameData } from "../../../src/lib";
+export {
+	createStreamingWorker,
+	detectStreamFormat,
+	getStreamingWorkerUrl,
+	usesBufferedContainerDecode,
+} from "../../../src/streaming";
+export type { StreamFormat } from "../../../src/streaming";

package/examples/streaming/src/framedRawOpus.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "bun:test";
+import {
+	FRAMED_RAW_OPUS_MAGIC,
+	createFramedRawOpusStreamState,
+	parseFramedRawOpusStream,
+} from "../framed-raw-opus";
+
+function concatBytes(...parts: Uint8Array[]): Uint8Array {
+	const total = parts.reduce((sum, part) => sum + part.length, 0);
+	const out = new Uint8Array(total);
+	let offset = 0;
+	for (const part of parts) {
+		out.set(part, offset);
+		offset += part.length;
+	}
+	return out;
+}
+
+function uint32LE(value: number): Uint8Array {
+	return new Uint8Array([
+		value & 0xff,
+		(value >>> 8) & 0xff,
+		(value >>> 16) & 0xff,
+		(value >>> 24) & 0xff,
+	]);
+}
+
+function buildOpusHead(channels = 2, preSkip = 312): Uint8Array {
+	const head = new Uint8Array(19);
+	head.set(new TextEncoder().encode("OpusHead"), 0);
+	head[8] = 1;
+	head[9] = channels;
+	head[10] = preSkip & 0xff;
+	head[11] = (preSkip >>> 8) & 0xff;
+	head[12] = 0x80;
+	head[13] = 0xbb;
+	return head;
+}
+
+describe("framed raw Opus transport", () => {
+	it("parses header and packets across chunk boundaries", () => {
+		const head = buildOpusHead();
+		const packetA = new Uint8Array([1, 2, 3, 4]);
+		const packetB = new Uint8Array([5, 6, 7]);
+		const bytes = concatBytes(
+			new TextEncoder().encode(FRAMED_RAW_OPUS_MAGIC),
+			uint32LE(head.length),
+			head,
+			uint32LE(packetA.length),
+			packetA,
+			uint32LE(packetB.length),
+			packetB,
+		);
+		const state = createFramedRawOpusStreamState();
+		const first = parseFramedRawOpusStream(bytes.slice(0, 20), state);
+		expect(first.head).toBeNull();
+		expect(first.packets).toHaveLength(0);
+		const second = parseFramedRawOpusStream(
+			concatBytes(first.leftover, bytes.slice(20)),
+			state,
+		);
+		expect(second.head?.channels).toBe(2);
+		expect(second.head?.preSkip).toBe(312);
+		expect(second.packets).toEqual([packetA, packetB]);
+		expect(second.leftover).toHaveLength(0);
+	});
+
+	it("rejects streams with the wrong magic header", () => {
+		const state = createFramedRawOpusStreamState();
+		expect(() =>
+			parseFramedRawOpusStream(new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]), state),
+		).toThrow(/FROPUS01/);
+	});
+});

package/examples/streaming/src/main.tsx

@@ -0,0 +1,6 @@
+import { createRoot } from "./react-dom-runtime";
+import { App } from "./App";
+
+const root = document.getElementById("root");
+if (!root) throw new Error("Missing #root element");
+createRoot(root).render(<App />);

package/examples/streaming/src/react-dom-runtime.d.ts

@@ -0,0 +1 @@
+export { createRoot } from "react-dom/client";

package/examples/streaming/src/react-dom-runtime.js

@@ -0,0 +1 @@
+export { createRoot } from "../../../node_modules/react-dom/client.js";

package/examples/streaming/src/react-runtime.d.ts

@@ -0,0 +1,2 @@
+export { memo, useCallback, useEffect, useRef, useState } from "react";
+export type { RefObject } from "react";

package/examples/streaming/src/react-runtime.js

@@ -0,0 +1,7 @@
+export {
+	memo,
+	useCallback,
+	useEffect,
+	useRef,
+	useState,
+} from "../../../node_modules/react/index.js";

package/examples/streaming/src/streamFormat.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from "bun:test";
+import { getDefaultUrlForFormat } from "./streamFormat";
+
+describe("streamFormat", () => {
+	it("returns format defaults", () => {
+		expect(getDefaultUrlForFormat("OggOpus")).toBe("../sounds/example.opus");
+		expect(getDefaultUrlForFormat("RawOpusFramed")).toBe("");
+		expect(getDefaultUrlForFormat("WebmOpus")).toBe("../sounds/example.webm");
+		expect(getDefaultUrlForFormat("Mp3")).toBe(
+			"../sounds/example.mp3",
+		);
+	});
+});

package/examples/streaming/src/streamFormat.ts

@@ -0,0 +1,14 @@
+import type { StreamFormat } from "./clip-node-lib";
+
+export function getDefaultUrlForFormat(format: StreamFormat): string {
+	if (format === "OggOpus") {
+		return "../sounds/example.opus";
+	}
+	if (format === "RawOpusFramed") {
+		return "";
+	}
+	if (format === "WebmOpus") {
+		return "../sounds/example.webm";
+	}
+	return "../sounds/example.mp3";
+}

package/examples/streaming/src/streamTimeline.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "bun:test";
+import {
+	clampSeekTargetSamples,
+	clampSeekTargetSeconds,
+	estimateTotalSamplesFromContentLength,
+	secondsFromSamples,
+} from "./streamTimeline";
+
+describe("streamTimeline", () => {
+	it("estimates total samples from content length with fallback bitrate", () => {
+		const estimated = estimateTotalSamplesFromContentLength({
+			totalBytes: 128_000,
+			bitrate: null,
+			sourceSampleRate: 44_100,
+			targetSampleRate: 48_000,
+		});
+		// 128000 bytes at 128kbps = 8 seconds -> 384000 samples at 48kHz.
+		expect(estimated).toBe(384_000);
+	});
+
+	it("prefers frame bitrate when provided", () => {
+		const estimated = estimateTotalSamplesFromContentLength({
+			totalBytes: 48_000,
+			bitrate: 192_000,
+			sourceSampleRate: 48_000,
+			targetSampleRate: 48_000,
+		});
+		// 48000 bytes * 8 / 192000 bps = 2 seconds -> 96000 samples
+		expect(estimated).toBe(96_000);
+	});
+
+	it("returns null for invalid inputs", () => {
+		expect(
+			estimateTotalSamplesFromContentLength({
+				totalBytes: null,
+				bitrate: null,
+				sourceSampleRate: 48_000,
+				targetSampleRate: 48_000,
+			}),
+		).toBeNull();
+	});
+
+	it("converts decoded samples to seconds", () => {
+		expect(secondsFromSamples(24_000, 48_000)).toBe(0.5);
+		expect(secondsFromSamples(0, 48_000)).toBeNull();
+	});
+
+	it("clamps seek target to decoded region", () => {
+		expect(clampSeekTargetSeconds(4, 2)).toEqual({ value: 2, clamped: true });
+		expect(clampSeekTargetSeconds(1.5, 2)).toEqual({
+			value: 1.5,
+			clamped: false,
+		});
+		expect(clampSeekTargetSeconds(1.5, null)).toEqual({
+			value: 1.5,
+			clamped: false,
+		});
+	});
+
+	it("clamps sample-based seek target to decoded samples", () => {
+		expect(clampSeekTargetSamples(96_000, 48_000)).toEqual({
+			value: 48_000,
+			clamped: true,
+		});
+		expect(clampSeekTargetSamples(47_999.9, 48_000)).toEqual({
+			value: 47_999,
+			clamped: false,
+		});
+		expect(clampSeekTargetSamples(-100, 48_000)).toEqual({
+			value: 0,
+			clamped: false,
+		});
+	});
+});

package/examples/streaming/src/streamTimeline.ts

@@ -0,0 +1,76 @@
+interface EstimateInput {
+	totalBytes: number | null;
+	bitrate: number | null;
+	sourceSampleRate: number;
+	targetSampleRate: number;
+}
+
+const FALLBACK_BITRATE_BPS = 128_000;
+
+export function estimateTotalSamplesFromContentLength({
+	totalBytes,
+	bitrate,
+	sourceSampleRate,
+	targetSampleRate,
+}: EstimateInput): number | null {
+	if (totalBytes == null || totalBytes <= 0) return null;
+	if (sourceSampleRate <= 0 || targetSampleRate <= 0) return null;
+	const safeBitrate =
+		bitrate != null && Number.isFinite(bitrate) && bitrate > 0
+			? bitrate
+			: FALLBACK_BITRATE_BPS;
+	const durationSeconds = (totalBytes * 8) / safeBitrate;
+	if (!Number.isFinite(durationSeconds) || durationSeconds <= 0) return null;
+	const totalSamples = Math.ceil(durationSeconds * targetSampleRate);
+	return Number.isFinite(totalSamples) && totalSamples > 0 ? totalSamples : null;
+}
+
+export function secondsFromSamples(
+	samples: number,
+	sampleRate: number,
+): number | null {
+	if (!Number.isFinite(samples) || samples <= 0) return null;
+	if (!Number.isFinite(sampleRate) || sampleRate <= 0) return null;
+	return samples / sampleRate;
+}
+
+export function clampSeekTargetSeconds(
+	targetSeconds: number,
+	seekableDurationSeconds: number | null,
+): { value: number; clamped: boolean } {
+	if (!Number.isFinite(targetSeconds) || targetSeconds < 0) {
+		return { value: 0, clamped: true };
+	}
+	if (
+		seekableDurationSeconds == null ||
+		!Number.isFinite(seekableDurationSeconds) ||
+		seekableDurationSeconds < 0
+	) {
+		return { value: targetSeconds, clamped: false };
+	}
+	if (targetSeconds <= seekableDurationSeconds) {
+		return { value: targetSeconds, clamped: false };
+	}
+	return { value: seekableDurationSeconds, clamped: true };
+}
+
+export function clampSeekTargetSamples(
+	targetSample: number,
+	seekableSamples: number | null,
+): { value: number; clamped: boolean } {
+	const requested = Number.isFinite(targetSample)
+		? Math.max(0, Math.floor(targetSample))
+		: 0;
+	if (
+		seekableSamples == null ||
+		!Number.isFinite(seekableSamples) ||
+		seekableSamples < 0
+	) {
+		return { value: requested, clamped: false };
+	}
+	const clampedValue = Math.min(requested, Math.max(0, Math.floor(seekableSamples)));
+	return {
+		value: clampedValue,
+		clamped: clampedValue !== requested,
+	};
+}