speechrevolutions 0.2.0

package/dist/cjs/exceptions.js

@@ -0,0 +1,77 @@
+"use strict";
+/** SDK exception hierarchy.
+ *
+ * Every error carries the HTTP `statusCode` and the server `requestId` (from the
+ * response headers, when present) so failures can be correlated with server
+ * logs. `RateLimitError` also exposes `retryAfter` seconds.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APIError = exports.TimeoutError = exports.UploadError = exports.JobFailedError = exports.JobNotFoundError = exports.RateLimitError = exports.AuthenticationError = exports.STTError = void 0;
+class STTError extends Error {
+    statusCode;
+    requestId;
+    body;
+    constructor(message, opts) {
+        super(opts?.requestId ? `${message} (request_id=${opts.requestId})` : message);
+        this.name = "STTError";
+        this.statusCode = opts?.statusCode;
+        this.requestId = opts?.requestId;
+        this.body = opts?.body;
+    }
+}
+exports.STTError = STTError;
+class AuthenticationError extends STTError {
+    constructor(message = "Unauthorized — check your API key", opts) {
+        super(message, opts);
+        this.name = "AuthenticationError";
+    }
+}
+exports.AuthenticationError = AuthenticationError;
+class RateLimitError extends STTError {
+    retryAfter;
+    constructor(message = "Rate limit exceeded — try again shortly", opts) {
+        super(message, opts);
+        this.name = "RateLimitError";
+        this.retryAfter = opts?.retryAfter;
+    }
+}
+exports.RateLimitError = RateLimitError;
+class JobNotFoundError extends STTError {
+    constructor(message = "Job not found or upload session expired", opts) {
+        super(message, opts);
+        this.name = "JobNotFoundError";
+    }
+}
+exports.JobNotFoundError = JobNotFoundError;
+class JobFailedError extends STTError {
+    step;
+    reason;
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "JobFailedError";
+        this.step = opts?.step;
+        this.reason = opts?.reason;
+    }
+}
+exports.JobFailedError = JobFailedError;
+class UploadError extends STTError {
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "UploadError";
+    }
+}
+exports.UploadError = UploadError;
+class TimeoutError extends STTError {
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "TimeoutError";
+    }
+}
+exports.TimeoutError = TimeoutError;
+class APIError extends STTError {
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "APIError";
+    }
+}
+exports.APIError = APIError;

package/dist/cjs/index.js

@@ -0,0 +1,28 @@
+"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 });
+exports.computePercent = exports.ProgressPrinter = exports.parseTranscript = exports.STTClient = exports.SpeechRevolutionsClient = exports.SpeechRevolutions = void 0;
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "SpeechRevolutions", { enumerable: true, get: function () { return client_js_1.SpeechRevolutions; } });
+Object.defineProperty(exports, "SpeechRevolutionsClient", { enumerable: true, get: function () { return client_js_1.SpeechRevolutionsClient; } });
+Object.defineProperty(exports, "STTClient", { enumerable: true, get: function () { return client_js_1.STTClient; } });
+__exportStar(require("./exceptions.js"), exports);
+var transcript_js_1 = require("./transcript.js");
+Object.defineProperty(exports, "parseTranscript", { enumerable: true, get: function () { return transcript_js_1.parseTranscript; } });
+var progress_js_1 = require("./progress.js");
+Object.defineProperty(exports, "ProgressPrinter", { enumerable: true, get: function () { return progress_js_1.ProgressPrinter; } });
+var types_js_1 = require("./types.js");
+Object.defineProperty(exports, "computePercent", { enumerable: true, get: function () { return types_js_1.computePercent; } });

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/progress.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * Optional console progress rendering for upload + transcription jobs.
+ *
+ * Neither AssemblyAI nor Deepgram surfaces live percentage progress for
+ * pre-recorded transcription — our pipeline is chunked and emits SSE progress
+ * events, so this is a Speech Revolutions extra. The same renderer also drives
+ * the byte-level *upload* bar.
+ *
+ * There is no tqdm in JS, so this is a tiny built-in renderer: a single line
+ * written to stderr, updated in place with a carriage return, showing a
+ * percentage and a `[####----]`-style bar. It always forwards each event to a
+ * user-supplied callback, so programmatic access via `onProgress` /
+ * `onUploadProgress` is unaffected whether or not the console display is on.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProgressPrinter = void 0;
+exports.resolveProgress = resolveProgress;
+const DEFAULT_LABEL = "Transcribing";
+// Minimum ms between redraws (a byte upload fires many events).
+const MIN_REDRAW_INTERVAL_MS = 80;
+const BAR_WIDTH = 30;
+function formatBytes(n) {
+    const units = ["B", "KB", "MB", "GB", "TB"];
+    let size = n;
+    let i = 0;
+    while (size >= 1024 && i < units.length - 1) {
+        size /= 1024;
+        i += 1;
+    }
+    return `${size.toFixed(i === 0 ? 0 : 1)}${units[i]}`;
+}
+function stderr() {
+    if (typeof process === "undefined" || !process.stderr)
+        return undefined;
+    return process.stderr;
+}
+/**
+ * A progress callback that renders to the console and forwards events.
+ *
+ * `bytesMode` renders sizes (e.g. `2.5MB/6.0MB`) alongside the bar. For
+ * transcription the volatile step name (preprocess / chunk:N / aggregation) is
+ * deliberately kept off the bar — chunks finish out of order and made the label
+ * jump around; callers who want it read `event.step` in their callback.
+ */
+class ProgressPrinter {
+    forward;
+    label;
+    bytesMode;
+    lastDraw = 0;
+    lastPct = 0;
+    drewAny = false;
+    finished = false;
+    closed = false;
+    constructor(opts = {}) {
+        this.forward = opts.forward;
+        this.label = opts.label ?? DEFAULT_LABEL;
+        this.bytesMode = opts.bytesMode ?? false;
+    }
+    /** Use as the `onProgress` callback — renders, then forwards. */
+    handle = (event) => {
+        try {
+            this.render(event);
+        }
+        finally {
+            this.forward?.(event);
+        }
+    };
+    render(event) {
+        const pct = event.percent;
+        if (pct === undefined)
+            return;
+        this.draw(pct, event.completed, event.total);
+    }
+    draw(pct, completed, total, force = false) {
+        const out = stderr();
+        if (!out)
+            return;
+        const complete = pct >= 100;
+        const now = Date.now();
+        // Throttle redraws (uploads emit many events); always draw the final 100%.
+        if (!force &&
+            !complete &&
+            this.lastDraw !== 0 &&
+            now - this.lastDraw < MIN_REDRAW_INTERVAL_MS) {
+            return;
+        }
+        this.lastDraw = now;
+        this.lastPct = pct;
+        const filled = Math.round((BAR_WIDTH * pct) / 100);
+        const bar = "#".repeat(filled) + "-".repeat(BAR_WIDTH - filled);
+        let line = `\r${this.label}: ${String(Math.round(pct)).padStart(3)}% [${bar}]`;
+        if (this.bytesMode && total) {
+            line += ` ${formatBytes(completed ?? 0)}/${formatBytes(total)}`;
+        }
+        out.write(line);
+        this.drewAny = true;
+        if (complete) {
+            out.write("\n");
+            this.finished = true;
+        }
+    }
+    /** Finish the bar. Safe to call more than once. Always leaves 100% drawn. */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (this.drewAny && !this.finished) {
+            this.draw(100, undefined, undefined, true);
+        }
+    }
+}
+exports.ProgressPrinter = ProgressPrinter;
+/**
+ * Build the effective progress callback for an upload/transcription phase.
+ *
+ * When `show` is true, wrap `onProgress` in a {@link ProgressPrinter} that
+ * renders to the console and still forwards to the user callback. The returned
+ * printer (or `undefined`) must have `.close()` called when done.
+ */
+function resolveProgress(onProgress, show, opts = {}) {
+    if (!show)
+        return { callback: onProgress };
+    const printer = new ProgressPrinter({
+        forward: onProgress,
+        label: opts.label,
+        bytesMode: opts.bytesMode,
+    });
+    return { callback: printer.handle, printer };
+}

