hume 0.13.3 → 0.13.5

package/wrapper/SilenceFiller.js

@@ -0,0 +1,203 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnclockedSilenceFiller = exports.SilenceFiller = void 0;
+const stream_1 = require("stream");
+/**
+ * SilenceFiller is a Readable stream that intersperses incoming audio data
+ * with bytes of silence. This is important in some cases to keep an audio
+ * stream "alive". Audio players, such as ffmpeg, can interpret inactivity as
+ * meaning the stream is ended, or disconnected.
+ *
+ * @example
+ * ```typescript
+ * import { SilenceFiller } from 'hume';
+ *
+ * const BYTES_PER_SAMPLE = 2; // 16-bit samples
+ * const SAMPLE_RATE = 48000;
+ * const BUFFER_SIZE = Math.floor(SAMPLE_RATE * 0.1 * BYTES_PER_SAMPLE); // 100ms buffer
+ * const silenceFiller = new SilenceFiller(BUFFER_SIZE, SAMPLE_RATE, BYTES_PER_SAMPLE, 10);
+ *
+ * // Pipe silence filler output to audio player stdin
+ * silenceFiller.pipe(audioPlayer.stdin);
+ *
+ * // Handle pipe errors
+ * silenceFiller.on('error', (err) => {
+ *   console.error("SilenceFiller error:", err);
+ * });
+ *
+ * // Write audio data as it arrives
+ * silenceFiller.writeAudio(audioBuffer);
+ *
+ * // End the stream when done
+ * await silenceFiller.endStream();
+ * ```
+ */
+class SilenceFiller extends stream_1.Readable {
+    /**
+     * Creates a new SilenceFiller instance.
+     *
+     * @param pushIntervalMs - The interval in milliseconds for pushing audio data (default: 5ms).
+     * @param sampleRate - The sample rate of the audio (e.g., 48000).
+     * @param bytesPerSample - The number of bytes per audio sample (e.g., 2 for 16-bit).
+     * @param bufferSize - How much to 'prebuffer'. If you set this too low there
+     * is a chance that playback will stutter, but if you set it too high
+     * playback will take longer to start.
+     */
+    constructor(pushIntervalMs = 5, sampleRate = 48000, bytesPerSample = 2, bufferSize = 9600) {
+        super({ objectMode: false });
+        this.isStarted = false;
+        this.pushInterval = null;
+        this.unclockedSilenceFiller = new UnclockedSilenceFiller(bufferSize, sampleRate, bytesPerSample);
+        this.bytesPerSample = bytesPerSample;
+        this.pushIntervalMs = pushIntervalMs;
+    }
+    /**
+     * Writes audio data to the silence filler.
+     *
+     * @param audioBuffer - The audio buffer to write.
+     */
+    writeAudio(audioBuffer) {
+        const now = Date.now();
+        try {
+            this.unclockedSilenceFiller.writeAudio(audioBuffer, now);
+            if (!this.isStarted && this.unclockedSilenceFiller.donePrebuffering) {
+                this.isStarted = true;
+                this.startPushInterval();
+            }
+        }
+        catch (error) {
+            console.error(`[SilenceFiller] Error writing audio:`, error);
+            this.emit("error", error);
+        }
+    }
+    startPushInterval() {
+        this.pushInterval = setInterval(() => {
+            this.pushData();
+        }, this.pushIntervalMs);
+    }
+    pushData() {
+        if (!this.isStarted)
+            return;
+        try {
+            const now = Date.now();
+            const audioChunk = this.unclockedSilenceFiller.readAudio(now);
+            if (audioChunk && audioChunk.length > 0) {
+                // Ensure chunk size is aligned to bytesPerSample
+                const alignedChunkSize = Math.floor(audioChunk.length / this.bytesPerSample) * this.bytesPerSample;
+                if (alignedChunkSize > 0) {
+                    const chunk = audioChunk.subarray(0, alignedChunkSize);
+                    this.push(chunk);
+                }
+            }
+        }
+        catch (error) {
+            console.error(`[SilenceFiller] Error pushing data:`, error);
+            this.emit("error", error);
+        }
+    }
+    _read() { }
+    _destroy(error, callback) {
+        super._destroy(error, callback);
+    }
+    /**
+     * Ends the stream and drains all remaining audio data.
+     *
+     * @returns A promise that resolves when the stream has ended.
+     */
+    endStream() {
+        return new Promise((resolve) => {
+            // Stop pushing data
+            if (this.pushInterval) {
+                clearInterval(this.pushInterval);
+                this.pushInterval = null;
+            }
+            // Drain all remaining audio from SilenceFiller
+            const now = Date.now();
+            // Keep reading until no more audio is available
+            while (true) {
+                const remainingChunk = this.unclockedSilenceFiller.readAudio(now);
+                if (!remainingChunk || remainingChunk.length === 0) {
+                    break;
+                }
+                const alignedChunkSize = Math.floor(remainingChunk.length / this.bytesPerSample) * this.bytesPerSample;
+                if (alignedChunkSize > 0) {
+                    const chunk = remainingChunk.subarray(0, alignedChunkSize);
+                    this.push(chunk);
+                }
+            }
+            this.push(null); // Signal end of stream
+            this.once("end", () => {
+                resolve();
+            });
+        });
+    }
+}
+exports.SilenceFiller = SilenceFiller;
+/**
+ * Does the actual calculation of how interspersing audio with silence
+ * is "pure" in the sense that it does not rely on the system clock.
+ * It's up to the caller to provide timestamps.
+ *
+ * @internal
+ */
+class UnclockedSilenceFiller {
+    constructor(bufferSize, sampleRate, bytesPerSample) {
+        this.audioQueue = [];
+        this.totalBufferedBytes = 0;
+        this.startTimestamp = null;
+        this.totalBytesSent = 0;
+        this.donePrebuffering = false;
+        this.bufferSize = bufferSize;
+        this.sampleRate = sampleRate;
+        this.bytesPerSample = bytesPerSample;
+    }
+    writeAudio(audioBuffer, timestamp) {
+        this.audioQueue.push(audioBuffer);
+        this.totalBufferedBytes += audioBuffer.length;
+        if (this.startTimestamp === null) {
+            this.startTimestamp = timestamp;
+        }
+        if (!this.donePrebuffering && this.totalBufferedBytes >= this.bufferSize) {
+            this.donePrebuffering = true;
+        }
+    }
+    readAudio(timestamp) {
+        if (this.startTimestamp === null || !this.donePrebuffering) {
+            return null;
+        }
+        const elapsedMs = timestamp - this.startTimestamp;
+        const targetBytesSent = Math.floor(((this.sampleRate * elapsedMs) / 1000) * this.bytesPerSample);
+        const bytesNeeded = targetBytesSent - this.totalBytesSent;
+        if (bytesNeeded <= 0) {
+            return null;
+        }
+        // Ensure bytesNeeded is a multiple of bytesPerSample
+        const alignedBytesNeeded = Math.floor(bytesNeeded / this.bytesPerSample) * this.bytesPerSample;
+        if (alignedBytesNeeded <= 0) {
+            return null;
+        }
+        let chunk = Buffer.alloc(0);
+        // Drain from queue until we have enough bytes
+        while (chunk.length < alignedBytesNeeded && this.audioQueue.length > 0) {
+            const nextBuffer = this.audioQueue.shift();
+            chunk = Buffer.concat([chunk, nextBuffer]);
+            this.totalBufferedBytes -= nextBuffer.length;
+        }
+        // If we have more than needed, put the excess back
+        if (chunk.length > alignedBytesNeeded) {
+            const excess = chunk.subarray(alignedBytesNeeded);
+            this.audioQueue.unshift(excess);
+            this.totalBufferedBytes += excess.length;
+            chunk = chunk.subarray(0, alignedBytesNeeded);
+        }
+        // Fill remaining with silence if needed
+        if (chunk.length < alignedBytesNeeded) {
+            const silenceNeeded = Buffer.alloc(alignedBytesNeeded - chunk.length, 0);
+            chunk = Buffer.concat([chunk, silenceNeeded]);
+        }
+        // Update total bytes sent
+        this.totalBytesSent += chunk.length;
+        return chunk;
+    }
+}
+exports.UnclockedSilenceFiller = UnclockedSilenceFiller;

