@startsimpli/llm 0.4.29 → 0.4.31

package/src/refine/types.ts

@@ -0,0 +1,54 @@
+import type { TokenUsage } from '../types';
+
+/** One line a gate reports. A bare string is a defect; `level: 'info'` is information and never fails the gate. */
+export type GateFinding = string | { text: string; level?: 'defect' | 'info' };
+
+/** Gates see the step's result and a caller-owned context. They may be async (a render check, a validator service). */
+export type RefineGate<T, C = unknown> = (result: T, context: C) => GateFinding[] | Promise<GateFinding[]>;
+
+/** The failures one gate found; a report is the list of gates that failed, empty when every gate passed. */
+export interface GateFailure { gate: string; failures: string[] }
+
+export interface GateNote { gate: string; text: string }
+
+/** What the step is handed on every try. Data only: the step decides how to put it in a prompt. */
+export interface StepInput<T> {
+  /** 1-based try number. */
+  n: number;
+  /** The previous try's result, or null on the first try and after a try that produced none. */
+  previous: T | null;
+  /** The previous try's gate report; empty on the first try. */
+  failures: GateFailure[];
+}
+
+export interface StepOutput<T> {
+  /** The revised result, or null when the reply could not be read. */
+  result: T | null;
+  /** What the step rejected in the reply (parse / schema errors). They count as failures of the `rejectedGate` gate. */
+  errors?: string[];
+  /** Model that answered, for the usage tally. */
+  model?: string;
+  usage?: TokenUsage;
+  /** USD this try's calls cost, when the step prices them. */
+  costUsd?: number;
+  /** Step calls this try made (more than one only for a step that regenerates parts). Default 1. */
+  calls?: number;
+}
+
+/** One call of the model (or several, for a step that regenerates parts of a result). The client is closed over, so it is injectable. */
+export type RefineStep<T> = (input: StepInput<T>) => Promise<StepOutput<T>>;
+
+export interface RefineCost { usd: number; promptTokens: number; completionTokens: number; cachedTokens: number }
+
+export interface RefineAttempt<T> {
+  n: number;
+  result: T | null;
+  /** Empty = every gate passed. */
+  report: GateFailure[];
+  /** Informational gate lines; never sent back to the step. */
+  notes: GateNote[];
+  cost: RefineCost;
+  passed: boolean;
+  seconds: number;
+  calls: number;
+}

package/src/speech/alignment.ts

@@ -0,0 +1,48 @@
+import type { AlignedCharacter, TranscriptWord } from './types';
+
+/**
+ * Character alignment -> word timings, split on whitespace.
+ *
+ * `[tag]` spans (v3-style audio tags such as `[excited]`) are delivery
+ * directions the vendor aligns like speech but nobody hears as words, so they
+ * are skipped by default. Skipping removes the characters, not the time: the
+ * next word keeps its true offset, so a ~0.2s tag leaves a gap rather than
+ * shifting everything left. A `[` with no closing `]` is ordinary text.
+ */
+export function wordsFromCharacters(
+  characters: AlignedCharacter[],
+  options: { keepTags?: boolean } = {},
+): TranscriptWord[] {
+  const words: TranscriptWord[] = [];
+  let text = '';
+  let start = 0;
+  let end = 0;
+  const flush = () => {
+    if (text) words.push({ text, start: round(start), end: round(end) });
+    text = '';
+  };
+  for (let i = 0; i < characters.length; i += 1) {
+    const c = characters[i];
+    if (!options.keepTags && c.text === '[' && !text) {
+      const close = closingBracket(characters, i);
+      if (close > 0) { i = close; continue; }
+    }
+    if (/\s/.test(c.text)) { flush(); continue; }
+    if (!text) start = c.start;
+    text += c.text;
+    end = c.end;
+  }
+  flush();
+  return words;
+}
+
+/** Index of the `]` closing a tag opened at `open`, or -1 (no close, or whitespace-only run is not a tag). */
+function closingBracket(characters: AlignedCharacter[], open: number): number {
+  for (let j = open + 1; j < characters.length; j += 1) {
+    if (characters[j].text === ']') return j > open + 1 ? j : -1;
+    if (characters[j].text === '[') return -1;
+  }
+  return -1;
+}
+
+const round = (n: number) => Math.round(n * 1000) / 1000;