package/dist/cjs/sse.js

@@ -0,0 +1,56 @@
+"use strict";
+/** Minimal SSE line parser for fetch ReadableStreams. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSSEStream = parseSSEStream;
+async function* parseSSEStream(reader) {
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let current = {};
+    let dataLines = [];
+    const flush = () => {
+        if (!dataLines.length)
+            return undefined;
+        const event = { ...current, data: dataLines.join("\n") };
+        dataLines = [];
+        return event;
+    };
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split(/\r?\n/);
+        buffer = lines.pop() ?? "";
+        for (const rawLine of lines) {
+            if (rawLine === "") {
+                const event = flush();
+                if (event)
+                    yield event;
+                current = {};
+                continue;
+            }
+            if (rawLine.startsWith(":"))
+                continue;
+            const colon = rawLine.indexOf(":");
+            let field;
+            let valueStr;
+            if (colon === -1) {
+                field = rawLine;
+                valueStr = "";
+            }
+            else {
+                field = rawLine.slice(0, colon);
+                valueStr = rawLine.slice(colon + 1).replace(/^ /, "");
+            }
+            if (field === "id")
+                current.id = valueStr;
+            else if (field === "event")
+                current.event = valueStr;
+            else if (field === "data")
+                dataLines.push(valueStr);
+        }
+    }
+    const event = flush();
+    if (event)
+        yield event;
+}

package/dist/cjs/transcript.js

@@ -0,0 +1,303 @@
+"use strict";
+/**
+ * Transcript models + Deepgram / AssemblyAI-style adapters.
+ */
+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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseTranscript = parseTranscript;
+function joinWords(words) {
+    const parts = [];
+    for (const w of words) {
+        const token = w.word;
+        if (!token)
+            continue;
+        if (parts.length && ".,!?;:%)]}'\"".includes(token[0])) {
+            parts[parts.length - 1] = parts[parts.length - 1] + token;
+        }
+        else {
+            parts.push(token);
+        }
+    }
+    return parts.join(" ");
+}
+function asNumber(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : undefined;
+}
+function parseWord(data) {
+    const word = String(data.word ?? data.text ?? "");
+    return {
+        word,
+        text: word,
+        start: asNumber(data.start),
+        end: asNumber(data.end),
+        speaker: data.speaker != null ? String(data.speaker) : undefined,
+        confidence: asNumber(data.confidence),
+        language: data.language != null ? String(data.language) : undefined,
+    };
+}
+function parseLanguageSegment(data) {
+    return {
+        start: asNumber(data.start) ?? 0,
+        end: asNumber(data.end) ?? 0,
+        language: String(data.language ?? ""),
+    };
+}
+function utteranceFromGroup(group) {
+    const text = joinWords(group);
+    return {
+        text,
+        transcript: text,
+        speaker: group[0]?.speaker,
+        start: group[0]?.start,
+        end: group[group.length - 1]?.end,
+        words: group,
+    };
+}
+function utterancesFromWords(words) {
+    if (!words.length)
+        return [];
+    if (words.every((w) => w.speaker == null)) {
+        return [utteranceFromGroup(words)];
+    }
+    const out = [];
+    let current = [words[0]];
+    for (let i = 1; i < words.length; i++) {
+        const w = words[i];
+        if (w.speaker === current[0].speaker)
+            current.push(w);
+        else {
+            out.push(utteranceFromGroup(current));
+            current = [w];
+        }
+    }
+    out.push(utteranceFromGroup(current));
+    return out;
+}
+/**
+ * Prefers the server's diarization segments, which separate turns the speaker
+ * labels alone cannot (the same speaker talking twice). Falls back to grouping
+ * consecutive words by speaker.
+ */
+function utterancesFromDiarization(words, diarization) {
+    if (!Array.isArray(diarization) || diarization.length === 0) {
+        return utterancesFromWords(words);
+    }
+    const out = [];
+    for (const seg of diarization) {
+        const start = asNumber(seg?.start);
+        const end = asNumber(seg?.end);
+        if (start === undefined || end === undefined)
+            continue;
+        const segWords = wordsWithin(words, start, end);
+        const text = joinWords(segWords);
+        out.push({
+            text,
+            transcript: text,
+            speaker: seg.speaker == null ? undefined : String(seg.speaker),
+            start,
+            end,
+            words: segWords,
+        });
+    }
+    return out.length ? out : utterancesFromWords(words);
+}
+/**
+ * Words a segment covers, falling back to a midpoint test for words that
+ * straddle the boundary.
+ */
+function wordsWithin(words, start, end) {
+    const eps = 1e-3;
+    const timed = words.filter((w) => w.start !== undefined && w.end !== undefined);
+    const inside = timed.filter((w) => w.start >= start - eps && w.end <= end + eps);
+    if (inside.length)
+        return inside;
+    return timed.filter((w) => {
+        const mid = (w.start + w.end) / 2;
+        return mid >= start && mid <= end;
+    });
+}
+function speakerIndex(speaker) {
+    if (speaker == null)
+        return undefined;
+    if (speaker.toUpperCase().startsWith("SPEAKER_")) {
+        const n = Number(speaker.split("_")[1]);
+        return Number.isFinite(n) ? n : speaker;
+    }
+    if (speaker.length === 1 && /[a-zA-Z]/.test(speaker)) {
+        return speaker.toUpperCase().charCodeAt(0) - "A".charCodeAt(0);
+    }
+    const n = Number(speaker);
+    return Number.isFinite(n) ? n : speaker;
+}
+function parseTranscript(opts) {
+    const { jobId, content, outputType } = opts;
+    const downloadUrl = opts.downloadUrl ?? "";
+    if (outputType !== "json") {
+        let text = "";
+        try {
+            text = new TextDecoder().decode(content);
+        }
+        catch {
+            text = "";
+        }
+        return makeTranscript({
+            jobId,
+            outputType,
+            content,
+            downloadUrl,
+            words: [],
+            utterances: [],
+            languages: [],
+            raw: null,
+            text,
+        });
+    }
+    let raw;
+    try {
+        raw = JSON.parse(new TextDecoder().decode(content));
+    }
+    catch {
+        return makeTranscript({
+            jobId,
+            outputType,
+            content,
+            downloadUrl,
+            words: [],
+            utterances: [],
+            languages: [],
+            raw: null,
+            text: "",
+        });
+    }
+    const words = Array.isArray(raw.words)
+        ? raw.words.map(parseWord)
+        : [];
+    const utterances = utterancesFromDiarization(words, raw.diarization);
+    const languages = Array.isArray(raw.languages)
+        ? raw.languages.map(parseLanguageSegment)
+        : [];
+    const text = joinWords(words);
+    return makeTranscript({
+        jobId,
+        outputType,
+        content,
+        downloadUrl,
+        words,
+        utterances,
+        languages,
+        raw,
+        text,
+    });
+}
+function makeTranscript(args) {
+    const textValue = args.text;
+    return {
+        jobId: args.jobId,
+        outputType: args.outputType,
+        content: args.content,
+        downloadUrl: args.downloadUrl,
+        words: args.words,
+        utterances: args.utterances,
+        languages: args.languages,
+        raw: args.raw,
+        get text() {
+            return textValue;
+        },
+        get transcript() {
+            return textValue;
+        },
+        async save(path) {
+            const name = path.includes("/") ? path.slice(path.lastIndexOf("/") + 1) : path;
+            const out = name.includes(".") ? path : `${path}.${args.outputType}`;
+            const { writeFile } = await Promise.resolve().then(() => __importStar(require("node:fs/promises")));
+            await writeFile(out, args.content);
+            return out;
+        },
+        toDict() {
+            const dict = {
+                id: args.jobId,
+                status: "completed",
+                text: textValue,
+                words: args.words,
+                utterances: args.utterances,
+                output_type: args.outputType,
+            };
+            if (args.languages.length)
+                dict.languages = args.languages;
+            return dict;
+        },
+        toDeepgram() {
+            return {
+                metadata: { request_id: args.jobId, channels: 1 },
+                results: {
+                    channels: [
+                        {
+                            alternatives: [
+                                {
+                                    transcript: textValue,
+                                    confidence: 1.0,
+                                    words: args.words.map((w) => ({
+                                        word: w.word.replace(/[.,!?;:]+$/g, "").toLowerCase(),
+                                        punctuated_word: w.word,
+                                        start: w.start,
+                                        end: w.end,
+                                        speaker: speakerIndex(w.speaker),
+                                    })),
+                                },
+                            ],
+                        },
+                    ],
+                    utterances: args.utterances.map((u) => ({
+                        transcript: u.text,
+                        channel: 0,
+                        start: u.start,
+                        end: u.end,
+                        speaker: speakerIndex(u.speaker),
+                        words: u.words.map((w) => ({
+                            word: w.word,
+                            punctuated_word: w.word,
+                            start: w.start,
+                            end: w.end,
+                            speaker: speakerIndex(w.speaker),
+                        })),
+                    })),
+                },
+            };
+        },
+    };
+}

