nixamp 0.26.7 → 0.27.0

package/dist/translation-passes.d.ts

@@ -0,0 +1,97 @@
+import type { Queryable } from "./follows.ts";
+export declare const TRANSLATION_MULTIPLIER = 5;
+export declare const TRANSLATION_PLANS: readonly [{
+    readonly id: "day";
+    readonly name: "Day";
+    readonly days: 1;
+    readonly priceCents: 500;
+}, {
+    readonly id: "week";
+    readonly name: "Week";
+    readonly days: 7;
+    readonly priceCents: 2500;
+}, {
+    readonly id: "month";
+    readonly name: "Month";
+    readonly days: 30;
+    readonly priceCents: 10000;
+}];
+export type TranslationPlan = typeof TRANSLATION_PLANS[number];
+export type TranslationUsage = "transcription" | "voice";
+export interface TranslationMeter {
+    require(by: string): Promise<void>;
+    eligible?(accounts: string[]): Promise<string[]>;
+    reserve(by: string, kind: TranslationUsage, units: number): Promise<string>;
+    reserveMany?(accounts: string[], kind: TranslationUsage, units: number): Promise<{
+        by: string;
+        id: string;
+    }[]>;
+    commitMany?(ids: string[]): Promise<void>;
+    refundMany?(ids: string[]): Promise<void>;
+    commit(id: string): Promise<void>;
+    refund(id: string): Promise<void>;
+}
+export interface TranslationAccess {
+    required: boolean;
+    available: boolean;
+    balanceMicros: number;
+    expires: string | null;
+    plans: readonly TranslationPlan[];
+    coins: string[];
+    orders: {
+        id: string;
+        url: string;
+        plan: string;
+    }[];
+    rates: {
+        transcriptionHour: number;
+        voiceThousand: number;
+        multiplier: number;
+    };
+}
+/** At the published rates: Scribe $0.22/submitted hour, Flash $0.05/1k chars.
+ * Transcription units are 16 kHz samples; overlap is charged exactly as sent. */
+export declare function translationCost(kind: TranslationUsage, units: number): {
+    cost: number;
+    charge: number;
+};
+export declare function verifyTranslationPayment(payment: Record<string, unknown>, id: string, priceCents: number): boolean;
+export declare class TranslationPasses implements TranslationMeter {
+    private readonly options;
+    private schema;
+    private merchant;
+    private merchantUntil;
+    private readonly fetcher;
+    private readonly now;
+    constructor(options: {
+        db: Queryable;
+        key: string;
+        site: string;
+        fetcher?: typeof fetch;
+        now?: () => number;
+    });
+    private ensure;
+    private provider;
+    private settings;
+    access(by?: string): Promise<TranslationAccess>;
+    require(by: string): Promise<void>;
+    eligible(accounts: string[]): Promise<string[]>;
+    reserve(by: string, kind: TranslationUsage, units: number): Promise<string>;
+    /** Batch a shared stream's access charges in one database round trip. */
+    reserveMany(accounts: string[], kind: TranslationUsage, units: number): Promise<{
+        by: string;
+        id: string;
+    }[]>;
+    commit(id: string): Promise<void>;
+    refund(id: string): Promise<void>;
+    commitMany(ids: string[]): Promise<void>;
+    refundMany(ids: string[]): Promise<void>;
+    checkout(by: string, planId: string, coin: string, requestKey: string): Promise<{
+        id: string;
+        url: string;
+    }>;
+    check(by: string, id: string): Promise<{
+        status: string;
+        access: TranslationAccess;
+    }>;
+}

package/dist/translation-passes.js

