@humeai/audio-decisions 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,350 @@
+"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 __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.iterAudioChunks = iterAudioChunks;
+exports.prepareChunks = prepareChunks;
+const checks_js_1 = require("./checks.js");
+const downmix_js_1 = require("./downmix.js");
+const errors_js_1 = require("./errors.js");
+const files_js_1 = require("./files.js");
+const integers_js_1 = require("./integers.js");
+const mp3_js_1 = require("./mp3.js");
+const wav_js_1 = require("./wav.js");
+// The Decisions API accepts audio up to 5 minutes long.
+const MAX_CHUNK_MS = 300000;
+// The API accepts a request body of up to this many bytes, its JSON part and multipart headers included.
+const MAX_REQUEST_BYTES = 25000000;
+// The rest is left for the JSON part and multipart headers, so a chunk this size is accepted with any
+// common request.
+const MAX_CHUNK_BYTES = 24000000;
+const SPLITS = ["even", "fixed"];
+/**
+ * Splits a recording, or part of one, into chunks short enough for the Decisions API.
+ *
+ * `maxChunkMs` is the longest a chunk can be, and `split` decides how the recording is divided:
+ *
+ * 1. "even", the default, cuts the fewest chunks that fit, of equal length, so that the last chunk
+ *    is not a short remainder: 10 minutes and 1 second at a `maxChunkMs` of 300000 is cut into 3
+ *    chunks of about 200 seconds.
+ * 2. "fixed" makes every chunk `maxChunkMs` long except the last, which holds what remains: the
+ *    same recording is cut into 2 chunks of 5 minutes and 1 of 1 second. The last chunk is billed
+ *    for its context and questions like any other, however short it is. Use it when chunks must be
+ *    the same length across recordings.
+ *
+ * No chunk is empty. Cuts fall where the format allows, as described below, so `startMs` and
+ * `endMs` on each chunk give where it actually starts and ends.
+ *
+ * The model hears audio at 16 kHz in one channel: the API resamples and mixes down every file
+ * before the model hears it. A WAV file is mixed down the same way before it is cut, by default, so
+ * that the chunks are smaller to upload while the model hears the same audio. `downmixStrategy`
+ * describes how. MP3 files are cut as they are, because they are already compressed.
+ *
+ * The whole recording is read into memory, mixed down and checked before the first chunk is
+ * produced, so that a file that cannot be split is rejected before any chunk is. The options are
+ * checked by this call, and the file when iteration starts, so errors about the file are thrown by
+ * the first `next()`. The mixdown runs on the calling thread, taking several seconds for an hour of
+ * audio above 16 kHz, and pauses regularly to let other work run. Each chunk's `data` is a copy, made
+ * as the chunk is produced, so keeping every chunk holds the recording in memory twice.
+ *
+ * Apart from the WAV mixdown `downmixStrategy` asks for, the audio is copied as it is, never decoded
+ * or re-encoded, so cuts fall where the format allows:
+ *
+ * 1. A WAV file is cut between samples, after the mixdown. With "fixed", a cut can fall up to one
+ *    sample before `startMs` plus a whole multiple of `maxChunkMs`, so the cuts stay on that grid.
+ *    Each chunk is a new WAV file in the sample format of the mixed-down audio, holding only its
+ *    audio; other chunks in the file, such as metadata, are left out.
+ * 2. An MP3 file is cut between frames, which last 24 to 72 ms depending on the sample rate, so
+ *    chunks can differ in length by a frame, and a "fixed" chunk can be up to one frame shorter
+ *    than `maxChunkMs`. `startMs` and `endMs` move to the nearest frame boundary. A frame can store
+ *    part of its audio data in the frames before it, and its sound continues from the frame before,
+ *    so each chunk also starts with the frames its first new frame needs to decode exactly. That is
+ *    usually a few frames, and up to about 2 seconds at the lowest bitrates. Those frames count
+ *    toward `maxChunkMs` and repeat the end of the previous chunk, or start before `startMs`. Each
+ *    chunk holds only the recording's frames; tags, and the header frame that states the whole
+ *    file's length, are left out. When that header frame has a LAME tag, as files from LAME and
+ *    ffmpeg do, it states the silence the encoder added at each end, which players skip. Times are
+ *    then measured from where a player starts the whole file, so the first chunk starts before 0,
+ *    by about 25 ms for a typical 44.1 kHz file, and the last ends where the player stops.
+ *
+ * @param file The recording, an MP3 or WAV file, in any form `create` accepts. MP3 files of MPEG-1,
+ * 2 and 2.5 layer III are supported, except free format. WAV files of integer PCM (8, 16, 24 or
+ * 32-bit) and floating point (32 or 64-bit) are supported, with either the basic or the extensible
+ * WAV header. A stream is read from where it is to its end. `{ path }` needs file system access,
+ * which browsers do not have.
+ * @param options How to cut the recording.
+ * @returns The chunks in order. Their times are measured from the start of the recording, not from
+ * `startMs`.
+ *
+ * @throws {TypeError} From this call, if `maxChunkMs`, `startMs` or `endMs` is not a safe integer, or
+ * `file` is a string, which is not read as a path.
+ * @throws {RangeError} From this call, if `split` is not "even" or "fixed", `downmixStrategy` is not
+ * "mix", "first_channel" or "none", `maxChunkMs` is out of range, or `startMs` and `endMs` do not
+ * select a range. From iteration, if `startMs` and `endMs` do
+ * not select audio within the recording, `maxChunkMs` is too long with "fixed" for a WAV chunk to
+ * fit the API's size limit, or too short for an MP3 chunk to hold a new frame and the frames it
+ * needs.
+ * @throws {UnsupportedAudioError} From iteration, if the recording is empty or not a file this helper supports, such
+ * as a compressed WAV or RF64 file. Any damage to an MP3 file is found before the first chunk, so no
+ * chunk is produced from a file that cannot be read to the end.
+ *
+ * @example
+ * import { iterAudioChunks } from "@humeai/audio-decisions/audio-helpers";
+ *
+ * for await (const chunk of iterAudioChunks({ path: "call.wav" }, { maxChunkMs: 60_000 })) {
+ *     console.log(chunk.index, chunk.startMs, chunk.endMs, chunk.data.length);
+ * }
+ */
+function iterAudioChunks(file, options) {
+    return produceChunks(prepareChunks(file, options));
+}
+function produceChunks(planRecording) {
+    return __asyncGenerator(this, arguments, function* produceChunks_1() {
+        for (const chunk of (yield __await(planRecording())).chunks) {
+            yield yield __await({ index: chunk.index, startMs: chunk.startMs, endMs: chunk.endMs, data: chunk.build() });
+        }
+    });
+}
+/**
+ * Checks `options` and `file`, and returns a function that reads the file, mixes it down and plans
+ * the chunks `iterAudioChunks` gives, without copying any chunk's data. The function rejects with a
+ * DecisionsError if `signal` aborts during the mixdown.
+ */
+function prepareChunks(file, options) {
+    const checked = checkChunkOptions(options);
+    (0, files_js_1.checkFile)(file);
+    // A generator that read the file itself would keep the recording in memory for the whole job, even
+    // after a WAV file is mixed down into a smaller copy.
+    return (signal) => __awaiter(this, void 0, void 0, function* () {
+        const { data, filename, contentType } = yield (0, files_js_1.readFile)(file);
+        return { filename, contentType, chunks: yield planAudioChunks(data, checked, signal) };
+    });
+}
+function checkChunkOptions(options) {
+    const split = (0, checks_js_1.checkChoice)("split", options.split === undefined ? "even" : options.split, SPLITS);
+    const downmixStrategy = (0, downmix_js_1.checkDownmixStrategy)(options.downmixStrategy);
+    const maxChunkMs = (0, checks_js_1.checkInteger)("maxChunkMs", options.maxChunkMs);
+    if (maxChunkMs < 1 || maxChunkMs > MAX_CHUNK_MS) {
+        throw new RangeError(`maxChunkMs must be between 1 and ${MAX_CHUNK_MS}, got ${maxChunkMs}.`);
+    }
+    const startMs = options.startMs === undefined ? 0 : (0, checks_js_1.checkInteger)("startMs", options.startMs);
+    if (startMs < 0) {
+        throw new RangeError(`startMs must not be negative, got ${startMs}.`);
+    }
+    const endMs = options.endMs === undefined ? undefined : (0, checks_js_1.checkInteger)("endMs", options.endMs);
+    if (endMs !== undefined && endMs <= startMs) {
+        throw new RangeError(`endMs must be greater than startMs, got ${endMs}.`);
+    }
+    return { maxChunkMs, startMs, endMs, split, downmixStrategy };
+}
+function planAudioChunks(data, options, signal) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        if ((0, wav_js_1.isWav)(data)) {
+            const wav = (0, wav_js_1.parseWav)(data);
+            const mixed = (_a = (yield (0, downmix_js_1.downmixWav)(data, wav, options.downmixStrategy, signal))) !== null && _a !== void 0 ? _a : { data, wav };
+            return wavChunks(mixed.data, mixed.wav, options);
+        }
+        if ((0, mp3_js_1.isMp3)(data)) {
+            return mp3Chunks(data, (0, mp3_js_1.parseMp3)(data), options);
+        }
+        throw new errors_js_1.UnsupportedAudioError("Unsupported audio format. Only MP3 and WAV files can be split into chunks.");
+    });
+}
+/** The first and last positions of the range `startMs` and `endMs` select from `length` positions. */
+function selectRange(length, msAt, positionAt, startMs, endMs) {
+    if (length === 0) {
+        throw new errors_js_1.UnsupportedAudioError("The audio is empty.");
+    }
+    // The longest range allowed ends at the duration that the final chunk reports.
+    // A recording shorter than half a millisecond has a duration of 0 ms but still starts at 0.
+    const durationMs = msAt(length);
+    if (startMs > 0 && startMs >= durationMs) {
+        throw new RangeError(`startMs must be less than the recording's duration of ${durationMs} ms, got ${startMs}.`);
+    }
+    if (endMs !== undefined && endMs > durationMs) {
+        throw new RangeError(`endMs must not exceed the recording's duration of ${durationMs} ms, got ${endMs}.`);
+    }
+    // The duration is rounded to the millisecond, so it can fall short of the final position. An MP3
+    // recording can start and end partway through a frame, so its first and last frames are kept whole.
+    const first = startMs === 0 ? 0 : positionAt(startMs);
+    const last = endMs === undefined || endMs >= durationMs ? length : Math.min(positionAt(endMs), length);
+    return [first, last];
+}
+function wavChunks(data, wav, { maxChunkMs, startMs, endMs, split }) {
+    const msAt = (sample) => toMs(sample, wav.sampleRate);
+    const [first, last] = selectRange(wav.sampleCount, msAt, (ms) => toSample(ms, wav.sampleRate), startMs, endMs);
+    // When maxChunkMs is not a whole number of samples, a chunk can be up to one sample longer.
+    const longest = (0, integers_js_1.ceilDiv)(maxChunkMs * wav.sampleRate, 1000);
+    const fitting = wavSamplesThatFit(wav);
+    let cuts;
+    if (split === "even") {
+        cuts = evenWavCuts(first, last, Math.min(longest, fitting));
+    }
+    else {
+        checkWavSize(wav, Math.min(longest, last - first), fitting);
+        cuts = fixedWavCuts(wav, maxChunkMs, startMs, first, last);
+    }
+    return plan(cuts, msAt, (start, end) => (0, wav_js_1.wavChunk)(data, wav, start, end));
+}
+function wavSamplesThatFit(wav) {
+    // An MP3 chunk needs no such limit: at the highest bitrate, 5 minutes of MP3 is about 12 MB.
+    // The header holds the RIFF, fmt and data chunk headers, and the data can need a padding byte.
+    const headerBytes = 28 + wav.fmt.length + 1;
+    return (0, integers_js_1.floorDiv)(MAX_CHUNK_BYTES - headerBytes, wav.frameBytes);
+}
+function checkWavSize(wav, longest, fitting) {
+    if (longest <= fitting) {
+        return;
+    }
+    const fittingMs = (0, integers_js_1.floorDiv)(fitting * 1000, wav.sampleRate);
+    throw new RangeError(`maxChunkMs must be at most ${fittingMs} for this WAV file with split="fixed", so that the request for` +
+        ` each chunk fits within the API limit of ${MAX_REQUEST_BYTES.toLocaleString("en-US")} bytes.` +
+        ` split="even" cuts shorter chunks that fit instead, and mono or stereo audio mixed down with` +
+        ` downmixStrategy="mix" fits 5-minute chunks.`);
+}
+function mp3Chunks(data, mp3, { maxChunkMs, startMs, endMs, split }) {
+    const msAt = (frame) => mp3TimeMs(mp3, frame);
+    const [first, last] = selectRange(mp3.frameCount, msAt, (ms) => frameAt(mp3, ms), startMs, endMs);
+    // Rounding down keeps every chunk within maxChunkMs, so a maxChunkMs of 300000 stays within the
+    // API's limit.
+    const framesPerChunk = (0, integers_js_1.floorDiv)(maxChunkMs * mp3.sampleRate, 1000 * mp3.samplesPerFrame);
+    const frameMs = framesMs(mp3, 1);
+    if (framesPerChunk === 0) {
+        throw new RangeError(`maxChunkMs must be at least ${frameMs} ms, the length of one frame of this MP3 file.`);
+    }
+    if (last <= first) {
+        throw new RangeError(`startMs and endMs must be at least ${frameMs} ms apart, the length of one frame of this MP3 file.`);
+    }
+    // A chunk that could hold only the frames needed before its first new frame would never advance.
+    // Filling fails only when this check does, which also rejects a maxChunkMs that happens to work
+    // for this range's cuts but not for every frame in it.
+    let neededBefore = 0;
+    for (let frame = first; frame < last; frame++) {
+        neededBefore = Math.max(neededBefore, (0, mp3_js_1.framesNeededBefore)(mp3, frame));
+    }
+    const filled = fillMp3Chunks(mp3, framesPerChunk, first, last);
+    if (filled === undefined || framesPerChunk <= neededBefore) {
+        throw new RangeError(`maxChunkMs must be at least ${framesMs(mp3, neededBefore + 1)} ms for this MP3 file. Its frames` +
+            ` need up to ${neededBefore} frames before them to decode, and a chunk must hold those along with` +
+            " at least one new frame.");
+    }
+    const cuts = split === "even" ? evenMp3Cuts(mp3, filled, framesPerChunk, first, last) : filled;
+    return plan(cuts, msAt, (start, end) => (0, mp3_js_1.mp3Chunk)(data, mp3, start, end));
+}
+function frameAt(mp3, ms) {
+    // Times given by the caller are often ones a chunk reported, which are rounded to the
+    // millisecond, so they move to the nearest frame boundary rather than the one before.
+    return (0, integers_js_1.roundDiv)(ms * mp3.sampleRate + 1000 * mp3.leadingSamples, 1000 * mp3.samplesPerFrame);
+}
+function framesMs(mp3, frames) {
+    return (0, integers_js_1.ceilDiv)(frames * mp3.samplesPerFrame * 1000, mp3.sampleRate);
+}
+function mp3TimeMs(mp3, frame) {
+    // Times are measured from where a player starts the recording, after the samples the encoder and
+    // decoder add, so the first chunk can start before 0 ms. The player also stops before the
+    // samples added at the end.
+    return toMs(Math.min(frame * mp3.samplesPerFrame, mp3.endSample) - mp3.leadingSamples, mp3.sampleRate);
+}
+function evenMp3Cuts(mp3, filled, framesPerChunk, first, last) {
+    // Filling every chunk gives the fewest chunks but can leave a short last chunk. The shortest
+    // chunk length that needs no more chunks than that shares the frames out evenly instead.
+    let cuts = filled;
+    let low = 1;
+    let high = framesPerChunk;
+    while (low < high) {
+        const middle = Math.floor((low + high) / 2);
+        const shorter = fillMp3Chunks(mp3, middle, first, last);
+        if (shorter !== undefined && shorter.length <= cuts.length) {
+            cuts = shorter;
+            high = middle;
+        }
+        else {
+            low = middle + 1;
+        }
+    }
+    return cuts;
+}
+/** Cuts chunks of `framesPerChunk` frames, or undefined when a chunk cannot hold a new frame. */
+function fillMp3Chunks(mp3, framesPerChunk, first, last) {
+    const cuts = [];
+    let next = first;
+    while (next < last) {
+        // Without the frames before it, the first new frame decodes wrongly. They repeat the end of
+        // the previous chunk.
+        const start = next - (0, mp3_js_1.framesNeededBefore)(mp3, next);
+        if (start + framesPerChunk <= next) {
+            return undefined;
+        }
+        const end = Math.min(start + framesPerChunk, last);
+        cuts.push([start, end]);
+        next = end;
+    }
+    return cuts;
+}
+function* evenWavCuts(first, last, longest) {
+    const length = last - first;
+    const count = (0, integers_js_1.ceilDiv)(length, longest);
+    // Chunk i starts at first + floor(length * i / count). That product can pass
+    // Number.MAX_SAFE_INTEGER, so the cuts are stepped by the quotient and carry the remainder.
+    const step = (0, integers_js_1.floorDiv)(length, count);
+    const extra = length - step * count;
+    let start = first;
+    let remainder = 0;
+    for (let index = 0; index < count; index++) {
+        let end = start + step;
+        remainder += extra;
+        if (remainder >= count) {
+            remainder -= count;
+            end += 1;
+        }
+        yield [start, end];
+        start = end;
+    }
+}
+function* fixedWavCuts(wav, maxChunkMs, startMs, first, last) {
+    let start = first;
+    let index = 0;
+    while (start < last) {
+        // Each cut is computed from startMs rather than from the previous cut, so rounding does not
+        // accumulate.
+        const end = Math.min(toSample(startMs + (index + 1) * maxChunkMs, wav.sampleRate), last);
+        yield [start, end];
+        index += 1;
+        start = end;
+    }
+}
+function* plan(cuts, msAt, build) {
+    let index = 0;
+    for (const [start, end] of cuts) {
+        yield { index, startMs: msAt(start), endMs: msAt(end), build: () => build(start, end) };
+        index += 1;
+    }
+}
+function toSample(ms, sampleRate) {
+    return (0, integers_js_1.floorDiv)(ms * sampleRate, 1000);
+}
+function toMs(sample, sampleRate) {
+    return (0, integers_js_1.roundDiv)(sample * 1000, sampleRate);
+}

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

