@humeai/audio-decisions 0.0.1 → 0.1.0

package/dist/esm/audio-helpers/downmix.mjs

@@ -0,0 +1,287 @@
+// Maintained by hand and listed in .fernignore, so SDK regeneration leaves it in place.
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { abortRawResponse } from "../core/fetcher/RawResponse.mjs";
+import { DecisionsError } from "../errors/DecisionsError.mjs";
+import { dataView } from "./bytes.mjs";
+import { checkChoice } from "./checks.mjs";
+import { ceilDiv, floorDiv } from "./integers.mjs";
+import { samplesWav } from "./wav.mjs";
+const STRATEGIES = ["mix", "first_channel", "none"];
+// The model hears audio at this rate, in one channel.
+const MODEL_SAMPLE_RATE = 16000;
+// Front left and front right.
+const STEREO_MASK = 0x3;
+// The settings of ffmpeg's default resampler, which the API uses before the model hears the audio, so
+// audio resampled here reaches the model as it would have without this step.
+const FILTER_SIZE = 32;
+const CUTOFF = 0.97;
+const KAISER_BETA = 9;
+// A ratio of rates that would need more phases than this gets this many instead, and an output
+// between two phases is interpolated linearly between them.
+const MAX_PHASES = 1024;
+// Outputs computed together. Each needs a filter's length of input, so this bounds the memory used.
+const BLOCK = 8192;
+// The mixdown runs on the calling thread, so it lets other work run after about this long.
+const YIELD_MS = 50;
+export function checkDownmixStrategy(strategy = "mix") {
+    return checkChoice("downmixStrategy", strategy, STRATEGIES);
+}
+/**
+ * The samples of `wav` mixed down by `strategy` into one channel, with a description of them, or
+ * undefined when the file is best sent as it is: the API would mix it the same way and converting it
+ * would not make it smaller. Resampled audio is at most MODEL_SAMPLE_RATE, in 32-bit floating point.
+ * Rejects with a DecisionsError once `signal` aborts.
+ */
+export function downmixWav(data, wav, strategy, signal) {
+    return __awaiter(this, void 0, void 0, function* () {
+        // ffmpeg weighs channels by the speakers in the header's channel mask and leaves out the LFE
+        // channel, and it refuses some two-channel masks, so only audio it mixes by adding the channels at
+        // equal weight is mixed here. Anything else is sent as it is for the API to mix.
+        if (strategy === "none" || (strategy === "mix" && !mixesEvenly(wav))) {
+            return undefined;
+        }
+        const sampleRate = Math.min(wav.sampleRate, MODEL_SAMPLE_RATE);
+        const count = ceilDiv(wav.sampleCount * sampleRate, wav.sampleRate);
+        // The API converts every sample to 32-bit floating point, so writing that loses nothing and cannot
+        // clip, but it is larger than some recordings that the API would convert just the same.
+        const converted = samplesWav({ channels: 1, sampleRate, sampleWidth: 4, isFloat: true, sampleCount: count });
+        const unchangedBytes = wav.sampleCount * wav.frameBytes;
+        const copyBytes = wav.sampleCount * wav.sampleWidth;
+        const convertedBytes = count * converted.frameBytes;
+        // The API would mix every channel, so the first is taken out even when that is not smaller.
+        const picksChannel = strategy === "first_channel" && wav.channels > 1;
+        if (!picksChannel && convertedBytes >= unchangedBytes) {
+            return undefined;
+        }
+        // A copy of the channel's samples is exact, so it is preferred whenever it is no larger.
+        if (picksChannel && copyBytes <= convertedBytes) {
+            const picked = new Uint8Array(copyBytes);
+            yield paced(copyFirstChannel(data, wav, picked), signal);
+            const { sampleWidth, isFloat, sampleCount } = wav;
+            return {
+                data: picked,
+                wav: samplesWav({ channels: 1, sampleRate: wav.sampleRate, sampleWidth, isFloat, sampleCount }),
+            };
+        }
+        const read = monoReader(data, wav, strategy === "mix" && wav.channels === 2);
+        const out = new Uint8Array(convertedBytes);
+        const view = dataView(out);
+        // Integer samples are scaled to the range -1 to 1, as ffmpeg does.
+        const fullScale = wav.isFloat ? 1 : Math.pow(2, (wav.sampleWidth * 8 - 1));
+        const write = (output, value) => view.setFloat32(output * 4, value / fullScale, true);
+        yield paced(sampleRate === wav.sampleRate
+            ? copySamples(read, write, count)
+            : resample(read, write, wav.sampleCount, wav.sampleRate, sampleRate, count), signal);
+        return { data: out, wav: converted };
+    });
+}
+function mixesEvenly({ channels, channelMask }) {
+    return channels === 1 || (channels === 2 && (channelMask === 0 || channelMask === STEREO_MASK));
+}
+function* copyFirstChannel(data, wav, picked) {
+    const { dataStart, frameBytes, sampleWidth, sampleCount } = wav;
+    for (let start = 0; start < sampleCount; start += BLOCK) {
+        const end = Math.min(start + BLOCK, sampleCount);
+        for (let sample = start; sample < end; sample++) {
+            const from = dataStart + sample * frameBytes;
+            const to = sample * sampleWidth;
+            for (let byte = 0; byte < sampleWidth; byte++) {
+                picked[to + byte] = data[from + byte];
+            }
+        }
+        yield;
+    }
+}
+function* copySamples(read, write, count) {
+    for (let start = 0; start < count; start += BLOCK) {
+        const end = Math.min(start + BLOCK, count);
+        for (let output = start; output < end; output++) {
+            write(output, read(output));
+        }
+        yield;
+    }
+}
+function* resample(read, write, length, fromRate, toRate, count) {
+    const phases = Math.min(toRate / gcd(fromRate, toRate), MAX_PHASES);
+    const interpolates = (phases * fromRate) % toRate !== 0;
+    const factor = (toRate * CUTOFF) / fromRate;
+    // ffmpeg rounds the filter length up to an even number.
+    let taps = Math.ceil(FILTER_SIZE / factor);
+    taps += taps % 2;
+    const center = (taps - 1) >> 1;
+    const bank = filterBank(phases, factor, taps, interpolates);
+    // Output k lies k * fromRate / toRate inputs in, which is `steps(k)` phases. With the ratio's exact
+    // phases, every output falls on a phase, and otherwise the remainder places it between two. k is
+    // split at toRate so that no product passes Number.MAX_SAFE_INTEGER.
+    const phaseStep = fromRate * phases;
+    const steps = (output) => floorDiv(output, toRate) * phaseStep + floorDiv((output % toRate) * phaseStep, toRate);
+    let segment = new Float64Array(0);
+    for (let start = 0; start < count; start += BLOCK) {
+        const end = Math.min(start + BLOCK, count);
+        const low = floorDiv(steps(start), phases) - center;
+        const inputs = floorDiv(steps(end - 1), phases) - center + taps - low;
+        if (segment.length < inputs) {
+            segment = new Float64Array(inputs);
+        }
+        for (let index = 0; index < inputs; index++) {
+            segment[index] = read(reflect(low + index, length));
+        }
+        for (let output = start; output < end; output++) {
+            const position = steps(output);
+            const first = floorDiv(position, phases);
+            const offset = first - center - low;
+            const row = (position - first * phases) * taps;
+            let sample = 0;
+            for (let tap = 0; tap < taps; tap++) {
+                sample += segment[offset + tap] * bank[row + tap];
+            }
+            if (interpolates) {
+                let following = 0;
+                for (let tap = 0; tap < taps; tap++) {
+                    following += segment[offset + tap] * bank[row + taps + tap];
+                }
+                const remainder = ((output % toRate) * phaseStep) % toRate;
+                sample += (following - sample) * (remainder / toRate);
+            }
+            write(output, sample);
+        }
+        yield;
+    }
+}
+function reflect(position, length) {
+    // ffmpeg reflects the audio at both ends, so the first and last outputs match its own.
+    let reflected = Math.abs(position);
+    if (reflected >= length) {
+        reflected = 2 * length - 1 - reflected;
+    }
+    return Math.min(Math.max(reflected, 0), length - 1);
+}
+/**
+ * A Kaiser-windowed sinc low-pass filter for each phase, built the way swresample builds its own, one
+ * row of `taps` after another, followed by the phase that ends an interpolation when `interpolates`.
+ */
+function filterBank(phases, factor, taps, interpolates) {
+    const center = (taps - 1) >> 1;
+    const bank = new Float64Array((phases + (interpolates ? 1 : 0)) * taps);
+    for (let phase = 0; phase < phases; phase++) {
+        for (let tap = 0; tap < taps; tap++) {
+            const x = Math.PI * (tap - center - phase / phases) * factor;
+            const sinc = x === 0 ? 1 : Math.sin(x) / x;
+            const ratio = (2 * x) / (factor * taps * Math.PI);
+            bank[phase * taps + tap] = sinc * besselI0(KAISER_BETA * Math.sqrt(Math.max(1 - ratio * ratio, 0)));
+        }
+    }
+    // Every phase is scaled by the first phase's sum, as swresample does, so a constant level is kept.
+    let sum = 0;
+    for (let tap = 0; tap < taps; tap++) {
+        sum += bank[tap];
+    }
+    for (let index = 0; index < phases * taps; index++) {
+        bank[index] /= sum;
+    }
+    if (interpolates) {
+        // swresample builds the phase that ends an interpolation by moving the first phase one tap later
+        // in its buffer, whose length is padded to a multiple of 8. The tap that falls off the end, zero
+        // unless the filter needs no padding, wraps around to the start.
+        const last = phases * taps;
+        bank[last] = taps % 8 === 0 ? bank[taps - 1] : 0;
+        bank.set(bank.subarray(0, taps - 1), last + 1);
+    }
+    return bank;
+}
+function besselI0(x) {
+    // The power series converges within a few dozen terms for the window's arguments, which are at
+    // most KAISER_BETA.
+    const quarterSquare = (x * x) / 4;
+    let sum = 1;
+    let term = 1;
+    for (let k = 1; term > sum * Number.EPSILON; k++) {
+        term *= quarterSquare / (k * k);
+        sum += term;
+    }
+    return sum;
+}
+function monoReader(data, wav, mixes) {
+    const read = sampleReader(data, wav);
+    const { dataStart, frameBytes, sampleWidth } = wav;
+    if (mixes) {
+        // ffmpeg adds the two channels at -3 dB each when it writes floating point, as the API does.
+        return (sample) => {
+            const offset = dataStart + sample * frameBytes;
+            return (read(offset) + read(offset + sampleWidth)) * Math.SQRT1_2;
+        };
+    }
+    return (sample) => read(dataStart + sample * frameBytes);
+}
+function sampleReader(data, wav) {
+    const view = dataView(data);
+    if (wav.isFloat) {
+        return wav.sampleWidth === 4
+            ? (offset) => view.getFloat32(offset, true)
+            : (offset) => view.getFloat64(offset, true);
+    }
+    switch (wav.sampleWidth) {
+        case 1:
+            // 8-bit WAV samples are unsigned, centered on 128.
+            return (offset) => data[offset] - 128;
+        case 2:
+            return (offset) => view.getInt16(offset, true);
+        case 3:
+            // Shifting the top byte into the sign bit and back sign-extends the sample.
+            return (offset) => ((data[offset] | (data[offset + 1] << 8) | (data[offset + 2] << 16)) << 8) >> 8;
+        default:
+            return (offset) => view.getInt32(offset, true);
+    }
+}
+/** Runs `work` a block at a time, letting other work run about every YIELD_MS. */
+function paced(work, signal) {
+    return __awaiter(this, void 0, void 0, function* () {
+        throwIfAborted(signal);
+        let resumed = Date.now();
+        while (!work.next().done) {
+            if (Date.now() - resumed >= YIELD_MS) {
+                yield nextTask();
+                throwIfAborted(signal);
+                resumed = Date.now();
+            }
+        }
+    });
+}
+function throwIfAborted(signal) {
+    if (signal === null || signal === void 0 ? void 0 : signal.aborted) {
+        // The error the client throws when it aborts a request, so that an abort is caught the same
+        // way wherever it lands.
+        throw new DecisionsError({
+            message: "The user aborted a request",
+            rawResponse: abortRawResponse,
+            cause: signal.reason,
+        });
+    }
+}
+function nextTask() {
+    // A promise alone would not let timers or I/O run, and browsers delay a nested setTimeout by at
+    // least 4 ms, which adds up over a long mixdown.
+    if (typeof setImmediate === "function") {
+        return new Promise((resolve) => setImmediate(() => resolve()));
+    }
+    return new Promise((resolve) => {
+        const channel = new MessageChannel();
+        channel.port1.onmessage = () => {
+            // A port with a message handler keeps Node's event loop alive until it is closed.
+            channel.port1.close();
+            resolve();
+        };
+        channel.port2.postMessage(undefined);
+    });
+}
+function gcd(a, b) {
+    return b === 0 ? a : gcd(b, a % b);
+}

