nixamp 0.25.0 → 0.26.0

package/src/captions.ts

@@ -32,7 +32,8 @@
  */
 import { spawn } from "node:child_process";
 import type { Listener } from "./channels.ts";
-import { RATE } from "./speech.ts";
+import { NATIVE_REVISION, RATE, SpeechError, reliableText } from "./speech.ts";
+import { voiceProfile } from "./voice-profile.ts";
 import { fetchTranscript, keepLines, keepMedia, translateTexts, type MediaToKeep } from "./transcript-client.ts";
 import { covered, lineAt, transcriptIdOf, type TranscriptLine } from "./transcripts.ts";
 
@@ -47,6 +48,8 @@ export interface CaptionLine {
   language?: string;
   /** What was heard, when this line is a translation of it. */
   original?: string;
+  sourceLanguage?: string;
+  voiceProfile?: "lower" | "higher" | "unknown";
 }
 
 /** What turns a channel's bytes into 16 kHz mono 16-bit PCM. ffmpeg, or a test's stand-in. */
@@ -104,6 +107,8 @@ export const IDLE_MS = 60_000;
 export const QUIET = 0.004;
 /** Windows waiting on the ear at once. Past this the sound is dropped, not queued: late words are worse than none. */
 export const IN_FLIGHT = 2;
+export const LIVE_DEADLINE_MS = 12_000;
+export const MAX_CAPTIONERS = 4;
 /** Heard lines wait this long, at most, before they are kept. */
 export const FLUSH_MS = 20_000;
 /** Or this many. */
