entangled-worlds-orbiters-shared 2.15.0 → 2.16.0

package/dist/audio/aiff.d.ts

@@ -0,0 +1,43 @@
+export type AiffErrorCode = 'not-aiff' | 'truncated' | 'compressed' | 'unsupported';
+export declare class AiffError extends Error {
+    readonly code: AiffErrorCode;
+    /** The AIFF-C compression id (`'ima4'`, `'ulaw'`, …) when `code` is `'compressed'`. */
+    readonly compression?: string;
+    constructor(code: AiffErrorCode, message: string, compression?: string);
+}
+export interface AiffInfo {
+    /** `'AIFF'`, or `'AIFC'` for AIFF-C. */
+    form: 'AIFF' | 'AIFC';
+    /** The AIFF-C compression id; `'NONE'` for plain AIFF. */
+    compression: string;
+    channels: number;
+    sampleRate: number;
+    /** Bits per sample as the file declares them (1–32 for integers, 32 or 64 for floats). */
+    bitsPerSample: number;
+    /** Sample frames that are really in the file (fewer than declared when it was cut short; all
+     *  of the sound data when the header says 0, as a streaming writer leaves it). */
+    frames: number;
+    /** True when the file promised more frames than it holds. */
+    truncated: boolean;
+}
+/** True when the bytes are an AIFF or AIFF-C file. Judged on the bytes, never on a file name. */
+export declare function isAiff(input: ArrayBuffer | ArrayBufferView): boolean;
+/** The header only: format, length, and whether the file can be read at all (throws `AiffError`). */
+export declare function readAiffInfo(input: ArrayBuffer | ArrayBufferView): AiffInfo;
+export interface AiffAudio extends AiffInfo {
+    /** One array per channel, samples in -1…1. */
+    channelData: Float32Array[];
+}
+/** Decode an AIFF file to float samples per channel. Throws `AiffError`. */
+export declare function readAiff(input: ArrayBuffer | ArrayBufferView): AiffAudio;
+/**
+ * Rewrite an AIFF file as a WAV with the same samples at the same bit depth (integers stay
+ * integers, 32-bit floats stay floats; 64-bit floats become 32-bit, which every browser decodes).
+ * An `ID3 ` chunk (the tags and cover) goes along as the WAV's `id3 ` chunk. Throws `AiffError`.
+ */
+export declare function aiffToWav(input: ArrayBuffer | ArrayBufferView): Uint8Array;
+/**
+ * A minimal valid AIFF (16-bit mono, 8000 Hz, a few frames of silence): enough for asking a
+ * browser whether its own decoder reads AIFF.
+ */
+export declare function makeProbeAiff(frames?: number): Uint8Array;

package/dist/audio/aiff.js