package/dist/esm/audio-helpers/errors.d.mts

@@ -0,0 +1,4 @@
+/** The recording cannot be split into chunks, because it is empty or not a file the helpers support. */
+export declare class UnsupportedAudioError extends Error {
+    constructor(message: string);
+}

package/dist/esm/audio-helpers/errors.mjs

@@ -0,0 +1,8 @@
+// Maintained by hand and listed in .fernignore, so SDK regeneration leaves it in place.
+/** The recording cannot be split into chunks, because it is empty or not a file the helpers support. */
+export class UnsupportedAudioError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UnsupportedAudioError";
+    }
+}

package/dist/esm/audio-helpers/files.d.mts

@@ -0,0 +1,27 @@
+import type { DecisionsUpload } from "../api/resources/decisions/client/requests/DecisionsUpload.mjs";
+import { type Uploadable } from "../core/file/index.mjs";
+import { type DownmixStrategy } from "./downmix.mjs";
+interface ReadFile {
+    readonly data: Uint8Array;
+    readonly filename: string | undefined;
+    readonly contentType: string | undefined;
+}
+export interface DownmixOptions {
+    /**
+     * How a WAV file is mixed down before it is sent: "mix", the default, mixes it the way the API
+     * does, so the model hears the same audio; "first_channel" keeps only the first channel; and
+     * "none" sends it as it is. MP3 files, and WAV files the SDK cannot read, are sent as they are.
+     * Unless it is "none", `create` reads the whole file into memory before sending it, since it must
+     * read the file to tell whether it is a WAV file. `iterAudioChunks` in `@humeai/audio-decisions/audio-helpers` describes each.
+     */
+    downmixStrategy?: DownmixStrategy;
+}
+export declare function checkFile(file: Uploadable): void;
+/** The file's contents, with the filename and content type its upload would carry. */
+export declare function readFile(file: Uploadable): Promise<ReadFile>;
+/**
+ * `upload` with a WAV recording mixed down as `downmixStrategy` asks, to send with `create`. Rejects
+ * with a DecisionsError if `signal` aborts during the mixdown.
+ */
+export declare function downmixUpload({ downmixStrategy, ...upload }: DecisionsUpload & DownmixOptions, signal?: AbortSignal): Promise<DecisionsUpload>;
+export {};