package/wrapper/collate.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Takes an async iterator that yields interleaved items from different groups
+ * and produces an iterator that yields items in group order.
+ *
+ * Example:
+ *   Input:  A1, B1, A2, A3 (final), C1, C2, C3 (final), B2 (final)
+ *   Output: A1, A2, A3, B1, B2, C1, C2, C3
+ *
+ * This is useful when using synthesizeJsonStreaming with num_generations > 1
+ *
+ * @example
+ * ```typescript
+ *
+ * import { collate } from 'hume';
+ *
+ * const stream = hume.synthesizeJsonStreaming({
+ *   ...
+ * })
+ *
+ * const contiguous = collate(
+ *   stream
+ *   (chunk) => chunk.generationId,
+ *   (chunk) => chunk.isLastChunk
+ * );
+ *
+ * for await (const item of contiguous) {
+ *   audioPlayer.write(item.audio)
+ * }
+ * ```
+ *
+ * @param source - Async iterable that yields interleaved items.
+ * @param groupBy - Function to determine a "key" that determines the group identity for each item.
+ * @param isFinal - Function to determine if an item is the final item in its group.
+ * @returns An async iterable that yields items in group order.
+ */
+export declare function collate<TItem, TKey>(source: AsyncIterable<TItem>, groupBy: (x: TItem) => TKey, isFinal: (x: TItem) => boolean): AsyncIterable<TItem>;

