Skip to content
Back to search

site-narrator

SkillWorks with Claude CodeGitHub

Give a website a pre-recorded voice with no paid speech service. Collects the lines of text a site should be able to read aloud, records each one locally with the free Kokoro text-to-speech model, names every MP3 by a hash of its text, and plays the right file in the browser with a small dependency-free player (queue, stop, per-line events, loudness level for a talking mouth, voice on/off). Use whenever the user wants a page, article, docs site, guide, tutorial or character to "read aloud", "speak", "narrate", have a "listen" button, "text to speech", "TTS", "voice-over for the site", "audio version of this page", or wants to re-record, re-voice, fix a pronunciation in, or check narration made this way.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 21 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/VinVirtual/site-narrator with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/VinVirtual/site-narrator'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vinvirtual--site-narrator/badge.svg)](/listings/vinvirtual--site-narrator)

HTML

<a href="/listings/vinvirtual--site-narrator"><img src="/api/listings/vinvirtual--site-narrator/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 1. the skill itself (for Claude Code; any folder works if you only use the command line)
git clone https://github.com/VinVirtual/site-narrator ~/.claude/skills/site-narrator

# 2. voice: a Python venv with Kokoro and an MP3 encoder, and the two model files
#    (on Debian or Ubuntu, first: sudo apt install python3-venv)
python3 -m venv ~/kokoro/.venv
~/kokoro/.venv/bin/pip install kokoro-onnx lameenc
curl -L -o ~/kokoro/kokoro-v1.0.onnx https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.1/kokoro-v1.0.onnx
curl -L -o ~/kokoro/voices-v1.0.bin  https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.1/voices-v1.0.bin

# 3. check
~/.claude/skills/site-narrator/narrate check

Everything is found in default places that you can change with environment variables:

