@startsimpli/llm 0.4.29 → 0.4.30

package/README.md

@@ -181,9 +181,9 @@ Per CLAUDE.md **rule 9**, LLM client wiring never belongs in app `src/`. If you
 
 ## Speech (`@startsimpli/llm/speech`)
 
-Pluggable speech-to-text, same provider pattern as the text service. **It picks the
-cheapest vendor that has a key** — each provider states its list price — and falls
-through to the next cheapest on failure.
+Pluggable speech-to-text and text-to-speech, same provider pattern as the text service.
+**Each direction picks the cheapest vendor that has a key** — each provider states its
+list price — and falls through to the next cheapest on failure.
 
 ```ts
 import { SpeechService } from '@startsimpli/llm/speech';
@@ -196,11 +196,39 @@ const { text, words } = await speech.transcribe({
 
 | Env | Provider | List price |
 | --- | --- | --- |
-| `OPENAI_API_KEY` | OpenAI `gpt-4o-mini-transcribe` (default; `gpt-4o-transcribe` / `whisper-1` cost 2x) | $0.18 / hour |
-| `ELEVENLABS_API_KEY` | ElevenLabs Scribe (keyterm hints are a billed add-on, so off unless `sendKeyterms`) | $0.22 / hour |
+| `OPENAI_API_KEY` | OpenAI TTS (`gpt-4o-mini-tts`, no alignment) and `gpt-4o-mini-transcribe` (default; `gpt-4o-transcribe` / `whisper-1` cost 2x) | $0.18 / hour |
+| `ELEVENLABS_API_KEY` | ElevenLabs Scribe + text-to-speech with alignment (`ELEVENLABS_VOICE_ID` = default voice); Scribe (keyterm hints are a billed add-on, so off unless `sendKeyterms`) | $0.22 / hour |
 | `SPEECH_PROVIDER=mock` | deterministic, for tests | — |
 | `SPEECH_PROVIDER` / `SPEECH_LANGUAGE` | force a vendor / pin the language (e.g. `en`) so short clips don't mis-detect | — |
 
+**Text to speech**
+
+```ts
+const { audio, mimeType, words, characters, durationSec, usage } = await speech.synthesize({
+  text: 'Plan mode changes that.',
+  voiceId, model: 'eleven_v3', outputFormat: 'mp3_44100_128',   // voiceId defaults to ELEVENLABS_VOICE_ID
+  style: { tags: ['excited'], speed: 1.05, stability: 0.4 },     // tags only on models that read them
+});
+// usage = { characters, costUsd } at the model's list rate
+```
+
+`words` come from the vendor's character alignment (absent when it gives none, as OpenAI's doesn't).
+`[tag]` audio markup is not a word: it is dropped from `words` with the timing offsets kept; `characters`
+is the raw alignment and `keepTags: true` keeps tags in `words`. `voiceSettings` passes raw vendor
+settings and wins over `style`.
+
+**CLI for non-TS callers** — `startsimpli-speech` (JSON in via `--in` or stdin, JSON on stdout, audio to a file;
+keys from env only; exit 0 ok, 1 provider error as `{"error":{code,retryable,...}}`, 2 bad command line):
+
+```bash
+echo '{"text":"[excited] Hello.","model":"eleven_v3","style":{"speed":1.0}}' \
+  | startsimpli-speech synthesize --out hello.mp3 [--voice ID --model ID --format pcm_22050 --voice-settings '{"stability":0.3}']
+# -> {"mimeType":"audio/mpeg","audioPath":"hello.mp3","bytes":...,"words":[{"text":"Hello.","start":..,"end":..}],"characters":[...],"usage":{"characters":..,"costUsd":..},...}
+echo '{"audioPath":"hello.mp3"}' | startsimpli-speech transcribe   # -> {"text":..,"words":[..],"usage":{..}}
+```
+
+It runs the tsup bundle when built (`pnpm --filter @startsimpli/llm build`), else the source via `tsx`.
+
 Retryable errors back off and retry; a failure that survives falls through to the next
 vendor (`fallback: false` to pin one). Bad audio (`INVALID_REQUEST`) never falls through.
 
@@ -213,6 +241,7 @@ registerSpeechProvider('mine', () => (process.env.MINE_KEY ? new MyProvider(proc
 ```
 
 `registerLLMProvider(name, factory)` does the same for text. Both sit on `ProviderRegistry`,
+<<<<<<< HEAD
 so a new modality (TTS, embeddings) reuses it rather than hard-coding a provider list.
 
 ## Links
@@ -220,3 +249,6 @@ so a new modality (TTS, embeddings) reuses it rather than hard-coding a provider
 - Source: https://github.com/qosha1/start-simpli/tree/main/packages/llm
 - Homepage: https://startsimpli.com
 - License: MIT, see [LICENSE](./LICENSE)
+=======
+so a new modality (embeddings) reuses it rather than hard-coding a provider list.
+>>>>>>> eda91372 (speech: synthesize() with alignment, ElevenLabs TTS, tags and style, startsimpli-speech CLI)

package/bin/startsimpli-speech.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// Launcher for the speech CLI. Packages here publish TypeScript source, so this
+// runs the tsup bundle (`pnpm build`) when it exists, else the source via tsx.
+const { existsSync } = require('node:fs');
+const { join } = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const root = join(__dirname, '..');
+const bundle = join(root, 'dist', 'speech', 'bin.js');
+const localTsx = join(root, 'node_modules', '.bin', 'tsx');
+const args = process.argv.slice(2);
+if (existsSync(bundle)) {
+  process.argv.splice(1, 1, bundle);
+  require(bundle);
+} else {
+  const tsx = spawnSync(existsSync(localTsx) ? localTsx : 'tsx', [join(root, 'src', 'speech', 'bin.ts'), ...args], { stdio: 'inherit' });
+  if (tsx.error) {
+    process.stdout.write(JSON.stringify({ error: { code: 'USAGE', message: 'startsimpli-speech needs a build (pnpm --filter @startsimpli/llm build) or tsx on PATH' } }) + '\n');
+    process.exit(2);
+  }
+  process.exit(tsx.status ?? 1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/llm",
-  "version": "0.4.29",
+  "version": "0.4.30",
   "description": "Generic LLM service infrastructure — provider abstraction, retry logic, JSON extraction",
   "license": "MIT",
   "homepage": "https://startsimpli.com",
@@ -21,6 +21,7 @@
   },
   "files": [
     "src",
+    "bin",
     "README.md",
     "LICENSE"
   ],
@@ -29,7 +30,7 @@
   },
   "dependencies": {
     "zod": "^4.3.6",
-    "@startsimpli/i18n": "^0.1.4"
+    "@startsimpli/i18n": "^0.1.3"
   },
   "devDependencies": {
     "@types/node": "^20.19.39",
@@ -37,6 +38,9 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.5"
   },
