@humeai/audio-decisions 0.0.1 → 0.1.0

package/dist/cjs/api/types/RunStatus.js

@@ -0,0 +1,9 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RunStatus = void 0;
+/** How a run ended: `ended` if it returned answers, and `errored` if it returned none because inference failed or the client closed the connection first. */
+exports.RunStatus = {
+    Ended: "ended",
+    Errored: "errored",
+};

package/dist/cjs/api/types/RunSummary.d.ts

@@ -0,0 +1,16 @@
+import type * as Decisions from "../index.js";
+/**
+ * One model inference, as the list returns it.
+ */
+export interface RunSummary {
+    /** The run's ID: the `run_id` of a decisions response. */
+    runId: string;
+    /** The ID of the Hume user who made the run. */
+    userId: string;
+    status: Decisions.RunStatus;
+    /** When the run started. */
+    startedAt: Date;
+    /** When the run ended. */
+    endedAt: Date;
+    received: Decisions.RunReceived;
+}

package/dist/cjs/api/types/RunSummary.js

@@ -0,0 +1,3 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/api/types/RunsPage.d.ts

@@ -0,0 +1,10 @@
+import type * as Decisions from "../index.js";
+/**
+ * One page of runs.
+ */
+export interface RunsPage {
+    /** The runs, newest first. */
+    runs: Decisions.RunSummary[];
+    /** Absent on the last page. Pass it back as `cursor` for the next one. */
+    nextCursor?: string;
+}

package/dist/cjs/api/types/RunsPage.js

@@ -0,0 +1,3 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/api/types/ScoreAnswer.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The answer to a `score` question.
+ */
+export interface ScoreAnswer {
+    /** The probability-weighted mean of the level indices, from 0 to the index of the highest level. */
+    score: number;
+    /** How much human raters would agree, from 0 when the probabilities are at least as spread out as a uniform distribution to 1 when all probability is on one level. */
+    confidence: number;
+    /** The probability of each level, keyed by level index as a string. Each estimates the share of human raters who would choose the level, and together they sum to 1, within rounding. */
+    probabilities: Record<string, number>;
+    /** The text of each level, as given in the question's `criteria`, keyed by level index like `probabilities`, so a score can be read without relying on the key order of a JSON object. */
+    legend: Record<string, string>;
+}

package/dist/cjs/api/types/ScoreAnswer.js

@@ -0,0 +1,3 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/api/types/ScoreQuestion.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Asks where the audio falls on a scale of two or more ordered levels.
+ */
+export interface ScoreQuestion {
+    /** The question, written in natural language. */
+    instructions: string;
+    /** The levels, ordered from lowest to highest and numbered from 0. The model reads each level's text, and the answer's `legend` returns it. A question with fewer than two levels or more than 10, or with duplicate levels, is rejected with `question_invalid`. */
+    criteria: string[];
+}

package/dist/cjs/api/types/ScoreQuestion.js

@@ -0,0 +1,3 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/api/types/index.d.ts

@@ -0,0 +1,28 @@
+export * from "./Answer.js";
+export * from "./Answers.js";
+export * from "./ChoiceAnswer.js";
+export * from "./ChoiceQuestion.js";
+export * from "./Criterion.js";
+export * from "./DecisionsRequest.js";
+export * from "./DecisionsResponse.js";
+export * from "./Error_.js";
+export * from "./ErrorCode.js";
+export * from "./ErrorType.js";
+export * from "./GatewayError.js";
+export * from "./InputTokensResponse.js";
+export * from "./Moment.js";
+export * from "./MomentAnswer.js";
+export * from "./MomentQuestion.js";
+export * from "./NoulAnswer.js";
+export * from "./NoulCriteria.js";
+export * from "./NoulQuestion.js";
+export * from "./Question.js";
+export * from "./Questions.js";
+export * from "./Received.js";
+export * from "./Run.js";
+export * from "./RunReceived.js";
+export * from "./RunStatus.js";
+export * from "./RunSummary.js";
+export * from "./RunsPage.js";
+export * from "./ScoreAnswer.js";
+export * from "./ScoreQuestion.js";

package/dist/cjs/api/types/index.js