package/src/speech/bin.ts

@@ -0,0 +1,12 @@
+import { runCli } from './cli';
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+runCli(process.argv.slice(2), { readStdin }).then(({ exitCode, output }) => {
+  process.stdout.write(`${JSON.stringify(output)}\n`);
+  process.exitCode = exitCode;
+});

package/src/speech/captions/cues.ts

@@ -0,0 +1,108 @@
+import type { CaptionWord, Cue, CueOptions } from './types';
+
+const CLAUSE_END = [',', ';', ':', '.', '?', '!'];
+const endsClause = (token: string) => CLAUSE_END.some((c) => token.endsWith(c));
+/** Length in code points, as Python counts. */
+const len = (s: string) => [...s].length;
+
+/**
+ * Index k of the last token (not the final one) that ends a clause with at least two tokens before the cut, else null.
+ * A cue that has to end early ends there instead of in the middle of a clause.
+ */
+function clauseCut(tokens: string[]): number | null {
+  if (endsClause(tokens[tokens.length - 1])) return null;
+  for (let k = tokens.length - 2; k > 0; k -= 1) if (endsClause(tokens[k])) return k;
+  return null;
+}
+
+/** Words -> cues of at most `maxWords` words and `maxChars` characters, also split at a silence over `maxGap`. */
+export function cuesFromWords(words: CaptionWord[], options: CueOptions = {}): Cue[] {
+  const { maxWords = 7, maxChars = 42, maxGap = 0.6, clauseBreaks = false } = options;
+  const cues: Cue[] = [];
+  let cur: CaptionWord[] = [];
+  const flush = (upto?: number) => {
+    const part = upto ? cur.slice(0, upto) : [...cur];
+    if (part.length) {
+      cues.push({ start: part[0].start, end: part[part.length - 1].end, text: part.map((w) => w.text).join(' ') });
+      cur = cur.slice(part.length);
+    }
+  };
+  for (const w of words) {
+    if (cur.length) {
+      const tooLong = len([...cur, w].map((x) => x.text).join(' ')) > maxChars;
+      const gap = w.start - cur[cur.length - 1].end;
+      if (cur.length >= maxWords || tooLong || gap > maxGap) {
+        const k = clauseBreaks && gap <= maxGap ? clauseCut(cur.map((x) => x.text)) : null;
+        flush(k !== null ? k + 1 : undefined);
+      }
+    }
+    cur.push(w);
+  }
+  flush();
+  return cues;
+}
+
+/** Text with no timings: spread evenly over [0, duration], each chunk weighted by its character count. */
+export function cuesFromText(text: string, duration: number, options: CueOptions = {}): Cue[] {
+  const { maxWords = 7, maxChars = 42, clauseBreaks = false } = options;
+  const tokens = text.split(/\s+/).filter(Boolean);
+  if (!tokens.length) return [];
+  const chunks: string[][] = [];
+  let cur: string[] = [];
+  for (const t of tokens) {
+    if (cur.length && (cur.length >= maxWords || len([...cur, t].join(' ')) > maxChars)) {
+      const k = clauseBreaks ? clauseCut(cur) : null;
+      chunks.push(k !== null ? cur.slice(0, k + 1) : cur);
+      cur = k !== null ? cur.slice(k + 1) : [];
+    }
+    cur.push(t);
+  }
+  chunks.push(cur);
+  const texts = chunks.map((c) => c.join(' '));
+  const total = texts.reduce((n, t) => n + len(t), 0);
+  let t0 = 0;
+  return texts.map((s, i) => {
+    const t1 = i === texts.length - 1 ? duration : t0 + (duration * len(s)) / total;
+    const cue = { start: t0, end: t1, text: s };
+    t0 = t1;
+    return cue;
+  });
+}
+
+/** One beat's cues: from its word timings when it has them, else from its text; shifted by `offset` seconds. */
+export function cuesForBeat(
+  words: CaptionWord[] | null | undefined, text: string | null | undefined, duration: number,
+  options: CueOptions & { offset?: number } = {},
+): Cue[] {
+  const { offset = 0, ...cueOptions } = options;
+  const cues = words?.length ? cuesFromWords(words, cueOptions) : cuesFromText(text ?? '', duration, cueOptions);
+  return cues.map((c) => ({ start: c.start + offset, end: c.end + offset, text: c.text }));
+}
+
+/**
+ * Cues with each end moved to the next cue's start when the silence between them is at most `maxGapS`, so a caption stays
+ * up across a short pause. Starts never move; 0 returns the cues unchanged. The input is not mutated.
+ */
+export function holdGaps(cues: Cue[], maxGapS: number): Cue[] {
+  const out = cues.map((c) => ({ ...c }));
+  if (maxGapS > 0) {
+    for (let i = 0; i + 1 < out.length; i += 1) {
+      const gap = out[i + 1].start - out[i].end;
+      if (gap > 0 && gap <= maxGapS) out[i].end = out[i + 1].start;
+    }
+  }
+  return out;
+}
+
+/** Round half to even, as Python's `round`. */
+function roundHalfEven(x: number): number {
+  const floor = Math.floor(x);
+  const diff = x - floor;
+  if (diff === 0.5) return floor % 2 === 0 ? floor : floor + 1;
+  return Math.round(x);
+}
+
+/** [first frame, end frame exclusive]: frame i is shown at time i / fps. */
+export function cueFrameRange(cue: Pick<Cue, 'start' | 'end'>, fps: number): [number, number] {
+  return [roundHalfEven(cue.start * fps), roundHalfEven(cue.end * fps)];
+}