+  "bin": {
+    "startsimpli-speech": "./bin/startsimpli-speech.js"
+  },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",

package/src/__tests__/fixtures/eleven-v3-tagged-alignment.json

@@ -0,0 +1 @@
+{"text": "[excited] Most people use Claude Code li", "model": "eleven_v3", "alignment": {"characters": ["[", "e", "x", "c", "i", "t", "e", "d", "]", " ", "M", "o", "s", "t", " ", "p", "e", "o", "p", "l", "e", " ", "u", "s", "e", " ", "C", "l", "a", "u", "d", "e", " ", "C", "o", "d", "e", " ", "l", "i"], "character_start_times_seconds": [0.0, 0.048, 0.064, 0.08, 0.096, 0.108, 0.12, 0.132, 0.144, 0.192, 0.202, 0.211, 0.221, 0.23, 0.24, 0.297, 0.354, 0.411, 0.469, 0.526, 0.583, 0.64, 0.72, 0.8, 0.88, 0.96, 1.017, 1.074, 1.131, 1.189, 1.246, 1.303, 1.36, 1.44, 1.52, 1.6, 1.68, 1.76, 1.84, 1.92], "character_end_times_seconds": [0.048, 0.064, 0.08, 0.096, 0.108, 0.12, 0.132, 0.144, 0.192, 0.202, 0.211, 0.221, 0.23, 0.24, 0.297, 0.354, 0.411, 0.469, 0.526, 0.583, 0.64, 0.72, 0.8, 0.88, 0.96, 1.017, 1.074, 1.131, 1.189, 1.246, 1.303, 1.36, 1.44, 1.52, 1.6, 1.68, 1.76, 1.84, 1.92, 2.0]}}

package/src/__tests__/speech-cli.test.ts

