@gtanczyk/diorama 0.0.0-stage → 0.1.0

package/app/src/sound/plan.ts

@@ -0,0 +1,154 @@
+// sound.json: what a world sounds like. Spark plans it from the world, each place's brief and floors,
+// and the story; code turns each line into a stable sound id, so a re-plan only regenerates what changed.
+import { z } from 'zod';
+import type { Memo } from '../meta/memo.ts';
+import { askSparkJson } from '../meta/spark.ts';
+import type { Brief } from '../scene/brief.ts';
+import type { Layout } from '../scene/layout.ts';
+import type { Story } from '../story/schema.ts';
+import { Fact } from '../story/schema.ts';
+import type { World } from '../world/schema.ts';
+
+const Prompt = z.string().min(8);
+/** 1 quiet, 2 normal, 3 loud: how it sits in the mix next to the place bed. */
+const Level = z.union([z.literal(1), z.literal(2), z.literal(3)]).default(2);
+
+export const SoundPlan = z.object({
+  /** Hash of what the plan was made from (world, story, briefs, floors); when that changes the plan is made again. */
+  from: z.string().optional(),
+  /** A music bed for the whole world, looped under everything. */
+  music: z.object({ prompt: Prompt }),
+  places: z.record(z.string(), z.object({
+    /** The constant air of the place: wind, sea, room tone. */
+    bed: Prompt,
+    /** A sound that comes from one thing and pans and fades with where the hero stands. */
+    loops: z.array(z.object({ thing: z.string(), prompt: Prompt, level: Level, when: z.array(Fact).default([]) })).max(6).default([]),
+    /** Floor key (layout.json) to the surface the hero's feet hit there. */
+    floors: z.record(z.string(), z.string()),
+  })),
+  /** Surface name to what a few footsteps on it sound like. */
+  steps: z.record(z.string(), Prompt),
+  /** Short one-shots: picking up an item, an exit, using a thing, the ending. */
+  shots: z.array(z.object({ on: z.string(), prompt: Prompt, seconds: z.number().min(0.5).max(5).default(1.5), level: Level })).max(16).default([]),
+});
+export type SoundPlan = z.infer<typeof SoundPlan>;
+
+/** What fires a one-shot; the runtime matches these. */
+export const SHOT_TRIGGERS = ['take', 'exit:<thing key>', 'use:<thing key>', 'talk', 'ending', 'click'] as const;
+
+export const slugOf = (text: string) => text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 40) || 'x';
+
+/** The id a planned sound is stored and played under. Ids depend on what the sound is for, never on its prompt. */
+export const soundIds = {
+  music: () => 'music',
+  bed: (place: string) => `${place}-bed`,
+  loop: (place: string, thing: string) => `${place}-${thing}-loop`,
+  step: (surface: string) => `step-${slugOf(surface)}`,
+  shot: (on: string) => `shot-${slugOf(on)}`,
+};
+
+export type PlaceSources = { brief?: Brief; layout?: Layout };
+
+export function planIssues(plan: SoundPlan, world: World, sources: Record<string, PlaceSources>): string[] {
+  const issues: string[] = [];
+  for (const place of world.places) {
+    const p = plan.places[place.key];
+    if (!p) {
+      issues.push(`no sounds for place ${place.key}`);
+      continue;
+    }
+    const things = new Set(place.things.map((t) => t.key));
+    for (const loop of p.loops) if (!things.has(loop.thing)) issues.push(`${place.key}: loop on "${loop.thing}", which is not one of its things`);
+    for (const floor of sources[place.key]?.layout?.floors ?? []) {
+      const surface = p.floors[floor.key];
+      if (!surface) issues.push(`${place.key}: floor ${floor.key} has no surface`);
+      else if (!plan.steps[surface]) issues.push(`${place.key}: surface "${surface}" of ${floor.key} has no footsteps in steps`);
+    }
+    // Every thing the brief animates should be heard too, unless it is silent by nature (a light, cloth).
+    // A moving floor (water under a quay) has nothing to pan to; the bed carries it.
+    // A boat the brief sets bobbing on the water ("water") is heard in the water's bed, not on its own.
+    for (const alive of sources[place.key]?.brief?.alive ?? []) {
+      if (things.has(alive.key) && ['water', 'fire', 'smoke'].includes(alive.as) && !(alive.as === 'water' && AFLOAT.test(alive.key)) && !p.loops.some((l) => l.thing === alive.key)) issues.push(`${place.key}: ${alive.key} is ${alive.as} but makes no sound`);
+    }
+  }
+  return issues;
+}
+
+/** Things that ride the water rather than being it. */
+const AFLOAT = /(^|-)(boats?|rowboat|dinghy|skiff|canoe|kayak|raft|ship|barge|ferry|yacht|sailboats?|buoy|[łl][óo]d[źz]|[łl]odzie|[łl][óo]dka|statek|tratwa)(-|$)/;
+
+/** Drops loops on keys that are not things of their place (a floor, say): nothing in the page to pan them to. */
+export function withoutStrayLoops(plan: SoundPlan, world: World): SoundPlan {
+  const places = Object.fromEntries(Object.entries(plan.places).map(([key, p]) => {
+    const things = new Set(world.places.find((w) => w.key === key)?.things.map((t) => t.key) ?? []);
+    return [key, { ...p, loops: p.loops.filter((l) => things.has(l.thing)) }];
+  }));
+  return { ...plan, places };
+}
+
+/**
+ * Things silent by nature (a lamp, a sign) or heard only when used (a ticket machine): a loop on them is three takes
+ * of hiss or one click in silence, all turned down. Dropped before anything is paid for, unless the brief animates
+ * the thing as fire, water or smoke (an oil lantern's flame).
+ */
+const SILENT = /(^|-)(lamp|lamps|lantern|lanterns|light|lights|streetlight|sign|signs|poster|posters|timetable|schedule|map|ticket|tickets|ticket-machine|validator|kasownik|latarnia|latarka|lampa|znak|plakat|rozklad|bilet|biletomat)(-|$)/;
+export function withoutSilentLoops(plan: SoundPlan, sources: Record<string, PlaceSources> = {}): SoundPlan {
+  const places = Object.fromEntries(Object.entries(plan.places).map(([key, p]) => {
+    const alive = new Set((sources[key]?.brief?.alive ?? []).filter((a) => ['water', 'fire', 'smoke'].includes(a.as)).map((a) => a.key));
+    return [key, { ...p, loops: p.loops.filter((l) => alive.has(l.thing) || !SILENT.test(l.thing)) }];
+  }));
+  return { ...plan, places };
+}
+
+function storyLines(story: Story | null): string[] {
+  if (!story) return [];
+  const lines = story.interactions.filter((i) => i.verb !== 'look').map((i) => `- ${i.place}: ${i.verb} ${i.thing}${i.with ? ` with ${i.with}` : ''} -> "${i.say}"`);
+  for (const c of story.changes) lines.push(`- ${c.place}: once ${c.when.join(' and ')}, ${c.thing} becomes "${c.looks}"`);
+  return lines;
+}
+
+export async function writeSoundPlan(memo: Memo, world: World, story: Story | null, sources: Record<string, PlaceSources>): Promise<SoundPlan> {
+  const places = world.places.map((place) => {
+    const brief = sources[place.key]?.brief;
+    const floors = sources[place.key]?.layout?.floors ?? [];
+    return `## ${place.key}
+Shows: ${place.shows}
+Mood: ${place.mood}
+Things: ${place.things.map((t) => `${t.key} (${t.role}: ${brief?.looks[t.key] ?? t.looks})`).join('; ')}
+Moving things: ${brief?.alive.map((a) => `${a.key} is ${a.as}`).join(', ') || 'none'}
+Floors: ${floors.map((f) => `${f.key} (${brief?.looks[f.key] ?? f.is})`).join('; ') || 'none'}
+Exits: ${place.exits.map((e) => `${e.via} to ${e.to}`).join(', ') || 'none'}`;
+  }).join('\n\n');
+  const prompt = `You are the sound designer of a 2D painted point-and-click adventure. Each sound you describe is generated by a text-to-sound model, so every prompt names concrete sources, materials, distance and character, never music theory or feelings alone.
+
+Game: ${world.title}. ${world.pitch}
+Look: ${world.style}
+
+${places}
+
+What the hero does in the story:
+${storyLines(story).join('\n') || '- (no story yet)'}
+
+Plan:
+- music: one instrumental music bed for the whole game, under everything: instruments, tempo, mood. No vocals.
+- per place: "bed", the quiet ambience of the place (water, distant life, birds far off, a room's warm hum) that loops for minutes without a single event standing out. Not wind, rustling leaves, "air tone" or breathing: those come out as hiss that tires the ear under the whole game. No footsteps, no voices, no music in it.
+- per place: "loops", at most 2 sounds that come from one of its things (thing key from its Things) and go on without stopping: running water, fire, a running engine or fan, a ticking clock, animals. Most places need 0 or 1. Only for things that make that sound all by themselves; every loop costs money to make. Never for lights, lamps, lanterns, signs, posters or timetables (they are silent), not for trees, bushes or grass in the wind, not for someone breathing, and not for things that sound only when used (a ticket machine, a door, a bell, a till): give those a "use:<thing>" shot instead. "when" lists story facts that must hold for it to play, e.g. ["lamp-lit"] for a fire that starts in the story (use [] when always). level 1 quiet, 2 normal, 3 loud.
+- per place: "floors", each floor key to a surface name such as "wood", "wet-wood", "stone", "gravel", "grass", "sand", "metal", "carpet". Reuse surface names across places.
+- "steps": each surface name used to a prompt for a few separate footsteps of one person walking on it, e.g. "slow footsteps of boots on wet wooden planks, 6 separate steps, dry close recording".
+- "shots": short one-shot effects. "on" is one of: ${SHOT_TRIGGERS.join(', ')}. Give one for "take" (picking up an item), "click" (a soft UI click), "talk" (a short sound as a conversation starts), "ending", one "exit:<thing>" per exit thing (exits of the same kind, two wooden doors or two garden gates, share one sound: give them word for word the same prompt, seconds and level, so it is made once), and "use:<thing>" for things the story changes when used. "seconds" 0.5 to 4.
+
+Reply with JSON only:
+{"music": {"prompt": "..."}, "places": {"<place key>": {"bed": "...", "loops": [{"thing": "<thing key>", "prompt": "...", "level": 2, "when": []}], "floors": {"<floor key>": "<surface>"}}}, "steps": {"<surface>": "..."}, "shots": [{"on": "take", "prompt": "...", "seconds": 1.5, "level": 2}]}`;
+  let feedback = '';
+  for (let attempt = 1; ; attempt++) {
+    const answer = await askSparkJson(memo, { label: `sound-plan${attempt > 1 ? `-${attempt}` : ''}`, prompt: prompt + feedback });
+    const parsed = SoundPlan.safeParse(answer);
+    const issues = parsed.success ? planIssues(parsed.data, world, sources) : parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`);
+    if (!issues.length && parsed.success) return withoutSilentLoops(parsed.data, sources);
+    if (attempt === 2) {
+      if (!parsed.success) throw new Error(`sound plan: ${issues.join('; ')}`);
+      return withoutSilentLoops(withoutStrayLoops(parsed.data, world), sources); // usable; the step prints what is still missing
+    }
+    feedback = `\n\nYour last plan had these problems, fix them:\n${issues.map((i) => `- ${i}`).join('\n')}`;
+  }
+}

package/app/src/sound/retry.ts

@@ -0,0 +1,43 @@
+import { refreshExistingLipSync } from './lipsync-make.ts';
+import type { WorldFiles } from '../world/files.ts';
+import { Story } from '../story/schema.ts';
+import { creditGuard } from './cost.ts';
+import { elevenKey } from './sources.ts';
+import { DesignedVoices, freeVoiceSlot, PENDING_DESIGN, storyLines, voiceLine, Voices } from './voices.ts';
+
+/** Resolve at queue time and again when the job starts, so removed dialogue cannot be regenerated. */
+export function voiceRetryTarget(files: WorldFiles, speaker: string, text: string) {
+  const saved = files.readJson(files.path('voices.json')) as Voices;
+  const old = Voices.parse(saved);
+  const line = storyLines(files.world(), Story.parse(files.readJson(files.path('story.json'))), true).find((l) => l.speaker === speaker && l.text === text);
+  if (!line) throw new Error('this speaker no longer says that line');
+  const voice = old.cast[speaker];
+  if (!voice || voice.voice === PENDING_DESIGN) throw new Error('the voice is not ready; run voices to finish voice design first');
+  return { old, saved, line, voice };
+}
+
+/** Retry only this line, preserving the cast, every other recording and every other failure. */
+export async function retryVoiceLine(files: WorldFiles, speaker: string, text: string) {
+  const { old, saved, line, voice } = voiceRetryTarget(files, speaker, text);
+  if (!elevenKey()) throw new Error('no ELEVENLABS_API_KEY');
+  const guard = await creditGuard(elevenKey(), 'voice retry');
+  if (voice.design && !(await freeVoiceSlot())) throw new Error('No free ElevenLabs voice slot; free one and retry. The selected voice is unchanged.');
+  const same = (l: { speaker: string; text: string }) => l.speaker === speaker && l.text === text;
+  const failed = old.failures.find(same);
+  const designed = new DesignedVoices(`diorama ${files.slug}`);
+  try {
+    const result = await voiceLine(files.memo, line, voice, (id, mp3) => {
+      const file = `sound/voice/${id}.mp3`;
+      files.write(files.path(file), mp3);
+      return file;
+    }, designed, { retryRejected: failed?.reason.startsWith('speech rejected') });
+    files.write(files.path('voices.json'), { ...saved, lines: [...saved.lines.filter((l) => !same(l)), result], failures: old.failures.filter((l) => !same(l)) });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    // Do not discard a previous recording if a requested replacement fails.
+    files.write(files.path('voices.json'), { ...saved, failures: [...old.failures.filter((l) => !same(l)), { speaker, text, reason }] });
+    throw error;
+  } finally { if (voice.design) await designed.close(); }
+  await refreshExistingLipSync(files, [speaker]);
+  console.log(`voice retry ${speaker}: ${text} · ${await guard.report()}`);
+}

package/app/src/sound/settings.ts

@@ -0,0 +1,28 @@
+// Machine-wide audio quality, shared by Studio and CLI jobs.
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { configDir } from '../secrets.ts';
+import type { Quality } from './cost.ts';
+
+const file = () => path.join(configDir(), 'sound.json');
+
+export function readSoundQuality(): Quality {
+  let raw: string;
+  try { raw = fs.readFileSync(file(), 'utf8'); }
+  catch (e) { if ((e as NodeJS.ErrnoException).code === 'ENOENT') return 'final'; throw e; }
+  const quality = JSON.parse(raw).quality;
+  if (quality !== 'final' && quality !== 'draft') throw new Error('Saved audio quality must be final or draft');
+  return quality;
+}
+
+export function writeSoundQuality(quality: Quality) {
+  if (quality !== 'final' && quality !== 'draft') throw new Error('Audio quality must be final or draft');
+  const target = file();
+  fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+  const tmp = `${target}.${randomUUID()}.tmp`;
+  try {
+    fs.writeFileSync(tmp, `${JSON.stringify({ quality }, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, target);
+  } finally { fs.rmSync(tmp, { force: true }); }
+}

package/app/src/sound/sources.ts

@@ -0,0 +1,81 @@
+// Where sounds come from. The Meta Model API has no audio generation, so effects come from ElevenLabs
+// and music from Meta's open-weights MusicGen run locally (or ElevenLabs music when Python is not set up).
+// Every take is kept in the memo by a hash of its request, so a rerun never pays twice.
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { inputHash, type Memo } from '../meta/memo.ts';
+import { checkCredits, noteRefusal, ttsModel } from './cost.ts';
+
+const ELEVEN = 'https://api.elevenlabs.io/v1';
+
+export function elevenKey(): string | undefined {
+  return process.env.ELEVENLABS_API_KEY || process.env.ELEVEN_API_KEY;
+}
+
+async function elevenPost(route: string, body: unknown): Promise<Buffer> {
+  const key = elevenKey();
+  if (!key) throw new Error('no ElevenLabs key: set ELEVENLABS_API_KEY');
+  checkCredits();
+  for (let n = 1; ; n++) {
+    const res = await fetch(ELEVEN + route, { method: 'POST', headers: { 'xi-api-key': key, 'Content-Type': 'application/json' }, body: JSON.stringify(body) });
+    if (res.ok) return Buffer.from(await res.arrayBuffer());
+    const text = (await res.text()).slice(0, 300);
+    noteRefusal(res.status, text);
+    if (![429, 500, 502, 503].includes(res.status) || n === 4) throw new Error(`ElevenLabs ${route}: ${res.status} ${text}`);
+    await new Promise((r) => setTimeout(r, 1000 * 2 ** n));
+  }
+}
+
+export type EffectAsk = { label: string; prompt: string; seconds: number; loop: boolean; take?: number };
+
+/** An effect or ambience from ElevenLabs text-to-sound, as mp3. `take` > 1 asks again for a different take. */
+const effectBody = (ask: EffectAsk) => ({ text: ask.prompt, duration_seconds: ask.seconds, loop: ask.loop, prompt_influence: 0.45, model_id: 'eleven_text_to_sound_v2' });
+const effectHash = (ask: EffectAsk) => inputHash('eleven-sfx', JSON.stringify(effectBody(ask)), String(ask.take ?? 1));
+
+export function soundEffect(memo: Memo, ask: EffectAsk): Promise<Buffer> {
+  return memo.remember('sound', ask.label, effectHash(ask), 'mp3', () => elevenPost('/sound-generation', effectBody(ask)));
+}
+
+/** A take the quality checks turned down is forgotten, so the next run asks for a new one instead of replaying it. */
+export function forgetEffect(memo: Memo, ask: EffectAsk) {
+  memo.forget('sound', effectHash(ask), 'mp3');
+}
+
+/** Music from ElevenLabs, for when MusicGen is not available. */
+export function elevenMusic(memo: Memo, label: string, prompt: string, seconds: number): Promise<Buffer> {
+  const body = { prompt, music_length_ms: Math.round(seconds * 1000), model_id: 'music_v1', force_instrumental: true };
+  return memo.remember('sound', label, inputHash('eleven-music', JSON.stringify(body)), 'mp3', () => elevenPost('/music', body));
+}
+
+const MUSICGEN_PY = fileURLToPath(new URL('./musicgen.py', import.meta.url));
+export const MUSICGEN_MODEL = 'facebook/musicgen-small';
+
+/** The Python that has torch and transformers: DIORAMA_PYTHON, or none. */
+export function musicgenPython(): string | undefined {
+  const py = process.env.DIORAMA_PYTHON;
+  if (!py) return undefined;
+  try {
+    execFileSync(py, ['-c', 'import torch, transformers'], { stdio: 'ignore' });
+    return py;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Music from Meta's MusicGen (open weights, runs on CPU in a few minutes), as wav. */
+export function musicgen(memo: Memo, label: string, prompt: string, seconds: number, python: string): Promise<Buffer> {
+  return memo.remember('music', label, inputHash(MUSICGEN_MODEL, prompt, String(seconds)), 'wav', async () => {
+    const out = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'musicgen-')), 'out.wav');
+    execFileSync(python, ['-I', MUSICGEN_PY, MUSICGEN_MODEL, prompt, String(seconds), out], { stdio: ['ignore', 'inherit', 'inherit'] });
+    return fs.readFileSync(out);
+  });
+}
+
+/** Speech in any language ElevenLabs reads (Flash v2.5: cheap and quick), as mp3. */
+export function elevenSpeech(memo: Memo, label: string, text: string, voice: string): Promise<Buffer> {
+  const body = { text, model_id: ttsModel() };
+  return memo.remember('voice', label, inputHash('eleven-tts', voice, JSON.stringify(body)), 'mp3', () => elevenPost(`/text-to-speech/${voice}?output_format=mp3_44100_128`, body));
+}