package/dist/esm/audio-helpers/files.mjs

@@ -0,0 +1,173 @@
+// Maintained by hand and listed in .fernignore, so SDK regeneration leaves it in place.
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+import { toMultipartDataPart } from "../core/file/index.mjs";
+import { checkDownmixStrategy, downmixWav } from "./downmix.mjs";
+import { isWav, parseWav, wavChunk } from "./wav.mjs";
+export function checkFile(file) {
+    if (typeof file === "string") {
+        throw new TypeError(`file must be the audio's contents or { path }, got a string. To read a file from disk, pass { path: ${JSON.stringify(file)} }.`);
+    }
+}
+/** The file's contents, with the filename and content type its upload would carry. */
+export function readFile(file) {
+    return __awaiter(this, void 0, void 0, function* () {
+        // Resolved the way `create` resolves an upload, so chunks carry the same filename and content
+        // type, and a path is opened through the same file system access.
+        const { data, filename, contentType } = yield toMultipartDataPart(file);
+        return { data: yield readBytes(data), filename, contentType };
+    });
+}
+/**
+ * `upload` with a WAV recording mixed down as `downmixStrategy` asks, to send with `create`. Rejects
+ * with a DecisionsError if `signal` aborts during the mixdown.
+ */
+export function downmixUpload(_a, signal) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var { downmixStrategy } = _a, upload = __rest(_a, ["downmixStrategy"]);
+        const strategy = checkDownmixStrategy(downmixStrategy);
+        if (strategy === "none") {
+            return upload;
+        }
+        checkFile(upload.file);
+        const { data, filename, contentType } = yield readFile(upload.file);
+        // A stream that has been read cannot always be read again, so what was read is sent instead.
+        return Object.assign(Object.assign({}, upload), { file: { data: yield downmixFile(data, strategy, signal), filename, contentType } });
+    });
+}
+function downmixFile(data, strategy, signal) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (!isWav(data)) {
+            return data;
+        }
+        let wav;
+        try {
+            wav = parseWav(data);
+        }
+        catch (_a) {
+            // A WAV file this parser cannot read may still be one the API can decode, so it is left to the API.
+            return data;
+        }
+        const mixed = yield downmixWav(data, wav, strategy, signal);
+        return mixed === undefined ? data : wavChunk(mixed.data, mixed.wav, 0, mixed.wav.sampleCount);
+    });
+}
+function readBytes(data) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, data_1, data_1_1;
+        var _b, e_1, _c, _d;
+        if (ArrayBuffer.isView(data)) {
+            return asUint8Array(data);
+        }
+        if (data instanceof ArrayBuffer ||
+            (typeof SharedArrayBuffer !== "undefined" && data instanceof SharedArrayBuffer)) {
+            return new Uint8Array(data);
+        }
+        if (typeof Blob !== "undefined" && data instanceof Blob) {
+            return new Uint8Array(yield data.arrayBuffer());
+        }
+        if (isReadableStream(data)) {
+            return concat(yield readStream(data));
+        }
+        if (isAsyncIterable(data)) {
+            // Node's Readable streams, which are read without importing the stream module.
+            const pieces = [];
+            try {
+                for (_a = true, data_1 = __asyncValues(data); data_1_1 = yield data_1.next(), _b = data_1_1.done, !_b; _a = true) {
+                    _d = data_1_1.value;
+                    _a = false;
+                    const piece = _d;
+                    pieces.push(toBytes(piece));
+                }
+            }
+            catch (e_1_1) { e_1 = { error: e_1_1 }; }
+            finally {
+                try {
+                    if (!_a && !_b && (_c = data_1.return)) yield _c.call(data_1);
+                }
+                finally { if (e_1) throw e_1.error; }
+            }
+            return concat(pieces);
+        }
+        throw new TypeError("file must be a Blob, a stream, an ArrayBuffer or a typed array, { path } or { data } holding one of those.");
+    });
+}
+function readStream(stream) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const reader = stream.getReader();
+        const pieces = [];
+        try {
+            for (;;) {
+                const { done, value } = yield reader.read();
+                if (done) {
+                    return pieces;
+                }
+                pieces.push(toBytes(value));
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    });
+}
+function toBytes(piece) {
+    if (ArrayBuffer.isView(piece)) {
+        return asUint8Array(piece);
+    }
+    // A stream given an encoding has already decoded the audio as text, which cannot be turned back
+    // into the same bytes.
+    throw new TypeError(`file must be a stream of bytes, got a stream holding ${typeof piece} values.`);
+}
+function asUint8Array(view) {
+    // A plain Uint8Array even for Node's Buffer, whose slice returns a view rather than a copy.
+    return new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+}
+function concat(pieces) {
+    if (pieces.length === 1) {
+        return pieces[0];
+    }
+    let length = 0;
+    for (const piece of pieces) {
+        length += piece.length;
+    }
+    const data = new Uint8Array(length);
+    let offset = 0;
+    for (const piece of pieces) {
+        data.set(piece, offset);
+        offset += piece.length;
+    }
+    return data;
+}
+function isReadableStream(value) {
+    return typeof value === "object" && value !== null && typeof value.getReader === "function";
+}
+function isAsyncIterable(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value[Symbol.asyncIterator] === "function");
+}