package/src/speech/captions/formats.ts

@@ -0,0 +1,33 @@
+import type { Cue } from './types';
+
+function stamp(ms: number, sep: ',' | '.'): string {
+  const pad = (n: number, w = 2) => String(n).padStart(w, '0');
+  return `${pad(Math.floor(ms / 3_600_000))}:${pad(Math.floor(ms / 60_000) % 60)}:${pad(Math.floor(ms / 1000) % 60)}${sep}${pad(ms % 1000, 3)}`;
+}
+
+/** Millisecond start/end; an end that rounds onto its start is lifted one millisecond so the cue stays valid. */
+function span(c: Cue): [number, number] {
+  const start = Math.max(0, Math.round(c.start * 1000));
+  return [start, Math.max(start + 1, Math.round(c.end * 1000))];
+}
+
+const oneBlock = (text: string) => text.split(/\n\s*\n/).map((s) => s.trim()).filter(Boolean).join('\n');
+
+/** SubRip. Cue text keeps its line breaks; blank lines inside a cue are dropped (they would end it). */
+export function toSrt(cues: Cue[]): string {
+  return cues.map((c, i) => {
+    const [a, b] = span(c);
+    return `${i + 1}\n${stamp(a, ',')} --> ${stamp(b, ',')}\n${oneBlock(c.text)}\n`;
+  }).join('\n');
+}
+
+const vttText = (text: string) => oneBlock(text).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/-->/g, '--&gt;');
+
+/** WebVTT. `&`, `<` and `-->` in cue text are escaped as the spec requires. */
+export function toVtt(cues: Cue[]): string {
+  const body = cues.map((c) => {
+    const [a, b] = span(c);
+    return `${stamp(a, '.')} --> ${stamp(b, '.')}\n${vttText(c.text)}\n`;
+  }).join('\n');
+  return `WEBVTT\n\n${body}`;
+}

package/src/speech/captions/index.ts

@@ -0,0 +1,6 @@
+/** Caption cues from word timings (or bare text), word-alignment checks, SRT / VTT output. Pure: no vendor, no I/O. */
+export { cueFrameRange, cuesForBeat, cuesFromText, cuesFromWords, holdGaps } from './cues';
+export { toSrt, toVtt } from './formats';
+export type { CaptionWord, Cue, CueOptions } from './types';
+export { InvalidWordsError, assertValidWords, captionTiming, splitWhitespaceTokens, wordsAreProportional } from './words';
+export type { CaptionTiming } from './words';