@@ -0,0 +1,67 @@
+import { mkdtemp, readFile, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { resetMockSpeechBehavior, setMockSpeechBehavior } from '../speech';
+import { runCli } from '../speech/cli';
+
+afterEach(() => { resetMockSpeechBehavior(); vi.unstubAllEnvs(); });
+
+const run = (argv: string[], stdin = '{}') => {
+  vi.stubEnv('SPEECH_PROVIDER', 'mock');
+  return runCli(argv, { readStdin: async () => stdin });
+};
+const tmp = () => mkdtemp(join(tmpdir(), 'speech-cli-'));
+
+describe('startsimpli-speech', () => {
+  it('synthesize: JSON in on stdin, audio to --out, JSON result on stdout', async () => {
+    const dir = await tmp();
+    const out = join(dir, 'a.mp3');
+    const res = await run(['synthesize', '--out', out], JSON.stringify({ text: '[calm] hi you', voiceId: 'v' }));
+    expect(res.exitCode).toBe(0);
+    expect(res.output).toMatchObject({ audioPath: out, mimeType: 'audio/mpeg', provider: 'mock', usage: { characters: 13 } });
+    expect((res.output as any).words.map((w: any) => w.text)).toEqual(['hi', 'you']);
+    expect((res.output as any).audio).toBeUndefined();
+    expect((await readFile(out)).byteLength).toBe((res.output as any).bytes);
+  });
+
+  it('synthesize: --in file and flags override the request', async () => {
+    const dir = await tmp();
+    const input = join(dir, 'req.json');
+    await writeFile(input, JSON.stringify({ text: 'hi', voiceId: 'from-file' }));
+    const res = await run(['synthesize', '--in', input, '--out', join(dir, 'o.mp3'), '--voice', 'from-flag', '--voice-settings', '{"stability":0.2}']);
+    expect(res.exitCode).toBe(0);
+    expect((res.output as any).voiceId).toBe('from-flag');
+  });
+
+  it('transcribe: reads audioPath, infers the mime type, returns the transcript', async () => {
+    const dir = await tmp();
+    const audio = join(dir, 'n.m4a');
+    await writeFile(audio, new Uint8Array([1, 2, 3]));
+    setMockSpeechBehavior({ text: 'hello' });
+    const res = await run(['transcribe'], JSON.stringify({ audioPath: audio }));
+    expect(res).toMatchObject({ exitCode: 0, output: { text: 'hello', provider: 'mock' } });
+  });
+
+  it('a provider failure is JSON on stdout with exit 1 and the typed code', async () => {
+    setMockSpeechBehavior({ authError: true });
+    const res = await run(['synthesize', '--out', join(await tmp(), 'x.mp3')], '{"text":"hi"}');
+    expect(res).toMatchObject({ exitCode: 1, output: { error: { code: 'AUTHENTICATION_ERROR', retryable: false, statusCode: 401 } } });
+  });
+
+  it.each([
+    [[], '{}', /usage/],
+    [['sing'], '{}', /usage/],
+    [['synthesize'], '{"text":"hi"}', /--out/],
+    [['synthesize', '--out'], '{}', /needs a value/],
+    [['synthesize', '--bogus', 'x'], '{}', /unknown argument/],
+    [['synthesize', '--out', 'x'], 'not json', /JSON object/],
+    [['transcribe'], '{}', /audioPath/],
+    [['synthesize', '--out', 'x', '--voice-settings', '[1]'], '{"text":"hi"}', /voice-settings/],
+  ])('malformed command %j exits 2 with a message', async (argv, stdin, message) => {
+    const res = await run(argv as string[], stdin);
+    expect(res.exitCode).toBe(2);
+    expect((res.output as any).error.message).toMatch(message);
+  });
+});

package/src/__tests__/speech-synthesize.test.ts

@@ -0,0 +1,277 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { LLMProviderError } from '../errors';
+import {
+  ElevenLabsSpeechProvider, MockSpeechProvider, OpenAISpeechProvider, SpeechService,
+  createElevenLabsSpeechProvider, resetMockSpeechBehavior, setMockSpeechBehavior, wordsFromCharacters,
+} from '../speech';
+import type { ISpeechProvider, SynthesizeRequest } from '../speech';
+
+afterEach(() => { resetMockSpeechBehavior(); vi.unstubAllEnvs(); });
+
+const req: SynthesizeRequest = { text: 'hi you', voiceId: 'v1' };
+const AUDIO = new Uint8Array([9, 8, 7, 6]);
+const b64 = Buffer.from(AUDIO).toString('base64');
+
+/** ElevenLabs with-timestamps body for `hi you`. */
+const elevenBody = (text = 'hi you') => {
+  const chars = [...text];
+  return {
+    audio_base64: b64,
+    alignment: {
+      characters: chars,
+      character_start_times_seconds: chars.map((_, i) => i * 0.1),
+      character_end_times_seconds: chars.map((_, i) => (i + 1) * 0.1),
+    },
+  };
+};
+
+const respond = (body: unknown | Uint8Array, status = 200) =>
+  vi.fn(async (_u: unknown, _i?: RequestInit) =>
+    new Response(body instanceof Uint8Array ? body : typeof body === 'string' ? body : JSON.stringify(body), { status }));
+
+const wires: Array<{ name: string; make: (f: typeof fetch) => ISpeechProvider; ok: unknown; aligned: boolean; mime: string }> = [
+  { name: 'elevenlabs', make: (fetchImpl) => new ElevenLabsSpeechProvider({ apiKey: 'k', fetchImpl }), ok: elevenBody(), aligned: true, mime: 'audio/mpeg' },
+  { name: 'openai', make: (fetchImpl) => new OpenAISpeechProvider({ apiKey: 'k', fetchImpl }), ok: AUDIO, aligned: false, mime: 'audio/mpeg' },
+];
+
+describe.each(wires)('synthesize contract: $name', ({ name, make, ok, aligned, mime }) => {
+  it('advertises the capability', () => {
+    expect(make(fetch).capabilities.synthesize).toBe(true);
+  });
+
+  it('returns audio bytes, mime, provider, model and character usage', async () => {
+    const out = await make(respond(ok) as never).synthesize!(req);
+    expect([...out.audio]).toEqual([...AUDIO]);
+    expect(out.mimeType).toBe(mime);
+    expect(out).toMatchObject({ provider: name });
+    expect(out.model).toBeTruthy();
+    expect(out.usage.characters).toBe(req.text.length);
+  });
+
+  it(aligned ? 'returns ordered, non-overlapping word timings' : 'has no alignment (the vendor gives none)', async () => {
+    const out = await make(respond(ok) as never).synthesize!(req);
+    if (!aligned) { expect(out.words).toBeUndefined(); return; }
+    expect(out.words?.map((w) => w.text)).toEqual(['hi', 'you']);
+    const [a, b] = out.words!;
+    expect(a.end).toBeLessThanOrEqual(b.start);
+    expect(out.durationSec).toBeGreaterThan(0);
+  });
+
+  it.each([[401, 'AUTHENTICATION_ERROR', false], [429, 'RATE_LIMITED', true], [503, 'SERVICE_UNAVAILABLE', true], [400, 'INVALID_REQUEST', false]])(
+    'classifies HTTP %i as %s (retryable=%s)', async (status, code, retryable) => {
+      const err = await make(respond('boom', status as number) as never).synthesize!(req).catch((e) => e);
+      expect(err).toBeInstanceOf(LLMProviderError);
+      expect(err).toMatchObject({ code, retryable, provider: name });
+      expect(err.message).not.toMatch(/transcription/);
+    });
+
+  it('refuses empty text without calling the vendor', async () => {
+    const f = respond(ok);
+    await expect(make(f as never).synthesize!({ ...req, text: '   ' })).rejects.toMatchObject({ code: 'INVALID_REQUEST' });
+    expect(f).not.toHaveBeenCalled();
+  });
+
+  it('turns a network failure into a retryable error', async () => {
+    const f = vi.fn(async () => { throw new TypeError('fetch failed'); });
+    await expect(make(f as never).synthesize!(req)).rejects.toMatchObject({ retryable: true, code: 'SERVICE_UNAVAILABLE' });
+  });
+});
+
+describe('elevenlabs synthesize specifics', () => {
+  const run = async (patch: Partial<SynthesizeRequest> = {}, body: unknown = elevenBody()) => {
+    const f = respond(body);
+    const out = await new ElevenLabsSpeechProvider({ apiKey: 'sekret', fetchImpl: f as never }).synthesize({ ...req, ...patch });
+    const [url, init] = f.mock.calls[0] as unknown as [string, RequestInit];
+    return { out, url, init, sent: JSON.parse(init.body as string) };
+  };
+
+  it('posts to with-timestamps with the key header and voice in the path', async () => {
+    const { url, init } = await run();
+    expect(url).toBe('https://api.elevenlabs.io/v1/text-to-speech/v1/with-timestamps?output_format=mp3_44100_128');
+    expect((init.headers as Record<string, string>)['xi-api-key']).toBe('sekret');
+  });
+
+  it('takes the voice from the call, else ELEVENLABS_VOICE_ID, else refuses', async () => {
+    const p = createElevenLabsSpeechProvider({ ELEVENLABS_API_KEY: 'k', ELEVENLABS_VOICE_ID: 'envvoice' })!;
+    const f = respond(elevenBody());
+    (p as any).fetchImpl = f;
+    await p.synthesize({ text: 'hi you' });
+    expect((f.mock.calls[0] as unknown as [string])[0]).toContain('/text-to-speech/envvoice/with-timestamps');
+    const bare = new ElevenLabsSpeechProvider({ apiKey: 'k', fetchImpl: respond(elevenBody()) as never });
+    await expect(bare.synthesize({ text: 'hi' })).rejects.toMatchObject({ code: 'INVALID_REQUEST' });
+  });
+
+  it('maps outputFormat to the mime type', async () => {
+    expect((await run({ outputFormat: 'pcm_22050' })).out.mimeType).toBe('audio/pcm');
+    expect((await run({ outputFormat: 'pcm_22050' })).url).toContain('output_format=pcm_22050');
+  });
+
+  it('passes model, language and voiceSettings through', async () => {
+    const { sent } = await run({ model: 'eleven_v3', language: 'en', voiceSettings: { stability: 0.5, similarity_boost: 0.7 } });
+    expect(sent).toMatchObject({ text: 'hi you', model_id: 'eleven_v3', language_code: 'en', voice_settings: { stability: 0.5, similarity_boost: 0.7 } });
+  });
+
+  it('typed style speed/stability become voice_settings; explicit voiceSettings win', async () => {
+    const { sent } = await run({ style: { speed: 1.1, stability: 0.3 }, voiceSettings: { stability: 0.9 } });
+    expect(sent.voice_settings).toEqual({ speed: 1.1, stability: 0.9 });
+  });
+
+  it('style tags are prefixed on models that read them', async () => {
+    const { sent, out } = await run({ model: 'eleven_v3', style: { tags: ['excited', 'whispers'] } },
+      elevenBody('[excited][whispers] hi you'));
+    expect(sent.text).toBe('[excited][whispers] hi you');
+    expect(out.usage.characters).toBe('[excited][whispers] hi you'.length);
+  });
+
+  it('style tags are dropped on models that would speak them aloud', async () => {
+    const { sent } = await run({ model: 'eleven_multilingual_v2', style: { tags: ['excited'] } });
+    expect(sent.text).toBe('hi you');
+  });
+
+  it('audio tags are not words: stripped from the words, offsets kept, characters untouched', async () => {
+    const text = '[excited] hi you';
+    const { out } = await run({ model: 'eleven_v3', text }, elevenBody(text));
+    expect(out.words?.map((w) => w.text)).toEqual(['hi', 'you']);
+    expect(out.words![0].start).toBeCloseTo(1.0);      // "[excited] " is 10 chars at 0.1s
+    expect(out.characters?.length).toBe(text.length);
+  });
+
+  it('keepTags:true leaves tags in the words', async () => {
+    const text = '[excited] hi you';
+    const { out } = await run({ model: 'eleven_v3', text, keepTags: true }, elevenBody(text));
+    expect(out.words?.map((w) => w.text)).toEqual(['[excited]', 'hi', 'you']);
+  });
+
+  it('cost follows the model rate table (USD per 1k characters)', async () => {
+    const text = 'x'.repeat(1000);
+    expect((await run({ model: 'eleven_v3', text }, elevenBody(text))).out.usage.costUsd).toBeCloseTo(0.08);
+    expect((await run({ model: 'eleven_multilingual_v2', text }, elevenBody(text))).out.usage.costUsd).toBeCloseTo(0.08);
+    expect((await run({ model: 'eleven_flash_v2_5', text }, elevenBody(text))).out.usage.costUsd).toBeCloseTo(0.04);
+    expect((await run({ model: 'some_future_model', text }, elevenBody(text))).out.usage.costUsd).toBeCloseTo(0.10);
+  });
+
+  it('a response with no alignment still returns audio', async () => {
+    const { out } = await run({}, { audio_base64: b64 });
+    expect(out.words).toBeUndefined();
+    expect([...out.audio]).toEqual([...AUDIO]);
+  });
+
+  it('openai: posts the voice and format to /v1/audio/speech', async () => {
+    const f = respond(AUDIO);
+    await new OpenAISpeechProvider({ apiKey: 'k', fetchImpl: f as never }).synthesize({ text: 'hi' });
+    const [url, init] = f.mock.calls[0] as unknown as [string, RequestInit];
+    expect(url).toBe('https://api.openai.com/v1/audio/speech');
+    expect(JSON.parse(init.body as string)).toMatchObject({ input: 'hi', response_format: 'mp3' });
+  });
+});
+
+describe('wordsFromCharacters', () => {
+  it('splits on whitespace and skips bracket tags by default', () => {
+    const chars = [...'[calm] a b'].map((text, i) => ({ text, start: i, end: i + 1 }));
+    expect(wordsFromCharacters(chars).map((w) => [w.text, w.start])).toEqual([['a', 7], ['b', 9]]);
+    expect(wordsFromCharacters(chars, { keepTags: true }).map((w) => w.text)).toEqual(['[calm]', 'a', 'b']);
+  });
+  it('leaves an unclosed bracket as ordinary text', () => {
+    const chars = [...'a [b'].map((text, i) => ({ text, start: i, end: i + 1 }));
+    expect(wordsFromCharacters(chars).map((w) => w.text)).toEqual(['a', '[b']);
+  });
+});
+
+describe('real v3 alignment fixture', () => {
+  it('drops the [excited] tag from the words but keeps the true offsets', () => {
+    const fx = JSON.parse(readFileSync(join(__dirname, 'fixtures', 'eleven-v3-tagged-alignment.json'), 'utf8'));
+    const chars = fx.alignment.characters.map((text: string, i: number) => ({
+      text, start: fx.alignment.character_start_times_seconds[i], end: fx.alignment.character_end_times_seconds[i] }));
+    const words = wordsFromCharacters(chars);
+    expect(words[0].text).toBe('Most');
+    expect(words[0].start).toBeCloseTo(0.202, 2);   // the tag took the first ~0.2s
+    expect(wordsFromCharacters(chars, { keepTags: true })[0].text).toBe('[excited]');
+  });
+});
+
+describe('mock synthesize', () => {
+  it('is deterministic with aligned words and usage', async () => {
+    const out = await new MockSpeechProvider().synthesize(req);
+    expect(out.audio.byteLength).toBeGreaterThan(0);
+    expect(out.words?.map((w) => w.text)).toEqual(['hi', 'you']);
+    expect(out.usage.characters).toBe(6);
+    expect(out.provider).toBe('mock');
+  });
+  it('refuses empty text and simulates auth and outage failures', async () => {
+    const mock = new MockSpeechProvider();
+    await expect(mock.synthesize({ text: '' })).rejects.toMatchObject({ code: 'INVALID_REQUEST' });
+    setMockSpeechBehavior({ authError: true });
+    await expect(mock.synthesize(req)).rejects.toMatchObject({ code: 'AUTHENTICATION_ERROR', retryable: false });
+    setMockSpeechBehavior({ failTimes: 1 });
+    await expect(mock.synthesize(req)).rejects.toMatchObject({ code: 'SERVICE_UNAVAILABLE', retryable: true });
+  });
+});
+
+describe('SpeechService.synthesize', () => {
+  const fake = (name: string, impl: () => Promise<any>, synth = true): ISpeechProvider => ({
+    name, capabilities: { transcribe: true, synthesize: synth }, defaultModel: 'm', isAvailable: () => true,
+    transcribe: vi.fn() as never, synthesize: vi.fn(impl) as never,
+  });
+  const withProviders = (service: SpeechService, ...ps: ISpeechProvider[]) => {
+    (service as any).providers = new Map(ps.map((p) => [p.name, p]));
+    return service;
+  };
+  const ok = (provider: string) => async () => ({ audio: AUDIO, mimeType: 'audio/mpeg', model: 'm', provider, usage: { characters: 6 } });
+  const outage = async () => { throw new LLMProviderError('down', 'SERVICE_UNAVAILABLE', true, 503); };
+
+  it('only considers providers that can synthesize', async () => {
+    const s = withProviders(new SpeechService(), fake('elevenlabs', ok('elevenlabs'), false), fake('openai', ok('openai')));
+    expect((await s.synthesize(req)).provider).toBe('openai');
+    expect(s.getAvailableProviders('synthesize')).toEqual(['openai']);
+  });
+  it('picks the cheapest vendor that states a price, then falls back to the dearer one', async () => {
+    const priced = (name: string, price: number, impl: () => Promise<any>) => ({ ...fake(name, impl), costPer1kCharsUsd: () => price });
+    const s = withProviders(new SpeechService({ retryDelayMs: 1, maxRetries: 0 }),
+      priced('elevenlabs', 0.08, ok('elevenlabs')), priced('openai', 0.015, outage));
+    expect((await s.synthesize(req)).provider).toBe('elevenlabs'); // openai (cheapest) failed, fell through
+    const cheap = withProviders(new SpeechService(), priced('elevenlabs', 0.08, ok('elevenlabs')), priced('openai', 0.015, ok('openai')));
+    expect((await cheap.synthesize(req)).provider).toBe('openai');
+    const pinned = withProviders(new SpeechService({ preferredProvider: 'elevenlabs' }), priced('elevenlabs', 0.08, ok('elevenlabs')), priced('openai', 0.015, ok('openai')));
+    expect((await pinned.synthesize(req)).provider).toBe('elevenlabs');
+  });
+  it('a provider without a key is unavailable, not an error', () => {
+    const none = new OpenAISpeechProvider({ apiKey: '' });
+    expect(none.isAvailable()).toBe(false);
+    expect(withProviders(new SpeechService(), none).getAvailableProviders('synthesize')).toEqual([]);
+  });
+  it('retries a retryable failure, then falls through', async () => {
+    const primary = fake('elevenlabs', outage);
+    const s = withProviders(new SpeechService({ retryDelayMs: 1, maxRetries: 2 }), primary, fake('openai', ok('openai')));
+    expect((await s.synthesize(req)).provider).toBe('openai');
+    expect(primary.synthesize).toHaveBeenCalledTimes(3);
+  });
+  it('never retries an auth error', async () => {
+    const bad = fake('elevenlabs', async () => { throw new LLMProviderError('no', 'AUTHENTICATION_ERROR', false, 401); });
+    const s = withProviders(new SpeechService({ retryDelayMs: 1 }), bad, fake('openai', ok('openai')));
+    await s.synthesize(req);
+    expect(bad.synthesize).toHaveBeenCalledTimes(1);
+  });
+  it('does not fall through on the caller\'s bad input', async () => {
+    const bad = fake('elevenlabs', async () => { throw new LLMProviderError('bad', 'INVALID_REQUEST', false, 400); });
+    const next = fake('openai', ok('openai'));
+    await expect(withProviders(new SpeechService(), bad, next).synthesize(req)).rejects.toMatchObject({ code: 'INVALID_REQUEST' });
+    expect(next.synthesize).not.toHaveBeenCalled();
+  });
+  it('says what to set when nothing can synthesize', async () => {
+    await expect(withProviders(new SpeechService()).synthesize(req)).rejects.toThrow(/ELEVENLABS_API_KEY/);
+  });
+  it('SPEECH_PROVIDER=mock synthesizes, and survives a cleared outage', async () => {
+    vi.stubEnv('SPEECH_PROVIDER', 'mock');
+    setMockSpeechBehavior({ failTimes: 2 });
+    const out = await new SpeechService({ retryDelayMs: 1 }).synthesize(req);
+    expect(out.provider).toBe('mock');
+  });
+  it('transcribe is untouched by synthesize-only providers', async () => {
+    const synthOnly = { ...fake('elevenlabs', ok('elevenlabs')), capabilities: { transcribe: false, synthesize: true } } as ISpeechProvider;
+    const s = withProviders(new SpeechService(), synthOnly);
+    await expect(s.transcribe({ audio: AUDIO, mimeType: 'audio/mp4' })).rejects.toThrow(/No speech providers/);
+  });
+});

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/cli.ts

@@ -0,0 +1,129 @@
+/**
+ * `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 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']);
+
+const USAGE = 'usage: startsimpli-speech <synthesize|transcribe> [--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 !== '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,22 @@
 /**
- * `@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';

package/src/speech/interface.ts

@@ -1,5 +1,5 @@
 import type { Selectable } from '../providers/registry';
-import type { TranscribeRequest, TranscriptResult } from './types';
+import type { SynthesizeRequest, SynthesizeResult, TranscribeRequest, TranscriptResult } from './types';
 
 /**
  * What a speech vendor implements. A provider supports whichever directions its
@@ -8,12 +8,11 @@ import type { TranscribeRequest, TranscriptResult } from './types';
  *
  * ADDING A VENDOR: implement this, then
  * `registerSpeechProvider('name', () => new Mine(process.env.MINE_KEY) )` — no
- * edit to `SpeechService`. Text-to-speech joins here as an optional
- * `synthesize` alongside `transcribe` (bd startsim-2lnyg); nothing in the
- * service needs to change for it either.
+ * edit to `SpeechService`. Each direction is an optional method gated by
+ * `capabilities`.
  */
 export interface ISpeechProvider extends Selectable {
-  readonly capabilities: { transcribe: boolean };
+  readonly capabilities: { transcribe: boolean; synthesize?: boolean };
   readonly defaultModel: string;
   /**
    * List price per audio minute, USD, for `model` (default model when omitted).
@@ -21,5 +20,8 @@ export interface ISpeechProvider extends Selectable {
    * that does not state a price is tried after every provider that does.
    */
   costPerMinuteUsd?(model?: string): number;
+  /** List price per 1,000 synthesized characters, USD. `synthesize` prefers the cheapest. */
+  costPer1kCharsUsd?(model?: string): number;
   transcribe?(request: TranscribeRequest): Promise<TranscriptResult>;
+  synthesize?(request: SynthesizeRequest): Promise<SynthesizeResult>;
 }

package/src/speech/providers/elevenlabs-models.ts

@@ -0,0 +1,34 @@
+/**
+ * What ElevenLabs' models can do and cost. Data, not logic: a new model is a
+ * row here. USD per 1,000 characters, elevenlabs.io/pricing/api.
+ */
+const RATE_PER_1K_CHARS: Record<string, number> = {
+  eleven_v3: 0.08,
+  eleven_multilingual_v2: 0.08,
+  eleven_flash_v2_5: 0.04,
+  eleven_v4_turbo: 0.04,
+};
+/** Rate for a model not in the table: the top published tier, so spend is never under-reported. */
+const DEFAULT_RATE_PER_1K_CHARS = 0.10;
+
+/** Models that read `[excited]`-style audio tags; the rest would speak them aloud. */
+const AUDIO_TAG_MODELS = new Set(['eleven_v3', 'eleven_v4', 'eleven_v4_turbo', 'eleven_v3_conversational']);
+
+export const DEFAULT_TTS_MODEL = 'eleven_multilingual_v2';
+
+export function supportsAudioTags(model: string): boolean {
+  return AUDIO_TAG_MODELS.has(model);
+}
+
+export function costUsd(model: string, characters: number): number {
+  return ((RATE_PER_1K_CHARS[model] ?? DEFAULT_RATE_PER_1K_CHARS) * characters) / 1000;
+}
+
+export const DEFAULT_OUTPUT_FORMAT = 'mp3_44100_128';
+
+/** Output formats are `<codec>_<rate>[_<bitrate>]`. */
+export function mimeForFormat(format: string): string {
+  const codec = format.split('_')[0];
+  return ({ mp3: 'audio/mpeg', pcm: 'audio/pcm', ulaw: 'audio/basic', alaw: 'audio/alaw', opus: 'audio/ogg' } as Record<string, string>)[codec]
+    ?? 'application/octet-stream';
+}

package/src/speech/providers/elevenlabs-tts.ts

@@ -0,0 +1,88 @@
+/**
+ * ElevenLabs text-to-speech with timestamps. Split from the provider so the
+ * request/response mapping reads on its own.
+ * https://elevenlabs.io/docs/api-reference/text-to-speech/convert-with-timestamps
+ */
+import { wordsFromCharacters } from '../alignment';
+import { LLMProviderError } from '../../errors';
+import { assertText, speechFetch } from '../http';
+import type { AlignedCharacter, SynthesizeRequest, SynthesizeResult } from '../types';
+import {
+  DEFAULT_OUTPUT_FORMAT, DEFAULT_TTS_MODEL, costUsd, mimeForFormat, supportsAudioTags,
+} from './elevenlabs-models';
+
+interface Alignment {
+  characters?: string[];
+  character_start_times_seconds?: number[];
+  character_end_times_seconds?: number[];
+}
+
+export interface TtsContext {
+  provider: string;
+  apiKey: string;
+  baseUrl: string;
+  defaultVoiceId?: string;
+  fetchImpl?: typeof fetch;
+}
+
+/** Text as sent: style tags go in front, but only on models that read them. */
+export function spokenText(request: SynthesizeRequest, model: string): string {
+  const tags = supportsAudioTags(model) ? (request.style?.tags ?? []) : [];
+  return tags.map((t) => `[${t.replace(/^\[|\]$/g, '')}]`).join('') + (tags.length ? ' ' : '') + request.text;
+}
+
+function voiceSettings(request: SynthesizeRequest): Record<string, number | boolean> | undefined {
+  const { speed, stability } = request.style ?? {};
+  const merged = {
+    ...(speed !== undefined ? { speed } : {}),
+    ...(stability !== undefined ? { stability } : {}),
+    ...request.voiceSettings,
+  };
+  return Object.keys(merged).length ? merged : undefined;
+}
+
+export async function elevenLabsSynthesize(ctx: TtsContext, request: SynthesizeRequest): Promise<SynthesizeResult> {
+  assertText(request, ctx.provider);
+  const voiceId = request.voiceId ?? ctx.defaultVoiceId;
+  if (!voiceId) {
+    throw new LLMProviderError('No voice: pass voiceId or set ELEVENLABS_VOICE_ID.', 'INVALID_REQUEST', false, undefined, ctx.provider);
+  }
+  const model = request.model ?? DEFAULT_TTS_MODEL;
+  const format = request.outputFormat ?? DEFAULT_OUTPUT_FORMAT;
+  const text = spokenText(request, model);
+  const settings = voiceSettings(request);
+
+  const response = await speechFetch(
+    ctx.provider,
+    `${ctx.baseUrl}/v1/text-to-speech/${encodeURIComponent(voiceId)}/with-timestamps?output_format=${encodeURIComponent(format)}`,
+    {
+      method: 'POST',
+      headers: { 'xi-api-key': ctx.apiKey, 'content-type': 'application/json' },
+      body: JSON.stringify({
+        text, model_id: model,
+        ...(request.language ? { language_code: request.language } : {}),
+        ...(settings ? { voice_settings: settings } : {}),
+      }),
+    },
+    request.timeoutMs, ctx.fetchImpl, 'synthesis',
+  );
+  const json = (await response.json()) as { audio_base64?: string; alignment?: Alignment | null };
+  const audio = new Uint8Array(Buffer.from(json.audio_base64 ?? '', 'base64'));
+  const characters = alignedCharacters(json.alignment);
+  const words = characters ? wordsFromCharacters(characters, { keepTags: request.keepTags }) : undefined;
+  return {
+    audio, mimeType: mimeForFormat(format),
+    ...(characters ? { characters, durationSec: characters[characters.length - 1].end } : {}),
+    ...(words ? { words } : {}),
+    voiceId, model, provider: ctx.provider,
+    usage: { characters: text.length, costUsd: costUsd(model, text.length) },
+  };
+}
+
+function alignedCharacters(a?: Alignment | null): AlignedCharacter[] | undefined {
+  const chars = a?.characters;
+  const starts = a?.character_start_times_seconds;
+  const ends = a?.character_end_times_seconds;
+  if (!chars?.length || !starts || !ends) return undefined;
+  return chars.map((text, i) => ({ text, start: starts[i], end: ends[i] }));
+}

package/src/speech/providers/elevenlabs.ts

@@ -1,10 +1,12 @@
 /**
- * ElevenLabs Scribe speech-to-text. https://elevenlabs.io/docs/api-reference/speech-to-text
- * Env: ELEVENLABS_API_KEY.
+ * ElevenLabs Scribe speech-to-text and text-to-speech. https://elevenlabs.io/docs/api-reference/speech-to-text
+ * Env: ELEVENLABS_API_KEY; ELEVENLABS_VOICE_ID is the default voice.
  */
 import type { ISpeechProvider } from '../interface';
 import { assertAudio, audioBlob, speechFetch } from '../http';
-import type { TranscribeRequest, TranscriptResult, TranscriptWord } from '../types';
+import type { SynthesizeRequest, SynthesizeResult, TranscribeRequest, TranscriptResult, TranscriptWord } from '../types';
+import { elevenLabsSynthesize } from './elevenlabs-tts';
+import { DEFAULT_TTS_MODEL, costUsd } from './elevenlabs-models';
 
 export interface ElevenLabsOptions {
   /**
@@ -14,6 +16,8 @@ export interface ElevenLabsOptions {
    */
   sendKeyterms?: boolean;
   apiKey?: string;
+  /** Voice used when a call names none. */
+  voiceId?: string;
   baseUrl?: string;
   fetchImpl?: typeof fetch;
 }
@@ -22,10 +26,11 @@ interface ScribeWord { text: string; start?: number; end?: number; type?: string
 
 export class ElevenLabsSpeechProvider implements ISpeechProvider {
   readonly name = 'elevenlabs';
-  readonly capabilities = { transcribe: true };
+  readonly capabilities = { transcribe: true, synthesize: true };
   readonly defaultModel = 'scribe_v1';
   private readonly apiKey: string;
   private readonly baseUrl: string;
+  private readonly voiceId?: string;
   private readonly fetchImpl?: typeof fetch;
   private readonly sendKeyterms: boolean;
 
@@ -33,6 +38,7 @@ export class ElevenLabsSpeechProvider implements ISpeechProvider {
     this.sendKeyterms = options.sendKeyterms ?? false;
     this.apiKey = options.apiKey ?? '';
     this.baseUrl = (options.baseUrl ?? 'https://api.elevenlabs.io').replace(/\/+$/, '');
+    this.voiceId = options.voiceId;
     this.fetchImpl = options.fetchImpl;
   }
 
@@ -45,6 +51,18 @@ export class ElevenLabsSpeechProvider implements ISpeechProvider {
     return 0.22 / 60;
   }
 
+  /** Cheapest TTS tier per 1,000 characters (eleven_flash_v2_5). */
+  costPer1kCharsUsd(model?: string): number {
+    return costUsd(model ?? DEFAULT_TTS_MODEL, 1000);
+  }
+
+  synthesize(request: SynthesizeRequest): Promise<SynthesizeResult> {
+    return elevenLabsSynthesize(
+      { provider: this.name, apiKey: this.apiKey, baseUrl: this.baseUrl, defaultVoiceId: this.voiceId, fetchImpl: this.fetchImpl },
+      request,
+    );
+  }
+
   async transcribe(request: TranscribeRequest): Promise<TranscriptResult> {
     assertAudio(request, this.name);
     const model = request.model ?? this.defaultModel;
@@ -81,5 +99,5 @@ export class ElevenLabsSpeechProvider implements ISpeechProvider {
 export function createElevenLabsSpeechProvider(
   env: Record<string, string | undefined> = typeof process !== 'undefined' ? process.env : {},
 ): ElevenLabsSpeechProvider | null {
-  return env.ELEVENLABS_API_KEY ? new ElevenLabsSpeechProvider({ apiKey: env.ELEVENLABS_API_KEY }) : null;
+  return env.ELEVENLABS_API_KEY ? new ElevenLabsSpeechProvider({ apiKey: env.ELEVENLABS_API_KEY, voiceId: env.ELEVENLABS_VOICE_ID || undefined }) : null;
 }

package/src/speech/providers/mock.ts

@@ -1,6 +1,8 @@
 import { LLMProviderError } from '../../errors';
 import type { ISpeechProvider } from '../interface';
-import type { TranscribeRequest, TranscriptResult } from '../types';
+import { wordsFromCharacters } from '../alignment';
+import { assertText } from '../http';
+import type { SynthesizeRequest, SynthesizeResult, TranscribeRequest, TranscriptResult } from '../types';
 
 export interface MockSpeechBehavior {
   text?: string;
@@ -24,15 +26,33 @@ export function resetMockSpeechBehavior() {
 /** Deterministic transcription for tests — selected with `SPEECH_PROVIDER=mock`. */
 export class MockSpeechProvider implements ISpeechProvider {
   readonly name = 'mock';
-  readonly capabilities = { transcribe: true };
+  readonly capabilities = { transcribe: true, synthesize: true };
   readonly defaultModel = 'mock-transcribe';
   isAvailable() { return true; }
-  async transcribe(request: TranscribeRequest): Promise<TranscriptResult> {
+  private maybeFail() {
     if (behavior.authError) throw new LLMProviderError('mock auth failure', 'AUTHENTICATION_ERROR', false, 401, this.name);
     if (remainingFailures > 0) {
       remainingFailures -= 1;
       throw new LLMProviderError('mock outage', 'SERVICE_UNAVAILABLE', true, 503, this.name);
     }
+  }
+
+  /** Fake audio (one byte per character) with 50ms-per-character alignment. */
+  async synthesize(request: SynthesizeRequest): Promise<SynthesizeResult> {
+    assertText(request, this.name);
+    this.maybeFail();
+    const characters = [...request.text].map((text, i) => ({ text, start: Math.round(i * 50) / 1000, end: Math.round((i + 1) * 50) / 1000 }));
+    return {
+      audio: new Uint8Array(characters.length).fill(1), mimeType: 'audio/mpeg',
+      characters, words: wordsFromCharacters(characters, { keepTags: request.keepTags }),
+      durationSec: characters[characters.length - 1].end,
+      voiceId: request.voiceId ?? 'mock-voice', model: 'mock-synthesize', provider: this.name,
+      usage: { characters: request.text.length, costUsd: 0 },
+    };
+  }
+
+  async transcribe(request: TranscribeRequest): Promise<TranscriptResult> {
+    this.maybeFail();
     return {
       text: behavior.text ?? `mock transcript of ${request.audio.byteLength} bytes`,
       model: this.defaultModel, provider: this.name, usage: { audioSeconds: 1 },

package/src/speech/providers/openai.ts

@@ -9,8 +9,8 @@
  * URL, default model, word-timing model and price table.
  */
 import type { ISpeechProvider } from '../interface';
-import { assertAudio, audioBlob, speechFetch } from '../http';
-import type { TranscribeRequest, TranscriptResult, TranscriptWord } from '../types';
+import { assertAudio, assertText, audioBlob, speechFetch } from '../http';
+import type { SynthesizeRequest, SynthesizeResult, TranscribeRequest, TranscriptResult, TranscriptWord } from '../types';
 
 export interface OpenAISpeechOptions {
   apiKey?: string;
@@ -34,7 +34,7 @@ const OPENAI_PRICES: Record<string, number> = {
 
 export class OpenAISpeechProvider implements ISpeechProvider {
   readonly name: string;
-  readonly capabilities = { transcribe: true };
+  readonly capabilities = { transcribe: true, synthesize: true };
   readonly defaultModel: string;
   private readonly apiKey: string;
   private readonly baseUrl: string;
@@ -62,6 +62,37 @@ export class OpenAISpeechProvider implements ISpeechProvider {
     return this.prices[model ?? this.defaultModel] ?? this.fallbackPrice;
   }
 
+  /** TTS list price per 1,000 characters (tts-1 $15/M; gpt-4o-mini-tts bills about the same per spoken minute). */
+  costPer1kCharsUsd(): number {
+    return 0.015;
+  }
+
+  /** `/v1/audio/speech`. OpenAI returns bare audio: no alignment, so no word timings. */
+  async synthesize(request: SynthesizeRequest): Promise<SynthesizeResult> {
+    assertText(request, this.name);
+    const model = request.model ?? 'gpt-4o-mini-tts';
+    const voice = request.voiceId ?? 'alloy';
+    const format = request.outputFormat ?? 'mp3';
+    const response = await speechFetch(
+      this.name, `${this.baseUrl}/v1/audio/speech`,
+      {
+        method: 'POST',
+        headers: { authorization: `Bearer ${this.apiKey}`, 'content-type': 'application/json' },
+        body: JSON.stringify({
+          model, voice, input: request.text, response_format: format,
+          ...(request.style?.speed !== undefined ? { speed: request.style.speed } : {}),
+        }),
+      },
+      request.timeoutMs, this.fetchImpl, 'synthesis',
+    );
+    const mimeType = ({ mp3: 'audio/mpeg', wav: 'audio/wav', opus: 'audio/ogg', aac: 'audio/aac', flac: 'audio/flac', pcm: 'audio/pcm' } as Record<string, string>)[format] ?? 'application/octet-stream';
+    return {
+      audio: new Uint8Array(await response.arrayBuffer()), mimeType,
+      voiceId: voice, model, provider: this.name,
+      usage: { characters: request.text.length, costUsd: (request.text.length * this.costPer1kCharsUsd()) / 1000 },
+    };
+  }
+
   async transcribe(request: TranscribeRequest): Promise<TranscriptResult> {
     assertAudio(request, this.name);
     const wantWords = request.timestamps === 'word';

package/src/speech/service.ts

@@ -4,7 +4,11 @@ import type { ISpeechProvider } from './interface';
 import { createElevenLabsSpeechProvider } from './providers/elevenlabs';
 import { MockSpeechProvider } from './providers/mock';
 import { createOpenAISpeechProvider } from './providers/openai';
-import type { SpeechServiceConfig, TranscribeRequest, TranscriptResult } from './types';
+import type {
+  SpeechServiceConfig, SynthesizeRequest, SynthesizeResult, TranscribeRequest, TranscriptResult,
+} from './types';
+
+type Direction = 'transcribe' | 'synthesize';
 
 /**
  * The speech registry. Built-ins register here; a new vendor is
@@ -48,14 +52,15 @@ export class SpeechService {
     return this.getAvailableProviders().length > 0;
   }
 
-  getAvailableProviders(): string[] {
-    return [...this.providers].filter(([, p]) => p.isAvailable() && p.capabilities.transcribe).map(([n]) => n);
+  getAvailableProviders(direction: Direction = 'transcribe'): string[] {
+    return [...this.providers].filter(([, p]) => p.isAvailable() && p.capabilities[direction]).map(([n]) => n);
   }
 
   /** Providers in the order they will be tried: the preferred one (if any), then cheapest first. */
-  private order(): ISpeechProvider[] {
-    const usable = [...this.providers.values()].filter((p) => p.isAvailable() && p.capabilities.transcribe);
-    const price = (p: ISpeechProvider) => p.costPerMinuteUsd?.() ?? Number.POSITIVE_INFINITY;
+  private order(direction: Direction): ISpeechProvider[] {
+    const usable = [...this.providers.values()].filter((p) => p.isAvailable() && p.capabilities[direction]);
+    const price = (p: ISpeechProvider) =>
+      (direction === 'synthesize' ? p.costPer1kCharsUsd?.() : p.costPerMinuteUsd?.()) ?? Number.POSITIVE_INFINITY;
     // Array.sort is stable, so equal/unknown prices keep registration order.
     const byPrice = [...usable].sort((a, b) => price(a) - price(b));
     const wanted = this.config.preferredProvider
@@ -71,18 +76,24 @@ export class SpeechService {
     // (an English note came back in French once). A per-call `language` wins.
     const env: Record<string, string | undefined> = typeof process !== 'undefined' ? process.env : {};
     const request = input.language || !env.SPEECH_LANGUAGE ? input : { ...input, language: env.SPEECH_LANGUAGE };
-    const order = this.order();
-    if (!order.length) {
-      throw new LLMProviderError(
-        'No speech providers available. Set OPENAI_API_KEY or ELEVENLABS_API_KEY.',
-        'AUTHENTICATION_ERROR', false,
-      );
-    }
+    return this.run('transcribe', 'No speech providers available. Set OPENAI_API_KEY or ELEVENLABS_API_KEY.',
+      (provider) => provider.transcribe!(request));
+  }
+
+  /** Text to speech, with the same retry, backoff and fallback as `transcribe`. */
+  async synthesize(request: SynthesizeRequest): Promise<SynthesizeResult> {
+    return this.run('synthesize', 'No text-to-speech provider available. Set OPENAI_API_KEY or ELEVENLABS_API_KEY.',
+      (provider) => provider.synthesize!(request));
+  }
+
+  private async run<T>(direction: Direction, none: string, call: (provider: ISpeechProvider) => Promise<T>): Promise<T> {
+    const order = this.order(direction);
+    if (!order.length) throw new LLMProviderError(none, 'AUTHENTICATION_ERROR', false);
     let last: unknown;
     for (const provider of order) {
       for (let attempt = 0; ; attempt += 1) {
         try {
-          return await provider.transcribe!(request);
+          return await call(provider);
         } catch (error) {
           last = error;
           const typed = error instanceof LLMProviderError ? error : null;

package/src/speech/types.ts

@@ -14,8 +14,10 @@ export interface TranscriptWord {
 export interface SpeechUsage {
   /** Billable input, when the provider reports it; else derived from word timings. */
   audioSeconds?: number;
-  /** Characters synthesized (TTS). */
+  /** Characters synthesized (TTS), as billed: tags included. */
   characters?: number;
+  /** Cost at the vendor's list rate, when the provider knows it. */
+  costUsd?: number;
 }
 
 export interface TranscribeRequest {
@@ -47,6 +49,58 @@ export interface TranscriptResult {
   usage: SpeechUsage;
 }
 
+/** One aligned unit (a character) with its time span, in seconds from the start of the audio. */
+export interface AlignedCharacter {
+  text: string;
+  start: number;
+  end: number;
+}
+
+/**
+ * Per-call delivery. Providers apply what their model supports and ignore the
+ * rest — a caller never needs to know which model reads which knob.
+ */
+export interface SpeechStyle {
+  /** Audio tags (`excited`, `whispers`), written as `[tag]` ahead of the text on models that read them. */
+  tags?: string[];
+  speed?: number;
+  /** Lower is more expressive. */
+  stability?: number;
+}
+
+export interface SynthesizeRequest {
+  text: string;
+  /** Provider voice id. Omit to use the provider's configured default (ELEVENLABS_VOICE_ID). */
+  voiceId?: string;
+  /** Provider-specific model override. */
+  model?: string;
+  /** ISO-639 hint. */
+  language?: string;
+  /** Vendor output format (`mp3_44100_128`, `pcm_22050`). Default: mp3. */
+  outputFormat?: string;
+  style?: SpeechStyle;
+  /** Raw vendor voice settings; wins over `style` where both set a key. */
+  voiceSettings?: Record<string, number | boolean>;
+  /** Keep `[tag]` markup in the returned words. Default false: tags are delivery, not speech. */
+  keepTags?: boolean;
+  timeoutMs?: number;
+}
+
+export interface SynthesizeResult {
+  audio: Uint8Array;
+  mimeType: string;
+  /** Per-character timings, exactly as the vendor aligned the text it was sent. Absent when the vendor gives none. */
+  characters?: AlignedCharacter[];
+  /** Word timings derived from `characters`; audio tags removed unless `keepTags`. */
+  words?: TranscriptWord[];
+  /** End of the last aligned character; absent without alignment. */
+  durationSec?: number;
+  voiceId?: string;
+  model: string;
+  provider: string;
+  usage: SpeechUsage;
+}
+
 export interface SpeechServiceConfig {
   /** Provider tried first. Default: `SPEECH_PROVIDER`, else the cheapest vendor with a key. */
   preferredProvider?: string;