use-voice-control 0.1.85 → 0.1.87

package/speech/node/render.ts

@@ -0,0 +1,79 @@
+/**
+ * @fileoverview Rendering a loaded document to an audio file on disk.
+ *
+ * Sits between `document.ts` (what to say) and `core/kokoro-node.ts` (how to say
+ * it): resolves the output path, runs the synthesizer, and writes the WAV.
+ */
+import {
+  synthesizeSamples,
+  type KokoroAudio,
+  type KokoroNodeOptions,
+} from "../core/kokoro-node";
+import { encodeWav, wavDurationSeconds } from "../utils/wav";
+import { extensionOf, loadDocument, type LoadDocumentOptions } from "./document";
+
+export interface RenderOptions extends LoadDocumentOptions, KokoroNodeOptions {
+  /** Where to write the audio. `-` writes the WAV to stdout. */
+  output?: string;
+  /**
+   * Replace the synthesizer. Used by the tests, and by hosts that already have a
+   * model loaded and do not want a second copy.
+   */
+  synthesize?: (text: string, options: KokoroNodeOptions) => Promise<KokoroAudio>;
+}
+
+export interface RenderResult {
+  /** Path written, or `-` when the audio went to stdout. */
+  output: string;
+  /** The text that was spoken, after Markdown conversion. */
+  text: string;
+  format: "markdown" | "text";
+  source: string;
+  durationSeconds: number;
+  bytes: number;
+}
+
+/** `notes.md` becomes `notes.wav`, next to the original. */
+export function defaultOutputPath(input: string): string {
+  const extension = extensionOf(input);
+  const base = extension ? input.slice(0, -extension.length) : input;
+  return `${base}.wav`;
+}
+
+/**
+ * Reads a document, synthesizes it, and writes a WAV file.
+ *
+ * Returns the spoken text alongside the file details so a caller can show what
+ * was read without converting the document a second time.
+ */
+export async function renderDocument(options: RenderOptions): Promise<RenderResult> {
+  const document = await loadDocument(options);
+
+  if (!document.text.trim()) {
+    throw new Error(`Nothing to speak: ${document.source} has no readable text`);
+  }
+
+  const synthesize = options.synthesize ?? synthesizeSamples;
+  const { samples, sampleRate } = await synthesize(document.text, options);
+  const audio = encodeWav(samples, sampleRate);
+
+  const output =
+    options.output ??
+    (options.file && options.file !== "-" ? defaultOutputPath(options.file) : "out.wav");
+
+  if (output === "-") {
+    process.stdout.write(Buffer.from(audio));
+  } else {
+    const { writeFile } = await import("node:fs/promises");
+    await writeFile(output, Buffer.from(audio));
+  }
+
+  return {
+    output,
+    text: document.text,
+    format: document.format,
+    source: document.source,
+    durationSeconds: wavDurationSeconds(samples, sampleRate),
+    bytes: audio.byteLength,
+  };
+}

package/speech/react/useReadAloud.ts

@@ -93,6 +93,8 @@ export function useReadAloud(options: UseReadAloudOptions = {}): UseReadAloudRet
     options.voice,
     options.endpoint,
     options.maxChunkLength,
+    options.format,
+    options.markdown,
     options.synthesize,
   ]);
 

package/speech/types/types.ts

@@ -15,16 +15,45 @@ export interface TTSResult {
   contentType: string;
 }
 
-// Kokoro voices from the model
+// Kokoro voices from the model. The `a`/`b` prefix is the accent (American /
+// British English) and the `f`/`m` that follows it is the voice's gender, which
+// is how `describeKokoroVoice` derives a listing without a second catalog.
 export const KOKORO_VOICES = [
-  "af_heart", "af_alloy", "af_aoede", "af_bella",
-  "af_jessica", "af_nicole", "af_river", "af_sarah", "af_sky",
-  "am_adam", "am_echo", "am_fable", "am_fenrir",
-  "am_liam", "am_michael", "am_onyx"
+  "af_heart", "af_alloy", "af_aoede", "af_bella", "af_jessica",
+  "af_kore", "af_nicole", "af_nova", "af_river", "af_sarah", "af_sky",
+  "am_adam", "am_echo", "am_eric", "am_fenrir", "am_liam",
+  "am_michael", "am_onyx", "am_puck", "am_santa",
+  "bf_alice", "bf_emma", "bf_isabella", "bf_lily",
+  "bm_daniel", "bm_fable", "bm_george", "bm_lewis",
 ] as const;
 
 export type KokoroVoice = (typeof KOKORO_VOICES)[number];
 