package/dist/esm/audio-helpers/index.d.mts

@@ -0,0 +1,4 @@
+export { type AudioChunk, type ChunkSplit, iterAudioChunks } from "./chunks.mjs";
+export type { DownmixStrategy } from "./downmix.mjs";
+export { UnsupportedAudioError } from "./errors.mjs";
+export { ChunkedDecisionsResult, type ChunkResult, type ChunkStatus } from "./results.mjs";

package/dist/esm/audio-helpers/index.mjs

@@ -0,0 +1,5 @@
+// Maintained by hand and listed in .fernignore, so SDK regeneration leaves it in place.
+// Helpers that split audio longer than the Decisions API accepts into chunks it does accept.
+export { iterAudioChunks } from "./chunks.mjs";
+export { UnsupportedAudioError } from "./errors.mjs";
+export { ChunkedDecisionsResult } from "./results.mjs";

package/dist/esm/audio-helpers/integers.d.mts

@@ -0,0 +1,3 @@
+export declare function floorDiv(numerator: number, denominator: number): number;
+export declare function roundDiv(numerator: number, denominator: number): number;
+export declare function ceilDiv(numerator: number, denominator: number): number;

package/dist/esm/audio-helpers/integers.mjs

@@ -0,0 +1,21 @@
+// Maintained by hand and listed in .fernignore, so SDK regeneration leaves it in place.
+// Callers keep every operand, and the quotient times the denominator, within Number.MAX_SAFE_INTEGER.
+export function floorDiv(numerator, denominator) {
+    // Floating-point division can round a quotient that falls just short of an integer up to that
+    // integer, so the remainder corrects it.
+    let quotient = Math.floor(numerator / denominator);
+    const remainder = numerator - quotient * denominator;
+    if (remainder < 0) {
+        quotient -= 1;
+    }
+    else if (remainder >= denominator) {
+        quotient += 1;
+    }
+    return quotient;
+}
+export function roundDiv(numerator, denominator) {
+    return floorDiv(2 * numerator + denominator, 2 * denominator);
+}
+export function ceilDiv(numerator, denominator) {
+    return -floorDiv(-numerator, denominator);
+}