@@ -0,0 +1,305 @@
+// Reading AIFF ourselves, because Chrome and Firefox can't (`decodeAudioData` and `<audio>` both
+// refuse it; Safari plays it). AIFF is the same uncompressed PCM as WAV, big-endian, in an IFF
+// container, so "decoding" is reading the header and putting the bytes in the right order: one
+// linear pass, no codec, no dependency.
+//
+// Two outputs from one parse:
+//   - `readAiff`  → float samples per channel, for building an `AudioBuffer` in memory;
+//   - `aiffToWav` → a WAV file with the same samples at the same bit depth, for a copy the browser
+//     plays natively from then on.
+//
+// Compressed AIFF-C (`ima4`, `ulaw`, `alaw`, `MAC3`, `MAC6`, …) is refused with `AiffError`
+// code `'compressed'`; there is no PCM in it to reorder.
+export class AiffError extends Error {
+    code;
+    /** The AIFF-C compression id (`'ima4'`, `'ulaw'`, …) when `code` is `'compressed'`. */
+    compression;
+    constructor(code, message, compression) {
+        super(message);
+        this.name = 'AiffError';
+        this.code = code;
+        this.compression = compression;
+    }
+}
+/** AIFF-C ids that hold plain PCM, and how to read them. */
+const PCM_COMPRESSIONS = {
+    NONE: { encoding: 'int-be' },
+    twos: { encoding: 'int-be' },
+    sowt: { encoding: 'int-le' },
+    in24: { encoding: 'int-be', bits: 24 },
+    in32: { encoding: 'int-be', bits: 32 },
+    '42ni': { encoding: 'int-le', bits: 24 },
+    '23ni': { encoding: 'int-le', bits: 32 },
+    fl32: { encoding: 'float-be', bits: 32 },
+    FL32: { encoding: 'float-be', bits: 32 },
+    fl64: { encoding: 'float-be', bits: 64 },
+    FL64: { encoding: 'float-be', bits: 64 },
+};
+function fourCC(bytes, at) {
+    return String.fromCharCode(bytes[at], bytes[at + 1], bytes[at + 2], bytes[at + 3]);
+}
+function asBytes(input) {
+    if (input instanceof Uint8Array)
+        return input;
+    if (ArrayBuffer.isView(input))
+        return new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
+    return new Uint8Array(input);
+}
+/** True when the bytes are an AIFF or AIFF-C file. Judged on the bytes, never on a file name. */
+export function isAiff(input) {
+    const bytes = asBytes(input);
+    if (bytes.length < 12)
+        return false;
+    const form = fourCC(bytes, 8);
+    return fourCC(bytes, 0) === 'FORM' && (form === 'AIFF' || form === 'AIFC');
+}
+/** The 80-bit IEEE 754 extended float AIFF stores its sample rate in. */
+function readExtended(view, at) {
+    const signExp = view.getUint16(at);
+    const hi = view.getUint32(at + 2);
+    const lo = view.getUint32(at + 6);
+    const exp = (signExp & 0x7fff) - 16383;
+    if ((signExp & 0x7fff) === 0 && hi === 0 && lo === 0)
+        return 0;
+    const value = hi * 2 ** (exp - 31) + lo * 2 ** (exp - 63);
+    return signExp & 0x8000 ? -value : value;
+}
+function parse(bytes) {
+    if (!isAiff(bytes))
+        throw new AiffError('not-aiff', 'Not an AIFF file');
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const form = fourCC(bytes, 8);
+    // The FORM size can be wrong: larger than the file (a file cut short) or 0 (a streaming writer
+    // that never went back to fill it in). The bytes we have are the real limit.
+    const formSize = view.getUint32(4);
+    const end = formSize >= 4 ? Math.min(bytes.length, 8 + formSize) : bytes.length;
+    let comm = null;
+    let ssnd = null;
+    let id3 = null;
+    // Chunks may come in any order; walk them all.
+    let at = 12;
+    while (at + 8 <= end) {
+        const id = fourCC(bytes, at);
+        const size = view.getUint32(at + 4);
+        const body = at + 8;
+        const bodyEnd = Math.min(body + size, end);
+        if (id === 'COMM') {
+            if (bodyEnd - body < 18)
+                throw new AiffError('truncated', 'The AIFF header is cut short');
+            let compression = 'NONE';
+            if (form === 'AIFC') {
+                if (bodyEnd - body < 22)
+                    throw new AiffError('truncated', 'The AIFF header is cut short');
+                compression = fourCC(bytes, body + 18);
+            }
+            comm = {
+                channels: view.getUint16(body),
+                frames: view.getUint32(body + 2),
+                bits: view.getUint16(body + 6),
+                sampleRate: readExtended(view, body + 8),
+                compression,
+            };
+        }
+        else if (id === 'SSND') {
+            if (bodyEnd - body < 8)
+                throw new AiffError('truncated', 'The AIFF sound data is cut short');
+            const offset = view.getUint32(body);
+            ssnd = { start: Math.min(body + 8 + offset, bodyEnd), end: bodyEnd };
+        }
+        else if (id === 'ID3 ' && bodyEnd > body) {
+            id3 = { start: body, end: bodyEnd };
+        }
+        // Chunk bodies are padded to an even length.
+        at = body + size + (size & 1);
+    }
+    if (!comm)
+        throw new AiffError('truncated', 'The AIFF file has no format chunk');
+    const pcm = PCM_COMPRESSIONS[comm.compression];
+    if (!pcm) {
+        throw new AiffError('compressed', `Compressed AIFF-C (${comm.compression.trim() || 'unknown'}) is not supported`, comm.compression);
+    }
+    const bits = pcm.bits ?? comm.bits;
+    if (comm.channels < 1)
+        throw new AiffError('unsupported', 'The AIFF file has no channels');
+    if (!(comm.sampleRate > 0) || !Number.isFinite(comm.sampleRate)) {
+        throw new AiffError('unsupported', 'The AIFF file has no usable sample rate');
+    }
+    if (pcm.encoding === 'float-be' ? bits !== 32 && bits !== 64 : bits < 1 || bits > 32) {
+        throw new AiffError('unsupported', `${bits}-bit AIFF samples are not supported`);
+    }
+    const bytesPerSample = Math.ceil(bits / 8);
+    const frameBytes = bytesPerSample * comm.channels;
+    const available = ssnd ? Math.floor((ssnd.end - ssnd.start) / frameBytes) : 0;
+    if (comm.frames > 0 && !ssnd)
+        throw new AiffError('truncated', 'The AIFF file has no sound data');
+    const frames = comm.frames > 0 ? Math.min(comm.frames, available) : available;
+    return {
+        form,
+        compression: comm.compression,
+        channels: comm.channels,
+        sampleRate: comm.sampleRate,
+        bitsPerSample: bits,
+        frames,
+        truncated: frames < comm.frames,
+        encoding: pcm.encoding,
+        bytesPerSample,
+        dataStart: ssnd ? ssnd.start : 0,
+        id3,
+    };
+}
+function infoOf(p) {
+    const { form, compression, channels, sampleRate, bitsPerSample, frames, truncated } = p;
+    return { form, compression, channels, sampleRate, bitsPerSample, frames, truncated };
+}
+/** The header only: format, length, and whether the file can be read at all (throws `AiffError`). */
+export function readAiffInfo(input) {
+    return infoOf(parse(asBytes(input)));
+}
+/** Decode an AIFF file to float samples per channel. Throws `AiffError`. */
+export function readAiff(input) {
+    const bytes = asBytes(input);
+    const p = parse(bytes);
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const { channels, frames, bytesPerSample: n, encoding } = p;
+    const channelData = Array.from({ length: channels }, () => new Float32Array(frames));
+    const scale = 1 / 2 ** (n * 8 - 1);
+    let at = p.dataStart;
+    if (encoding === 'float-be') {
+        const read = n === 4 ? (i) => view.getFloat32(i) : (i) => view.getFloat64(i);
+        for (let f = 0; f < frames; f++) {
+            for (let c = 0; c < channels; c++, at += n)
+                channelData[c][f] = read(at);
+        }
+    }
+    else if (n === 2) {
+        const le = encoding === 'int-le';
+        for (let f = 0; f < frames; f++) {
+            for (let c = 0; c < channels; c++, at += 2)
+                channelData[c][f] = view.getInt16(at, le) * scale;
+        }
+    }
+    else if (n === 4) {
+        const le = encoding === 'int-le';
+        for (let f = 0; f < frames; f++) {
+            for (let c = 0; c < channels; c++, at += 4)
+                channelData[c][f] = view.getInt32(at, le) * scale;
+        }
+    }
+    else {
+        // 8- and 24-bit (and anything else that fills 1 or 3 bytes): assemble, then sign-extend.
+        const le = encoding === 'int-le';
+        const shift = 32 - n * 8;
+        for (let f = 0; f < frames; f++) {
+            for (let c = 0; c < channels; c++, at += n) {
+                let v = 0;
+                for (let b = 0; b < n; b++)
+                    v = (v << 8) | bytes[le ? at + n - 1 - b : at + b];
+                channelData[c][f] = ((v << shift) >> shift) * scale;
+            }
+        }
+    }
+    return { ...infoOf(p), channelData };
+}
+/**
+ * Rewrite an AIFF file as a WAV with the same samples at the same bit depth (integers stay
+ * integers, 32-bit floats stay floats; 64-bit floats become 32-bit, which every browser decodes).
+ * An `ID3 ` chunk (the tags and cover) goes along as the WAV's `id3 ` chunk. Throws `AiffError`.
+ */
+export function aiffToWav(input) {
+    const bytes = asBytes(input);
+    const p = parse(bytes);
+    const { channels, frames, encoding } = p;
+    const inN = p.bytesPerSample;
+    const isFloat = encoding === 'float-be';
+    const outN = isFloat ? 4 : inN;
+    const dataBytes = frames * channels * outN;
+    const headerBytes = 44;
+    const dataEnd = headerBytes + dataBytes + (dataBytes & 1);
+    const id3Bytes = p.id3 ? p.id3.end - p.id3.start : 0;
+    const out = new Uint8Array(dataEnd + (id3Bytes ? 8 + id3Bytes + (id3Bytes & 1) : 0));
+    const w = new DataView(out.buffer);
+    const ascii = (at, s) => {
+        for (let i = 0; i < 4; i++)
+            out[at + i] = s.charCodeAt(i);
+    };
+    ascii(0, 'RIFF');
+    w.setUint32(4, out.length - 8, true);
+    ascii(8, 'WAVE');
+    ascii(12, 'fmt ');
+    w.setUint32(16, 16, true);
+    w.setUint16(20, isFloat ? 3 : 1, true);
+    w.setUint16(22, channels, true);
+    // WAV holds an integer rate; AIFF's is a float that is almost always whole already.
+    const rate = Math.round(p.sampleRate);
+    w.setUint32(24, rate, true);
+    w.setUint32(28, rate * channels * outN, true);
+    w.setUint16(32, channels * outN, true);
+    w.setUint16(34, outN * 8, true);
+    ascii(36, 'data');
+    w.setUint32(40, dataBytes, true);
+    const src = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const samples = frames * channels;
+    let i = p.dataStart;
+    let o = headerBytes;
+    if (isFloat) {
+        for (let s = 0; s < samples; s++, i += inN, o += 4) {
+            w.setFloat32(o, inN === 4 ? src.getFloat32(i) : src.getFloat64(i), true);
+        }
+    }
+    else if (inN === 1) {
+        // AIFF 8-bit is signed, WAV 8-bit is unsigned.
+        for (let s = 0; s < samples; s++)
+            out[o++] = bytes[i++] ^ 0x80;
+    }
+    else if (encoding === 'int-le') {
+        out.set(bytes.subarray(i, i + samples * inN), o);
+    }
+    else {
+        for (let s = 0; s < samples; s++, i += inN, o += inN) {
+            for (let b = 0; b < inN; b++)
+                out[o + b] = bytes[i + inN - 1 - b];
+        }
+    }
+    if (p.id3) {
+        ascii(dataEnd, 'id3 ');
+        w.setUint32(dataEnd + 4, id3Bytes, true);
+        out.set(bytes.subarray(p.id3.start, p.id3.end), dataEnd + 8);
+    }
+    return out;
+}
+function writeExtended(view, at, value) {
+    // Positive, whole sample rates only; enough for the probe below.
+    const exp = Math.floor(Math.log2(value));
+    view.setUint16(at, exp + 16383);
+    const mantissa = value / 2 ** exp;
+    view.setUint32(at + 2, Math.floor(mantissa * 2 ** 31) >>> 0);
+    view.setUint32(at + 6, 0);
+}
+/**
+ * A minimal valid AIFF (16-bit mono, 8000 Hz, a few frames of silence): enough for asking a
+ * browser whether its own decoder reads AIFF.
+ */
+export function makeProbeAiff(frames = 8) {
+    const sampleRate = 8000;
+    const dataBytes = frames * 2;
+    const out = new Uint8Array(12 + 26 + 16 + dataBytes);
+    const w = new DataView(out.buffer);
+    const ascii = (at, s) => {
+        for (let i = 0; i < 4; i++)
+            out[at + i] = s.charCodeAt(i);
+    };
+    ascii(0, 'FORM');
+    w.setUint32(4, out.length - 8);
+    ascii(8, 'AIFF');
+    ascii(12, 'COMM');
+    w.setUint32(16, 18);
+    w.setUint16(20, 1);
+    w.setUint32(22, frames);
+    w.setUint16(26, 16);
+    writeExtended(w, 28, sampleRate);
+    ascii(38, 'SSND');
+    w.setUint32(42, 8 + dataBytes);
+    w.setUint32(46, 0);
+    w.setUint32(50, 0);
+    return out;
+}