package/src/speech/captions/types.ts

@@ -0,0 +1,18 @@
+import type { TranscriptWord } from '../types';
+
+/** A word with an optional vendor flag: `alignment: 'proportional'` says the times are guesses spread by character count. */
+export type CaptionWord = TranscriptWord & { alignment?: string };
+
+/** A caption on the video timeline, seconds. */
+export interface Cue { start: number; end: number; text: string }
+
+export interface CueOptions {
+  /** Most words in one cue. Default 7. */
+  maxWords?: number;
+  /** Most characters in one cue. Default 42. */
+  maxChars?: number;
+  /** A silence longer than this (seconds) starts a new cue. Default 0.6. */
+  maxGap?: number;
+  /** A cue that must end early ends at its last clause end (comma, full stop, ...) when it holds one. Default off. */
+  clauseBreaks?: boolean;
+}

package/src/speech/captions/words.ts

@@ -0,0 +1,91 @@
+import { pyFloat, repr } from '../repr';
+import type { CaptionWord, Cue } from './types';
+
+/** A transcript that cannot be captioned: empty, or its times run backwards. Callers stop; nothing substitutes another. */
+export class InvalidWordsError extends Error {
+  constructor(message: string) { super(message); this.name = 'InvalidWordsError'; }
+}
+
+/** Throws `InvalidWordsError` unless there is at least one word and the words are in time order, each ending after it starts. */
+export function assertValidWords<T extends CaptionWord>(words: T[]): T[] {
+  if (!words.length) throw new InvalidWordsError('transcription returned no words');
+  let prev = -1.0;
+  words.forEach((w, i) => {
+    if (w.end < w.start) throw new InvalidWordsError(`word ${i} (${repr(w.text)}) ends before it starts (${pyFloat(w.start)} > ${pyFloat(w.end)})`);
+    if (w.start < prev) {
+      throw new InvalidWordsError(`words are not in time order: word ${i} (${repr(w.text)}) starts at ${pyFloat(w.start)}, before ${pyFloat(prev)}`);
+    }
+    prev = w.start;
+  });
+  return words;
+}
+
+const round3 = (n: number) => Math.round(n * 1000) / 1000;
+
+/** A token holding spaces becomes several words sharing its time evenly; an all-space token is dropped. */
+export function splitWhitespaceTokens(words: CaptionWord[]): CaptionWord[] {
+  const out: CaptionWord[] = [];
+  for (const w of words) {
+    const parts = w.text.split(/\s+/).filter(Boolean);
+    if (parts.length <= 1) {
+      if (parts.length) out.push({ ...w, text: parts[0] });
+      continue;
+    }
+    const step = (w.end - w.start) / parts.length;
+    parts.forEach((p, i) => out.push({ ...w, text: p, start: round3(w.start + i * step), end: round3(w.start + (i + 1) * step) }));
+  }
+  return out;
+}
+
+const median = (xs: number[]) => {
+  const s = [...xs].sort((a, b) => a - b);
+  const m = s.length >> 1;
+  return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
+};
+
+/**
+ * True when the words say so (`alignment: 'proportional'`) or, unflagged, when seconds-per-character barely changes from one
+ * word to the next (median relative step). Real vendor alignments step by 30% and more; characters spread evenly by 0%.
+ */
+export function wordsAreProportional(words: CaptionWord[], options: { stepMax?: number; minWords?: number } = {}): boolean {
+  const { stepMax = 0.02, minWords = 8 } = options;
+  const flags = new Set(words.map((w) => w.alignment).filter(Boolean));
+  if (flags.size) return flags.has('proportional');
+  const rate = words.filter((w) => w.end > w.start).map((w) => (w.end - w.start) / Math.max(1, [...w.text].length));
+  if (rate.length < minWords) return false;
+  const mean = rate.reduce((a, b) => a + b, 0) / rate.length;
+  if (mean <= 0) return false;
+  const steps = rate.slice(1).map((r, i) => Math.abs(r - rate[i]));
+  return steps.length > 0 && median(steps) / mean < stepMax;
+}
+
+export type CaptionTiming =
+  | { measured: false; pass: null; n: number; reason: string }
+  | { measured: true; n: number; max_abs_start_err_ms: number; median_abs_start_err_ms: number; max_abs_end_err_ms: number; pass: boolean };
+
+/**
+ * Each caption covers the next `text.split().length` words; compare its start and end with those words'. Proportional words
+ * make the error 0 by construction, which is not a pass: it is `measured: false`. Report keys match the Python review reports.
+ */
+export function captionTiming(captions: Cue[], words: CaptionWord[], options: { maxStartErrMs?: number } = {}): CaptionTiming {
+  const { maxStartErrMs = 250 } = options;
+  if (wordsAreProportional(words)) {
+    return { measured: false, pass: null, n: captions.length, reason: 'word times are proportional guesses (no forced alignment), so caption timing cannot be checked against them' };
+  }
+  let i = 0;
+  const startErr: number[] = [];
+  const endErr: number[] = [];
+  for (const c of captions) {
+    const k = Math.max(1, c.text.split(/\s+/).filter(Boolean).length);
+    const part = words.slice(i, i + k);
+    i += k;
+    if (!part.length) break;
+    startErr.push(Math.abs(c.start - part[0].start) * 1000);
+    endErr.push(Math.abs(c.end - part[part.length - 1].end) * 1000);
+  }
+  if (!startErr.length) return { measured: true, n: 0, max_abs_start_err_ms: 0, median_abs_start_err_ms: 0, max_abs_end_err_ms: 0, pass: false };
+  return {
+    measured: true, n: startErr.length, max_abs_start_err_ms: Math.max(...startErr), median_abs_start_err_ms: median(startErr),
+    max_abs_end_err_ms: Math.max(...endErr), pass: Math.max(...startErr) <= maxStartErrMs,
+  };
+}