| Variable | Default | What | |---|---|---| | `KOKORO_HOME` | `~/kokoro` | folder with the model files and the `.venv` | | `KOKORO_MODEL`, `KOKORO_VOICES` | `$KOKORO_HOME/kokoro-v1.0.onnx`, `$KOKORO_HOME/voices-v1.0.bin` | the two model files | | `NARRATE_PYTHON` | `$KOKORO_HOME/.venv/bin/python`, else `python3` | Python that has kokoro-onnx | | `NARRATE_FFMPEG` | `ffmpeg` on PATH, else the one from the `imageio-ffmpeg` package | ffmpeg binary, only used when lameenc is missing or `--encoder ffmpeg` is given |

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 81 lines
  1. ---
  2. name: site-narrator
  3. description: Give a website a pre-recorded voice with no paid speech service. Collects the lines of text a site should be able to read aloud, records each one locally with the free Kokoro text-to-speech model, names every MP3 by a hash of its text, and plays the right file in the browser with a small dependency-free player (queue, stop, per-line events, loudness level for a talking mouth, voice on/off). Use whenever the user wants a page, article, docs site, guide, tutorial or character to "read aloud", "speak", "narrate", have a "listen" button, "text to speech", "TTS", "voice-over for the site", "audio version of this page", or wants to re-record, re-voice, fix a pronunciation in, or check narration made this way.
  4. ---
  5. # site-narrator
  6. Local pipeline: **collect** the lines → **record** each with Kokoro TTS into `<hash>.mp3` → **manifest + verify** → **play** in the browser by hashing the same text. The site serves static MP3 files. Nothing is generated while a visitor listens, and nothing is uploaded.
  7. Skill folder: `~/.claude/skills/site-narrator/` (written below as `$N`). Every command is `$N/narrate <command> [project]`. `$N/narrate help` lists them.
  8. ```
  9. $N/narrate the command line (check, voices, collect, record, manifest, verify, serve, test)
  10. $N/cli/record.py Kokoro -> MP3 (run by `narrate record`)
  11. $N/cli/lib/ collectors, pronunciation fixes, recording plan, MP3 length, manifest, verify
  12. $N/player/player.js the browser player: copy this one file into the site
  13. $N/examples/demo/ a working page with committed recordings
  14. $N/README.md install, licences, limits, the player's full API
  15. ```
  16. ## What it cannot do
  17. Say these to the user before starting if they matter:
  18. - A fixed list of Kokoro voices. **No voice cloning**, no "make it sound like me".
  19. - Only text known ahead of time. Visitor input and per-request text cannot be spoken.
  20. - Every text edit needs `narrate record` again. Until then that line is silent (the player reports `missing` and moves on).
  21. - About 4 KB per second of speech at the default 32 kbit/s (about 240 KB a minute).
  22. - You cannot hear the result. You can check that files exist, have the right length and are not silent. The user has to listen for pronunciation and tone.
  23. ## Workflow
  24. 1. **Check the machine** with `$N/narrate check`. It tells you how to fix anything missing.
  25. 2. **Decide what gets a voice**, with the user. Prefer short, self-contained lines: a paragraph, a recap sentence, a caption. One line is one file and one highlight.
  26. 3. **Choose the source**:
  27. - Static HTML: add `data-narrate` to each element to be read. Without any, every `<p>` is taken.
  28. - Markdown or JSON: point at the file.
  29. - Text that lives in code (React, a CMS export, a glossary object): write a collector module, a `.mjs` whose default export returns the array of lines. Import the site's own data so the lines can never drift from what the page shows.
  30. 4. **Write `narrate.json`** next to the site (fields are in `README.md`): `source`, `out` (a folder the site serves, for example `public/voice`), `voice`, `speed`, `say`.
  31. - Pick the voice with the user: `$N/narrate voices`. The prefix is language and gender (`af_` American female, `am_` American male, `bf_`/`bm_` British). `lang` must suit the voice.
  32. - Around `speed` 0.95 reads more calmly than 1.
  33. 5. **Collect**: `$N/narrate collect <project>`. Read the output. Fix what should not be there (navigation text, duplicates, empty lines), and look at each `said as:` line.
  34. - Add names, abbreviations and symbols the voice will get wrong to `say` (`"SQL": "sequel"`, `"IMU": "I M U"`). Fixes are case-sensitive and whole-word.
  35. 6. **Record**: `$N/narrate record <project> --dry-run` first, then without it. It records new and changed lines, deletes this project's own recordings whose line is gone (only files its `manifest.json` lists), and writes `manifest.json`. Keep `--workers` at 2 on a shared machine. Give every project its own `out` folder; if `record` says the manifest was written for other sources, stop and ask the user before using `--adopt`.
  36. 7. **Verify**: `$N/narrate verify <project>` must end in `ok`. Fix every `ERROR`. Report the total size to the user.
  37. 8. **Wire the player**: copy `$N/player/player.js` into the site and use `createNarrator({ base })`. See "Player rules" below and the API in `README.md`.
  38. 9. **Test in a browser**: serve the site (`$N/narrate serve <folder>` for a static one), click a Listen control, and confirm `start` and `end` events fire in order and no `missing` event appears. A `missing` event means the page's text and the collected text differ.
  39. 10. **Deliver**: commit the recordings with the site. Tell the user what was recorded (lines, seconds, size), which voice, and that they need to listen to it. List any pronunciation fixes you added.
  40. After any text change: steps 5 to 7 again. Add `narrate verify` to the site's build or CI so a forgotten re-record fails loudly.
  41. ## Player rules
  42. - **Pass the same text that was collected.** For a marked element use `element.textContent`. The hash ignores white-space differences, nothing else. Never build the line differently on the page than in the collector.
  43. - **Start from a click or tap.** Browsers block sound otherwise; `speak()` then resolves with `'blocked'`. Do not auto-play narration on page load.
  44. - **Always give a Stop control and a voice on/off control** (`setEnabled`). The choice is remembered in `localStorage`.
  45. - **Say on the page that the voice is computer-generated**, near the control.
  46. - Highlight with the `start` event (`index`, plus your own `id`), clear on `done`, `stopped` and `blocked`.
  47. - For a talking mouth or meter, read `level()` inside `requestAnimationFrame` and handle `null` (keep an idle rhythm).
  48. - Recordings on another origin play as normal, and `level()` returns `null` for them. Set `crossOrigin: 'anonymous'` only when that origin sends CORS headers; without the headers the option makes every line `missing`.
  49. - Respect `prefers-reduced-motion` for whatever moves with the voice.
  50. - Do not fetch `manifest.json` just to play. Use it for durations or preloading if the design needs them.
  51. ## When something is wrong
  52. | Symptom | Cause and fix |
  53. |---|---|
  54. | `missing` event for a line that was recorded | the page's text differs from the collected text. Compare `narrator.urlFor(text)` with the keys from `narrate collect` |
  55. | `verify` reports orphans | the text changed since the last recording. Run `narrate record` |
  56. | `verify` warns "recorded with other settings" | voice, speed or a `say` fix changed. Run `narrate record` |
  57. | a word is said wrong | add it to `say`, run `narrate record` (only lines containing it are redone) |
  58. | `speak()` resolves `'blocked'` | it was not called from a user gesture |
  59. | `level()` is always `null` | no Web Audio, or the recordings are on another origin and `crossOrigin` is not set |
  60. | every line is `missing` after setting `crossOrigin` | the other origin does not send CORS headers |
  61. | `unknown option --...` | a mistyped flag; nothing was run. `narrate help` lists the options |
  62. | `manifest.json was written for ...` | the `out` folder belongs to another project, or `source` changed. Use another folder, or `--adopt` after asking the user |
  63. | `no MP3 encoder` | `pip install lameenc` in the Kokoro venv, or install ffmpeg |
  64. ## Honesty
  65. Report only what you ran. You cannot hear audio: say so, and give the numbers you did check (count, seconds, size, non-silence from `verify`). Do not describe how the voice sounds.
