@humeai/audio-decisions 0.0.0-stage → 0.1.0

package/dist/cjs/audio-helpers/errors.js

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

package/dist/cjs/audio-helpers/files.d.ts

@@ -0,0 +1,27 @@
+import type { DecisionsUpload } from "../api/resources/decisions/client/requests/DecisionsUpload.js";
+import { type Uploadable } from "../core/file/index.js";
+import { type DownmixStrategy } from "./downmix.js";
+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/cjs/audio-helpers/files.js

@@ -0,0 +1,178 @@
+"use strict";
+// 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); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkFile = checkFile;
+exports.readFile = readFile;
+exports.downmixUpload = downmixUpload;
+const index_js_1 = require("../core/file/index.js");
+const downmix_js_1 = require("./downmix.js");
+const wav_js_1 = require("./wav.js");
+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. */
+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 (0, index_js_1.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.
+ */
+function downmixUpload(_a, signal) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var { downmixStrategy } = _a, upload = __rest(_a, ["downmixStrategy"]);
+        const strategy = (0, downmix_js_1.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 (!(0, wav_js_1.isWav)(data)) {
+            return data;
+        }
+        let wav;
+        try {
+            wav = (0, wav_js_1.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 (0, downmix_js_1.downmixWav)(data, wav, strategy, signal);
+        return mixed === undefined ? data : (0, wav_js_1.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/cjs/audio-helpers/index.d.ts

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

package/dist/cjs/audio-helpers/index.js

@@ -0,0 +1,11 @@
+"use strict";
+// Maintained by hand and listed in .fernignore, so SDK regeneration leaves it in place.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChunkedDecisionsResult = exports.UnsupportedAudioError = exports.iterAudioChunks = void 0;
+// Helpers that split audio longer than the Decisions API accepts into chunks it does accept.
+var chunks_js_1 = require("./chunks.js");
+Object.defineProperty(exports, "iterAudioChunks", { enumerable: true, get: function () { return chunks_js_1.iterAudioChunks; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "UnsupportedAudioError", { enumerable: true, get: function () { return errors_js_1.UnsupportedAudioError; } });
+var results_js_1 = require("./results.js");
+Object.defineProperty(exports, "ChunkedDecisionsResult", { enumerable: true, get: function () { return results_js_1.ChunkedDecisionsResult; } });

package/dist/cjs/audio-helpers/integers.d.ts

@@ -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/cjs/audio-helpers/integers.js

@@ -0,0 +1,26 @@
+"use strict";
+// Maintained by hand and listed in .fernignore, so SDK regeneration leaves it in place.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.floorDiv = floorDiv;
+exports.roundDiv = roundDiv;
+exports.ceilDiv = ceilDiv;
+// Callers keep every operand, and the quotient times the denominator, within Number.MAX_SAFE_INTEGER.
+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;
+}
+function roundDiv(numerator, denominator) {
+    return floorDiv(2 * numerator + denominator, 2 * denominator);
+}
+function ceilDiv(numerator, denominator) {
+    return -floorDiv(-numerator, denominator);
+}

package/dist/cjs/audio-helpers/mp3.d.ts

@@ -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;

package/dist/cjs/audio-helpers/mp3.js

@@ -0,0 +1,245 @@
+"use strict";
+// Maintained by hand and listed in .fernignore, so SDK regeneration leaves it in place.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isMp3 = isMp3;
+exports.parseMp3 = parseMp3;
+exports.framesNeededBefore = framesNeededBefore;
+exports.mp3Chunk = mp3Chunk;
+const bytes_js_1 = require("./bytes.js");
+const errors_js_1 = require("./errors.js");
+const CONVERT_COMMAND = "ffmpeg -i input.mp3 -c:a libmp3lame -q:a 2 output.mp3";
+// Keyed by the version bits of a frame header. Version 1 is reserved.
+const SAMPLE_RATES = {
+    3: [44100, 48000, 32000],
+    2: [22050, 24000, 16000],
+    0: [11025, 12000, 8000],
+};
+const MPEG1 = 3;
+// Layer III bitrates in kbit/s. Index 0 is free format.
+const MPEG1_BITRATES = [0, 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320];
+const MPEG2_BITRATES = [0, 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160];
+const LAYER_III = 1;
+const MONO = 3;
+// Samples a layer III decoder outputs before the first sample the encoder was given.
+const DECODER_DELAY = 529;
+// Encoders whose header frame carries a LAME tag, which states the samples added at each end.
+const LAME_TAG_ENCODERS = ["LAME", "Lavf", "Lavc"];
+// Tags that some writers append after the last frame. Nothing after one is audio.
+const TRAILING_TAGS = ["TAG", "APETAGEX", "LYRICSBEGIN", "ID3"];
+const NO_HEADER_FRAME = { leadingSamples: 0, trailingSamples: 0, statedFrames: undefined };
+function isMp3(data) {
+    return (0, bytes_js_1.hasBytes)(data, 0, "ID3") || hasFrameSync(data, 0);
+}
+function parseMp3(data) {
+    let offset = skipId3v2(data);
+    const first = readHeader(data, offset);
+    // The first frame can be a Xing, Info or VBRI header, which holds the length of the whole file
+    // instead of audio. Left in a chunk, it would tell players the chunk is that long.
+    const headerFrame = offset + first.length <= data.length ? readHeaderFrame(data, offset, first) : undefined;
+    if (headerFrame !== undefined) {
+        offset += first.length;
+    }
+    const offsets = [];
+    const reservoirBytes = [];
+    const mainDataBytes = [];
+    while (offset + 4 <= data.length && !startsTrailingTag(data, offset)) {
+        const header = tryReadHeader(data, offset);
+        if (typeof header === "string") {
+            // Players skip bytes after the last frame that are neither a frame nor a tag, such as
+            // padding. When frames follow them, the bytes are damage instead.
+            if (framesFollow(data, offset + 1, first)) {
+                throw unsupported(header);
+            }
+            break;
+        }
+        if (header.version !== first.version || header.sampleRate !== first.sampleRate) {
+            throw unsupported(`the sample rate changes at byte ${offset}`);
+        }
+        // A file cut short is read up to its last whole frame.
+        if (offset + header.length > data.length) {
+            break;
+        }
+        offsets.push(offset);
+        reservoirBytes.push(readReservoirBytes(data, offset, header));
+        mainDataBytes.push(header.length - header.sideInfoStart - header.sideInfoSize);
+        offset += header.length;
+    }
+    offsets.push(offset);
+    const frameCount = offsets.length - 1;
+    const { leadingSamples, trailingSamples, statedFrames } = headerFrame !== null && headerFrame !== void 0 ? headerFrame : NO_HEADER_FRAME;
+    const samplesPerFrame = first.version === MPEG1 ? 1152 : 576;
+    return {
+        sampleRate: first.sampleRate,
+        samplesPerFrame,
+        offsets,
+        reservoirBytes,
+        mainDataBytes,
+        leadingSamples,
+        frameCount,
+        // The samples added at the end close the frames the header counts. A file cut short has lost
+        // them, and players then leave nothing out at the end.
+        endSample: frameCount * samplesPerFrame - (statedFrames === frameCount ? trailingSamples : 0),
+    };
+}
+/** Counts the frames that must come before `frame` in a chunk for it to decode exactly. */
+function framesNeededBefore(mp3, frame) {
+    if (frame === 0) {
+        return 0;
+    }
+    // Each frame's output is blended with the end of the previous frame's, so the previous frame
+    // must decode exactly too, and so needs its own stored audio data.
+    return Math.max(framesHoldingDataOf(mp3, frame), 1 + framesHoldingDataOf(mp3, frame - 1));
+}
+/** Builds an MP3 file holding frames `start` to `end` and none of the source's tags. */
+function mp3Chunk(data, mp3, start, end) {
+    // Copied rather than sliced, since a Buffer's slice is a view that would keep the whole recording.
+    return new Uint8Array(data.subarray(mp3.offsets[start], mp3.offsets[end]));
+}
+function framesHoldingDataOf(mp3, frame) {
+    let needed = mp3.reservoirBytes[frame];
+    if (needed === 0) {
+        return 0;
+    }
+    let count = 0;
+    while (needed > 0 && count < frame) {
+        count += 1;
+        needed -= mp3.mainDataBytes[frame - count];
+    }
+    // Decoders such as ffmpeg and mpg123 do not keep the audio data of the first frame they read
+    // when they cannot decode it, so the data must start after the chunk's first frame.
+    return Math.min(count + 1, frame);
+}
+function hasFrameSync(data, offset) {
+    return offset + 2 <= data.length && data[offset] === 0xff && (data[offset + 1] & 0xe0) === 0xe0;
+}
+function startsTrailingTag(data, offset) {
+    return TRAILING_TAGS.some((tag) => (0, bytes_js_1.hasBytes)(data, offset, tag));
+}
+function readReservoirBytes(data, offset, header) {
+    // Layer III frames may store audio data in the unused space of the frames before them. The side
+    // information starts with how far back that data begins: 9 bits in MPEG-1 and 8 bits otherwise.
+    const sideInfo = offset + header.sideInfoStart;
+    if (header.version === MPEG1) {
+        return (data[sideInfo] << 1) | (data[sideInfo + 1] >> 7);
+    }
+    return data[sideInfo];
+}
+function skipId3v2(data) {
+    let offset = 0;
+    while ((0, bytes_js_1.hasBytes)(data, offset, "ID3") && offset + 10 <= data.length) {
+        const flags = data[offset + 5];
+        // ID3v2 sizes store 7 bits in each byte.
+        let size = 0;
+        for (let index = offset + 6; index < offset + 10; index++) {
+            size = (size << 7) | (data[index] & 0x7f);
+        }
+        offset += 10 + size + (flags & 0x10 ? 10 : 0);
+    }
+    return offset;
+}
+function readHeader(data, offset) {
+    const header = tryReadHeader(data, offset);
+    if (typeof header === "string") {
+        throw unsupported(header);
+    }
+    return header;
+}
+/** The frame header at `offset`, or the reason there is none. */
+function tryReadHeader(data, offset) {
+    if (offset + 4 > data.length) {
+        return "no MPEG audio frame";
+    }
+    if (!hasFrameSync(data, offset)) {
+        return `no MPEG audio frame at byte ${offset}`;
+    }
+    const b1 = data[offset + 1];
+    const b2 = data[offset + 2];
+    const b3 = data[offset + 3];
+    const version = (b1 >> 3) & 3;
+    const layer = (b1 >> 1) & 3;
+    const bitrateIndex = b2 >> 4;
+    const sampleRateIndex = (b2 >> 2) & 3;
+    const sampleRates = SAMPLE_RATES[version];
+    if (sampleRates === undefined || layer === 0 || bitrateIndex === 15 || sampleRateIndex === 3) {
+        return `invalid frame header at byte ${offset}`;
+    }
+    if (layer !== LAYER_III) {
+        return "MPEG layer I and II audio is not supported";
+    }
+    if (bitrateIndex === 0) {
+        return "free format MP3 files are not supported";
+    }
+    const mpeg1 = version === MPEG1;
+    const sampleRate = sampleRates[sampleRateIndex];
+    const bitrate = (mpeg1 ? MPEG1_BITRATES : MPEG2_BITRATES)[bitrateIndex];
+    const length = Math.floor(((mpeg1 ? 144000 : 72000) * bitrate) / sampleRate) + ((b2 >> 1) & 1);
+    const mono = b3 >> 6 === MONO;
+    const sideInfoSize = mpeg1 ? (mono ? 17 : 32) : mono ? 9 : 17;
+    // A protection bit of 0 means a 16-bit checksum follows the header.
+    const sideInfoStart = b1 & 1 ? 4 : 6;
+    if (length < sideInfoStart + sideInfoSize) {
+        return `invalid frame header at byte ${offset}`;
+    }
+    return { version, sampleRate, length, sideInfoStart, sideInfoSize };
+}
+/**
+ * Reads a Xing, Info or VBRI header frame: the samples added before and after the recording, and
+ * the frame count it states. Undefined when the frame holds audio instead.
+ */
+function readHeaderFrame(data, offset, header) {
+    var _a;
+    // Fields that would run past the end of the frame are absent, not read from the next frame.
+    const frame = data.subarray(offset, offset + header.length);
+    // Encoders place the Xing tag after the side information as if the frame had no checksum.
+    const xing = 4 + header.sideInfoSize;
+    if (!(0, bytes_js_1.hasBytes)(frame, xing, "Xing") && !(0, bytes_js_1.hasBytes)(frame, xing, "Info")) {
+        return (0, bytes_js_1.hasBytes)(frame, 36, "VBRI") ? NO_HEADER_FRAME : undefined;
+    }
+    const flags = (_a = (0, bytes_js_1.uint32BE)(frame, xing + 4)) !== null && _a !== void 0 ? _a : 0;
+    let position = xing + 8;
+    let statedFrames;
+    if (flags & 1) {
+        statedFrames = (0, bytes_js_1.uint32BE)(frame, position);
+        position += 4;
+    }
+    // The byte count, table of contents and quality follow when their flags are set.
+    position += (flags & 2 ? 4 : 0) + (flags & 4 ? 100 : 0) + (flags & 8 ? 4 : 0);
+    if (position + 24 > frame.length || !LAME_TAG_ENCODERS.some((encoder) => (0, bytes_js_1.hasBytes)(frame, position, encoder))) {
+        return { leadingSamples: 0, trailingSamples: 0, statedFrames };
+    }
+    // Two 12-bit counts after the encoder's name and other settings: the samples the encoder added
+    // before the recording, and after it. The decoder's own delay precedes both.
+    const b0 = frame[position + 21];
+    const b1 = frame[position + 22];
+    const b2 = frame[position + 23];
+    const delay = (b0 << 4) | (b1 >> 4);
+    const padding = ((b1 & 0x0f) << 8) | b2;
+    return {
+        leadingSamples: delay + DECODER_DELAY,
+        trailingSamples: Math.max(0, padding - DECODER_DELAY),
+        statedFrames,
+    };
+}
+/** Whether two frames in a row, of the same version and sample rate as `first`, start at or after `offset`. */
+function framesFollow(data, offset, first) {
+    // Requiring two frames in a row keeps bytes that happen to look like a frame header from counting.
+    let position = data.indexOf(0xff, offset);
+    while (position !== -1) {
+        const header = matchingHeader(data, position, first);
+        if (header !== undefined && matchingHeader(data, position + header.length, first) !== undefined) {
+            return true;
+        }
+        position = data.indexOf(0xff, position + 1);
+    }
+    return false;
+}
+function matchingHeader(data, offset, first) {
+    const header = tryReadHeader(data, offset);
+    if (typeof header === "string") {
+        return undefined;
+    }
+    return header.version === first.version && header.sampleRate === first.sampleRate ? header : undefined;
+}
+function unsupported(reason) {
+    return new errors_js_1.UnsupportedAudioError(`The audio is not a supported MP3 file (${reason}). Convert it first, for example with: ${CONVERT_COMMAND}`);
+}

package/dist/cjs/audio-helpers/results.d.ts

@@ -0,0 +1,74 @@
+import type { DecisionsUpload } from "../api/resources/decisions/client/requests/DecisionsUpload.js";
+import type { DecisionsResponse } from "../api/types/DecisionsResponse.js";
+import { DecisionsError } from "../errors/DecisionsError.js";
+import { type iterAudioChunks } from "./chunks.js";
+import type { DownmixOptions } from "./files.js";
+interface ChunkPosition {
+    /** Position of the chunk in the recording, starting at 0. */
+    readonly index: number;
+    /**
+     * Where the chunk starts in the recording, in milliseconds. A moment's `audioStartMs` and
+     * `audioEndMs` are measured from the start of the chunk, so add this to place the moment in the
+     * recording. The first chunk of an MP3 file can start a few tens of milliseconds before 0.
+     */
+    readonly startMs: number;
+    /** Where the chunk ends in the recording, in milliseconds. */
+    readonly endMs: number;
+}
+interface SucceededChunk extends ChunkPosition {
+    readonly status: "succeeded";
+    /** The API's response for the chunk, unchanged. */
+    readonly response: DecisionsResponse;
+    readonly error?: undefined;
+}
+interface FailedChunk extends ChunkPosition {
+    readonly status: "failed";
+    readonly response?: undefined;
+    /**
+     * The error the request threw. When the response's body could not be read, a DecisionsError with
+     * no status code whose `cause` holds the parse error.
+     */
+    readonly error: DecisionsError;
+}
+interface NotAttemptedChunk extends ChunkPosition {
+    /** No request was sent for the chunk, so it was not billed. */
+    readonly status: "not_attempted";
+    readonly response?: undefined;
+    readonly error?: undefined;
+}
+/** The outcome of one chunk's request. Checking `status` narrows it to the chunk's response or error. */
+export type ChunkResult = SucceededChunk | FailedChunk | NotAttemptedChunk;
+export type ChunkStatus = ChunkResult["status"];
+/** The outcome of every chunk's request, in the order of the chunks. */
+export declare class ChunkedDecisionsResult {
+    /** One result for each chunk of the requested range. */
+    readonly chunks: readonly ChunkResult[];
+    /** The `startMs` the job was given, or 0 when it was given none. */
+    readonly startMs: number;
+    /**
+     * @param chunks The results of a job, such as those collected from `iterCreateChunked`, in order.
+     * @param startMs The `startMs` the job was given.
+     * @throws {TypeError} If `startMs` is not a safe integer.
+     */
+    constructor(chunks: Iterable<ChunkResult>, startMs?: number);
+    /** Each chunk's response, or undefined for a chunk without one, in the order of the chunks. */
+    get responses(): (DecisionsResponse | undefined)[];
+    /** Whether every chunk's request succeeded. */
+    get complete(): boolean;
+    /**
+     * The `startMs` to give a new job, with the same `endMs`, so that it sends again the audio from
+     * the chunk that stopped this job to the end. Earlier chunks that failed because their audio could
+     * not be decoded are not sent again. A WAV chunk's `endMs` is rounded to the millisecond, so the
+     * new job can skip or repeat a few samples where it starts. Undefined when no chunk stopped the job.
+     */
+    get resumeMs(): number | undefined;
+}
+type Create = (upload: DecisionsUpload & DownmixOptions) => Promise<DecisionsResponse>;
+/**
+ * Sends each chunk of `upload.file` with `create`, as `iterCreateChunked` describes. The options are
+ * checked by this call, and the file when iteration starts.
+ */
+export declare function sendChunks(create: Create, { request, file, ...options }: DecisionsUpload & iterAudioChunks.Options, signal: AbortSignal | undefined): AsyncGenerator<ChunkResult, void, undefined>;
+/** Collects the results of `iterCreateChunked` for `createChunked`. */
+export declare function collectResults(results: AsyncIterable<ChunkResult>, startMs: number | undefined): Promise<ChunkedDecisionsResult>;
+export {};