@@ -252,6 +257,9 @@ class Captioner {
   private stopped = false;
   private complainedAt = 0;
   private windows = 0;
+  private audioUntil = 0;
+  private lastEmittedAt = -Infinity;
+  private readonly requests = new Set<AbortController>();
   /** What the channel is playing, when the store is to be told. */
   private readonly media: ChannelMedia | null;
   private readonly transcriptId: string | null;
@@ -264,6 +272,8 @@ class Captioner {
   private flush: ReturnType<typeof setTimeout> | null = null;
   /** Translations in order, per language: a slow one must not overtake the next. */
   private readonly chains = new Map<string, Promise<void>>();
+  private readonly translating = new Set<string>();
+  private readonly nextTranslation = new Map<string, { line: CaptionLine; mediaStart: number | null }>();
 
   constructor(
     readonly id: string,
@@ -326,16 +336,18 @@ class Captioner {
     this.asked.add(language);
     const session = this.options.session();
     if (session === null) return;
-    const got = await fetchTranscript(session, this.transcriptId, language, this.options.fetcher ?? fetch);
+    const got = await fetchTranscript(session, this.transcriptId, language, this.options.fetcher ?? fetch, true);
     if (this.stopped) return;
     if (!got.ok) {
       if (got.status !== 404) this.complain(`the store did not answer: ${got.error}`);
       return;
     }
-    this.known.set(language, got.body.lines);
-    if (language === "" && this.language === "" && got.body.language) this.language = got.body.language;
-    if (got.body.lines.length > 0) {
-      this.options.onEvent?.(`captions for "${this.id}": the store knows ${got.body.lines.length} lines of this${language ? ` in ${language}` : ""}`);
+    // A row's model/language could have been updated while its old bad lines remained.
+    // Trust individual lines made with the corrected native pipeline only.
+    const usable = got.body.lines.filter((line) => line.revision === NATIVE_REVISION && reliableText(line.text, line.end - line.start));
+    this.known.set(language, usable);
+    if (usable.length > 0) {
+      this.options.onEvent?.(`captions for "${this.id}": the store knows ${usable.length} lines of this${language ? ` in ${language}` : ""}`);
     }
   }
 
@@ -350,7 +362,9 @@ class Captioner {
       const rest = all.subarray(size);
       this.pending = rest.length > 0 ? [Buffer.from(rest)] : [];
       this.pendingBytes = rest.length;
-      const until = this.now();
+      const duration = this.options.windowMs ?? WINDOW_MS;
+      const until = Math.max(this.audioUntil + duration, this.now() - rest.length / (RATE * 2) * 1000);
+      this.audioUntil = until;
       const index = this.windows;
       this.windows += 1;
       void this.hear(Buffer.from(window), until - (this.options.windowMs ?? WINDOW_MS), until, index);
@@ -368,7 +382,8 @@ class Captioner {
           if (this.readOut.has(line.start)) continue;
           this.readOut.add(line.start);
           const lineAt = at + (line.start - span.start) * 1000;
-          this.emit({ channel: this.id, at: lineAt, until: lineAt + (line.end - line.start) * 1000, text: line.text, ...(this.language ? { language: this.language } : {}) }, line.start);
+          this.emit({ channel: this.id, at: lineAt, until: lineAt + (line.end - line.start) * 1000, text: line.text,
+            ...(line.language ? { language: line.language } : {}), ...(line.voiceProfile ? { voiceProfile: line.voiceProfile } : {}) }, line.start);
         }
         return;
       }
@@ -380,37 +395,47 @@ class Captioner {
       return;
     }
     this.inFlight += 1;
+    const controller = new AbortController();
+    this.requests.add(controller);
+    const timeout = setTimeout(() => controller.abort(), LIVE_DEADLINE_MS);
     try {
       const wav = wavAround(pcm);
       const url = new URL(`${session.site.replace(/\/+$/, "")}/api/v1/speech/transcribe`);
-      if (this.language) url.searchParams.set("language", this.language);
+      // Let each audio window detect its own language. Cached text and a viewer's
+      // translation selection must never constrain the recognizer.
+      url.searchParams.set("live", "1");
       const response = await (this.options.fetcher ?? fetch)(url.toString(), {
         method: "POST",
         headers: { authorization: `Bearer ${session.token}`, "content-type": "audio/wav" },
         body: new Blob([wav.buffer.slice(wav.byteOffset, wav.byteOffset + wav.byteLength) as ArrayBuffer]),
+        signal: controller.signal,
       });
       const body = (await response.json().catch(() => ({}))) as { text?: string; language?: string; model?: string; error?: string };
       if (!response.ok) {
         this.complain(body.error ?? `nixamp.com answered ${response.status}`);
         return;
       }
-      const text = (body.text ?? "").trim();
-      if (text === "" || this.stopped) return;
+      const text = reliableText(body.text ?? "", (until - at) / 1000);
+      if (text === "" || this.stopped || controller.signal.aborted || this.now() - until > LIVE_DEADLINE_MS) return;
       this.error = "";
-      if (body.language && this.language === "") this.language = body.language;
       if (body.model) this.model = body.model;
-      const line: CaptionLine = { channel: this.id, at, until, text, ...(this.language ? { language: this.language } : {}) };
+      const line: CaptionLine = { channel: this.id, at, until, text, ...(body.language ? { language: body.language } : {}), voiceProfile: voiceProfile(pcm) };
       this.emit(line, span?.start ?? null);
-      if (span) this.keep("", { start: span.start, end: span.end, text });
+      if (span) this.keep("", { start: span.start, end: span.end, text, language: line.language, voiceProfile: line.voiceProfile, revision: NATIVE_REVISION });
     } catch (error) {
       this.complain(`could not reach the ear: ${(error as Error).message}`);
     } finally {
+      clearTimeout(timeout);
+      this.requests.delete(controller);
       this.inFlight -= 1;
     }
   }
 
   /** A line as heard, to whoever wants the original, and translated to whoever wants another language. */
   private emit(line: CaptionLine, mediaStart: number | null): void {
+    if (line.at <= this.lastEmittedAt) return;
+    this.lastEmittedAt = line.at;
+    this.language = line.language ?? "";
     this.lines.push(line);
     while (this.lines.length > KEEP) this.lines.shift();
     for (const [subscriber, language] of this.subscribers) {
@@ -436,33 +461,46 @@ class Captioner {
 
   /** The line in another language: from the store when it has been through this moment, from nixamp.com otherwise. */
   private translated(language: string, line: CaptionLine, mediaStart: number | null): void {
-    const chain = (this.chains.get(language) ?? Promise.resolve()).then(async () => {
-      if (this.stopped) return;
+    // One active request and the latest pending line per target, never a promise
+    // chain containing minutes of stale commentary.
+    if (this.translating.has(language)) {
+      this.nextTranslation.set(language, { line, mediaStart });
+      return;
+    }
+    this.translating.add(language);
+    const chain = Promise.resolve().then(async () => {
+      if (this.stopped || !this.wanted().has(language) || this.now() - line.until > LIVE_DEADLINE_MS) return;
       let text = "";
       const stored = mediaStart === null ? null : lineAt(this.known.get(language) ?? [], mediaStart);
-      if (stored) {
+      if (stored && stored.original === line.text) {
         text = stored.text;
       } else {
         const session = this.options.session();
         if (session === null) return;
-        const got = await translateTexts(session, [line.text], this.language, language, this.options.fetcher ?? fetch);
+        if (!line.language) return;
+        const got = await translateTexts(session, [line.text], line.language, language, this.options.fetcher ?? fetch, AbortSignal.timeout(LIVE_DEADLINE_MS));
         if (!got.ok) {
           this.complain(`could not translate to ${language}: ${got.error}`);
           return;
         }
-        text = (got.body.texts[0] ?? "").trim();
+        text = reliableText(got.body.texts[0] ?? "", (line.until - line.at) / 1000);
         if (text === "") return;
-        if (mediaStart !== null) this.keep(language, { start: mediaStart, end: round(mediaStart + (line.until - line.at) / 1000), text });
+        if (mediaStart !== null) this.keep(language, { start: mediaStart, end: round(mediaStart + (line.until - line.at) / 1000), text, original: line.text, revision: NATIVE_REVISION });
       }
-      if (this.stopped) return;
-      const said: CaptionLine = { ...line, text, language, original: line.text };
+      if (this.stopped || !this.wanted().has(language) || this.now() - line.until > LIVE_DEADLINE_MS) return;
+      const said: CaptionLine = { ...line, text, language, sourceLanguage: line.language, original: line.text };
       const lines = this.linesBy.get(language) ?? [];
       lines.push(said);
       while (lines.length > KEEP) lines.shift();
       this.linesBy.set(language, lines);
       for (const [subscriber, wanted] of this.subscribers) if (wanted === language) this.tell(subscriber, said);
     });
-    this.chains.set(language, chain.catch(() => undefined));
+    this.chains.set(language, chain.catch(() => undefined).finally(() => {
+      this.translating.delete(language);
+      const next = this.nextTranslation.get(language);
+      this.nextTranslation.delete(language);
+      if (next && !this.stopped) this.translated(language, next.line, next.mediaStart);
+    }));
   }
 
   /** A line for the store, kept with the others of its language until the next flush. */
@@ -494,7 +532,7 @@ class Captioner {
       const got = await keepLines(session, this.transcriptId, {
         media: this.media.media,
         title: this.media.title,
-        language: language === "" ? this.language : language,
+        language,
         ...(language === "" ? {} : { translatedFrom: this.language }),
         ...(this.model ? { model: this.model } : {}),
         lines,
@@ -529,7 +567,7 @@ class Captioner {
   }
 
   recent(after: number, language = ""): CaptionLine[] {
-    const lines = language === "" || language === this.language ? this.lines : (this.linesBy.get(language) ?? []);
+    const lines = language === "" ? this.lines : [...this.lines.filter((line) => line.language === language), ...(this.linesBy.get(language) ?? [])].sort((a, b) => a.at - b.at);
     return after > 0 ? lines.filter((line) => line.at > after) : [...lines];
   }
 
@@ -548,6 +586,9 @@ class Captioner {
   stop(): void {
     if (this.stopped) return;
     this.stopped = true;
+    for (const request of this.requests) request.abort();
+    this.requests.clear();
+    this.nextTranslation.clear();
     if (this.idle) clearTimeout(this.idle);
     this.idle = null;
     this.detach?.();
@@ -572,6 +613,25 @@ export class Captions {
     return this.options.session() !== null;
   }
 
+  capacity(id: string): boolean { return this.running.has(id) || this.running.size < MAX_CAPTIONERS; }
+
+  /** Voice requests are constrained to captions this channel actually produced. */
+  async voiceRequest(id: string, at: number | null, language: string, voice: string, signal: AbortSignal, grant = ""): Promise<Response> {
+    const session = this.options.session();
+    if (!session) throw new SpeechError("this server must sign in to use translated audio", 503);
+    if (at === null) return (this.options.fetcher ?? fetch)(`${session.site.replace(/\/+$/, "")}/api/v1/speech/voices`, {
+      headers: { authorization: `Bearer ${session.token}` }, signal,
+    });
+    if (!language) throw new SpeechError("choose a translation language first", 400);
+    if (!/^nxd_[A-Za-z0-9_-]{43}$/.test(grant)) throw new SpeechError("sign in to enable translated audio", 401);
+    const line = this.recent(id, 0, language).find(line => line.at === at);
+    if (!line || (this.options.now ?? Date.now)() - line.until > 30_000) throw new SpeechError("that live caption is no longer available for audio", 404);
+    return (this.options.fetcher ?? fetch)(`${session.site.replace(/\/+$/, "")}/api/v1/speech/synthesize`, {
+      method: "POST", headers: { authorization: `Bearer ${grant}`, "content-type": "application/json" },
+      body: JSON.stringify({ text: line.text, language, voice, profile: line.voiceProfile, channel: id }), signal,
+    });
+  }
+
   /**
    * Lines for a channel as they are heard, starting the captioner if it is
    * not running. Null when there is no such channel. The returned function
@@ -580,6 +640,7 @@ export class Captions {
    * "" is the original.
    */
   subscribe(id: string, subscriber: Subscriber, language = ""): (() => void) | null {
+    if (!this.capacity(id)) return null;
     let captioner = this.running.get(id);
     if (!captioner) {
       const made = new Captioner(id, this.options, () => {

package/src/live-voice.ts

@@ -0,0 +1,255 @@
+/** ElevenLabs Flash for live captions. The key stays on the account server. */
+import { createHash, randomBytes } from "node:crypto";
+import { SpeechError, decodeWav, encodeWav, quietSamples } from "./speech.ts";
+import { speakerTurns, type ScribeResult, type SpeakerTranscript } from "./speaker-turns.ts";
+import type { VoiceProfile } from "./voice-profile.ts";
+import { Guard } from "./guard.ts";
+import type { Queryable } from "./follows.ts";
+
+export const LIVE_VOICE_MODEL = "eleven_flash_v2_5";
+export const LIVE_VOICE_RATE = 16_000;
+export const LIVE_VOICE_LANGUAGES = new Set("en ja zh de hi fr ko pt it es id nl tr fil pl sv bg ro ar cs el fi hr ms sk da ta uk ru hu no vi".split(" "));
+export interface LiveVoiceChoice { id: string; name: string; gender: string; language: string; }
+export interface VoiceRequest { text: string; language: string; voice?: string; profile?: VoiceProfile; channel?: string; }
+const HEADERS = { "content-type": "audio/pcm", "cache-control": "no-store", "x-audio-sample-rate": String(LIVE_VOICE_RATE) };
+const budget = (value: number | undefined, fallback: number): number => Number.isFinite(value) && value! >= 0 ? Math.floor(value!) : fallback;
+
+export class LiveVoice {
+  private readonly key: string;
+  private readonly fetcher: typeof fetch;
+  private readonly now: () => number;
+  private catalog: Promise<LiveVoiceChoice[]> | null = null;
+  private catalogUntil = 0;
+  private readonly cache = new Map<string, { until: number; bytes: Uint8Array }>();
+  private readonly pending = new Map<string, Promise<Uint8Array>>();
+  private readonly usage = new Map<string, { minute: number; chars: number }>();
+  private readonly charsPerMinute: number;
+  private readonly requests: Guard;
+  private readonly grants = new Map<string, { by: string; channel: string; expires: number; remaining: number }>();
+  private readonly activeBy = new Map<string, number>();
+  private readonly db?: Queryable;
+  private schema: Promise<unknown> | null = null;
+  private readonly dailyChars: number;
+  private cleanupAt = 0;
+  private readonly hearing = new Set<string>();
+  private readonly dailyAudioSeconds: number;
+  private readonly userDailyChars: number;
+  private readonly userDailyAudioSeconds: number;
+
+  constructor(options: { apiKey?: string; fetcher?: typeof fetch; now?: () => number; charsPerMinute?: number; dailyChars?: number; dailyAudioSeconds?: number; userDailyChars?: number; userDailyAudioSeconds?: number; db?: Queryable } = {}) {
+    this.key = options.apiKey ?? process.env["ELEVENLABS_API_KEY"] ?? "";
+    this.fetcher = options.fetcher ?? fetch;
+    this.now = options.now ?? Date.now;
+    this.charsPerMinute = budget(options.charsPerMinute, 3000);
+    this.dailyChars = budget(options.dailyChars, 200_000);
+    this.dailyAudioSeconds = budget(options.dailyAudioSeconds, 86_400);
+    this.userDailyChars = budget(options.userDailyChars, 120_000);
+    this.userDailyAudioSeconds = budget(options.userDailyAudioSeconds, 43_200);
+    this.requests = new Guard(this.now);
+    this.db = options.db;
+  }
+
+  available(): boolean { return this.key !== ""; }
+
+  /** Optional diarization, billed only while a signed-in listener requests it.
+   * Rolling audio is bounded to 15 seconds, including overlap. Every second
+   * submitted (also repeated context) consumes the persistent provider budget. */
+  async hear(bytes: Uint8Array, by: string, signal?: AbortSignal): Promise<SpeakerTranscript> {
+    if (!this.available()) throw new SpeechError("speaker voices are unavailable", 503);
+    const wav = decodeWav(bytes);
+    const seconds = wav.samples.length / wav.rate;
+    if (wav.rate !== 16000 || wav.channels !== 1 || seconds < 0.2 || seconds > 15.1) throw new SpeechError("send up to 15 seconds of mono 16 kHz WAV", 400);
+    if (wav.samples.some(sample => !Number.isFinite(sample))) throw new SpeechError("invalid audio samples", 400);
+    if (!this.requests.check(`hear:${by}`, { allowed: 20, windowMs: 60_000 }).ok) throw new SpeechError("too many speaker transcription requests", 429);
+    if (quietSamples(wav.samples)) return { language: "", seconds, turns: [] };
+    if (this.hearing.has(by) || this.hearing.size >= 4) throw new SpeechError("speaker transcription is busy", 429);
+    this.hearing.add(by);
+    try {
+      const billed = Math.ceil(seconds);
+      await this.reserve(`scribe:user:${by}`, billed, 300, 60_000);
+      await this.reserve("scribe:server", billed, 600, 60_000);
+      await this.reserve(`scribe:user:${by}`, billed, this.userDailyAudioSeconds, 86_400_000);
+      await this.reserve("scribe:server", billed, this.dailyAudioSeconds, 86_400_000);
+      signal?.throwIfAborted();
+      const form = new FormData();
+      // Canonical PCM prevents a crafted container from billing more audio
+      // than the duration we validated, and removes uploaded metadata.
+      form.set("file", new Blob([new Uint8Array(encodeWav(wav.samples))], { type: "audio/wav" }), "listening.wav");
+      form.set("model_id", "scribe_v2");
+      form.set("diarize", "true");
+      form.set("tag_audio_events", "false");
+      form.set("timestamps_granularity", "word");
+      // No language_code: preserve the source language, including Spanish.
+      const answer = await this.fetcher("https://api.elevenlabs.io/v1/speech-to-text", {
+        method: "POST", headers: { "xi-api-key": this.key }, body: form,
+        signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(10_000)]) : AbortSignal.timeout(10_000),
+      });
+      if (!answer.ok) throw new SpeechError("speaker transcription could not run; check provider quota and permissions", answer.status === 429 ? 429 : 502);
+      return speakerTurns(await answer.json() as ScribeResult, wav);
+    } finally { this.hearing.delete(by); }
+  }
+
+  async voices(): Promise<LiveVoiceChoice[]> {
+    if (!this.available()) throw new SpeechError("translated audio needs ELEVENLABS_API_KEY on the account server", 503);
+    if (!this.catalog || this.now() >= this.catalogUntil) {
+      this.catalogUntil = this.now() + 3600_000;
+      this.catalog = this.fetcher("https://api.elevenlabs.io/v2/voices?page_size=100&voice_type=default", {
+        headers: { "xi-api-key": this.key }, signal: AbortSignal.timeout(8000),
+      }).then(async response => {
+        if (!response.ok) throw new SpeechError("ElevenLabs could not list voices; check the server key and its voice permissions", 503);
+        const body = await response.json() as { voices: { voice_id: string; name: string; labels?: Record<string, string> }[] };
+        return body.voices.filter(voice => /^[a-zA-Z0-9_-]+$/.test(voice.voice_id)).map(voice => ({
+          id: voice.voice_id, name: voice.name, gender: voice.labels?.["gender"] ?? "neutral", language: voice.labels?.["language"] ?? "",
+        }));
+      }).catch(error => { this.catalog = null; throw error; });
+    }
+    return this.catalog;
+  }
+
+  /** A 90-second capability for one channel, never the viewer's account credential. */
+  async grant(by: string, channel: string): Promise<{ token: string; expires: number }> {
+    if (!/^[\w-]{1,80}$/.test(channel)) throw new SpeechError("choose a playback session or live channel", 400);
+    if (!this.requests.check(`grant:${by}`, { allowed: 10, windowMs: 60_000 }).ok) throw new SpeechError("too many audio authorization requests", 429);
+    for (const [token, grant] of this.grants) if (grant.expires <= this.now()) this.grants.delete(token);
+    if (this.grants.size >= 5000) throw new SpeechError("audio authorization is busy", 503);
+    const token = `nxd_${randomBytes(32).toString("base64url")}`;
+    const expires = this.now() + 90_000;
+    if (this.db) {
+      await this.ensure();
+      await this.db.query("INSERT INTO live_voice_grants (token_hash, by_account, channel, expires_at, remaining) VALUES ($1, $2, $3, $4, 2000)", [createHash("sha256").update(token).digest("hex"), by, channel, new Date(expires)]);
+    } else this.grants.set(token, { by, channel, expires, remaining: 2000 });
+    return { token, expires };
+  }
+
+  async authorize(token: string, channel: string, chars: number): Promise<string> {
+    if (!/^nxd_[A-Za-z0-9_-]{43}$/.test(token)) throw new SpeechError("sign in to enable translated audio", 401);
+    if (!Number.isFinite(chars) || chars < 1 || chars > 600) throw new SpeechError("invalid caption length", 400);
+    if (this.db) {
+      await this.ensure();
+      const result = await this.db.query(`UPDATE live_voice_grants SET remaining = remaining - $3
+        WHERE token_hash = $1 AND channel = $2 AND expires_at > $4 AND remaining >= $3 RETURNING by_account`, [createHash("sha256").update(token).digest("hex"), channel, chars, new Date(this.now())]);
+      if (!result.rows.length) throw new SpeechError("audio authorization expired or reached its limit; enable translated audio again", 401);
+      return String(result.rows[0]?.["by_account"]);
+    }
+    const grant = this.grants.get(token);
+    if (!grant || grant.expires <= this.now() || grant.channel !== channel) throw new SpeechError("sign in to renew translated audio", 401);
+    if (grant.remaining < chars) throw new SpeechError("this audio authorization reached its character limit", 429);
+    grant.remaining -= chars;
+    return grant.by;
+  }
+
+  private async ensure(): Promise<void> {
+    if (!this.db) return;
+    this.schema ??= (async () => {
+      await this.db!.query("CREATE TABLE IF NOT EXISTS live_voice_usage (bucket TEXT PRIMARY KEY, chars BIGINT NOT NULL, expires_at TIMESTAMPTZ NOT NULL)");
+      await this.db!.query("CREATE TABLE IF NOT EXISTS live_voice_grants (token_hash TEXT PRIMARY KEY, by_account TEXT NOT NULL, channel TEXT NOT NULL, expires_at TIMESTAMPTZ NOT NULL, remaining INTEGER NOT NULL)");
+    })().catch(error => { this.schema = null; throw error; });
+    await this.schema;
+    if (this.now() >= this.cleanupAt) {
+      this.cleanupAt = this.now() + 60_000;
+      // Keep only live windows; accounting survives restarts and is shared by replicas.
+      await this.db.query("DELETE FROM live_voice_usage WHERE expires_at <= $1", [new Date(this.now())]);
+      await this.db.query("DELETE FROM live_voice_grants WHERE expires_at <= $1", [new Date(this.now())]);
+    }
+  }
+
+  private async reserve(bucket: string, chars: number, limit: number, windowMs: number): Promise<void> {
+    if (chars > limit) throw new SpeechError("translated audio reached its character budget; try again later", 429);
+    const window = Math.floor(this.now() / windowMs);
+    const key = `${bucket}:${windowMs}:${window}`;
+    if (this.db) {
+      await this.ensure();
+      const result = await this.db.query(`INSERT INTO live_voice_usage (bucket, chars, expires_at) VALUES ($1, $2, $4)
+        ON CONFLICT (bucket) DO UPDATE SET chars = live_voice_usage.chars + EXCLUDED.chars
+        WHERE live_voice_usage.chars + EXCLUDED.chars <= $3 RETURNING chars`, [key, chars, limit, new Date((window + 1) * windowMs)]);
+      if (!result.rows.length) throw new SpeechError("translated audio reached its character budget; try again later", 429);
+      return;
+    }
+    // Local/single-process installations without a database. Account servers pass their pool.
+    const record = this.usage.get(key) ?? { minute: (window + 1) * windowMs, chars: 0 };
+    if (record.chars + chars > limit) throw new SpeechError("translated audio reached its character budget; try again later", 429);
+    record.chars += chars; this.usage.set(key, record);
+  }
+
+  private async charge(by: string, channel: string, chars: number): Promise<void> {
+    for (const [key, record] of this.usage) if (record.minute <= this.now()) this.usage.delete(key);
+    await this.reserve(`user:${by}`, chars, this.charsPerMinute, 60_000);
+    await this.reserve(`channel:${channel}`, chars, 6000, 60_000);
+    await this.reserve("server", chars, 12_000, 60_000);
+    await this.reserve(`user:${by}`, chars, this.userDailyChars, 86400_000);
+    await this.reserve("server", chars, this.dailyChars, 86400_000);
+  }
+
+  private checkRequest(by: string): void {
+    if (!this.requests.check(`audio:${by}`, { allowed: 60, windowMs: 60_000 }).ok) throw new SpeechError("too many translated audio requests", 429);
+  }
+
+  /** Stream the first request immediately; concurrent listeners share its cached result. */
+  async stream(ask: VoiceRequest, by: string, signal?: AbortSignal): Promise<Response> {
+    this.checkRequest(by);
+    const text = typeof ask.text === "string" ? ask.text.trim() : "";
+    if (!text || text.length > 600) throw new SpeechError("translated audio needs a caption of 1–600 characters", 400);
+    if (!LIVE_VOICE_LANGUAGES.has(ask.language)) throw new SpeechError("this language is not supported by Flash voices", 400);
+    const voices = await this.voices();
+    signal?.throwIfAborted();
+    const gender = ask.profile === "lower" ? "male" : ask.profile === "higher" ? "female" : "neutral";
+    const voice = ask.voice && ask.voice !== "auto"
+      ? voices.find(voice => voice.id === ask.voice)
+      : voices.find(voice => voice.gender === gender) ?? voices[0];
+    if (!voice) throw new SpeechError("choose an available voice", 400);
+    const id = createHash("sha256").update(JSON.stringify([LIVE_VOICE_MODEL, voice.id, ask.language, text])).digest("hex");
+    for (const [key, item] of this.cache) if (item.until < this.now()) this.cache.delete(key);
+    const cached = this.cache.get(id);
+    if (cached) return new Response(new Uint8Array(cached.bytes), { headers: HEADERS });
+    const pending = this.pending.get(id);
+    if (pending) return new Response(new Uint8Array(await pending), { headers: HEADERS });
+    if (this.pending.size >= 4) throw new SpeechError("translated audio is busy; waiting for the next caption", 429);
+    if ((this.activeBy.get(by) ?? 0) >= 2) throw new SpeechError("two voice requests are already active for this account", 429);
+    // Register before the first provider await, so identical requests cannot both bill.
+    let done!: (bytes: Uint8Array) => void;
+    let fail!: (error: unknown) => void;
+    const finished = new Promise<Uint8Array>((resolve, reject) => { done = resolve; fail = reject; });
+    this.pending.set(id, finished);
+    this.activeBy.set(by, (this.activeBy.get(by) ?? 0) + 1);
+    const release = (): void => { this.pending.delete(id); this.activeBy.set(by, Math.max(0, (this.activeBy.get(by) ?? 1) - 1)); if (!this.activeBy.get(by)) this.activeBy.delete(by); };
+    void finished.catch(() => undefined);
+    try {
+      await this.charge(by, ask.channel ?? "direct", text.length);
+      signal?.throwIfAborted();
+      const response = await this.fetcher(`https://api.elevenlabs.io/v1/text-to-speech/${voice.id}/stream?output_format=pcm_16000`, {
+        method: "POST",
+        headers: { "xi-api-key": this.key, "content-type": "application/json" },
+        body: JSON.stringify({ text, model_id: LIVE_VOICE_MODEL, language_code: ask.language }),
+        signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(10_000)]) : AbortSignal.timeout(10_000),
+      });
+      if (!response.ok || !response.body) throw new SpeechError(response.status === 429 ? "ElevenLabs audio quota is temporarily exhausted" : "ElevenLabs could not generate audio; check the server key and quota", response.status === 429 ? 429 : 502);
+      const [play, keep] = response.body.tee();
+      void (async () => {
+        const reader = keep.getReader();
+        const chunks: Uint8Array[] = [];
+        let size = 0;
+        try {
+          while (true) {
+            const { done: ended, value } = await reader.read();
+            if (ended) break;
+            size += value.length;
+            if (size > 2 * 1024 * 1024) { await reader.cancel(); throw new SpeechError("voice response was too long", 502); }
+            chunks.push(value);
+          }
+          if (!size || size % 2) throw new SpeechError("voice response contained incomplete audio", 502);
+          const bytes = new Uint8Array(size);
+          let at = 0;
+          for (const chunk of chunks) { bytes.set(chunk, at); at += chunk.length; }
+          this.cache.set(id, { until: this.now() + 60_000, bytes });
+          // At most a few MB for recent lines, never a recording archive.
+          while (this.cache.size > 32) this.cache.delete(this.cache.keys().next().value as string);
+          done(bytes);
+        } catch (error) { fail(error); }
+        finally { reader.releaseLock(); release(); }
+      })();
+      return new Response(play, { headers: HEADERS });
+    } catch (error) {
+      fail(error); release(); throw error;
+    }
+  }
+}