+export interface KokoroVoiceDescription {
+  id: string;
+  /** Display name, e.g. `Heart` for `af_heart`. */
+  name: string;
+  /** `American English` or `British English`. */
+  accent: string;
+  gender: "Female" | "Male";
+}
+
+/**
+ * Describes a voice from its id, so listings (`--list-voices`, a voice picker)
+ * do not need a hand-maintained table that can drift from `KOKORO_VOICES`.
+ */
+export function describeKokoroVoice(id: string): KokoroVoiceDescription {
+  const [accentCode, genderCode] = id;
+  const suffix = id.slice(3) || id;
+
+  return {
+    id,
+    name: suffix.charAt(0).toUpperCase() + suffix.slice(1),
+    accent: accentCode === "b" ? "British English" : "American English",
+    gender: genderCode === "m" ? "Male" : "Female",
+  };
+}
+
 // Deepgram Aura speakers
 export const DEEPGRAM_SPEAKERS = [
   "angus", "asteria", "arcas", "orion", "orpheus", "athena",

package/speech/utils/markdown-to-speech.ts

@@ -0,0 +1,426 @@
+/**
+ * @fileoverview Turns Markdown into text a speech synthesizer can read.
+ *
+ * Markdown handed straight to a TTS engine is read literally: "hash hash Getting
+ * started", "star star important star star". This module parses the document
+ * instead and emits only the words, keeping the *structure* the marks encoded —
+ * a heading becomes its own spoken segment ending in a full stop so the
+ * synthesizer pauses, a list item becomes one sentence, a fenced code block is
+ * announced rather than spelled out.
+ *
+ * It is deliberately dependency-free and runs in the browser as well as Node, so
+ * `ReadAloudController` and the CLI can share it.
+ */
+
+/** Kind of block the converter recognised. */
+export type SpeechSegmentType =
+  | "heading"
+  | "paragraph"
+  | "list-item"
+  | "quote"
+  | "code"
+  | "table-row";
+
+export interface SpeechSegment {
+  type: SpeechSegmentType;
+  /** Spoken text of the block, with every Markdown mark already removed. */
+  text: string;
+  /** Heading level 1-6. Only set on `heading` segments. */
+  level?: number;
+}
+
+export interface MarkdownToSpeechOptions {
+  /**
+   * How headings are spoken. `text` (default) reads the heading words on their
+   * own so they land between pauses; `announce` prefixes them with "Heading:";
+   * `skip` drops them entirely.
+   */
+  headings?: "text" | "announce" | "skip";
+  /**
+   * What to do with fenced code blocks. `announce` (default) replaces the block
+   * with a short spoken note, `read` reads the code verbatim, `skip` drops it.
+   */
+  codeBlocks?: "announce" | "read" | "skip";
+  /** `text` (default) speaks the link text and drops the URL; `text-and-url` reads both. */
+  links?: "text" | "text-and-url";
+  /** `alt` (default) speaks the image's alt text; `skip` drops images. */
+  images?: "alt" | "skip";
+  /** Read the YAML front matter block. Off by default. */
+  frontMatter?: boolean;
+  /** `rows` (default) reads table rows as comma-separated cells; `skip` drops tables. */
+  tables?: "rows" | "skip";
+  /**
+   * Append a full stop to blocks that do not end in punctuation, so the
+   * synthesizer pauses between them instead of running them together.
+   * Default true.
+   */
+  addTerminalPunctuation?: boolean;
+}
+
+type ResolvedOptions = Required<MarkdownToSpeechOptions>;
+
+const DEFAULTS: ResolvedOptions = {
+  headings: "text",
+  codeBlocks: "announce",
+  links: "text",
+  images: "alt",
+  frontMatter: false,
+  tables: "rows",
+  addTerminalPunctuation: true,
+};
+
+/** Spoken names for code fence languages that would otherwise be read as letters. */
+const LANGUAGE_NAMES: Record<string, string> = {
+  js: "JavaScript",
+  jsx: "JavaScript",
+  mjs: "JavaScript",
+  cjs: "JavaScript",
+  ts: "TypeScript",
+  tsx: "TypeScript",
+  py: "Python",
+  rb: "Ruby",
+  rs: "Rust",
+  sh: "shell",
+  bash: "shell",
+  zsh: "shell",
+  shell: "shell",
+  console: "shell",
+  yml: "YAML",
+  yaml: "YAML",
+  md: "Markdown",
+  json: "JSON",
+  html: "HTML",
+  css: "CSS",
+  sql: "SQL",
+  go: "Go",
+  java: "Java",
+  c: "C",
+  cpp: "C plus plus",
+  cs: "C sharp",
+  php: "PHP",
+  swift: "Swift",
+  kt: "Kotlin",
+  diff: "diff",
+  text: "",
+  txt: "",
+  plaintext: "",
+};
+
+const ENTITIES: Record<string, string> = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: " ",
+  mdash: "—",
+  ndash: "–",
+  hellip: "…",
+  ldquo: '"',
+  rdquo: '"',
+  lsquo: "'",
+  rsquo: "'",
+};
+
+const ATX_HEADING = /^ {0,3}(#{1,6})(?:\s+(.*?))?\s*$/;
+const SETEXT_UNDERLINE = /^ {0,3}(=+|-+)\s*$/;
+const THEMATIC_BREAK = /^ {0,3}([-*_])[ \t]*(?:\1[ \t]*){2,}$/;
+const FENCE_OPEN = /^ {0,3}(`{3,}|~{3,})\s*([^`]*)$/;
+const LIST_ITEM = /^ *(?:[-+*]|\d{1,9}[.)])(?:\s+(.*))?$/;
+const ORDERED_ITEM = /^ *(\d{1,9})[.)]\s+(.*)$/;
+const TASK_MARKER = /^\[([ xX])\]\s+/;
+const LINK_REFERENCE_DEFINITION = /^ {0,3}\[[^\]]+\]:\s*\S+.*$/;
+const TABLE_DELIMITER_ROW = /^[\s|:-]*-[\s|:-]*$/;
+
+/** Marks the slot where a protected substring was lifted out of the line. */
+const PLACEHOLDER_OPEN = "\u0000";
+const PLACEHOLDER_CLOSE = "\u0001";
+const PLACEHOLDER_PATTERN = /\u0000(\d+)\u0001/g;
+
+/** Ends a block with a full stop unless it already ends in sentence punctuation. */
+function withTerminalPunctuation(text: string): string {
+  return /[.!?:;,…]["')\]]?$/.test(text) ? text : `${text}.`;
+}
+
+/** Replaces `&amp;`-style entities with the characters they stand for. */
+function decodeEntities(text: string): string {
+  return text
+    .replace(/&#(\d{1,7});/g, (_m, code) => String.fromCodePoint(Number(code)))
+    .replace(/&#[xX]([0-9a-fA-F]{1,6});/g, (_m, code) =>
+      String.fromCodePoint(parseInt(code, 16))
+    )
+    .replace(/&([a-zA-Z]+);/g, (match, name) => ENTITIES[name.toLowerCase()] ?? match);
+}
+
+/**
+ * Strips the inline marks — emphasis, code spans, links, images, raw HTML — from
+ * a single line, leaving the words behind.
+ */
+export function stripInlineMarkdown(
+  input: string,
+  options: MarkdownToSpeechOptions = {}
+): string {
+  const opts: ResolvedOptions = { ...DEFAULTS, ...options };
+  const protectedRuns: string[] = [];
+  const hold = (value: string): string =>
+    `${PLACEHOLDER_OPEN}${protectedRuns.push(value) - 1}${PLACEHOLDER_CLOSE}`;
+
+  let text = input;
+
+  // Backslash escapes and code spans come out first: whatever they contain must
+  // survive the emphasis pass untouched.
+  text = text.replace(/\\([\\`*_{}[\]()#+\-.!>~|])/g, (_m, char) => hold(char));
+  text = text.replace(/(`+)([^`]|[^`][\s\S]*?[^`])\1(?!`)/g, (_m, _ticks, code) =>
+    hold(String(code).trim())
+  );
+
+  text = text.replace(/<!--[\s\S]*?-->/g, "");
+
+  // Images before links: `![alt](src)` is a link whose text starts with `!`.
+  text = text.replace(/!\[([^\]]*)\]\([^)]*\)/g, (_m, alt) =>
+    opts.images === "skip" ? "" : String(alt)
+  );
+  text = text.replace(/!\[([^\]]*)\]\[[^\]]*\]/g, (_m, alt) =>
+    opts.images === "skip" ? "" : String(alt)
+  );
+
+  // Footnote references carry no spoken meaning.
+  text = text.replace(/\[\^[^\]]+\]/g, "");
+
+  text = text.replace(/\[([^\]]*)\]\(\s*<?([^\s)]*)>?[^)]*\)/g, (_m, label, url) =>
+    opts.links === "text-and-url" && url ? `${label}, ${url}` : String(label)
+  );
+  text = text.replace(/\[([^\]]*)\]\[[^\]]*\]/g, "$1");
+
+  // Autolinks: `<https://example.com>` reads better as the bare address.
+  text = text.replace(/<((?:https?|mailto):[^>\s]+)>/gi, (_m, url) =>
+    opts.links === "text-and-url"
+      ? String(url)
+      : String(url).replace(/^mailto:/i, "")
+  );
+
+  // Remaining angle brackets are raw HTML tags.
+  text = text.replace(/<\/?[a-zA-Z][^>]*>/g, "");
+
+  text = text.replace(/\*\*\*(?=\S)([\s\S]*?\S)\*\*\*/g, "$1");
+  text = text.replace(/\*\*(?=\S)([\s\S]*?\S)\*\*/g, "$1");
+  text = text.replace(/(?<![A-Za-z0-9_])__(?=\S)([\s\S]*?\S)__(?![A-Za-z0-9_])/g, "$1");
+  text = text.replace(/~~(?=\S)([\s\S]*?\S)~~/g, "$1");
+  text = text.replace(/\*(?=\S)([^*\n]*?\S)\*/g, "$1");
+  // Underscores are only emphasis between word boundaries, so `snake_case` survives.
+  text = text.replace(/(?<![A-Za-z0-9_])_(?=\S)([^_\n]*?\S)_(?![A-Za-z0-9_])/g, "$1");
+
+  text = decodeEntities(text);
+  text = text.replace(
+    PLACEHOLDER_PATTERN,
+    (_m, index) => protectedRuns[Number(index)] ?? ""
+  );
+
+  return text.replace(/[ \t]+/g, " ").trim();
+}
+
+/** Spoken stand-in for a fenced code block, e.g. "TypeScript code block." */
+function announceCode(language: string): string {
+  const key = language.trim().split(/[\s,{]/)[0]?.toLowerCase() ?? "";
+  const name = key in LANGUAGE_NAMES ? LANGUAGE_NAMES[key] : key;
+  return name ? `${name} code block.` : "Code block.";
+}
+
+/**
+ * Parses Markdown into the blocks that should be spoken, in reading order.
+ *
+ * Use this when the caller wants the structure — to highlight the current
+ * heading, say, or to skip to a section. Callers that only need something to
+ * feed a synthesizer want {@link markdownToSpeech}.
+ */
+export function markdownToSpeechSegments(
+  markdown: string,
+  options: MarkdownToSpeechOptions = {}
+): SpeechSegment[] {
+  const opts: ResolvedOptions = { ...DEFAULTS, ...options };
+  const segments: SpeechSegment[] = [];
+
+  let source = (markdown ?? "").replace(/\r\n?/g, "\n").replace(/\t/g, "    ");
+  source = source.replace(/<!--[\s\S]*?-->/g, "");
+
+  const lines = source.split("\n");
+  let index = 0;
+
+  // YAML front matter: only when it opens on the very first line.
+  if (!opts.frontMatter && /^---\s*$/.test(lines[0] ?? "")) {
+    const closing = lines.findIndex((line, i) => i > 0 && /^(---|\.\.\.)\s*$/.test(line));
+    if (closing > 0) index = closing + 1;
+  }
+
+  /** Soft-wrapped lines of the paragraph being accumulated. */
+  let paragraph: string[] = [];
+  let quoting = false;
+
+  const push = (type: SpeechSegmentType, text: string, level?: number): void => {
+    const trimmed = text.trim();
+    if (!trimmed) return;
+    const spoken = opts.addTerminalPunctuation ? withTerminalPunctuation(trimmed) : trimmed;
+    segments.push(level === undefined ? { type, text: spoken } : { type, text: spoken, level });
+  };
+
+  const flushParagraph = (): void => {
+    if (paragraph.length === 0) return;
+    const text = stripInlineMarkdown(paragraph.join(" "), opts);
+    paragraph = [];
+    const type = quoting ? "quote" : "paragraph";
+    quoting = false;
+    push(type, text);
+  };
+
+  for (; index < lines.length; index += 1) {
+    let line = lines[index];
+
+    // A fence closes any paragraph before it and swallows lines until it ends.
+    const fence = FENCE_OPEN.exec(line);
+    if (fence) {
+      flushParagraph();
+      const marker = fence[1];
+      const language = fence[2] ?? "";
+      const closingFence = new RegExp(`^ {0,3}\\${marker[0]}{${marker.length},}\\s*$`);
+      const body: string[] = [];
+      index += 1;
+      for (; index < lines.length; index += 1) {
+        if (closingFence.test(lines[index])) break;
+        body.push(lines[index]);
+      }
+      if (opts.codeBlocks === "announce") {
+        push("code", announceCode(language));
+      } else if (opts.codeBlocks === "read") {
+        push("code", body.join(" ").replace(/\s+/g, " "));
+      }
+      continue;
+    }
+
+    if (line.trim() === "") {
+      flushParagraph();
+      continue;
+    }
+
+    // Blockquote markers are stripped so the quoted content is parsed normally.
+    let isQuote = false;
+    while (/^ {0,3}>\s?/.test(line)) {
+      line = line.replace(/^ {0,3}>\s?/, "");
+      isQuote = true;
+    }
+    if (isQuote) {
+      if (paragraph.length === 0) quoting = true;
+      if (line.trim() === "") {
+        flushParagraph();
+        continue;
+      }
+    }
+
+    if (THEMATIC_BREAK.test(line)) {
+      flushParagraph();
+      continue;
+    }
+
+    const heading = ATX_HEADING.exec(line);
+    if (heading) {
+      flushParagraph();
+      if (opts.headings === "skip") continue;
+      // A closing run of hashes (`## Title ##`) is decoration, not content.
+      const text = stripInlineMarkdown((heading[2] ?? "").replace(/\s+#+$/, ""), opts);
+      if (!text) continue;
+      push("heading", opts.headings === "announce" ? `Heading: ${text}` : text, heading[1].length);
+      continue;
+    }
+
+    // Setext heading: the underline applies to the single line above it.
+    const underline = SETEXT_UNDERLINE.exec(line);
+    if (underline && paragraph.length > 0 && opts.headings !== "skip") {
+      const text = stripInlineMarkdown(paragraph.join(" "), opts);
+      paragraph = [];
+      quoting = false;
+      if (text) {
+        push(
+          "heading",
+          opts.headings === "announce" ? `Heading: ${text}` : text,
+          underline[1].startsWith("=") ? 1 : 2
+        );
+      }
+      continue;
+    }
+
+    if (LINK_REFERENCE_DEFINITION.test(line) && paragraph.length === 0) continue;
+
+    if (line.trimStart().startsWith("|")) {
+      flushParagraph();
+      if (opts.tables === "skip" || TABLE_DELIMITER_ROW.test(line)) continue;
+      const cells = line
+        .trim()
+        .replace(/^\|/, "")
+        .replace(/\|$/, "")
+        .split(/(?<!\\)\|/)
+        .map((cell) => stripInlineMarkdown(cell, opts))
+        .filter((cell) => cell.length > 0);
+      if (cells.length > 0) push("table-row", cells.join(", "));
+      continue;
+    }
+
+    const item = LIST_ITEM.exec(line);
+    if (item) {
+      flushParagraph();
+      const ordered = ORDERED_ITEM.exec(line);
+      // Keep the number — a listener needs it — but drop bullets and checkboxes.
+      const body = (ordered ? ordered[2] : (item[1] ?? "")).replace(TASK_MARKER, "");
+      const text = stripInlineMarkdown(body, opts);
+      if (!text) continue;
+      push("list-item", ordered ? `${ordered[1]}. ${text}` : text);
+      continue;
+    }
+
+    paragraph.push(line.trim());
+  }
+
+  flushParagraph();
+  return segments;
+}
+
+/**
+ * Converts Markdown to plain text ready for a speech synthesizer.
+ *
+ * Blocks are separated by blank lines so downstream chunkers (`splitTextSmart`)
+ * break on them; runs of list items and table rows stay in one block so a list
+ * is not chopped into one request per bullet.
+ */
+export function markdownToSpeech(
+  markdown: string,
+  options: MarkdownToSpeechOptions = {}
+): string {
+  const segments = markdownToSpeechSegments(markdown, options);
+
+  return segments.reduce((out, segment, i) => {
+    if (i === 0) return segment.text;
+    const previous = segments[i - 1].type;
+    const runsOn =
+      (segment.type === "list-item" || segment.type === "table-row") &&
+      previous === segment.type;
+    return `${out}${runsOn ? "\n" : "\n\n"}${segment.text}`;
+  }, "");
+}
+
+/**
+ * Guesses whether a blob of text is Markdown, for callers with no filename to go
+ * on (piped stdin, a paste). Errs towards `false`: prose read as Markdown is
+ * mostly unchanged anyway, so only reasonably clear signals count.
+ */
+export function looksLikeMarkdown(text: string): boolean {
+  if (!text) return false;
+  const sample = text.slice(0, 20000);
+  const signals = [
+    /^ {0,3}#{1,6}\s+\S/m,
+    /^ {0,3}(?:```|~~~)/m,
+    /^ {0,3}[-+*]\s+\S/m,
+    /^ {0,3}>\s+\S/m,
+    /\[[^\]]+\]\([^)]+\)/,
+    /(?<![A-Za-z0-9])\*\*\S[\s\S]*?\S\*\*/,
+    /^ {0,3}\|.*\|\s*$/m,
+  ];
+  return signals.filter((pattern) => pattern.test(sample)).length >= 2;
+}

package/speech/utils/wav.ts

@@ -0,0 +1,89 @@
+/**
+ * @fileoverview Minimal WAV (RIFF) encoder for raw Float32 PCM.
+ *
+ * The browser path gets its WAV from `convertAudioBufferToWav`, which needs a Web
+ * Audio `AudioBuffer`. Node has no such thing: the Kokoro model hands back a bare
+ * `Float32Array`, and long documents are synthesized one chunk at a time and
+ * joined before encoding. Both of those are pure buffer work, so they live here
+ * with no platform dependency.
+ */
+
+/** Number of bytes in the fixed RIFF/fmt/data header this encoder writes. */
+const HEADER_BYTES = 44;
+
+/**
+ * Joins per-chunk sample buffers into one contiguous track.
+ *
+ * @param chunks Sample buffers in playback order.
+ * @param silenceSamples Samples of silence to insert between chunks, so the
+ *   seams between separately synthesized chunks do not sound clipped.
+ */
+export function concatSamples(
+  chunks: Float32Array[],
+  silenceSamples = 0
+): Float32Array {
+  const gaps = Math.max(chunks.length - 1, 0) * Math.max(silenceSamples, 0);
+  const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0) + gaps;
+  const out = new Float32Array(total);
+
+  let offset = 0;
+  chunks.forEach((chunk, i) => {
+    out.set(chunk, offset);
+    offset += chunk.length;
+    if (i < chunks.length - 1) offset += Math.max(silenceSamples, 0);
+  });
+
+  return out;
+}
+
+/**
+ * Encodes Float32 samples (nominally -1..1) as a 16-bit PCM WAV file.
+ *
+ * @param samples Interleaved samples when `channels` is greater than 1.
+ * @param sampleRate Sample rate of the audio, e.g. 24000 for Kokoro.
+ * @param channels Channel count. Kokoro is mono.
+ */
+export function encodeWav(
+  samples: Float32Array,
+  sampleRate = 24000,
+  channels = 1
+): ArrayBuffer {
+  const buffer = new ArrayBuffer(HEADER_BYTES + samples.length * 2);
+  const view = new DataView(buffer);
+
+  const writeString = (offset: number, value: string): void => {
+    for (let i = 0; i < value.length; i += 1) {
+      view.setUint8(offset + i, value.charCodeAt(i));
+    }
+  };
+
+  const byteRate = sampleRate * channels * 2;
+
+  writeString(0, "RIFF");
+  view.setUint32(4, 36 + samples.length * 2, true);
+  writeString(8, "WAVE");
+  writeString(12, "fmt ");
+  view.setUint32(16, 16, true); // PCM header size
+  view.setUint16(20, 1, true); // format: PCM
+  view.setUint16(22, channels, true);
+  view.setUint32(24, sampleRate, true);
+  view.setUint32(28, byteRate, true);
+  view.setUint16(32, channels * 2, true); // block align
+  view.setUint16(34, 16, true); // bits per sample
+  writeString(36, "data");
+  view.setUint32(40, samples.length * 2, true);
+
+  for (let i = 0; i < samples.length; i += 1) {
+    // Clamp before scaling: the model occasionally overshoots 1.0 and wrapping
+    // a 16-bit sample turns that into a loud click.
+    const sample = Math.max(-1, Math.min(1, samples[i]));
+    view.setInt16(HEADER_BYTES + i * 2, sample < 0 ? sample * 0x8000 : sample * 0x7fff, true);
+  }
+
+  return buffer;
+}
+
+/** Duration of a Float32 track in seconds, for progress and log lines. */
+export function wavDurationSeconds(samples: Float32Array, sampleRate: number): number {
+  return sampleRate > 0 ? samples.length / sampleRate : 0;
+}