package/wrapper/collate.js

@@ -0,0 +1,126 @@
+"use strict";
+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); }
+};
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncDelegator = (this && this.__asyncDelegator) || function (o) {
+    var i, p;
+    return i = {}, verb("next"), verb("throw", function (e) { throw e; }), verb("return"), i[Symbol.iterator] = function () { return this; }, i;
+    function verb(n, f) { i[n] = o[n] ? function (v) { return (p = !p) ? { value: __await(o[n](v)), done: false } : f ? f(v) : v; } : f; }
+};
+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.collate = collate;
+/**
+ * Takes an async iterator that yields interleaved items from different groups
+ * and produces an iterator that yields items in group order.
+ *
+ * Example:
+ *   Input:  A1, B1, A2, A3 (final), C1, C2, C3 (final), B2 (final)
+ *   Output: A1, A2, A3, B1, B2, C1, C2, C3
+ *
+ * This is useful when using synthesizeJsonStreaming with num_generations > 1
+ *
+ * @example
+ * ```typescript
+ *
+ * import { collate } from 'hume';
+ *
+ * const stream = hume.synthesizeJsonStreaming({
+ *   ...
+ * })
+ *
+ * const contiguous = collate(
+ *   stream
+ *   (chunk) => chunk.generationId,
+ *   (chunk) => chunk.isLastChunk
+ * );
+ *
+ * for await (const item of contiguous) {
+ *   audioPlayer.write(item.audio)
+ * }
+ * ```
+ *
+ * @param source - Async iterable that yields interleaved items.
+ * @param groupBy - Function to determine a "key" that determines the group identity for each item.
+ * @param isFinal - Function to determine if an item is the final item in its group.
+ * @returns An async iterable that yields items in group order.
+ */
+function collate(source, groupBy, isFinal) {
+    return __asyncGenerator(this, arguments, function* collate_1() {
+        var _a, e_1, _b, _c;
+        const buffers = new Map();
+        const order = [];
+        let current;
+        const ensure = (k) => {
+            if (!buffers.has(k)) {
+                buffers.set(k, []);
+                order.push(k);
+            }
+        };
+        const flushGroup = function* (k) {
+            const buf = buffers.get(k);
+            if (!buf)
+                return;
+            for (const item of buf)
+                yield item;
+            buffers.delete(k);
+        };
+        const nextGroup = () => {
+            // pop the next group in first-seen order that still has a buffer
+            while (order.length && !buffers.has(order[0]))
+                order.shift();
+            return order.shift();
+        };
+        try {
+            for (var _d = true, source_1 = __asyncValues(source), source_1_1; source_1_1 = yield __await(source_1.next()), _a = source_1_1.done, !_a; _d = true) {
+                _c = source_1_1.value;
+                _d = false;
+                const item = _c;
+                const k = groupBy(item);
+                if (current === undefined)
+                    current = k;
+                ensure(k);
+                buffers.get(k).push(item);
+                // if we just saw the final item for the current group, flush it and advance
+                if (k === current && isFinal(item)) {
+                    yield __await(yield* __asyncDelegator(__asyncValues(flushGroup(current))));
+                    current = nextGroup();
+                }
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (!_d && !_a && (_b = source_1.return)) yield __await(_b.call(source_1));
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+        // stream ended; flush remaining groups in first-seen order
+        if (current !== undefined) {
+            if (buffers.has(current))
+                yield __await(yield* __asyncDelegator(__asyncValues(flushGroup(current))));
+            while (true) {
+                const k = nextGroup();
+                if (k === undefined)
+                    break;
+                yield __await(yield* __asyncDelegator(__asyncValues(flushGroup(k))));
+            }
+        }
+    });
+}

package/wrapper/convertFrequencyScale.d.ts

@@ -0,0 +1 @@
+export declare function convertLinearFrequenciesToBark(linearData: Uint8Array, sampleRate: number): number[];

package/wrapper/convertFrequencyScale.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertLinearFrequenciesToBark = convertLinearFrequenciesToBark;
+// This function converts linear-scaled frequency decibels from an AnalyserNode's frequncy data to Bark scale [https://en.wikipedia.org/wiki/Bark_scale]
+// This implementation uses a simple approach of mapping indices in the linear-scaled array to the closest
+// Bark scale center frequency and is not intended to be an accurate representation, but rather "close-enough" for visualization purposes
+const barkCenterFrequencies = [
+    50, 150, 250, 350, 450, 570, 700, 840, 1000, 1170, 1370, 1600, 1850, 2150, 2500, 2900, 3400, 4000, 4800, 5800, 7000,
+    8500, 10500, 13500,
+]; // Center frequency value in Hz
+// Min/max values from https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode/getByteFrequencyData
+const minValue = 0;
+const maxValue = 255;
+function convertLinearFrequenciesToBark(linearData, sampleRate) {
+    const maxFrequency = sampleRate / 2;
+    const frequencyResolution = maxFrequency / linearData.length;
+    const barkFrequencies = barkCenterFrequencies.map((barkFreq) => {
+        var _a;
+        const linearDataIndex = Math.round(barkFreq / frequencyResolution);
+        if (linearDataIndex >= 0 && linearDataIndex < linearData.length) {
+            return ((((_a = linearData[linearDataIndex]) !== null && _a !== void 0 ? _a : 0) - minValue) / (maxValue - minValue)) * 2;
+        }
+        else {
+            return 0;
+        }
+    });
+    return barkFrequencies;
+}

package/wrapper/generateEmptyFft.d.ts

@@ -0,0 +1 @@
+export declare function generateEmptyFft(): number[];

package/wrapper/generateEmptyFft.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateEmptyFft = generateEmptyFft;
+function generateEmptyFft() {
+    return Array.from({ length: 24 }).map(() => 0);
+}

package/wrapper/index.d.ts

@@ -9,3 +9,5 @@ export { getAudioStream } from "./getAudioStream";
 export { MimeType, getBrowserSupportedMimeType } from "./getBrowserSupportedMimeType";
 export { HumeClient } from "./HumeClient";
 export { EVIWebAudioPlayer, EVIWebAudioPlayerFFTOptions, EVIWebAudioPlayerOptions } from "./EVIWebAudioPlayer";
+export { collate } from "./collate";
+export { SilenceFiller } from "./SilenceFiller";

package/wrapper/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EVIWebAudioPlayer = exports.HumeClient = exports.getBrowserSupportedMimeType = exports.MimeType = exports.getAudioStream = exports.fetchAccessToken = exports.checkForAudioTracks = exports.ensureSingleValidAudioTrack = exports.convertBlobToBase64 = exports.convertBase64ToBlob = exports.base64Encode = exports.base64Decode = void 0;
+exports.SilenceFiller = exports.collate = exports.EVIWebAudioPlayer = exports.HumeClient = exports.getBrowserSupportedMimeType = exports.MimeType = exports.getAudioStream = exports.fetchAccessToken = exports.checkForAudioTracks = exports.ensureSingleValidAudioTrack = exports.convertBlobToBase64 = exports.convertBase64ToBlob = exports.base64Encode = exports.base64Decode = void 0;
 var base64Decode_1 = require("./base64Decode");
 Object.defineProperty(exports, "base64Decode", { enumerable: true, get: function () { return base64Decode_1.base64Decode; } });
 var base64Encode_1 = require("./base64Encode");
@@ -24,3 +24,7 @@ var HumeClient_1 = require("./HumeClient");
 Object.defineProperty(exports, "HumeClient", { enumerable: true, get: function () { return HumeClient_1.HumeClient; } });
 var EVIWebAudioPlayer_1 = require("./EVIWebAudioPlayer");
 Object.defineProperty(exports, "EVIWebAudioPlayer", { enumerable: true, get: function () { return EVIWebAudioPlayer_1.EVIWebAudioPlayer; } });
+var collate_1 = require("./collate");
+Object.defineProperty(exports, "collate", { enumerable: true, get: function () { return collate_1.collate; } });
+var SilenceFiller_1 = require("./SilenceFiller");
+Object.defineProperty(exports, "SilenceFiller", { enumerable: true, get: function () { return SilenceFiller_1.SilenceFiller; } });

package/.mock/definition/api.yml

@@ -1,12 +0,0 @@
-name: api
-error-discrimination:
-  strategy: status-code
-default-environment: Production
-environments:
-  Production: https://api.hume.ai
-auth: HeaderAuthScheme
-auth-schemes:
-  HeaderAuthScheme:
-    header: X-Hume-Api-Key
-    type: optional<string>
-    name: apiKey