@@ -0,0 +1,227 @@
+/** Account-bound, prepaid translation credit. Money is integer micro-USD;
+ * each listening account reserves 5x base provider cost for paid access. */
+import { randomUUID } from "node:crypto";
+import { SpeechError } from "./speech.js";
+export const TRANSLATION_MULTIPLIER = 5;
+export const TRANSLATION_PLANS = [
+    { id: "day", name: "Day", days: 1, priceCents: 500 },
+    { id: "week", name: "Week", days: 7, priceCents: 2500 },
+    { id: "month", name: "Month", days: 30, priceCents: 10000 },
+];
+const COINS = ["USDC_POL", "USDC_SOL", "SOL", "POL", "BTC", "ETH", "USDC_ETH", "BCH", "DOGE"];
+const ID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i;
+const DAY = 86_400_000;
+const PAID = new Set(["confirmed", "forwarding", "forwarded", "forwarding_failed", "completed"]);
+/** At the published rates: Scribe $0.22/submitted hour, Flash $0.05/1k chars.
+ * Transcription units are 16 kHz samples; overlap is charged exactly as sent. */
+export function translationCost(kind, units) {
+    if (!["voice", "transcription"].includes(kind) || !Number.isSafeInteger(units) || units < 1 || (kind === "voice" ? units > 600 : units > 241600))
+        throw new SpeechError("invalid translation usage", 400);
+    const cost = Math.ceil(kind === "voice" ? units * 50 : units * 220_000 / 57_600_000);
+    return { cost, charge: cost * TRANSLATION_MULTIPLIER };
+}
+function cents(value) {
+    if (typeof value !== "number" && typeof value !== "string")
+        return -1;
+    const text = String(value);
+    if (!/^\d+(?:\.\d{1,2}0*)?$/.test(text))
+        return -1;
+    const result = Math.round(Number(text) * 100);
+    return Number.isSafeInteger(result) ? result : -1;
+}
+export function verifyTranslationPayment(payment, id, priceCents) {
+    return payment["id"] === id && PAID.has(String(payment["status"])) &&
+        String(payment["currency"]).toUpperCase() === "USD" && cents(payment["amount"]) === priceCents;
+}
+export class TranslationPasses {
+    options;
+    schema = null;
+    merchant = null;
+    merchantUntil = 0;
+    fetcher;
+    now;
+    constructor(options) {
+        this.options = options;
+        this.fetcher = options.fetcher ?? fetch;
+        this.now = options.now ?? Date.now;
+    }
+    async ensure() {
+        this.schema ??= (async () => {
+            await this.options.db.query(`CREATE TABLE IF NOT EXISTS translation_wallets (
+        by_account TEXT PRIMARY KEY, balance_micros BIGINT NOT NULL CHECK (balance_micros >= 0), expires_at TIMESTAMPTZ NOT NULL)`);
+            await this.options.db.query(`CREATE TABLE IF NOT EXISTS translation_orders (
+        id TEXT PRIMARY KEY, by_account TEXT NOT NULL, request_key TEXT NOT NULL, plan TEXT NOT NULL,
+        price_cents INTEGER NOT NULL CHECK (price_cents > 0), days INTEGER NOT NULL,
+        business_id TEXT NOT NULL, coin TEXT NOT NULL, payment_id TEXT UNIQUE,
+        status TEXT NOT NULL DEFAULT 'pending', created_at TIMESTAMPTZ NOT NULL,
+        credited_at TIMESTAMPTZ, expires_at TIMESTAMPTZ, UNIQUE(by_account, request_key))`);
+            await this.options.db.query(`CREATE TABLE IF NOT EXISTS translation_usage (
+        id TEXT PRIMARY KEY, by_account TEXT NOT NULL, kind TEXT NOT NULL, units BIGINT NOT NULL,
+        cost_micros BIGINT NOT NULL, charge_micros BIGINT NOT NULL, status TEXT NOT NULL DEFAULT 'reserved',
+        created_at TIMESTAMPTZ NOT NULL)`);
+            await this.options.db.query(`CREATE TABLE IF NOT EXISTS translation_checkout_limits (bucket TEXT PRIMARY KEY, attempts INTEGER NOT NULL)`);
+            await this.options.db.query("CREATE INDEX IF NOT EXISTS translation_orders_account ON translation_orders (by_account, created_at)");
+        })().catch(error => { this.schema = null; throw error; });
+        await this.schema;
+    }
+    async provider(path, init = {}) {
+        if (!this.options.key)
+            throw new SpeechError("Translation checkout is unavailable.", 503);
+        const response = await this.fetcher(`https://coinpayportal.com${path}`, {
+            ...init, signal: AbortSignal.timeout(15_000), headers: { authorization: `Bearer ${this.options.key}`, "content-type": "application/json", ...init.headers },
+        });
+        const body = await response.json();
+        if (!response.ok || body.success !== true)
+            throw new SpeechError("The payment service is unavailable. Your purchase has not been activated; retry to check its status.", 502);
+        return body;
+    }
+    async settings() {
+        if (!this.merchant || this.now() >= this.merchantUntil) {
+            this.merchantUntil = this.now() + 600_000;
+            this.merchant = this.provider("/api/supported-coins").then(body => {
+                if (!ID.test(body.business_id))
+                    throw new SpeechError("Translation checkout is unavailable.", 503);
+                const coins = COINS.filter(symbol => body.coins?.some((coin) => coin.symbol === symbol && coin.is_active && coin.has_wallet));
+                return { business: body.business_id, coins };
+            }).catch(error => { this.merchant = null; throw error; });
+        }
+        return this.merchant;
+    }
+    async access(by) {
+        await this.ensure();
+        const config = await this.settings().catch(() => ({ business: "", coins: [] }));
+        const row = by ? (await this.options.db.query("SELECT balance_micros, expires_at FROM translation_wallets WHERE by_account = $1 AND expires_at > $2", [by, new Date(this.now())])).rows[0] : null;
+        const orders = by ? (await this.options.db.query("SELECT id, payment_id, plan FROM translation_orders WHERE by_account = $1 AND status = 'pending' AND payment_id IS NOT NULL ORDER BY created_at DESC LIMIT 5", [by])).rows.map(order => ({ id: String(order["id"]), plan: String(order["plan"]), url: `https://coinpayportal.com/pay/${order["payment_id"]}` })) : [];
+        return { required: true, available: config.coins.length > 0, balanceMicros: Number(row?.["balance_micros"] ?? 0),
+            expires: row ? new Date(String(row["expires_at"])).toISOString() : null, plans: TRANSLATION_PLANS, coins: config.coins, orders,
+            rates: { transcriptionHour: 0.22, voiceThousand: 0.05, multiplier: TRANSLATION_MULTIPLIER } };
+    }
+    async require(by) {
+        await this.ensure();
+        const found = await this.options.db.query("SELECT by_account FROM translation_wallets WHERE by_account = $1 AND expires_at > $2 AND balance_micros > 0", [by, new Date(this.now())]);
+        if (!found.rows.length)
+            throw new SpeechError("Buy a translation pass to enable translated audio.", 402);
+    }
+    async eligible(accounts) {
+        await this.ensure();
+        const result = await this.options.db.query("SELECT by_account FROM translation_wallets WHERE by_account = ANY($1::text[]) AND expires_at > $2 AND balance_micros > 0", [accounts, new Date(this.now())]);
+        return result.rows.map(row => String(row["by_account"]));
+    }
+    async reserve(by, kind, units) {
+        await this.ensure();
+        const { cost, charge } = translationCost(kind, units), id = randomUUID();
+        const result = await this.options.db.query(`WITH debit AS (
+      UPDATE translation_wallets SET balance_micros = balance_micros - $2
+      WHERE by_account = $1 AND expires_at > $3 AND balance_micros >= $2 RETURNING by_account)
+      INSERT INTO translation_usage (id, by_account, kind, units, cost_micros, charge_micros, created_at)
+      SELECT $4, by_account, $5, $6, $7, $2, $3 FROM debit RETURNING id`, [by, charge, new Date(this.now()), id, kind, units, cost]);
+        if (!result.rows.length)
+            throw new SpeechError("Your translation balance is used up or expired. Buy another pass to continue.", 402);
+        return id;
+    }
+    /** Batch a shared stream's access charges in one database round trip. */
+    async reserveMany(accounts, kind, units) {
+        await this.ensure();
+        const { cost, charge } = translationCost(kind, units);
+        const result = await this.options.db.query(`WITH debit AS (
+      UPDATE translation_wallets SET balance_micros = balance_micros - $2
+      WHERE by_account = ANY($1::text[]) AND expires_at > $3 AND balance_micros >= $2 RETURNING by_account)
+      INSERT INTO translation_usage (id, by_account, kind, units, cost_micros, charge_micros, created_at)
+      SELECT gen_random_uuid()::text, by_account, $4, $5, $6, $2, $3 FROM debit RETURNING id, by_account`, [[...new Set(accounts)], charge, new Date(this.now()), kind, units, cost]);
+        return result.rows.map(row => ({ by: String(row["by_account"]), id: String(row["id"]) }));
+    }
+    async commit(id) {
+        await this.options.db.query("UPDATE translation_usage SET status = 'charged' WHERE id = $1 AND status = 'reserved'", [id]);
+    }
+    async refund(id) {
+        await this.options.db.query(`WITH undone AS (
+      UPDATE translation_usage SET status = 'refunded' WHERE id = $1 AND status = 'reserved'
+      RETURNING by_account, charge_micros)
+      UPDATE translation_wallets AS wallet SET balance_micros = wallet.balance_micros + undone.charge_micros
+      FROM undone WHERE wallet.by_account = undone.by_account`, [id]);
+    }
+    async commitMany(ids) {
+        await this.options.db.query("UPDATE translation_usage SET status = 'charged' WHERE id = ANY($1::text[]) AND status = 'reserved'", [ids]);
+    }
+    async refundMany(ids) {
+        await this.options.db.query(`WITH undone AS (
+      UPDATE translation_usage SET status = 'refunded' WHERE id = ANY($1::text[]) AND status = 'reserved'
+      RETURNING by_account, charge_micros), totals AS (SELECT by_account, SUM(charge_micros) AS charge FROM undone GROUP BY by_account)
+      UPDATE translation_wallets AS wallet SET balance_micros = wallet.balance_micros + totals.charge
+      FROM totals WHERE wallet.by_account = totals.by_account`, [ids]);
+    }
+    async checkout(by, planId, coin, requestKey) {
+        await this.ensure();
+        const plan = TRANSLATION_PLANS.find(plan => plan.id === planId);
+        if (!plan || !ID.test(requestKey))
+            throw new SpeechError("Choose a translation pass.", 400);
+        const config = await this.settings();
+        if (!config.coins.includes(coin))
+            throw new SpeechError("Choose an available payment currency.", 400);
+        // Durable caps across restarts/replicas protect the merchant's invoice quota.
+        // Retrying an existing order does not consume another invoice allowance.
+        const existing = await this.options.db.query("SELECT id FROM translation_orders WHERE by_account = $1 AND request_key = $2", [by, requestKey]);
+        if (!existing.rows.length) {
+            for (const [scope, limit] of [[`account:${by}`, 5], ["server", 50]]) {
+                const limited = await this.options.db.query(`INSERT INTO translation_checkout_limits (bucket, attempts) VALUES ($1, 1)
+          ON CONFLICT (bucket) DO UPDATE SET attempts = translation_checkout_limits.attempts + 1
+          WHERE translation_checkout_limits.attempts < $2 RETURNING attempts`, [`${scope}:${Math.floor(this.now() / DAY)}`, limit]);
+                if (!limited.rows.length)
+                    throw new SpeechError("Too many new checkouts today. Resume an existing purchase or try tomorrow.", 429);
+            }
+        }
+        const id = randomUUID();
+        await this.options.db.query(`INSERT INTO translation_orders (id, by_account, request_key, plan, price_cents, days, business_id, coin, created_at)
+      VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9) ON CONFLICT (by_account, request_key) DO NOTHING`, [id, by, requestKey, plan.id, plan.priceCents, plan.days, config.business, coin, new Date(this.now())]);
+        const order = (await this.options.db.query("SELECT * FROM translation_orders WHERE by_account = $1 AND request_key = $2", [by, requestKey])).rows[0];
+        if (order["plan"] !== plan.id || order["coin"] !== coin)
+            throw new SpeechError("This checkout already belongs to a different pass. Start a new purchase.", 409);
+        let paymentId = String(order["payment_id"] ?? "");
+        if (!paymentId) {
+            const created = await this.provider("/api/payments/create", {
+                method: "POST", headers: { "idempotency-key": `nixamp-translation-${order["id"]}` },
+                body: JSON.stringify({ business_id: order["business_id"], amount_usd: Number(order["price_cents"]) / 100,
+                    currency: coin.toLowerCase(), payment_method: "crypto", description: `Nixamp translated audio: ${plan.name} pass`,
+                    metadata: { app: "nixamp", product: "translation", order_id: order["id"] },
+                    redirect_url: `${this.options.site}/?translation_order=${order["id"]}` }),
+            });
+            paymentId = created.payment?.id;
+            if (!ID.test(paymentId ?? ""))
+                throw new SpeechError("Checkout did not return a valid payment. Retry this purchase.", 502);
+            await this.options.db.query("UPDATE translation_orders SET payment_id = $2 WHERE id = $1 AND payment_id IS NULL", [order["id"], paymentId]);
+        }
+        return { id: String(order["id"]), url: `https://coinpayportal.com/pay/${paymentId}` };
+    }
+    async check(by, id) {
+        if (!ID.test(id))
+            throw new SpeechError("Purchase not found.", 404);
+        await this.ensure();
+        const order = (await this.options.db.query("SELECT * FROM translation_orders WHERE id = $1 AND by_account = $2", [id, by])).rows[0];
+        if (!order)
+            throw new SpeechError("Purchase not found.", 404);
+        let status = String(order["status"]);
+        if (["pending", "expired"].includes(status) && order["payment_id"]) {
+            const result = await this.provider(`/api/payments/${encodeURIComponent(String(order["payment_id"]))}`);
+            const payment = result.payment;
+            if (payment && verifyTranslationPayment(payment, String(order["payment_id"]), Number(order["price_cents"]))) {
+                const now = new Date(this.now()), expires = new Date(this.now() + Number(order["days"]) * DAY);
+                // One statement atomically marks the order and adds credit. A retry,
+                // second tab or second replica cannot activate the same money twice.
+                await this.options.db.query(`WITH paid AS (
+          UPDATE translation_orders SET status = 'paid', credited_at = $3, expires_at = $4
+          WHERE id = $1 AND by_account = $2 AND status IN ('pending', 'expired') RETURNING by_account, price_cents)
+          INSERT INTO translation_wallets (by_account, balance_micros, expires_at)
+          SELECT by_account, price_cents::bigint * 10000, $4 FROM paid
+          ON CONFLICT (by_account) DO UPDATE SET
+            balance_micros = CASE WHEN translation_wallets.expires_at > $3 THEN translation_wallets.balance_micros ELSE 0 END + EXCLUDED.balance_micros,
+            expires_at = GREATEST(translation_wallets.expires_at, EXCLUDED.expires_at)`, [id, by, now, expires]);
+                status = "paid";
+            }
+            else if (payment && ["expired", "failed", "refunded"].includes(payment.status)) {
+                status = payment.status;
+                await this.options.db.query("UPDATE translation_orders SET status = $3 WHERE id = $1 AND by_account = $2 AND status = 'pending'", [id, by, status]);
+            }
+        }
+        return { status, access: await this.access(by) };
+    }
+}