@@ -0,0 +1,17 @@
+import { type WavAudio } from "./wav.js";
+declare const STRATEGIES: readonly ["mix", "first_channel", "none"];
+/** How a WAV file is mixed down before it is sent: "mix", "first_channel", or "none" to send it as it is. */
+export type DownmixStrategy = (typeof STRATEGIES)[number];
+interface Downmixed {
+    readonly data: Uint8Array;
+    readonly wav: WavAudio;
+}
+export declare function checkDownmixStrategy(strategy?: unknown): DownmixStrategy;
+/**
+ * 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 declare function downmixWav(data: Uint8Array, wav: WavAudio, strategy: DownmixStrategy, signal?: AbortSignal): Promise<Downmixed | undefined>;
+export {};

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

@@ -0,0 +1,291 @@
+"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());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkDownmixStrategy = checkDownmixStrategy;
+exports.downmixWav = downmixWav;
+const RawResponse_js_1 = require("../core/fetcher/RawResponse.js");
+const DecisionsError_js_1 = require("../errors/DecisionsError.js");
+const bytes_js_1 = require("./bytes.js");
+const checks_js_1 = require("./checks.js");
+const integers_js_1 = require("./integers.js");
+const wav_js_1 = require("./wav.js");
+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;
+function checkDownmixStrategy(strategy = "mix") {
+    return (0, checks_js_1.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.
+ */
+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 = (0, integers_js_1.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 = (0, wav_js_1.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: (0, wav_js_1.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 = (0, bytes_js_1.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) => (0, integers_js_1.floorDiv)(output, toRate) * phaseStep + (0, integers_js_1.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 = (0, integers_js_1.floorDiv)(steps(start), phases) - center;
+        const inputs = (0, integers_js_1.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 = (0, integers_js_1.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 = (0, bytes_js_1.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_js_1.DecisionsError({
+            message: "The user aborted a request",
+            rawResponse: RawResponse_js_1.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/cjs/audio-helpers/errors.d.ts

@@ -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);
+}