package/dist/audio/index.d.ts

@@ -0,0 +1,32 @@
+export { AiffError, aiffToWav, isAiff, readAiff, readAiffInfo } from './aiff.js';
+export type { AiffAudio, AiffErrorCode, AiffInfo } from './aiff.js';
+/** The slice of `BaseAudioContext` decoding needs, so tests and workers can pass a stand-in. */
+export interface DecodeContext {
+    readonly sampleRate: number;
+    decodeAudioData(data: ArrayBuffer): Promise<AudioBuffer>;
+    createBuffer(channels: number, length: number, sampleRate: number): AudioBuffer;
+}
+/** Build an `AudioBuffer` from AIFF bytes with our own decoder. Throws `AiffError`. */
+export declare function decodeAiff(ctx: DecodeContext, bytes: ArrayBuffer | ArrayBufferView): Promise<AudioBuffer>;
+/**
+ * Decode audio bytes to an `AudioBuffer`: the browser's decoder first, then, if that fails and the
+ * bytes are AIFF, ours. Detected by the bytes, not by `name` (which only labels the error).
+ * A compressed AIFF-C rejects with `AiffError` code `'compressed'`; anything else the browser
+ * can't read rejects with the browser's own error.
+ *
+ * Like `decodeAudioData`, this may detach an `ArrayBuffer` it is given: anything that is not AIFF
+ * goes to the browser as it is, so a large download is never held twice. AIFF goes straight to
+ * ours where the browser is known not to read it (`canDecodeAiffNatively`, asked once); elsewhere
+ * it is copied for the browser's try, because ours may still need it.
+ *
+ * Ours runs on the calling thread, as one linear pass: fine for a file the size of a take, felt as
+ * a pause for a long high-rate one.
+ */
+export declare function decodeAudio(ctx: DecodeContext, bytes: ArrayBuffer | ArrayBufferView, name?: string): Promise<AudioBuffer>;
+/** Forget the answer of `canDecodeAiffNatively`; for tests. */
+export declare function resetAiffProbeForTests(): void;
+/**
+ * Whether this browser's own decoder reads AIFF (Safari does; Chrome and Firefox don't). Asked
+ * once with a tiny generated file and remembered for the page's life.
+ */
+export declare function canDecodeAiffNatively(ctx: DecodeContext): Promise<boolean>;