@@ -0,0 +1,44 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./Answer.js"), exports);
+__exportStar(require("./Answers.js"), exports);
+__exportStar(require("./ChoiceAnswer.js"), exports);
+__exportStar(require("./ChoiceQuestion.js"), exports);
+__exportStar(require("./Criterion.js"), exports);
+__exportStar(require("./DecisionsRequest.js"), exports);
+__exportStar(require("./DecisionsResponse.js"), exports);
+__exportStar(require("./Error_.js"), exports);
+__exportStar(require("./ErrorCode.js"), exports);
+__exportStar(require("./ErrorType.js"), exports);
+__exportStar(require("./GatewayError.js"), exports);
+__exportStar(require("./InputTokensResponse.js"), exports);
+__exportStar(require("./Moment.js"), exports);
+__exportStar(require("./MomentAnswer.js"), exports);
+__exportStar(require("./MomentQuestion.js"), exports);
+__exportStar(require("./NoulAnswer.js"), exports);
+__exportStar(require("./NoulCriteria.js"), exports);
+__exportStar(require("./NoulQuestion.js"), exports);
+__exportStar(require("./Question.js"), exports);
+__exportStar(require("./Questions.js"), exports);
+__exportStar(require("./Received.js"), exports);
+__exportStar(require("./Run.js"), exports);
+__exportStar(require("./RunReceived.js"), exports);
+__exportStar(require("./RunStatus.js"), exports);
+__exportStar(require("./RunSummary.js"), exports);
+__exportStar(require("./RunsPage.js"), exports);
+__exportStar(require("./ScoreAnswer.js"), exports);
+__exportStar(require("./ScoreQuestion.js"), exports);

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

@@ -0,0 +1,6 @@
+export declare function dataView(data: Uint8Array): DataView;
+/** Whether the bytes at `offset` spell `text`, which is ASCII. False when they run past the end. */
+export declare function hasBytes(data: Uint8Array, offset: number, text: string): boolean;
+export declare function writeAscii(data: Uint8Array, offset: number, text: string): void;
+/** The big-endian integer in the 4 bytes from `offset`, or undefined when they do not all lie within `data`. */
+export declare function uint32BE(data: Uint8Array, offset: number): number | undefined;

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

@@ -0,0 +1,38 @@
+"use strict";
+// Maintained by hand and listed in .fernignore, so SDK regeneration leaves it in place.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dataView = dataView;
+exports.hasBytes = hasBytes;
+exports.writeAscii = writeAscii;
+exports.uint32BE = uint32BE;
+function dataView(data) {
+    return new DataView(data.buffer, data.byteOffset, data.byteLength);
+}
+/** Whether the bytes at `offset` spell `text`, which is ASCII. False when they run past the end. */
+function hasBytes(data, offset, text) {
+    if (offset < 0 || offset + text.length > data.length) {
+        return false;
+    }
+    for (let index = 0; index < text.length; index++) {
+        if (data[offset + index] !== text.charCodeAt(index)) {
+            return false;
+        }
+    }
+    return true;
+}
+function writeAscii(data, offset, text) {
+    for (let index = 0; index < text.length; index++) {
+        data[offset + index] = text.charCodeAt(index);
+    }
+}
+/** The big-endian integer in the 4 bytes from `offset`, or undefined when they do not all lie within `data`. */
+function uint32BE(data, offset) {
+    if (offset < 0 || offset + 4 > data.length) {
+        return undefined;
+    }
+    let value = 0;
+    for (let index = offset; index < offset + 4; index++) {
+        value = value * 256 + data[index];
+    }
+    return value;
+}

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

@@ -0,0 +1,2 @@
+export declare function checkInteger(name: string, value: unknown): number;
+export declare function checkChoice<T>(name: string, value: unknown, choices: readonly T[]): T;

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

@@ -0,0 +1,25 @@
+"use strict";
+// Maintained by hand and listed in .fernignore, so SDK regeneration leaves it in place.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkInteger = checkInteger;
+exports.checkChoice = checkChoice;
+function checkInteger(name, value) {
+    // Arithmetic on larger numbers is not exact, and the bounds checked later assume it is.
+    if (typeof value !== "number" || !Number.isSafeInteger(value)) {
+        throw new TypeError(`${name} must be a safe integer, got ${describe(value)}.`);
+    }
+    return value;
+}
+function checkChoice(name, value, choices) {
+    if (!isOneOf(value, choices)) {
+        const quoted = choices.map(describe);
+        throw new RangeError(`${name} must be ${quoted.slice(0, -1).join(", ")} or ${quoted[quoted.length - 1]}, got ${describe(value)}.`);
+    }
+    return value;
+}
+function isOneOf(value, choices) {
+    return choices.includes(value);
+}
+function describe(value) {
+    return typeof value === "string" ? JSON.stringify(value) : String(value);
+}

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