package/src/speech/captions-cli.ts

@@ -0,0 +1,50 @@
+import { writeFile } from 'node:fs/promises';
+
+import {
+  InvalidWordsError, assertValidWords, cueFrameRange, cuesForBeat, holdGaps, toSrt, toVtt,
+  type CaptionWord,
+} from './captions';
+
+export interface CaptionsOutcome { exitCode: 0 | 1 | 2; output: unknown }
+
+const FORMATS = ['json', 'srt', 'vtt'];
+
+/** The Python side names a word's text `word`; either spelling is read. */
+const toWord = (w: Record<string, any>): CaptionWord => {
+  const { word, text, ...rest } = w;
+  return { ...rest, text: text ?? word } as CaptionWord;
+};
+
+/**
+ * `startsimpli-speech captions [--format json|srt|vtt] [--out FILE]` — caption cues from word timings or bare text:
+ *   {"words":[{"text"|"word","start","end"}] | "text" + "duration", "offset"?, "clauseBreaks"?, "maxWords"?, "maxChars"?,
+ *    "maxGap"?, "holdGapS"?, "fps"?}
+ * Output `{format, cues, content?, frames?, path?}`: `content` is the SRT / VTT text (also written to --out), `frames` the
+ * [first, end) frame of each cue when `fps` is given. Unusable words are `{error: {code: "INVALID_WORDS"}}`, exit 1.
+ */
+export async function runCaptions(body: Record<string, any>, flags: Record<string, string>): Promise<CaptionsOutcome> {
+  const usage = (message: string): CaptionsOutcome => ({ exitCode: 2, output: { error: { code: 'USAGE', message } } });
+  const format = flags.format ?? 'json';
+  if (!FORMATS.includes(format)) return usage(`--format must be ${FORMATS.join(', ')}, got "${format}"`);
+  const words: CaptionWord[] | undefined = Array.isArray(body.words) ? body.words.map(toWord) : undefined;
+  if (!words?.length && !(typeof body.text === 'string' && typeof body.duration === 'number')) {
+    return usage('captions needs "words" (timed), or "text" and "duration" in the request');
+  }
+  try {
+    if (words?.length) assertValidWords(words);
+    let cues = cuesForBeat(words, body.text, body.duration ?? 0, {
+      offset: body.offset, clauseBreaks: body.clauseBreaks, maxWords: body.maxWords, maxChars: body.maxChars, maxGap: body.maxGap,
+    });
+    if (typeof body.holdGapS === 'number') cues = holdGaps(cues, body.holdGapS);
+    const output: Record<string, unknown> = { format, cues };
+    if (typeof body.fps === 'number') output.frames = cues.map((c) => cueFrameRange(c, body.fps));
+    if (format !== 'json') {
+      output.content = format === 'srt' ? toSrt(cues) : toVtt(cues);
+      if (flags.out) { await writeFile(flags.out, output.content as string); output.path = flags.out; }
+    }
+    return { exitCode: 0, output };
+  } catch (error) {
+    if (error instanceof InvalidWordsError) return { exitCode: 1, output: { error: { code: 'INVALID_WORDS', message: error.message } } };
+    throw error;
+  }
+}

