speechrevolutions 0.2.0

package/src/exceptions.ts

@@ -0,0 +1,92 @@
+/** 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.
+ */
+
+export interface STTErrorOptions {
+  statusCode?: number;
+  requestId?: string;
+  body?: string;
+}
+
+export class STTError extends Error {
+  statusCode?: number;
+  requestId?: string;
+  body?: string;
+
+  constructor(message: string, opts?: STTErrorOptions) {
+    super(opts?.requestId ? `${message} (request_id=${opts.requestId})` : message);
+    this.name = "STTError";
+    this.statusCode = opts?.statusCode;
+    this.requestId = opts?.requestId;
+    this.body = opts?.body;
+  }
+}
+
+export class AuthenticationError extends STTError {
+  constructor(message = "Unauthorized — check your API key", opts?: STTErrorOptions) {
+    super(message, opts);
+    this.name = "AuthenticationError";
+  }
+}
+
+export class RateLimitError extends STTError {
+  retryAfter?: number;
+
+  constructor(
+    message = "Rate limit exceeded — try again shortly",
+    opts?: STTErrorOptions & { retryAfter?: number },
+  ) {
+    super(message, opts);
+    this.name = "RateLimitError";
+    this.retryAfter = opts?.retryAfter;
+  }
+}
+
+export class JobNotFoundError extends STTError {
+  constructor(
+    message = "Job not found or upload session expired",
+    opts?: STTErrorOptions,
+  ) {
+    super(message, opts);
+    this.name = "JobNotFoundError";
+  }
+}
+
+export class JobFailedError extends STTError {
+  step?: string;
+  reason?: string;
+
+  constructor(
+    message: string,
+    opts?: STTErrorOptions & { step?: string; reason?: string },
+  ) {
+    super(message, opts);
+    this.name = "JobFailedError";
+    this.step = opts?.step;
+    this.reason = opts?.reason;
+  }
+}
+
+export class UploadError extends STTError {
+  constructor(message: string, opts?: STTErrorOptions) {
+    super(message, opts);
+    this.name = "UploadError";
+  }
+}
+
+export class TimeoutError extends STTError {
+  constructor(message: string, opts?: STTErrorOptions) {
+    super(message, opts);
+    this.name = "TimeoutError";
+  }
+}
+
+export class APIError extends STTError {
+  constructor(message: string, opts?: STTErrorOptions) {
+    super(message, opts);
+    this.name = "APIError";
+  }
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+export {
+  SpeechRevolutions,
+  SpeechRevolutionsClient,
+  STTClient,
+} from "./client.js";
+export * from "./exceptions.js";
+export type { LanguageSegment, Transcript, Utterance, Word } from "./transcript.js";
+export { parseTranscript } from "./transcript.js";
+export { ProgressPrinter } from "./progress.js";
+export { computePercent } from "./types.js";
+export type {
+  JobStatus,
+  OutputType,
+  ProcessingTier,
+  ProgressCallback,
+  ProgressEvent,
+  STTClientOptions,
+  TranscribeOptions,
+  UploadJob,
+} from "./types.js";

package/src/progress.ts

@@ -0,0 +1,147 @@
+/**
+ * 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.
+ */
+
+import type { ProgressCallback, ProgressEvent } from "./types.js";
+
+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: number): string {
+  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(): NodeJS.WriteStream | undefined {
+  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.
+ */
+export class ProgressPrinter {
+  private readonly forward?: ProgressCallback;
+  private readonly label: string;
+  private readonly bytesMode: boolean;
+  private lastDraw = 0;
+  private lastPct = 0;
+  private drewAny = false;
+  private finished = false;
+  private closed = false;
+
+  constructor(opts: {
+    forward?: ProgressCallback;
+    label?: string;
+    bytesMode?: boolean;
+  } = {}) {
+    this.forward = opts.forward;
+    this.label = opts.label ?? DEFAULT_LABEL;
+    this.bytesMode = opts.bytesMode ?? false;
+  }
+
+  /** Use as the `onProgress` callback — renders, then forwards. */
+  readonly handle: ProgressCallback = (event: ProgressEvent): void => {
+    try {
+      this.render(event);
+    } finally {
+      this.forward?.(event);
+    }
+  };
+
+  private render(event: ProgressEvent): void {
+    const pct = event.percent;
+    if (pct === undefined) return;
+    this.draw(pct, event.completed, event.total);
+  }
+
+  private draw(
+    pct: number,
+    completed?: number,
+    total?: number,
+    force = false,
+  ): void {
+    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(): void {
+    if (this.closed) return;
+    this.closed = true;
+    if (this.drewAny && !this.finished) {
+      this.draw(100, undefined, undefined, true);
+    }
+  }
+}
+
+/**
+ * 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.
+ */
+export function resolveProgress(
+  onProgress: ProgressCallback | undefined,
+  show: boolean,
+  opts: { label?: string; bytesMode?: boolean } = {},
+): { callback?: ProgressCallback; printer?: ProgressPrinter } {
+  if (!show) return { callback: onProgress };
+  const printer = new ProgressPrinter({
+    forward: onProgress,
+    label: opts.label,
+    bytesMode: opts.bytesMode,
+  });
+  return { callback: printer.handle, printer };
+}

package/src/sse.ts

@@ -0,0 +1,61 @@
+/** Minimal SSE line parser for fetch ReadableStreams. */
+
+export interface SSEEvent {
+  id?: string;
+  event?: string;
+  data?: string;
+}
+
+export async function* parseSSEStream(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+): AsyncGenerator<SSEEvent> {
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let current: SSEEvent = {};
+  let dataLines: string[] = [];
+
+  const flush = (): SSEEvent | undefined => {
+    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: string;
+      let valueStr: string;
+      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/src/transcript.ts

@@ -0,0 +1,334 @@
+/**
+ * Transcript models + Deepgram / AssemblyAI-style adapters.
+ */
+
+export interface Word {
+  word: string;
+  text: string;
+  start?: number;
+  end?: number;
+  speaker?: string;
+  confidence?: number;
+  language?: string;
+}
+
+/** A contiguous time range spoken in a single detected language. */
+export interface LanguageSegment {
+  start: number;
+  end: number;
+  language: string;
+}
+
+export interface Utterance {
+  text: string;
+  transcript: string;
+  speaker?: string;
+  start?: number;
+  end?: number;
+  words: Word[];
+  confidence?: number;
+}
+
+export interface Transcript {
+  jobId: string;
+  outputType: string;
+  content: Uint8Array;
+  downloadUrl: string;
+  words: Word[];
+  utterances: Utterance[];
+  languages: LanguageSegment[];
+  raw: Record<string, unknown> | null;
+  /** Full transcript text (AssemblyAI / ElevenLabs-style). */
+  readonly text: string;
+  /** Deepgram-compatible alias for text. */
+  readonly transcript: string;
+  /** Write raw content to disk (Node). Appends `.outputType` if path has no extension. */
+  save(path: string): Promise<string>;
+  toDict(): Record<string, unknown>;
+  toDeepgram(): Record<string, unknown>;
+}
+
+function joinWords(words: Word[]): string {
+  const parts: string[] = [];
+  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: unknown): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+function parseWord(data: Record<string, unknown>): Word {
+  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: Record<string, unknown>): LanguageSegment {
+  return {
+    start: asNumber(data.start) ?? 0,
+    end: asNumber(data.end) ?? 0,
+    language: String(data.language ?? ""),
+  };
+}
+
+function utteranceFromGroup(group: Word[]): Utterance {
+  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: Word[]): Utterance[] {
+  if (!words.length) return [];
+  if (words.every((w) => w.speaker == null)) {
+    return [utteranceFromGroup(words)];
+  }
+  const out: Utterance[] = [];
+  let current: Word[] = [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: Word[], diarization: unknown): Utterance[] {
+  if (!Array.isArray(diarization) || diarization.length === 0) {
+    return utterancesFromWords(words);
+  }
+
+  const out: Utterance[] = [];
+  for (const seg of diarization as Record<string, unknown>[]) {
+    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: Word[], start: number, end: number): Word[] {
+  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?: string): number | string | undefined {
+  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;
+}
+
+export function parseTranscript(opts: {
+  jobId: string;
+  content: Uint8Array;
+  outputType: string;
+  downloadUrl?: string;
+}): Transcript {
+  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: Record<string, unknown>;
+  try {
+    raw = JSON.parse(new TextDecoder().decode(content)) as Record<string, unknown>;
+  } catch {
+    return makeTranscript({
+      jobId,
+      outputType,
+      content,
+      downloadUrl,
+      words: [],
+      utterances: [],
+      languages: [],
+      raw: null,
+      text: "",
+    });
+  }
+
+  const words = Array.isArray(raw.words)
+    ? (raw.words as Record<string, unknown>[]).map(parseWord)
+    : [];
+  const utterances = utterancesFromDiarization(words, raw.diarization);
+  const languages = Array.isArray(raw.languages)
+    ? (raw.languages as Record<string, unknown>[]).map(parseLanguageSegment)
+    : [];
+  const text = joinWords(words);
+
+  return makeTranscript({
+    jobId,
+    outputType,
+    content,
+    downloadUrl,
+    words,
+    utterances,
+    languages,
+    raw,
+    text,
+  });
+}
+
+function makeTranscript(args: {
+  jobId: string;
+  outputType: string;
+  content: Uint8Array;
+  downloadUrl: string;
+  words: Word[];
+  utterances: Utterance[];
+  languages: LanguageSegment[];
+  raw: Record<string, unknown> | null;
+  text: string;
+}): Transcript {
+  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: string): Promise<string> {
+      const name = path.includes("/") ? path.slice(path.lastIndexOf("/") + 1) : path;
+      const out = name.includes(".") ? path : `${path}.${args.outputType}`;
+      const { writeFile } = await import("node:fs/promises");
+      await writeFile(out, args.content);
+      return out;
+    },
+    toDict() {
+      const dict: Record<string, unknown> = {
+        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),
+            })),
+          })),
+        },
+      };
+    },
+  };
+}