@@ -0,0 +1,160 @@
+import type { Uploadable } from "../core/file/index.js";
+import { type DownmixStrategy } from "./downmix.js";
+declare const SPLITS: readonly ["even", "fixed"];
+export type ChunkSplit = (typeof SPLITS)[number];
+/** One chunk of a longer recording, a complete audio file to send to the Decisions API on its own. */
+export interface AudioChunk {
+    /** Position of the chunk in the recording, starting at 0. */
+    readonly index: number;
+    /**
+     * Where the chunk starts in the recording, in milliseconds, rounded to the nearest millisecond.
+     * 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, rounded to the nearest millisecond. */
+    readonly endMs: number;
+    /** The chunk as a file in the recording's format, after any mixdown `downmixStrategy` asks for. */
+    readonly data: Uint8Array;
+}
+export declare namespace iterAudioChunks {
+    interface Options {
+        /**
+         * The longest a chunk can be, in milliseconds, from 1 to 300000. A WAV chunk must also be at
+         * most 24,000,000 bytes, which leaves room for the rest of its request within the API's limit
+         * of 25,000,000 bytes. 5 minutes of WAV fits only at just under 80,000 bytes per second, and
+         * always fits for mono or stereo under "mix". With "even", a WAV file that does not fit is cut
+         * into shorter chunks that do. With "fixed", it throws, and 16-bit stereo that is not mixed
+         * down needs a `maxChunkMs` of at most 136054 at 44.1 kHz and 124999 at 48 kHz.
+         */
+        maxChunkMs: number;
+        /** Where in the recording to start, in milliseconds. Defaults to the start of the recording. */
+        startMs?: number;
+        /**
+         * Where in the recording to stop, in milliseconds, no later than the recording's duration.
+         * Defaults to the end of the recording.
+         */
+        endMs?: number;
+        /**
+         * "even" for the fewest chunks of equal length, or "fixed" for chunks of `maxChunkMs` with a
+         * shorter last chunk. Defaults to "even".
+         */
+        split?: ChunkSplit;
+        /**
+         * How a WAV file is mixed down before it is cut. Audio above 16 kHz is resampled to 16 kHz
+         * with the filter the API uses, and audio at 16 kHz or below keeps its rate. Resampled audio
+         * is written as 32-bit floating point, the format the API converts every file to, so loud
+         * audio cannot clip.
+         *
+         * 1. "mix", the default, mixes two channels into one the way the API does, adding them at
+         *    -3 dB each, so the model hears the same audio as it would from the original file. A file
+         *    that this would not make smaller, such as 16-bit mono at 16 kHz, is cut as it is, and so
+         *    is audio with more than two channels, or two channels whose header places them anywhere
+         *    but front left and front right, because the API weighs those channels by the speaker
+         *    positions the header declares.
+         * 2. "first_channel" keeps only the first channel of a file with more than one, so the model
+         *    hears only that channel. The channel is copied exactly in the recording's sample format
+         *    when that is no larger than resampling it, as it is at 16 kHz or below for every sample
+         *    format but 64-bit floating point. Use it when that channel holds the speaker to judge.
+         *    Mono audio is treated as by "mix".
+         * 3. "none" cuts the audio as it is.
+         */
+        downmixStrategy?: DownmixStrategy;
+    }
+}
+/** A chunk's place in the recording, with its data left to be copied when it is needed. */
+interface PlannedChunk {
+    readonly index: number;
+    readonly startMs: number;
+    readonly endMs: number;
+    readonly build: () => Uint8Array;
+}
+/** A recording's chunks, with the filename and content type its upload would carry. */
+export interface PlannedRecording {
+    readonly filename: string | undefined;
+    readonly contentType: string | undefined;
+    readonly chunks: Iterable<PlannedChunk>;
+}
+/**
+ * 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);
+ * }
+ */
+export declare function iterAudioChunks(file: Uploadable, options: iterAudioChunks.Options): AsyncGenerator<AudioChunk, void, undefined>;
+/**
+ * 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.
+ */
+export declare function prepareChunks(file: Uploadable, options: iterAudioChunks.Options): (signal?: AbortSignal) => Promise<PlannedRecording>;
+export {};