package/dist/audio/index.js

@@ -0,0 +1,89 @@
+// Decoding audio bytes in any browser: the browser's own decoder first, and ours for the formats
+// it can't read (AIFF in Chrome and Firefox). Framework-free; needs only a Web Audio context.
+import { AiffError, isAiff, makeProbeAiff, readAiff } from './aiff.js';
+export { AiffError, aiffToWav, isAiff, readAiff, readAiffInfo } from './aiff.js';
+/** The bytes as an `ArrayBuffer` for `decodeAudioData`, copied only when `copy` or a view needs it. */
+function toArrayBuffer(bytes, copy) {
+    if (bytes instanceof ArrayBuffer)
+        return copy ? bytes.slice(0) : bytes;
+    const view = new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (!copy && bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength && bytes.buffer instanceof ArrayBuffer) {
+        return bytes.buffer;
+    }
+    return view.slice().buffer;
+}
+/**
+ * Bring a buffer to the context's rate, as `decodeAudioData` would have. Without an
+ * `OfflineAudioContext` (a worker, a test) the buffer keeps its own rate, which a source node
+ * still plays correctly.
+ */
+async function resampleTo(buffer, sampleRate) {
+    const Offline = globalThis.OfflineAudioContext;
+    if (!Offline || buffer.sampleRate === sampleRate)
+        return buffer;
+    const length = Math.max(1, Math.round((buffer.length * sampleRate) / buffer.sampleRate));
+    const offline = new Offline(buffer.numberOfChannels, length, sampleRate);
+    const source = offline.createBufferSource();
+    source.buffer = buffer;
+    source.connect(offline.destination);
+    source.start();
+    return offline.startRendering();
+}
+/** Build an `AudioBuffer` from AIFF bytes with our own decoder. Throws `AiffError`. */
+export async function decodeAiff(ctx, bytes) {
+    const audio = readAiff(bytes);
+    if (audio.frames === 0)
+        throw new AiffError('truncated', 'The AIFF file holds no audio');
+    const buffer = ctx.createBuffer(audio.channels, audio.frames, audio.sampleRate);
+    audio.channelData.forEach((data, c) => buffer.copyToChannel(data, c));
+    return resampleTo(buffer, ctx.sampleRate);
+}
+/**
+ * Decode audio bytes to an `AudioBuffer`: the browser's decoder first, then, if that fails and the
+ * bytes are AIFF, ours. Detected by the bytes, not by `name` (which only labels the error).
+ * A compressed AIFF-C rejects with `AiffError` code `'compressed'`; anything else the browser
+ * can't read rejects with the browser's own error.
+ *
+ * Like `decodeAudioData`, this may detach an `ArrayBuffer` it is given: anything that is not AIFF
+ * goes to the browser as it is, so a large download is never held twice. AIFF goes straight to
+ * ours where the browser is known not to read it (`canDecodeAiffNatively`, asked once); elsewhere
+ * it is copied for the browser's try, because ours may still need it.
+ *
+ * Ours runs on the calling thread, as one linear pass: fine for a file the size of a take, felt as
+ * a pause for a long high-rate one.
+ */
+export async function decodeAudio(ctx, bytes, name) {
+    if (!isAiff(bytes))
+        return ctx.decodeAudioData(toArrayBuffer(bytes, false));
+    try {
+        if (!(await canDecodeAiffNatively(ctx)))
+            throw new Error('not native');
+        return await ctx.decodeAudioData(toArrayBuffer(bytes, true));
+    }
+    catch {
+        try {
+            return await decodeAiff(ctx, bytes);
+        }
+        catch (aiffErr) {
+            if (aiffErr instanceof AiffError && name)
+                aiffErr.message = `${name}: ${aiffErr.message}`;
+            throw aiffErr;
+        }
+    }
+}
+let nativeAiff = null;
+/** Forget the answer of `canDecodeAiffNatively`; for tests. */
+export function resetAiffProbeForTests() {
+    nativeAiff = null;
+}
+/**
+ * Whether this browser's own decoder reads AIFF (Safari does; Chrome and Firefox don't). Asked
+ * once with a tiny generated file and remembered for the page's life.
+ */
+export function canDecodeAiffNatively(ctx) {
+    nativeAiff ??= ctx
+        .decodeAudioData(makeProbeAiff().buffer)
+        .then((buffer) => buffer.length > 0)
+        .catch(() => false);
+    return nativeAiff;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "entangled-worlds-orbiters-shared",
-  "version": "2.15.0",
+  "version": "2.16.0",
   "description": "Shared library for entangled worlds orbiters - contains core world rendering, moons system, and UI components",
   "type": "module",
   "main": "src/index.js",
@@ -61,12 +61,17 @@
     "./star": {
       "types": "./dist/star/index.d.ts",
       "import": "./dist/star/index.js"
+    },
+    "./audio": {
+      "types": "./dist/audio/index.d.ts",
+      "import": "./dist/audio/index.js"
     }
   },
   "files": [
     "src/**/*",
     "!src/**/*.test.ts",
     "!src/**/*.test.js",
+    "!src/**/fixtures/**",
     "dist/**/*",
     "public/**/*",
     "README.md",
@@ -129,8 +134,9 @@
     "test:faust": "node --test --import tsx src/faust/*.test.ts",
     "test:studio": "node --test --import tsx src/studio/*.test.js",
     "test:uploads": "node --test --import tsx src/uploads/*.test.js",
+    "test:audio": "node --test --import tsx src/audio/*.test.ts",
     "test:render": "node --test src/render/*.test.js",
-    "test": "npm run test:clock && npm run test:capabilities && npm run test:notes && npm run test:faust && npm run test:studio && npm run test:uploads && npm run test:render && npm run test:moons && npm run test:star",
+    "test": "npm run test:clock && npm run test:capabilities && npm run test:notes && npm run test:faust && npm run test:studio && npm run test:uploads && npm run test:audio && npm run test:render && npm run test:moons && npm run test:star",
     "test:moons": "node --test src/moons/*.test.js",
     "test:star": "node --test --import tsx src/star/*.test.ts",
     "bench:star:build": "esbuild bench/star/main.ts --bundle --format=esm --target=es2022 --outfile=bench/star/build/main.js --log-level=warning",

package/src/audio/aiff.ts

@@ -0,0 +1,337 @@
+// Reading AIFF ourselves, because Chrome and Firefox can't (`decodeAudioData` and `<audio>` both
+// refuse it; Safari plays it). AIFF is the same uncompressed PCM as WAV, big-endian, in an IFF
+// container, so "decoding" is reading the header and putting the bytes in the right order: one
+// linear pass, no codec, no dependency.
+//
+// Two outputs from one parse:
+//   - `readAiff`  → float samples per channel, for building an `AudioBuffer` in memory;
+//   - `aiffToWav` → a WAV file with the same samples at the same bit depth, for a copy the browser
+//     plays natively from then on.
+//
+// Compressed AIFF-C (`ima4`, `ulaw`, `alaw`, `MAC3`, `MAC6`, …) is refused with `AiffError`
+// code `'compressed'`; there is no PCM in it to reorder.
+
+export type AiffErrorCode = 'not-aiff' | 'truncated' | 'compressed' | 'unsupported'
+
+export class AiffError extends Error {
+  readonly code: AiffErrorCode
+  /** The AIFF-C compression id (`'ima4'`, `'ulaw'`, …) when `code` is `'compressed'`. */
+  readonly compression?: string
+
+  constructor(code: AiffErrorCode, message: string, compression?: string) {
+    super(message)
+    this.name = 'AiffError'
+    this.code = code
+    this.compression = compression
+  }
+}
+
+/** How the sample bytes are laid out. Every AIFF-C id we accept maps to one of these. */
+type SampleEncoding = 'int-be' | 'int-le' | 'float-be'
+
+export interface AiffInfo {
+  /** `'AIFF'`, or `'AIFC'` for AIFF-C. */
+  form: 'AIFF' | 'AIFC'
+  /** The AIFF-C compression id; `'NONE'` for plain AIFF. */
+  compression: string
+  channels: number
+  sampleRate: number
+  /** Bits per sample as the file declares them (1–32 for integers, 32 or 64 for floats). */
+  bitsPerSample: number
+  /** Sample frames that are really in the file (fewer than declared when it was cut short; all
+   *  of the sound data when the header says 0, as a streaming writer leaves it). */
+  frames: number
+  /** True when the file promised more frames than it holds. */
+  truncated: boolean
+}
+
+interface ParsedAiff extends AiffInfo {
+  encoding: SampleEncoding
+  /** Bytes per sample in the file (integers are left-justified in whole bytes). */
+  bytesPerSample: number
+  /** Byte offset of the first sample frame. */
+  dataStart: number
+  /** Where an `ID3 ` chunk's body is (the file's tags and cover), when it has one. */
+  id3: { start: number; end: number } | null
+}
+
+/** AIFF-C ids that hold plain PCM, and how to read them. */
+const PCM_COMPRESSIONS: Record<string, { encoding: SampleEncoding; bits?: number }> = {
+  NONE: { encoding: 'int-be' },
+  twos: { encoding: 'int-be' },
+  sowt: { encoding: 'int-le' },
+  in24: { encoding: 'int-be', bits: 24 },
+  in32: { encoding: 'int-be', bits: 32 },
+  '42ni': { encoding: 'int-le', bits: 24 },
+  '23ni': { encoding: 'int-le', bits: 32 },
+  fl32: { encoding: 'float-be', bits: 32 },
+  FL32: { encoding: 'float-be', bits: 32 },
+  fl64: { encoding: 'float-be', bits: 64 },
+  FL64: { encoding: 'float-be', bits: 64 },
+}
+
+function fourCC(bytes: Uint8Array, at: number): string {
+  return String.fromCharCode(bytes[at], bytes[at + 1], bytes[at + 2], bytes[at + 3])
+}
+
+function asBytes(input: ArrayBuffer | ArrayBufferView): Uint8Array {
+  if (input instanceof Uint8Array) return input
+  if (ArrayBuffer.isView(input)) return new Uint8Array(input.buffer, input.byteOffset, input.byteLength)
+  return new Uint8Array(input)
+}
+
+/** True when the bytes are an AIFF or AIFF-C file. Judged on the bytes, never on a file name. */
+export function isAiff(input: ArrayBuffer | ArrayBufferView): boolean {
+  const bytes = asBytes(input)
+  if (bytes.length < 12) return false
+  const form = fourCC(bytes, 8)
+  return fourCC(bytes, 0) === 'FORM' && (form === 'AIFF' || form === 'AIFC')
+}
+
+/** The 80-bit IEEE 754 extended float AIFF stores its sample rate in. */
+function readExtended(view: DataView, at: number): number {
+  const signExp = view.getUint16(at)
+  const hi = view.getUint32(at + 2)
+  const lo = view.getUint32(at + 6)
+  const exp = (signExp & 0x7fff) - 16383
+  if ((signExp & 0x7fff) === 0 && hi === 0 && lo === 0) return 0
+  const value = hi * 2 ** (exp - 31) + lo * 2 ** (exp - 63)
+  return signExp & 0x8000 ? -value : value
+}
+
+function parse(bytes: Uint8Array): ParsedAiff {
+  if (!isAiff(bytes)) throw new AiffError('not-aiff', 'Not an AIFF file')
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  const form = fourCC(bytes, 8) as 'AIFF' | 'AIFC'
+  // The FORM size can be wrong: larger than the file (a file cut short) or 0 (a streaming writer
+  // that never went back to fill it in). The bytes we have are the real limit.
+  const formSize = view.getUint32(4)
+  const end = formSize >= 4 ? Math.min(bytes.length, 8 + formSize) : bytes.length
+
+  let comm: { channels: number; frames: number; bits: number; sampleRate: number; compression: string } | null = null
+  let ssnd: { start: number; end: number } | null = null
+  let id3: { start: number; end: number } | null = null
+
+  // Chunks may come in any order; walk them all.
+  let at = 12
+  while (at + 8 <= end) {
+    const id = fourCC(bytes, at)
+    const size = view.getUint32(at + 4)
+    const body = at + 8
+    const bodyEnd = Math.min(body + size, end)
+    if (id === 'COMM') {
+      if (bodyEnd - body < 18) throw new AiffError('truncated', 'The AIFF header is cut short')
+      let compression = 'NONE'
+      if (form === 'AIFC') {
+        if (bodyEnd - body < 22) throw new AiffError('truncated', 'The AIFF header is cut short')
+        compression = fourCC(bytes, body + 18)
+      }
+      comm = {
+        channels: view.getUint16(body),
+        frames: view.getUint32(body + 2),
+        bits: view.getUint16(body + 6),
+        sampleRate: readExtended(view, body + 8),
+        compression,
+      }
+    } else if (id === 'SSND') {
+      if (bodyEnd - body < 8) throw new AiffError('truncated', 'The AIFF sound data is cut short')
+      const offset = view.getUint32(body)
+      ssnd = { start: Math.min(body + 8 + offset, bodyEnd), end: bodyEnd }
+    } else if (id === 'ID3 ' && bodyEnd > body) {
+      id3 = { start: body, end: bodyEnd }
+    }
+    // Chunk bodies are padded to an even length.
+    at = body + size + (size & 1)
+  }
+
+  if (!comm) throw new AiffError('truncated', 'The AIFF file has no format chunk')
+  const pcm = PCM_COMPRESSIONS[comm.compression]
+  if (!pcm) {
+    throw new AiffError(
+      'compressed',
+      `Compressed AIFF-C (${comm.compression.trim() || 'unknown'}) is not supported`,
+      comm.compression,
+    )
+  }
+  const bits = pcm.bits ?? comm.bits
+  if (comm.channels < 1) throw new AiffError('unsupported', 'The AIFF file has no channels')
+  if (!(comm.sampleRate > 0) || !Number.isFinite(comm.sampleRate)) {
+    throw new AiffError('unsupported', 'The AIFF file has no usable sample rate')
+  }
+  if (pcm.encoding === 'float-be' ? bits !== 32 && bits !== 64 : bits < 1 || bits > 32) {
+    throw new AiffError('unsupported', `${bits}-bit AIFF samples are not supported`)
+  }
+  const bytesPerSample = Math.ceil(bits / 8)
+  const frameBytes = bytesPerSample * comm.channels
+  const available = ssnd ? Math.floor((ssnd.end - ssnd.start) / frameBytes) : 0
+  if (comm.frames > 0 && !ssnd) throw new AiffError('truncated', 'The AIFF file has no sound data')
+  const frames = comm.frames > 0 ? Math.min(comm.frames, available) : available
+  return {
+    form,
+    compression: comm.compression,
+    channels: comm.channels,
+    sampleRate: comm.sampleRate,
+    bitsPerSample: bits,
+    frames,
+    truncated: frames < comm.frames,
+    encoding: pcm.encoding,
+    bytesPerSample,
+    dataStart: ssnd ? ssnd.start : 0,
+    id3,
+  }
+}
+
+function infoOf(p: ParsedAiff): AiffInfo {
+  const { form, compression, channels, sampleRate, bitsPerSample, frames, truncated } = p
+  return { form, compression, channels, sampleRate, bitsPerSample, frames, truncated }
+}
+
+/** The header only: format, length, and whether the file can be read at all (throws `AiffError`). */
+export function readAiffInfo(input: ArrayBuffer | ArrayBufferView): AiffInfo {
+  return infoOf(parse(asBytes(input)))
+}
+
+export interface AiffAudio extends AiffInfo {
+  /** One array per channel, samples in -1…1. */
+  channelData: Float32Array[]
+}
+
+/** Decode an AIFF file to float samples per channel. Throws `AiffError`. */
+export function readAiff(input: ArrayBuffer | ArrayBufferView): AiffAudio {
+  const bytes = asBytes(input)
+  const p = parse(bytes)
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  const { channels, frames, bytesPerSample: n, encoding } = p
+  const channelData = Array.from({ length: channels }, () => new Float32Array(frames))
+  const scale = 1 / 2 ** (n * 8 - 1)
+  let at = p.dataStart
+
+  if (encoding === 'float-be') {
+    const read = n === 4 ? (i: number) => view.getFloat32(i) : (i: number) => view.getFloat64(i)
+    for (let f = 0; f < frames; f++) {
+      for (let c = 0; c < channels; c++, at += n) channelData[c][f] = read(at)
+    }
+  } else if (n === 2) {
+    const le = encoding === 'int-le'
+    for (let f = 0; f < frames; f++) {
+      for (let c = 0; c < channels; c++, at += 2) channelData[c][f] = view.getInt16(at, le) * scale
+    }
+  } else if (n === 4) {
+    const le = encoding === 'int-le'
+    for (let f = 0; f < frames; f++) {
+      for (let c = 0; c < channels; c++, at += 4) channelData[c][f] = view.getInt32(at, le) * scale
+    }
+  } else {
+    // 8- and 24-bit (and anything else that fills 1 or 3 bytes): assemble, then sign-extend.
+    const le = encoding === 'int-le'
+    const shift = 32 - n * 8
+    for (let f = 0; f < frames; f++) {
+      for (let c = 0; c < channels; c++, at += n) {
+        let v = 0
+        for (let b = 0; b < n; b++) v = (v << 8) | bytes[le ? at + n - 1 - b : at + b]
+        channelData[c][f] = ((v << shift) >> shift) * scale
+      }
+    }
+  }
+  return { ...infoOf(p), channelData }
+}
+
+/**
+ * Rewrite an AIFF file as a WAV with the same samples at the same bit depth (integers stay
+ * integers, 32-bit floats stay floats; 64-bit floats become 32-bit, which every browser decodes).
+ * An `ID3 ` chunk (the tags and cover) goes along as the WAV's `id3 ` chunk. Throws `AiffError`.
+ */
+export function aiffToWav(input: ArrayBuffer | ArrayBufferView): Uint8Array {
+  const bytes = asBytes(input)
+  const p = parse(bytes)
+  const { channels, frames, encoding } = p
+  const inN = p.bytesPerSample
+  const isFloat = encoding === 'float-be'
+  const outN = isFloat ? 4 : inN
+  const dataBytes = frames * channels * outN
+  const headerBytes = 44
+  const dataEnd = headerBytes + dataBytes + (dataBytes & 1)
+  const id3Bytes = p.id3 ? p.id3.end - p.id3.start : 0
+  const out = new Uint8Array(dataEnd + (id3Bytes ? 8 + id3Bytes + (id3Bytes & 1) : 0))
+  const w = new DataView(out.buffer)
+  const ascii = (at: number, s: string) => {
+    for (let i = 0; i < 4; i++) out[at + i] = s.charCodeAt(i)
+  }
+  ascii(0, 'RIFF')
+  w.setUint32(4, out.length - 8, true)
+  ascii(8, 'WAVE')
+  ascii(12, 'fmt ')
+  w.setUint32(16, 16, true)
+  w.setUint16(20, isFloat ? 3 : 1, true)
+  w.setUint16(22, channels, true)
+  // WAV holds an integer rate; AIFF's is a float that is almost always whole already.
+  const rate = Math.round(p.sampleRate)
+  w.setUint32(24, rate, true)
+  w.setUint32(28, rate * channels * outN, true)
+  w.setUint16(32, channels * outN, true)
+  w.setUint16(34, outN * 8, true)
+  ascii(36, 'data')
+  w.setUint32(40, dataBytes, true)
+
+  const src = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  const samples = frames * channels
+  let i = p.dataStart
+  let o = headerBytes
+  if (isFloat) {
+    for (let s = 0; s < samples; s++, i += inN, o += 4) {
+      w.setFloat32(o, inN === 4 ? src.getFloat32(i) : src.getFloat64(i), true)
+    }
+  } else if (inN === 1) {
+    // AIFF 8-bit is signed, WAV 8-bit is unsigned.
+    for (let s = 0; s < samples; s++) out[o++] = bytes[i++] ^ 0x80
+  } else if (encoding === 'int-le') {
+    out.set(bytes.subarray(i, i + samples * inN), o)
+  } else {
+    for (let s = 0; s < samples; s++, i += inN, o += inN) {
+      for (let b = 0; b < inN; b++) out[o + b] = bytes[i + inN - 1 - b]
+    }
+  }
+  if (p.id3) {
+    ascii(dataEnd, 'id3 ')
+    w.setUint32(dataEnd + 4, id3Bytes, true)
+    out.set(bytes.subarray(p.id3.start, p.id3.end), dataEnd + 8)
+  }
+  return out
+}
+
+function writeExtended(view: DataView, at: number, value: number) {
+  // Positive, whole sample rates only; enough for the probe below.
+  const exp = Math.floor(Math.log2(value))
+  view.setUint16(at, exp + 16383)
+  const mantissa = value / 2 ** exp
+  view.setUint32(at + 2, Math.floor(mantissa * 2 ** 31) >>> 0)
+  view.setUint32(at + 6, 0)
+}
+
+/**
+ * A minimal valid AIFF (16-bit mono, 8000 Hz, a few frames of silence): enough for asking a
+ * browser whether its own decoder reads AIFF.
+ */
+export function makeProbeAiff(frames = 8): Uint8Array {
+  const sampleRate = 8000
+  const dataBytes = frames * 2
+  const out = new Uint8Array(12 + 26 + 16 + dataBytes)
+  const w = new DataView(out.buffer)
+  const ascii = (at: number, s: string) => {
+    for (let i = 0; i < 4; i++) out[at + i] = s.charCodeAt(i)
+  }
+  ascii(0, 'FORM')
+  w.setUint32(4, out.length - 8)
+  ascii(8, 'AIFF')
+  ascii(12, 'COMM')
+  w.setUint32(16, 18)
+  w.setUint16(20, 1)
+  w.setUint32(22, frames)
+  w.setUint16(26, 16)
+  writeExtended(w, 28, sampleRate)
+  ascii(38, 'SSND')
+  w.setUint32(42, 8 + dataBytes)
+  w.setUint32(46, 0)
+  w.setUint32(50, 0)
+  return out
+}

package/src/audio/index.ts

@@ -0,0 +1,102 @@
+// Decoding audio bytes in any browser: the browser's own decoder first, and ours for the formats
+// it can't read (AIFF in Chrome and Firefox). Framework-free; needs only a Web Audio context.
+
+import { AiffError, isAiff, makeProbeAiff, readAiff } from './aiff.js'
+
+export { AiffError, aiffToWav, isAiff, readAiff, readAiffInfo } from './aiff.js'
+export type { AiffAudio, AiffErrorCode, AiffInfo } from './aiff.js'
+
+/** The slice of `BaseAudioContext` decoding needs, so tests and workers can pass a stand-in. */
+export interface DecodeContext {
+  readonly sampleRate: number
+  decodeAudioData(data: ArrayBuffer): Promise<AudioBuffer>
+  createBuffer(channels: number, length: number, sampleRate: number): AudioBuffer
+}
+
+/** The bytes as an `ArrayBuffer` for `decodeAudioData`, copied only when `copy` or a view needs it. */
+function toArrayBuffer(bytes: ArrayBuffer | ArrayBufferView, copy: boolean): ArrayBuffer {
+  if (bytes instanceof ArrayBuffer) return copy ? bytes.slice(0) : bytes
+  const view = new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  if (!copy && bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength && bytes.buffer instanceof ArrayBuffer) {
+    return bytes.buffer
+  }
+  return view.slice().buffer
+}
+
+/**
+ * Bring a buffer to the context's rate, as `decodeAudioData` would have. Without an
+ * `OfflineAudioContext` (a worker, a test) the buffer keeps its own rate, which a source node
+ * still plays correctly.
+ */
+async function resampleTo(buffer: AudioBuffer, sampleRate: number): Promise<AudioBuffer> {
+  const Offline = (globalThis as { OfflineAudioContext?: typeof OfflineAudioContext }).OfflineAudioContext
+  if (!Offline || buffer.sampleRate === sampleRate) return buffer
+  const length = Math.max(1, Math.round((buffer.length * sampleRate) / buffer.sampleRate))
+  const offline = new Offline(buffer.numberOfChannels, length, sampleRate)
+  const source = offline.createBufferSource()
+  source.buffer = buffer
+  source.connect(offline.destination)
+  source.start()
+  return offline.startRendering()
+}
+
+/** Build an `AudioBuffer` from AIFF bytes with our own decoder. Throws `AiffError`. */
+export async function decodeAiff(ctx: DecodeContext, bytes: ArrayBuffer | ArrayBufferView): Promise<AudioBuffer> {
+  const audio = readAiff(bytes)
+  if (audio.frames === 0) throw new AiffError('truncated', 'The AIFF file holds no audio')
+  const buffer = ctx.createBuffer(audio.channels, audio.frames, audio.sampleRate)
+  audio.channelData.forEach((data, c) => buffer.copyToChannel(data as Float32Array<ArrayBuffer>, c))
+  return resampleTo(buffer, ctx.sampleRate)
+}
+
+/**
+ * Decode audio bytes to an `AudioBuffer`: the browser's decoder first, then, if that fails and the
+ * bytes are AIFF, ours. Detected by the bytes, not by `name` (which only labels the error).
+ * A compressed AIFF-C rejects with `AiffError` code `'compressed'`; anything else the browser
+ * can't read rejects with the browser's own error.
+ *
+ * Like `decodeAudioData`, this may detach an `ArrayBuffer` it is given: anything that is not AIFF
+ * goes to the browser as it is, so a large download is never held twice. AIFF goes straight to
+ * ours where the browser is known not to read it (`canDecodeAiffNatively`, asked once); elsewhere
+ * it is copied for the browser's try, because ours may still need it.
+ *
+ * Ours runs on the calling thread, as one linear pass: fine for a file the size of a take, felt as
+ * a pause for a long high-rate one.
+ */
+export async function decodeAudio(
+  ctx: DecodeContext,
+  bytes: ArrayBuffer | ArrayBufferView,
+  name?: string,
+): Promise<AudioBuffer> {
+  if (!isAiff(bytes)) return ctx.decodeAudioData(toArrayBuffer(bytes, false))
+  try {
+    if (!(await canDecodeAiffNatively(ctx))) throw new Error('not native')
+    return await ctx.decodeAudioData(toArrayBuffer(bytes, true))
+  } catch {
+    try {
+      return await decodeAiff(ctx, bytes)
+    } catch (aiffErr) {
+      if (aiffErr instanceof AiffError && name) aiffErr.message = `${name}: ${aiffErr.message}`
+      throw aiffErr
+    }
+  }
+}
+
+let nativeAiff: Promise<boolean> | null = null
+
+/** Forget the answer of `canDecodeAiffNatively`; for tests. */
+export function resetAiffProbeForTests(): void {
+  nativeAiff = null
+}
+
+/**
+ * Whether this browser's own decoder reads AIFF (Safari does; Chrome and Firefox don't). Asked
+ * once with a tiny generated file and remembered for the page's life.
+ */
+export function canDecodeAiffNatively(ctx: DecodeContext): Promise<boolean> {
+  nativeAiff ??= ctx
+    .decodeAudioData(makeProbeAiff().buffer as ArrayBuffer)
+    .then((buffer) => buffer.length > 0)
+    .catch(() => false)
+  return nativeAiff
+}