package/src/speech/cli.ts

@@ -0,0 +1,140 @@
+/**
+ * `startsimpli-speech` — the speech service for callers that are not TypeScript.
+ *
+ *   startsimpli-speech synthesize  --in request.json --out speech.mp3   > result.json
+ *   startsimpli-speech transcribe  --in request.json                    > result.json
+ *
+ * JSON in (a file with --in, else stdin), JSON out on stdout, audio as a file.
+ * Keys come from the environment only (ELEVENLABS_API_KEY, ELEVENLABS_VOICE_ID,
+ * OPENAI_API_KEY, SPEECH_PROVIDER). Nothing here knows who is calling.
+ *
+ * Failures print `{"error": {code, message, retryable, statusCode, provider}}`
+ * and exit 1; a malformed command line exits 2. Success exits 0.
+ */
+import { readFile, writeFile } from 'node:fs/promises';
+import { extname } from 'node:path';
+
+import { LLMProviderError } from '../errors';
+import { SpeechService } from './service';
+import { runCaptions } from './captions-cli';
+import { runVoices } from './voices-cli';
+import type { SynthesizeRequest, TranscribeRequest } from './types';
+
+export interface CliIO {
+  /** Reads all of stdin; only called when --in is absent. */
+  readStdin: () => Promise<string>;
+  /** Builds the service; a seam for tests. */
+  makeService?: () => SpeechService;
+}
+
+export interface CliOutcome {
+  exitCode: 0 | 1 | 2;
+  /** JSON document for stdout. */
+  output: unknown;
+}
+
+const MIME_BY_EXT: Record<string, string> = {
+  '.webm': 'audio/webm', '.ogg': 'audio/ogg', '.mp4': 'audio/mp4', '.m4a': 'audio/mp4', '.mp3': 'audio/mpeg',
+  '.wav': 'audio/wav', '.flac': 'audio/flac',
+};
+
+const FLAGS = new Set(['in', 'out', 'provider', 'model', 'voice', 'format', 'voice-settings', 'language', 'library', 'expiring', 'today']);
+
+const USAGE = 'usage: startsimpli-speech <synthesize|transcribe|voices resolve|captions> [--in request.json] [--out audio-file] '
+  + '[--provider NAME] [--model ID] [--voice ID] [--format FMT] [--voice-settings JSON] [--language CODE]';
+
+class UsageError extends Error {}
+
+function parseFlags(args: string[]): Record<string, string> {
+  const flags: Record<string, string> = {};
+  for (let i = 0; i < args.length; i += 1) {
+    const name = args[i].startsWith('--') ? args[i].slice(2) : '';
+    if (!FLAGS.has(name)) throw new UsageError(`unknown argument "${args[i]}"`);
+    const value = args[i + 1];
+    if (value === undefined) throw new UsageError(`--${name} needs a value`);
+    flags[name] = value;
+    i += 1;
+  }
+  return flags;
+}
+
+async function readRequest(flags: Record<string, string>, io: CliIO): Promise<Record<string, any>> {
+  const raw = flags.in ? await readFile(flags.in, 'utf8') : await io.readStdin();
+  try {
+    const parsed = JSON.parse(raw || '{}');
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('not an object');
+    return parsed;
+  } catch (error) {
+    throw new UsageError(`request is not a JSON object: ${(error as Error).message}`);
+  }
+}
+
+export async function runCli(argv: string[], io: CliIO): Promise<CliOutcome> {
+  try {
+    const [command, ...rest] = argv;
+    if (command === 'voices') {
+      const [sub, ...flagArgs] = rest;
+      const flags = parseFlags(flagArgs);
+      return runVoices(sub, sub === 'resolve' ? await readRequest(flags, io) : {}, flags);
+    }
+    if (command === 'captions') {
+      const flags = parseFlags(rest);
+      return runCaptions(await readRequest(flags, io), flags);
+    }
+    if (command !== 'synthesize' && command !== 'transcribe') throw new UsageError(USAGE);
+    const flags = parseFlags(rest);
+    const body = await readRequest(flags, io);
+    const service = io.makeService ? io.makeService() : new SpeechService(flags.provider ? { preferredProvider: flags.provider } : {});
+    return { exitCode: 0, output: command === 'synthesize' ? await synthesize(service, body, flags) : await transcribe(service, body, flags) };
+  } catch (error) {
+    if (error instanceof UsageError) return { exitCode: 2, output: { error: { code: 'USAGE', message: error.message } } };
+    if (error instanceof LLMProviderError) {
+      const { code, message, retryable, statusCode, provider } = error;
+      return { exitCode: 1, output: { error: { code, message, retryable, statusCode, provider } } };
+    }
+    return { exitCode: 1, output: { error: { code: 'UNKNOWN_ERROR', message: (error as Error)?.message ?? String(error), retryable: false } } };
+  }
+}
+
+async function synthesize(service: SpeechService, body: Record<string, any>, flags: Record<string, string>) {
+  const out: string | undefined = flags.out ?? body.out;
+  if (!out) throw new UsageError('synthesize needs --out <audio file> (or "out" in the request)');
+  const request: SynthesizeRequest = {
+    ...body,
+    ...(flags.model ? { model: flags.model } : {}),
+    ...(flags.voice ? { voiceId: flags.voice } : {}),
+    ...(flags.format ? { outputFormat: flags.format } : {}),
+    ...(flags.language ? { language: flags.language } : {}),
+    ...(flags['voice-settings'] ? { voiceSettings: parseSettings(flags['voice-settings']) } : {}),
+  } as SynthesizeRequest;
+  delete (request as any).out;
+  delete (request as any).provider;
+  const result = await service.synthesize(request);
+  await writeFile(out, result.audio);
+  const { audio, ...rest } = result;
+  return { ...rest, audioPath: out, bytes: audio.byteLength };
+}
+
+function parseSettings(text: string): Record<string, number | boolean> {
+  try {
+    const parsed = JSON.parse(text);
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) return parsed;
+  } catch { /* fall through */ }
+  throw new UsageError('--voice-settings must be a JSON object, e.g. \'{"stability":0.4}\'');
+}
+
+async function transcribe(service: SpeechService, body: Record<string, any>, flags: Record<string, string>) {
+  const audioPath: string | undefined = body.audioPath;
+  if (!audioPath) throw new UsageError('transcribe needs "audioPath" in the request');
+  const audio = new Uint8Array(await readFile(audioPath));
+  const { audioPath: _drop, provider: _p, ...rest } = body;
+  const request: TranscribeRequest = {
+    timestamps: 'word',
+    ...rest,
+    audio,
+    mimeType: body.mimeType ?? MIME_BY_EXT[extname(audioPath).toLowerCase()] ?? 'audio/mpeg',
+    ...(flags.model ? { model: flags.model } : {}),
+    ...(flags.language ? { language: flags.language } : {}),
+  };
+  return service.transcribe(request);
+}