package/dist/web-sites.d.ts

@@ -0,0 +1,6 @@
+export interface WebSite {
+    web: string;
+    site: string;
+}
+/** Explicit origins only: a caller's Host header must never become an invite URL. */
+export declare function webSitesFromEnv(value?: string | undefined): Map<string, WebSite>;

package/dist/web-sites.js

@@ -0,0 +1,26 @@
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+/** Explicit origins only: a caller's Host header must never become an invite URL. */
+export function webSitesFromEnv(value = process.env["NIXAMP_WEB_SITES"]) {
+    const sites = new Map();
+    if (!value)
+        return sites;
+    const entries = JSON.parse(value);
+    if (!entries || typeof entries !== "object" || Array.isArray(entries)) {
+        throw new Error("NIXAMP_WEB_SITES must map public origins to web directories");
+    }
+    for (const [origin, directory] of Object.entries(entries)) {
+        const url = new URL(origin);
+        if (!["https:", "http:"].includes(url.protocol) || url.username || url.password
+            || url.pathname !== "/" || url.search || url.hash || typeof directory !== "string") {
+            throw new Error(`Invalid web site: ${origin}`);
+        }
+        const web = resolve(directory);
+        if (!existsSync(join(web, "index.html")))
+            throw new Error(`Missing web build: ${web}`);
+        if (sites.has(url.host))
+            throw new Error(`Duplicate web host: ${url.host}`);
+        sites.set(url.host, { web, site: url.origin });
+    }
+    return sites;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nixamp",
-  "version": "0.26.7",
+  "version": "0.27.0",
   "description": "It really whips the terminal's ass. A Winamp-shaped audio player for your terminal.",
   "license": "MIT",
   "type": "module",

package/src/live-interpreter.ts

@@ -0,0 +1,194 @@
+import { encodeWav } from "./pcm-wav.ts";
+import type { SpeakerTranscript, SpeakerTurn } from "./speaker-turns.ts";
+export interface Caption { channel: string; at: number; until: number; text: string; language?: string; original?: string; sourceLanguage?: string; speaker?: string; voiceProfile?: "lower" | "higher" | "unknown"; }
+export interface VoiceChoice { id: string; name: string; gender: string; language: string; }
+export interface AudioWindow { samples: Float32Array; at: number; until: number; freshAt: number; }
+
+export interface Speaker { id: string; profile: string; voice: string; }
+/** Match provider labels across overlapping timestamps. A speaker absent from
+ * the rolling context gets a new label; pitch alone never identifies someone. */
+export class SpeakerTracker {
+  private previous: { start: number; end: number; speaker: string }[] = [];
+  private sequence = 0;
+  readonly speakers = new Map<string, Speaker>();
+  constructor(private readonly random: () => number = Math.random) {}
+  reset(): void { this.previous = []; this.sequence = 0; this.speakers.clear(); }
+
+  reconcile(turns: SpeakerTurn[], at: number, voices: VoiceChoice[]): Map<string, Speaker> {
+    const links = new Map<string, Speaker>();
+    const used = new Set<string>();
+    const candidates: { local: string; global: string; overlap: number }[] = [];
+    const totals = new Map<string, number>();
+    for (const turn of turns) for (const old of this.previous) {
+      const overlap = Math.min(at + turn.end * 1000, old.end) - Math.max(at + turn.start * 1000, old.start);
+      if (overlap > 120) { const key = `${turn.speaker}|${old.speaker}`; totals.set(key, (totals.get(key) ?? 0) + overlap); }
+    }
+    for (const [key, overlap] of totals) { const [local, global] = key.split("|"); candidates.push({ local: local!, global: global!, overlap }); }
+    for (const one of candidates.sort((a, b) => b.overlap - a.overlap)) {
+      const speaker = this.speakers.get(one.global);
+      if (speaker && !links.has(one.local) && !used.has(one.global)) { links.set(one.local, speaker); used.add(one.global); }
+    }
+    for (const turn of turns) {
+      let speaker = links.get(turn.speaker);
+      if (!speaker) {
+        // Assign contrasting stock voices, without guessing a person's
+        // gender from pitch or a noisy, short opening phrase.
+        const taken = new Set([...this.speakers.values()].map(one => one.voice));
+        const available = voices.filter(voice => !taken.has(voice.id));
+        const pool = available.length ? available : voices;
+        const voice = pool[Math.floor(this.random() * pool.length)];
+        speaker = { id: `speaker-${++this.sequence}`, profile: turn.profile, voice: voice?.id ?? "auto" };
+        this.speakers.set(speaker.id, speaker); links.set(turn.speaker, speaker);
+      }
+    }
+    this.previous = turns.map(turn => ({ start: at + turn.start * 1000, end: at + turn.end * 1000, speaker: links.get(turn.speaker)!.id }));
+    const present = new Set(this.previous.map(turn => turn.speaker));
+    for (const key of this.speakers.keys()) if (this.speakers.size > 64 && !present.has(key)) this.speakers.delete(key);
+    return links;
+  }
+}
+
+/** Listener-local interpretation for the playing media. One request in flight and only the latest pending audio window. */
+export class Interpreter {
+  readonly tracker = new SpeakerTracker();
+  private generation = 0;
+  private pending: AudioWindow | null = null;
+  private committedUntil: number | null = null;
+  private running: number | null = null;
+  private controller: AbortController | null = null;
+  private translating: number | null = null;
+  private translationController: AbortController | null = null;
+  private translations: { lines: Caption[]; language: string; target: string; until: number }[] = [];
+  constructor(private readonly options: {
+    language: () => string; speakers: () => boolean; voices: () => VoiceChoice[];
+    channel: () => string; lines: (lines: Caption[]) => void;
+    status: (text: string) => void; failed: () => void;
+    fetcher?: typeof fetch;
+  }) {}
+
+  reset(): void {
+    this.generation++; this.controller?.abort(); this.translationController?.abort();
+    this.pending = null; this.running = null; this.translating = null;
+    this.translations = []; this.committedUntil = null; this.tracker.reset();
+  }
+  push(window: AudioWindow): void {
+    this.committedUntil ??= window.freshAt;
+    this.pending = window;
+    if (this.running === null) void this.run(this.generation);
+  }
+  private async json(path: string, init: RequestInit, signal: AbortSignal): Promise<any> {
+    const response = await (this.options.fetcher ?? fetch)(path, { ...init, signal });
+    const body = await response.json();
+    if (!response.ok) throw new Error(body.error || "Audio translation is unavailable.");
+    return body;
+  }
+  private async run(generation: number): Promise<void> {
+    this.running = generation;
+    try {
+      while (this.pending && generation === this.generation) {
+        const window = this.pending; this.pending = null;
+        if (Date.now() - window.until > 12_000) continue;
+        const controller = new AbortController(); this.controller = controller;
+        const signal = AbortSignal.any([controller.signal, AbortSignal.timeout(12_000)]);
+        const speakers = this.options.speakers(), target = this.options.language();
+        const heard = await this.json(speakers ? "/api/v1/speech/speakers" : "/api/v1/speech/transcribe?live=1", {
+          method: "POST", headers: { "content-type": "audio/wav" }, body: new Uint8Array(encodeWav(speakers ? window.samples : window.samples.slice(-80_000))),
+        }, signal) as SpeakerTranscript & { text?: string };
+        if (generation !== this.generation) return;
+        const language = heard.language;
+        let lines: Caption[] = [];
+        if (speakers) {
+          const links = this.tracker.reconcile(heard.turns ?? [], window.at, this.options.voices());
+          // The watermark follows emitted words, not the newest capture
+          // interval: an overlapping window can recover audio that arrived
+          // while recognition/translation was busy. Keep unfinished phrases
+          // in that overlap so short capture intervals do not split every
+          // sentence (especially damaging when German changes word order).
+          const cutoff = this.committedUntil ?? window.freshAt;
+          const turns = heard.turns ?? [];
+          for (const [index, turn] of turns.entries()) {
+            const speaker = links.get(turn.speaker)!;
+            const words = turn.words.filter(word =>
+              window.at + (word.start + word.end) * 500 >= cutoff &&
+              (window.at + word.end * 1000 <= window.until - 100 || /[.!?。！？]$/.test(word.text)));
+            let phrase: typeof words = [];
+            const emit = (): void => {
+              if (!phrase.length) return;
+              lines.push({ channel: this.options.channel(), at: window.at + phrase[0]!.start * 1000,
+                until: window.at + phrase.at(-1)!.end * 1000, text: phrase.map(word => word.text).join(" ").trim(),
+                language, speaker: speaker.id, voiceProfile: turn.profile });
+              phrase = [];
+            };
+            for (const word of words) {
+              if (phrase.length && word.start - phrase.at(-1)!.end >= 0.45) emit();
+              phrase.push(word);
+              if (/[.!?。！？]$/.test(word.text) || phrase.map(word => word.text).join(" ").length >= 400) emit();
+            }
+            if (phrase.length && (index < turns.length - 1 ||
+              window.until - (window.at + phrase.at(-1)!.end * 1000) >= 350 ||
+              window.until - (window.at + phrase[0]!.start * 1000) >= 3000)) emit();
+          }
+        } else if (heard.text) {
+          lines = [{ channel: this.options.channel(), at: window.freshAt, until: window.until, text: heard.text, language }];
+        }
+        if (!lines.length) continue;
+        this.committedUntil = Math.max(this.committedUntil ?? window.freshAt, ...lines.map(line => line.until));
+        if (this.translations.length >= 12) throw new Error("Translation fell behind. Try again after the language model has warmed up.");
+        this.translations.push({ lines, language, target, until: window.until });
+        // Recognition of the next audio window can proceed while the text
+        // model translates this phrase. Voice synthesis is a third stage.
+        if (this.translating === null) void this.translate(this.generation);
+      }
+    } catch (error) {
+      if (generation === this.generation) { this.reset(); this.options.failed(); this.options.status(error instanceof Error ? error.message : "Live translation stopped."); }
+    } finally { if (this.running === generation) this.running = null; }
+  }
+
+  private async translate(generation: number): Promise<void> {
+    this.translating = generation;
+    try {
+      while (this.translations.length && generation === this.generation) {
+        const item = this.translations.shift()!;
+        let { lines } = item;
+        const { language, target, until } = item;
+        if (Date.now() - until > 12_000) throw new Error("Translation fell behind. Try again after the language model has warmed up.");
+        const controller = new AbortController(); this.translationController = controller;
+        if (target && language !== target) {
+          if (!language) throw new Error("The audio language could not be detected. Waiting for clearer speech.");
+          const translated = await this.json("/api/v1/translate?live=1", {
+            method: "POST", headers: { "content-type": "application/json" },
+            body: JSON.stringify({ texts: lines.map(line => line.text), from: language, to: target }),
+          }, AbortSignal.any([controller.signal, AbortSignal.timeout(12_000)])) as { texts: string[] };
+          if (translated.texts.length !== lines.length || translated.texts.some(text => !text.trim())) throw new Error("Translation omitted a phrase. Enable translated audio again to retry.");
+          lines = lines.map((line, i) => ({ ...line, original: line.text, sourceLanguage: language, language: target, text: translated.texts[i]! }));
+        }
+        if (generation !== this.generation) return;
+        if (Date.now() - until > 12_000) throw new Error("Translation fell behind. Try again after the language model has warmed up.");
+        this.options.lines(lines.flatMap(line => splitCaption(line)));
+        this.options.status(target ? `${language} → ${target} · live translation` : `Original audio language: ${language || "detecting…"}`);
+      }
+    } catch (error) {
+      if (generation === this.generation) { this.reset(); this.options.failed(); this.options.status(error instanceof Error ? error.message : "Live translation stopped."); }
+    } finally { if (this.translating === generation) this.translating = null; }
+  }
+}
+
+/** Preserve all words while respecting the speech API's character limit. */
+export function splitCaption(line: Caption): Caption[] {
+  const text = line.text.trim();
+  if (!text) return [];
+  const parts: string[] = [];
+  let rest = text;
+  while (rest.length > 600) {
+    const space = rest.lastIndexOf(" ", 600);
+    const end = space > 300 ? space : 600;
+    parts.push(rest.slice(0, end)); rest = rest.slice(end).trimStart();
+  }
+  if (rest) parts.push(rest);
+  let offset = 0;
+  return parts.map(part => {
+    const at = line.at + (line.until - line.at) * offset / text.length;
+    offset += part.length + 1;
+    return { ...line, text: part, at, until: Math.min(line.until, line.at + (line.until - line.at) * offset / text.length) };
+  });
+}