package/dist/cjs/types.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computePercent = computePercent;
+exports.makeProgressEvent = makeProgressEvent;
+exports.resolveOptions = resolveOptions;
+/** Completion as a 0–100 number clamped to [0, 100], or `undefined` if unknown. */
+function computePercent(completed, total) {
+    if (completed === undefined || completed === null || !total)
+        return undefined;
+    return Math.max(0, Math.min(100, (completed / total) * 100));
+}
+/** Build a {@link ProgressEvent} with its `percent` derived from completed/total. */
+function makeProgressEvent(event) {
+    return { ...event, percent: computePercent(event.completed, event.total) };
+}
+function resolveOptions(options = {}) {
+    const speakerLabels = options.diarize !== undefined
+        ? options.diarize
+        : options.speakerLabels !== undefined
+            ? options.speakerLabels
+            : true;
+    return {
+        outputType: options.outputType ?? "json",
+        wordTimestamps: options.wordTimestamps ?? true,
+        speakerLabels,
+        nltk: options.nltk ?? true,
+        tier: options.tier ?? "standard",
+        customVocabulary: options.customVocabulary,
+        callbackUrl: options.callbackUrl,
+    };
+}

package/dist/cjs/upload.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * Upload-body helpers that report byte-level progress.
+ *
+ * The HTTP client can only observe upload progress if it reads the body through
+ * something we control. For a presigned S3 PUT that's a byte-chunk async
+ * generator (`iterWithProgress`) paired with an explicit `Content-Length`
+ * header, which keeps S3 happy — undici (Node's fetch) would otherwise switch a
+ * streamed body to `Transfer-Encoding: chunked`, which presigned PUTs reject.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UPLOAD_CHUNK_SIZE = void 0;
+exports.byteProgressAdapter = byteProgressAdapter;
+exports.iterWithProgress = iterWithProgress;
+const types_js_1 = require("./types.js");
+exports.UPLOAD_CHUNK_SIZE = 64 * 1024;
+/**
+ * Adapt a {@link ProgressCallback} to a `(sent, total)` byte callback.
+ *
+ * Upload events are reported as `ProgressEvent(step="upload")` so they share the
+ * same shape (and `.percent`) as transcription progress.
+ */
+function byteProgressAdapter(onProgress) {
+    if (!onProgress)
+        return undefined;
+    return (sent, total) => {
+        onProgress((0, types_js_1.makeProgressEvent)({ completed: sent, total, step: "upload" }));
+    };
+}
+/**
+ * Yield `data` in chunks, reporting progress after each — used as the streamed
+ * PUT body. A fresh generator is created per upload attempt, so a retry simply
+ * restarts progress from 0.
+ */
+async function* iterWithProgress(data, callback) {
+    const total = data.byteLength;
+    let sent = 0;
+    for (let start = 0; start < total; start += exports.UPLOAD_CHUNK_SIZE) {
+        const chunk = data.subarray(start, Math.min(start + exports.UPLOAD_CHUNK_SIZE, total));
+        sent += chunk.byteLength;
+        yield chunk;
+        callback?.(sent, total);
+    }
+}