package/src/speech/http.ts

@@ -1,6 +1,6 @@
 import { LLMProviderError } from '../errors';
 import type { LLMErrorCode } from '../errors';
-import type { TranscribeRequest } from './types';
+import type { SynthesizeRequest, TranscribeRequest } from './types';
 
 /** Container extension a vendor can recognise, from the recorder's MIME type. */
 const EXTENSIONS: Record<string, string> = {
@@ -34,8 +34,14 @@ export function assertAudio(request: Pick<TranscribeRequest, 'audio'>, provider:
   }
 }
 
+export function assertText(request: Pick<SynthesizeRequest, 'text'>, provider: string): void {
+  if (!request.text?.trim()) {
+    throw new LLMProviderError('There is no text to speak.', 'INVALID_REQUEST', false, undefined, provider);
+  }
+}
+
 /** One HTTP-status -> error-code mapping, so every vendor classifies failures the same way. */
-export function speechHttpError(status: number, body: string, provider: string): LLMProviderError {
+export function speechHttpError(status: number, body: string, provider: string, operation = 'transcription'): LLMProviderError {
   const code: LLMErrorCode =
     status === 401 || status === 403 ? 'AUTHENTICATION_ERROR'
     : status === 429 ? 'RATE_LIMITED'
@@ -45,7 +51,7 @@ export function speechHttpError(status: number, body: string, provider: string):
     : 'UNKNOWN_ERROR';
   const retryable = code === 'RATE_LIMITED' || code === 'SERVICE_UNAVAILABLE' || code === 'TIMEOUT';
   return new LLMProviderError(
-    `${provider} transcription failed (${status}): ${body.slice(0, 300)}`,
+    `${provider} ${operation} failed (${status}): ${body.slice(0, 300)}`,
     code, retryable, status, provider,
   );
 }
@@ -57,10 +63,11 @@ export async function speechFetch(
   init: RequestInit,
   timeoutMs = 240_000,
   fetchImpl: typeof fetch = fetch,
+  operation = 'transcription',
 ): Promise<Response> {
   try {
     const response = await fetchImpl(url, { ...init, signal: AbortSignal.timeout(timeoutMs) });
-    if (!response.ok) throw speechHttpError(response.status, await response.text().catch(() => ''), provider);
+    if (!response.ok) throw speechHttpError(response.status, await response.text().catch(() => ''), provider, operation);
     return response;
   } catch (error) {
     if (error instanceof LLMProviderError) throw error;

package/src/speech/index.ts

@@ -1,18 +1,24 @@
 /**
- * `@startsimpli/llm/speech` — pluggable speech-to-text.
+ * `@startsimpli/llm/speech` — pluggable speech-to-text and text-to-speech.
  *
  *   const speech = new SpeechService();            // SPEECH_PROVIDER, else the cheapest vendor with a key
  *   const { text } = await speech.transcribe({ audio, mimeType: 'audio/webm' });
  *
+ *   const { audio, words } = await speech.synthesize({ text: 'Hello there.' });
+ *
  * A new vendor: implement `ISpeechProvider`, then `registerSpeechProvider(name, factory)`.
  */
 export { SpeechService, registerSpeechProvider, speechProviders } from './service';
 export type { ISpeechProvider } from './interface';
 export type {
-  SpeechServiceConfig, SpeechUsage, TranscribeRequest, TranscriptResult, TranscriptWord,
+  AlignedCharacter, SpeechServiceConfig, SpeechStyle, SpeechUsage, SynthesizeRequest, SynthesizeResult,
+  TranscribeRequest, TranscriptResult, TranscriptWord,
 } from './types';
 export { ElevenLabsSpeechProvider, createElevenLabsSpeechProvider } from './providers/elevenlabs';
 export { OpenAISpeechProvider, createOpenAISpeechProvider } from './providers/openai';
 export type { OpenAISpeechOptions } from './providers/openai';
 export { MockSpeechProvider, setMockSpeechBehavior, resetMockSpeechBehavior } from './providers/mock';
 export { audioExtension, speechHttpError } from './http';
+export { wordsFromCharacters } from './alignment';
+export * from './voices';
+export * from './captions';