narrate
Skill0 starsChanged 5 months agoMITView on GitHub
Turns any text, Markdown, or book into spoken audio entirely on your own machine using the local Kokoro text-to-speech model (voice "Heart" / af_heart) — no cloud, no API keys, nothing uploaded, free. Three modes: speak a short string, narrate a .txt/.md file to an mp3, or compile a folder of chapters into a chaptered .m4b audiobook ready for Apple Books. Trigger this skill whenever someone says "narrate this", "read this aloud", "make an audiobook", "turn this into an mp3", "turn this into audio", "make a voiceover", "say this with Heart", "read me this file", or otherwise wants text spoken locally. Handles Markdown-to-spoken cleanup (strips syntax, linearizes tables and lists, expands symbols Kokoro mispronounces) and chunked, resumable synthesis.
2 other projects use a version of this.
Adopted by
Most recently taken up by
- tslateman/skillstheir own version, first seen Oct 11, 2026
- AlexAnsart/demo-studiotheir own version, first seen Jul 26, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- AlexAnsart/demo-studio★ 3same name
- tslateman/skills★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository3 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .cursor/rules/spitfire-storybook.mdcCursor rule
- brutally-honest-book-builderSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 136
Use --clean plain to just collapse whitespace (keeps the raw text), or --clean none to feed the text through untouched.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
narrate
narrate is the narration half of spitfire-storybook — a privacy-first,
local-only, open-source tool. It doesn't just help write your book, it reads it
to you. Every byte of synthesis happens on your own hardware via a bundled local
Kokoro server. There is no hosted version and nothing is ever uploaded.
The script lives at cli/narrate.py (relative to the repo root). Run it with
your system Python:
python3 cli/narrate.py <mode> [args] [flags]Prerequisites
- A local Kokoro server. The CLI talks to it over HTTP. Start one from
cli/kokoro/(./start.sh, orpython3 cli/kokoro/server.py). First run downloads the ~330 MB Kokoro-82M model and caches it locally. Seecli/kokoro/README.md. - python3 + ffmpeg on your PATH. That's it — synthesis is dependency-light;
all audio decode/concat/encode goes through ffmpeg (no numpy/soundfile).
PILis optional and only used to auto-generate a book cover. - The CLI auto-detects the server at
http://localhost:8081(andhttp://127.0.0.1:8081). Override the endpoint with theKOKORO_URLenvironment variable or the--serverflag.KOKORO_VOICEoverrides the default voice. If no server is reachable, the CLI exits with a message telling you to start one.
Three modes
1. say — speak a string
python3 cli/narrate.py say "Welcome to the first chapter." -o intro.mp3 --playSpeaks the given text. Defaults to narration.mp3 when -o is omitted.
2. file — narrate a .txt/.md file
python3 cli/narrate.py file notes.md -o notes.mp3Reads the file, applies Markdown cleaning, and synthesizes it. The default
output name is the input filename with an .mp3 extension.
3. book — build a chaptered .m4b audiobook
python3 cli/narrate.py book ./my-book \
--title "The Fictional Field Guide" \
--subtitle "An Imaginary Manual" \
--author "A. N. Author" \
--year 2026The input is either:
- a directory of
.md/.txtfiles (sorted recursively). Each file becomes a chapter; its title is the first# H1heading, or the filename if there's none. - a manifest
manifest.json: a list of[{title, text|src|text_inline, ...}]entries, giving explicit chapter order, titles, and content.
It synthesizes each chapter, then muxes them into a single .m4b with embedded
chapter markers, metadata, and (by default) an auto-generated cover. Output
defaults to a slugified title with the .m4b extension.
Book mode is resumable. Chapter WAVs are cached in a .narrate_build/
directory next to the output; if a chapter file already exists, it's skipped on
the next run. Delete that directory (or a single chapter WAV) to force a
re-synthesis.
Flags
Common to all modes:
| Flag | Meaning |
-o, --out PATH | Output file (.mp3 / .wav / .m4a / .m4b). Sensible default per mode. |
--voice NAME | Kokoro voice (default af_heart = "Heart"). |
--gap SECONDS | Pause inserted between chunks (default 0.3). |
--play | Play the result when done (macOS afplay). |
--server URL | Override the Kokoro endpoint (else auto-detect / KOKORO_URL). |
file and book also accept:
| Flag | Meaning |
--clean md|plain|none | Markdown cleaning mode (default md). |
Book-only:
| Flag | Meaning |
--title | Book / album title. |
--subtitle | Subtitle (stored as comment). |
--author | Author. |
--narrator | Narrator credit (default Heart · Kokoro TTS). |
--year | Publication year. |
--cover auto|none|PATH | auto generates a cover (needs PIL); default auto. |
--bitrate | AAC bitrate for the .m4b (default 96k). |
Markdown → spoken cleaning
With --clean md (the default), the text is converted from Markdown into
something that reads naturally aloud before synthesis:
- strips YAML frontmatter, code fences, inline code, HTML, images, and bare URLs
- turns links into their visible text
- linearizes tables into spoken rows and flattens list markers / blockquotes into sentences
- converts headings into spoken lines with a terminal period
- removes emphasis markers (
**,*,_) - expands symbols Kokoro otherwise mispronounces:
%→ "percent",$1,500→ "1500 dollars",$5k→ "5 thousand dollars",3x→ "3 times",&→ "and",→/->→ "leads to",24/7→ "twenty-four seven", plus common abbreviations (e.g.,i.e.,etc.,vs.,approx.,w/).
Use --clean plain to just collapse whitespace (keeps the raw text), or
--clean none to feed the text through untouched. In book mode, .txt chapters
are always treated as plain regardless of --clean.
Long text is automatically split into ~1500-character chunks at paragraph and sentence boundaries, synthesized chunk-by-chunk, and stitched together with the configured gap.
Importing the .m4b into Apple Books
- Open the Books app on macOS.
- Drag the generated
.m4bonto the Books window, or use File → Add to Library… and select it. - It appears under Audiobooks with chapter navigation, the embedded cover, and resume-where-you-left-off playback. It syncs to your iPhone/iPad via the same Apple ID.
(.m4b is a standard AAC audiobook container, so the same file also imports into
Podcasts and most third-party audiobook players.)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