README.md · README · 276 lines
  1. # site-narrator
  2. A pre-recorded voice for any website, made on your own machine, with no paid speech service.
  3. You mark the text a page should be able to read aloud. site-narrator collects those lines, records each one with the free [Kokoro](https://huggingface.co/hexgrad/Kokoro-82M) text-to-speech model, and names every file by a hash of the line's text. In the browser, a small player hashes the text it wants to say and plays the file with that name. The site serves plain MP3 files: no server code, no API key, nothing generated while a visitor listens.
  4. It is packaged as a [Claude Code](https://claude.com/claude-code) skill (`SKILL.md` tells the assistant how to use it), and it also works by hand from the command line.
  5. ## What you get
  6. - **`narrate`**, a command line that collects lines from HTML, Markdown, JSON or your own collector module, records only what is new or changed, deletes its own recordings whose line is gone, writes a manifest and verifies the folder.
  7. - **`player/player.js`**, one framework-free ES module with no dependencies: a `speak(lines)` queue, `stop()`, events for the start and end of each line, a `level()` loudness reading for a talking mouth or a meter, and a voice on/off setting it remembers.
  8. - **`examples/demo/`**, a working page with five recorded paragraphs (204 KB of audio in all).
  9. ## Limits
  10. - **A fixed set of voices.** Kokoro ships a list of voices (`narrate voices` prints it). It does **not clone voices**, and site-narrator cannot make it sound like a particular person.
  11. - **Only text known ahead of time.** A line can be spoken only if it was recorded. Text typed by visitors, or anything that changes per request, has no recording.
  12. - **Change the text, record again.** The file name is a hash of the text, so an edited line has no recording until you run `narrate record` again. Until then the player reports the line as missing and moves on.
  13. - **Size grows with the text.** At the default 32 kbit/s mono, speech costs about 4 KB a second, so about 240 KB a minute. A few minutes of narration is fine to commit and serve; an hour is about 14 MB and probably wants its own storage. `narrate verify` warns past 10 MB in total or 512 KB for one line (both adjustable).
  14. - **Tell visitors the voice is computer-generated.** Say it on the page, near the control that starts it. The demo does, and the manifest carries a `notice` field you can show.
  15. - **Pronunciation is the model's.** Names and abbreviations can come out wrong; fix them with the `say` table. You have to listen to the result: no tool here can judge how a recording sounds.
  16. - **Simple HTML only.** The HTML collector reads static files with a small scanner, not a browser. It decodes every HTML character reference (`&eacute;`, `&#233;`) the way a browser does, but it does not run scripts or apply CSS. For a site built by a framework, export the lines from a collector module.
  17. - Tested on Linux only. See "What was tested".
  18. ## Requirements
  19. | Needed | Why | Licence |
  20. |---|---|---|
  21. | Node.js 18 or newer | runs the command line and the tests | MIT |
  22. | Python 3.10 or newer | runs the recorder | PSF |
  23. | [kokoro-onnx](https://github.com/thewh1teagle/kokoro-onnx) | text to speech | MIT |
  24. | Kokoro v1.0 model files (`kokoro-v1.0.onnx`, `voices-v1.0.bin`, about 340 MB) | the voice model | Apache-2.0 (see the note below) |
  25. | phonemizer and espeak-ng (installed with kokoro-onnx) | turn text into phonemes | GPL-3.0-or-later |
  26. | onnxruntime, numpy (installed with kokoro-onnx) | run the model | MIT, BSD-3-Clause |
  27. | [lameenc](https://github.com/chrisstaite/lameenc) | writes the MP3 files | LGPL-3.0-or-later, as declared in the package metadata of lameenc 1.9.0 |
  28. | ffmpeg with libmp3lame (optional, used when lameenc is not installed) | writes the MP3 files | LGPL or GPL, depending on the build |
  29. None of these is included in this repository. You install them yourself, and their licences apply to your use of them. The browser player needs none of them.
  30. No GPU is needed. Nothing is uploaded: the text never leaves the machine that records it.
  31. ### Licence notes
  32. Checked on 21 November 2026. Check again before you rely on them.
  33. - **kokoro-onnx** is MIT (its `LICENSE` file). Its README says the Kokoro model is Apache-2.0.
  34. - **Kokoro-82M** (the model, by hexgrad) is tagged Apache-2.0 on its Hugging Face model card. The model card does not give a separate licence for the individual voice files. This could not be verified beyond the model's own Apache-2.0 tag.
  35. - **phonemizer** (GPL-3.0-or-later, from its package metadata) and **espeak-ng** (GPL-3.0-or-later, from its README) are loaded by kokoro-onnx inside the Python process that runs `cli/record.py`. If you redistribute a bundle that includes them, or build a product on top, read the GPL's terms.
  36. - **lameenc**: the package metadata of version 1.9.0, read on 21 November 2026, declares `License-Expression: LGPL-3.0-or-later`, and the package ships the text of the GNU Lesser General Public License version 3 as its licence file. Its wheel is a compiled module that includes the LAME encoder; LAME's own licence was not checked separately. lameenc is imported by `cli/record.py` and is not part of this repository.
  37. - **The recordings you make** are files you generated with the model. The MP3 files in `examples/demo/voice/` were made this way with the `af_heart` voice and encoded with lameenc 1.9.0.
  38. - This is a summary of what the packages state, not legal advice.
  39. site-narrator's own code is under the **MIT License** (see `LICENSE`).
  40. ## Install
  41. ```bash
  42. # 1. the skill itself (for Claude Code; any folder works if you only use the command line)
  43. git clone https://github.com/VinVirtual/site-narrator ~/.claude/skills/site-narrator
  44. # 2. voice: a Python venv with Kokoro and an MP3 encoder, and the two model files
  45. # (on Debian or Ubuntu, first: sudo apt install python3-venv)
  46. python3 -m venv ~/kokoro/.venv
  47. ~/kokoro/.venv/bin/pip install kokoro-onnx lameenc
  48. curl -L -o ~/kokoro/kokoro-v1.0.onnx https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.1/kokoro-v1.0.onnx
  49. curl -L -o ~/kokoro/voices-v1.0.bin https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.1/voices-v1.0.bin
  50. # 3. check
  51. ~/.claude/skills/site-narrator/narrate check
  52. ```
  53. Everything is found in default places that you can change with environment variables:
  54. | Variable | Default | What |
  55. |---|---|---|
  56. | `KOKORO_HOME` | `~/kokoro` | folder with the model files and the `.venv` |
  57. | `KOKORO_MODEL`, `KOKORO_VOICES` | `$KOKORO_HOME/kokoro-v1.0.onnx`, `$KOKORO_HOME/voices-v1.0.bin` | the two model files |
  58. | `NARRATE_PYTHON` | `$KOKORO_HOME/.venv/bin/python`, else `python3` | Python that has kokoro-onnx |
  59. | `NARRATE_FFMPEG` | `ffmpeg` on PATH, else the one from the `imageio-ffmpeg` package | ffmpeg binary, only used when lameenc is missing or `--encoder ffmpeg` is given |
  60. ## Quick start
  61. 1. Mark what the page may read aloud:
  62. ```html
  63. <p data-narrate>Each paragraph was turned into a small sound file.</p>
  64. ```
  65. 2. Put a `narrate.json` next to the page:
  66. ```json
  67. {
  68. "source": "index.html",
  69. "out": "voice",
  70. "voice": "af_heart",
  71. "speed": 0.96,
  72. "say": { "CSS": "C S S" }
  73. }
  74. ```
  75. 3. Record, then check:
  76. ```bash
  77. N=~/.claude/skills/site-narrator/narrate
  78. $N collect . # the lines, their file names, and how each will be said
  79. $N record . # voice/<hash>.mp3 for every line, plus voice/manifest.json
  80. $N verify . # every line has a recording, nothing is left over
  81. ```
  82. 4. Copy `player/player.js` into the site and play a line:
  83. ```html
  84. <script type="module">
  85. import { createNarrator } from './player.js';
  86. const narrator = createNarrator({ base: './voice/' });
  87. const paragraph = document.querySelector('[data-narrate]');
  88. narrator.on('start', () => paragraph.classList.add('is-spoken'));
  89. narrator.on('done', () => paragraph.classList.remove('is-spoken'));
  90. document.querySelector('button').addEventListener('click', () => narrator.speak([paragraph.textContent]));
  91. </script>
  92. ```
  93. Edit the text and run `narrate record` again: only the changed lines are recorded, and the recordings of the old wording are deleted. Commit the `voice/` folder with the site.
  94. ### The demo
  95. ```bash
  96. $N serve ~/.claude/skills/site-narrator # then open http://127.0.0.1:4173/examples/demo/
  97. ```
  98. `examples/demo/` is a static page with a Listen button on each paragraph, a highlight on the paragraph being read, a loudness meter and a voice on/off switch. Its recordings are committed. To make them again: `$N record examples/demo --force`.
  99. ## Commands
  100. | Command | What it does |
  101. |---|---|
  102. | `narrate check` | checks node, Python, kokoro-onnx, the two model files and an MP3 encoder, and says how to fix what is missing |
  103. | `narrate voices` | lists the voices in the model file |
  104. | `narrate collect [project]` | prints every line with its file name, and the spoken form when it differs. `--json` prints `[{ key, text, say }]`, `--out-file <file>` saves it |
  105. | `narrate record [project]` | records lines that have no file or whose voice, speed, language, bit rate or pronunciation changed; deletes this project's recordings whose line is gone, and half-written files left by an interrupted run; writes `manifest.json`. `--dry-run` only shows the plan, `--force` records everything, `--keep-stale` deletes nothing, `--adopt` takes over a folder whose manifest was written for other sources |
  106. | `narrate manifest [project]` | rewrites `manifest.json` from the files in the folder: for each key, the file, its length in seconds and its size |
  107. | `narrate verify [project]` | exits non-zero when a line has no recording, a recording has no line (an orphan), or a file is unreadable, shorter than 0.3 s or silent. Warns about large files and recordings made with other settings. `--json` prints the result |
  108. | `narrate serve [folder]` | serves a folder on `http://127.0.0.1:4173` to try a page (`--port N`). For local use only: it listens on this machine alone, answers only requests addressed to `localhost`, `127.0.0.1` or `[::1]`, and does not serve files or folders whose name starts with a dot |
  109. | `narrate test` | runs the unit tests (plain `node --test`, no extra packages) |
  110. `project` is a folder that holds `narrate.json` (default: the current folder) or the path of such a file. Options override the file: `--source`, `--out`, `--voice`, `--speed`, `--lang`, `--bitrate`, `--workers`, `--attribute`, `--encoder auto|lameenc|ffmpeg`. An option the command line does not know is an error, so a typing mistake such as `--dryrun` stops the command instead of changing what it does.
  111. ### narrate.json
  112. | Field | Default | Meaning |
  113. |---|---|---|
  114. | `source` | none (required) | a file, or a list of files: `.html`, `.md`, `.json`, or a `.js`/`.mjs` collector module |
  115. | `out` | `voice` | folder for the recordings, relative to the file |
  116. | `voice` | `af_heart` | a name from `narrate voices` |
  117. | `speed` | `1` | 0.5 to 2 |
  118. | `lang` | `en-us` | language code passed to Kokoro (it must suit the voice) |
  119. | `bitrate` | `32` | MP3 kbit/s, mono |
  120. | `workers` | `2` | lines recorded at once. On the test machine, 1 and 2 workers gave byte-identical files |
  121. | `attribute` | `data-narrate` | the HTML attribute that marks a line |
  122. | `say` | `{}` | pronunciation fixes: `"written": "spoken"`. Case-sensitive; a fix that starts or ends with a letter only matches whole words |
  123. | `limits` | see `cli/lib/verify.mjs` | `maxTotalBytes`, `maxFileBytes`, `minSeconds`, `minLevel` for `verify` |
  124. Symbols such as `°C`, `×`, `→`, ` = ` and curly quotes are spelled out for the voice without any setup. The page keeps the original text; only the recording uses the spoken form, and the file name is always the hash of the original.
  125. ### Where lines come from
  126. - **HTML**: the text of every element with the `data-narrate` attribute, or of every `<p>` when no element has it.
  127. - **Markdown**: one line per heading, paragraph and list item. Code blocks, tables and front matter are skipped.
  128. - **JSON**: an array of strings or of `{ "text": "..." }` objects, or an object with a `lines` array.
  129. - **A collector module**: any `.js` or `.mjs` file whose default export is an array of lines or a function (it may be async) that returns one. Use this when the text lives in your source code:
  130. ```js
  131. // voice-lines.mjs
  132. import { CHAPTERS } from './src/chapters.js';
  133. export default () => CHAPTERS.flatMap((chapter) => [chapter.title, ...chapter.recap]);
  134. ```
  135. The text the page passes to `speak()` must be the text that was collected. White space and Unicode composition are normalised on both sides, so `element.textContent` of a marked element matches. Text that the page assembles differently from the collector will not.
  136. ## The player
  137. ```js
  138. const narrator = createNarrator({
  139. base: '/voice/', // folder the recordings are served from
  140. gap: 180, // pause between lines, in milliseconds
  141. captions: true, // voice off or file missing: still step through the lines at reading speed
  142. storageKey: 'site-narrator:voice', // where the visitor's on/off choice is kept; null: do not remember
  143. crossOrigin: null, // 'anonymous' only when the recordings are on another origin that sends CORS headers
  144. });
  145. ```
  146. | Member | What it does |
  147. |---|---|
  148. | `speak(lines, { id })` | plays the lines in order, replacing anything in progress. Resolves with `'done'`, `'stopped'`, `'blocked'` or `'off'` |
  149. | `stop()` | stops at once |
  150. | `on(type, listener)` | `start` and `end` for each line, `missing`, `blocked`, `done`, `stopped`. Line events carry `{ id, line, index, total, key, url, silent }`. Returns a function that unsubscribes |
  151. | `level()` | loudness right now, 0 to 1, or `null` when nothing is playing or it cannot be measured. Call it from `requestAnimationFrame` |
  152. | `enabled`, `setEnabled(on)` | the visitor's voice setting, remembered in `localStorage` |
  153. | `speaking` | true from `speak()` until its last line ends |
  154. | `urlFor(text)` | the address of a line's recording |
  155. The module also exports `voiceKey(text)`, `tidy(text)`, `readingMs(text)` and `loudness(samples)`.
  156. How it behaves when things go wrong:
  157. - **A recording is missing or will not load**: a `missing` event, then the line is held for its reading time (`start` with `silent: true`) so a caption or highlight still shows, and the queue goes on. With `captions: false` the line is skipped.
  158. - **The browser blocks sound** because the visitor has not tapped or clicked yet: a `blocked` event, the queue stops and `speak()` resolves with `'blocked'`. Call `speak()` from a click handler.
  159. - **The visitor turned the voice off**: no file is requested. With `captions: true` the lines advance at reading speed; with `captions: false`, `speak()` resolves with `'off'`.
  160. - **No Web Audio**: the voice still plays and `level()` returns `null`. The meter is only built the first time `level()` is called.
  161. - **Recordings on another origin** (a CDN, another port): they play as normal, and `level()` returns `null`, because the player never routes sound from another origin through Web Audio (a browser would silence it). To measure loudness there, the other origin must send CORS headers (`Access-Control-Allow-Origin`) and you set `crossOrigin: 'anonymous'`. If you set that option and the headers are missing, the recordings do not load and each line is reported as `missing`.
  162. ### In React
  163. A sketch, not shipped or tested as part of this repository:
  164. ```jsx
  165. import { useEffect, useMemo, useState } from 'react';
  166. import { createNarrator } from './player.js';
  167. export function useNarrator(base = '/voice/') {
  168. const narrator = useMemo(() => createNarrator({ base }), [base]);
  169. const [current, setCurrent] = useState(null); // { id, index } of the line being read, or null
  170. useEffect(() => {
  171. const clear = () => setCurrent(null);
  172. const off = [
  173. narrator.on('start', ({ id, index }) => setCurrent({ id, index })),
  174. narrator.on('done', clear),
  175. narrator.on('stopped', clear),
  176. narrator.on('blocked', clear),
  177. ];
  178. return () => {
  179. off.forEach((unsubscribe) => unsubscribe());
  180. narrator.stop();
  181. };
  182. }, [narrator]);
  183. return { current, speak: narrator.speak, stop: narrator.stop, level: narrator.level };
  184. }
  185. ```
  186. ## How it works
  187. 1. **Collect.** `cli/lib/collect.mjs` reads the sources and returns each distinct line as `{ key, text, say }`. `key` is `voiceKey(text)`: 32-bit FNV-1a over the text, in hex, followed by the text's length in hex. `say` is the text after the pronunciation fixes.
  188. 2. **Record.** `cli/lib/plan.mjs` compares the lines with the folder and the last manifest. `cli/record.py` speaks each line that needs it with Kokoro and writes `<key>.mp3`. A recording is deleted only when this project's own `manifest.json` lists it and no line says it any more. Any other file in the folder is left alone, including an MP3 with a similar name, and so is everything when there is no manifest. The manifest records the `sources` it was written for; if a folder's manifest was written for other sources, `record` stops and asks for another `out` folder or `--adopt`, so two projects cannot delete each other's files.
  189. 3. **Manifest and verify.** `cli/lib/mp3.mjs` reads each file's length from its MP3 frame headers. `manifest.json` lists every key with its file, seconds and bytes; `verify` compares lines, files and manifest.
  190. 4. **Play.** `player/player.js` contains the same `voiceKey`, so the page asks for `voice/<key>.mp3` directly. The command line imports the function from that file, so there is one implementation, and a test checks it against published FNV-1a values.
  191. The player does not read `manifest.json`. It is there for you: to show durations, to preload, or to check a deploy.
  192. ## What was tested
  193. On one Linux machine (Node 24, Python 3.10, kokoro-onnx 0.6.1; MP3 written with lameenc 1.9.0, and with the ffmpeg from imageio-ffmpeg for the fallback):
  194. - `narrate test`: 88 unit tests for the hash, text clean-up, collectors, recording plan, MP3 length, manifest, verify, project file, local server and the player's queue (with a stand-in for the browser's audio).
  195. - The demo was recorded for real (lameenc) and checked with `narrate verify`. Each of its MP3 files was decoded in headless Chromium: the decoded lengths match the manifest, and the signal is not silent. The ffmpeg encoder, stale-file deletion and re-recording after a voice change were run on a second small project.
  196. - The demo page was opened in headless Chromium from `narrate serve`. Pressing "Listen to all" played the five recordings in order with start and end events at the expected times, the highlight followed, and `level()` returned changing values. A missing recording, `stop()` and the voice-off setting behaved as described above.
  197. - The HTML entity decoder was compared with Chromium's `textContent` for all 2,125 named references and 744 other cases (names without a semicolon, numeric references). They agree except for the malformed `&#x;`, which Chromium turns into U+FFFD and the collector leaves as written.
  198. - Recording the same 12 lines with `--force` twice with 2 workers and once with 1 worker gave byte-identical MP3 files.
  199. - Recordings served from another origin without CORS headers played to the end in headless Chromium with `level()` returning `null`; with `crossOrigin: 'anonymous'` they were reported as `missing`.
  200. Not tested: macOS and Windows; Firefox and Safari; real phones; the autoplay-blocked path in a real browser (it is covered only by a unit test with a stand-in); the React sketch; languages other than English. Nobody has checked the recordings by ear as part of the automated checks: listen to yours.
  201. ## Development
  202. ```bash
  203. ./narrate test # unit tests
  204. ./narrate record examples/demo # records nothing when the demo is up to date
  205. ./narrate verify examples/demo
  206. ```
  207. Text handling that can be tested without Kokoro or a browser lives in `cli/lib/` and `player/player.js`. `cli/record.py` is the only part that needs the model.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.