package/app/src/sound/spoken.ts

@@ -0,0 +1,70 @@
+// What a line sounds like read aloud: "10+10=20" on screen is "dziesięć plus dziesięć równa się dwadzieścia" spoken.
+// The voice actor reads the spoken form, and the transcript is checked against it, so a line with digits and signs
+// is neither left to the actor's guess nor failed because the transcriber wrote words where the line has digits.
+import { languageKey } from './language.ts';
+
+type Words = { number: (n: number) => string; ops: Record<string, string> };
+
+const PL_UNITS = ['zero', 'jeden', 'dwa', 'trzy', 'cztery', 'pięć', 'sześć', 'siedem', 'osiem', 'dziewięć'];
+const PL_TEENS = ['dziesięć', 'jedenaście', 'dwanaście', 'trzynaście', 'czternaście', 'piętnaście', 'szesnaście', 'siedemnaście', 'osiemnaście', 'dziewiętnaście'];
+const PL_TENS = ['', '', 'dwadzieścia', 'trzydzieści', 'czterdzieści', 'pięćdziesiąt', 'sześćdziesiąt', 'siedemdziesiąt', 'osiemdziesiąt', 'dziewięćdziesiąt'];
+const PL_HUNDREDS = ['', 'sto', 'dwieście', 'trzysta', 'czterysta', 'pięćset', 'sześćset', 'siedemset', 'osiemset', 'dziewięćset'];
+
+function plBelow1000(n: number): string[] {
+  const h = Math.floor(n / 100), r = n % 100, t = Math.floor(r / 10), u = r % 10;
+  return [PL_HUNDREDS[h], r >= 10 && r < 20 ? PL_TEENS[r - 10] : PL_TENS[t], r >= 10 && r < 20 ? '' : u ? PL_UNITS[u] : ''].filter(Boolean);
+}
+
+function plNumber(n: number): string {
+  if (n === 0) return PL_UNITS[0];
+  const thousands = Math.floor(n / 1000), rest = n % 1000;
+  const k = thousands === 0 ? [] : thousands === 1 ? ['tysiąc']
+    : [...plBelow1000(thousands), [2, 3, 4].includes(thousands % 10) && ![12, 13, 14].includes(thousands % 100) ? 'tysiące' : 'tysięcy'];
+  return [...k, ...plBelow1000(rest)].join(' ');
+}
+
+const EN_UNITS = ['zero', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten', 'eleven', 'twelve', 'thirteen', 'fourteen', 'fifteen', 'sixteen', 'seventeen', 'eighteen', 'nineteen'];
+const EN_TENS = ['', '', 'twenty', 'thirty', 'forty', 'fifty', 'sixty', 'seventy', 'eighty', 'ninety'];
+
+function enBelow1000(n: number): string[] {
+  const h = Math.floor(n / 100), r = n % 100;
+  const tail = r === 0 ? [] : r < 20 ? [EN_UNITS[r]] : [EN_TENS[Math.floor(r / 10)] + (r % 10 ? `-${EN_UNITS[r % 10]}` : '')];
+  return [...(h ? [EN_UNITS[h], 'hundred'] : []), ...tail];
+}
+
+function enNumber(n: number): string {
+  if (n === 0) return 'zero';
+  const thousands = Math.floor(n / 1000), rest = n % 1000;
+  return [...(thousands ? [...enBelow1000(thousands), 'thousand'] : []), ...enBelow1000(rest)].join(' ');
+}
+
+const LANGUAGES: Record<string, Words> = {
+  pl: { number: plNumber, ops: { '+': 'plus', '-': 'minus', '−': 'minus', '×': 'razy', '*': 'razy', '÷': 'podzielić przez', '=': 'równa się' } },
+  en: { number: enNumber, ops: { '+': 'plus', '-': 'minus', '−': 'minus', '×': 'times', '*': 'times', '÷': 'divided by', '=': 'equals' } },
+};
+
+/** Whole numbers up to 999 999 read as words; others (a year said its own way, decimals) are left to the actor. */
+const NUMBER = /(?<![\d.,:])\d{1,6}(?![\d]|[.,:]\d)/g;
+
+/** The line as it is said: whole numbers as words, and a sign between two numbers ("10+10", "3 × 4 = 12") as its word. */
+export function spokenText(text: string, language?: string): string {
+  const words = LANGUAGES[languageKey(language)];
+  if (!words) return text;
+  const signs = Object.keys(words.ops).map((s) => s.replace(/[-*+]/g, '\\$&')).join('');
+  // Only between numbers: a dash between words is punctuation, not "minus".
+  const between = new RegExp(`(\\d)\\s*([${signs}])\\s*(?=\\d)`, 'g');
+  // "22 000" is one number: a space (or a no-break one) between thousands goes first.
+  let out = text.replace(/(?<![\d.,])(\d{1,3})[ \u00a0](\d{3})(?![\d])/g, '$1$2');
+  for (let i = 0; i < 2; i++) out = out.replace(between, (_, a: string, op: string) => `${a} ${words.ops[op]} `);
+  return out.replace(NUMBER, (d) => words.number(Number(d))).replace(/\s+/g, ' ');
+}
+
+/** The number words of a language, in the order said: "dziesięć plus dziesięć równa się dwadzieścia" has dziesięć, dziesięć, dwadzieścia. */
+export function numberWords(spoken: string, language?: string): string[] {
+  const words = LANGUAGES[languageKey(language)];
+  if (!words) return [];
+  const vocabulary = new Set(language && languageKey(language) === 'pl'
+    ? [...PL_UNITS, ...PL_TEENS, ...PL_TENS, ...PL_HUNDREDS, 'tysiąc', 'tysiące', 'tysięcy'].filter(Boolean)
+    : [...EN_UNITS, ...EN_TENS, 'hundred', 'thousand'].filter(Boolean));
+  return spoken.normalize('NFC').toLowerCase().split(/[^\p{L}]+/u).flatMap((w) => w.split('-')).filter((w) => vocabulary.has(w));
+}