package/dist/esm/audio-helpers/mp3.d.mts

@@ -0,0 +1,24 @@
+export interface Mp3Audio {
+    readonly sampleRate: number;
+    readonly samplesPerFrame: number;
+    /** Where each frame starts, followed by where the last one ends. Frames are contiguous. */
+    readonly offsets: readonly number[];
+    /** For each frame, how many bytes of its audio data are stored in the frames before it. */
+    readonly reservoirBytes: readonly number[];
+    /** For each frame, how many bytes of audio data, its own or later frames', it holds itself. */
+    readonly mainDataBytes: readonly number[];
+    /**
+     * Samples decoded from the frames before the recording starts, which players leave out when a
+     * LAME tag states them. 0 without one.
+     */
+    readonly leadingSamples: number;
+    readonly frameCount: number;
+    /** The sample after the recording's last, counted from the start of the first frame. */
+    readonly endSample: number;
+}
+export declare function isMp3(data: Uint8Array): boolean;
+export declare function parseMp3(data: Uint8Array): Mp3Audio;
+/** Counts the frames that must come before `frame` in a chunk for it to decode exactly. */
+export declare function framesNeededBefore(mp3: Mp3Audio, frame: number): number;
+/** Builds an MP3 file holding frames `start` to `end` and none of the source's tags. */
+export declare function mp3Chunk(data: Uint8Array, mp3: Mp3Audio, start: number, end: number): Uint8Array;