Text to Narration: local AI audio

By Utpal Kumar

Turn plain text or simple Markdown into narration on your own computer. Text to Narration prepares a reviewable transcript, synthesizes speech with the open-weight Kokoro AI model, and exports a WAV master and MP3 listening copy. Source-line accounting and pronunciation records help you review what changed before sharing the audio.

Download source package (ZIP) View on GitHub

Version: 0.1.0, source revision be8d3ee. The ZIP contains the installable Python project, examples, tests, and documentation. Speech models are downloaded separately. This is a command-line source package.

Requirements

• Python 3.10 or later; Python 3.12 is recommended.
• FFmpeg with MP3 encoding support, available on your PATH.
• Internet access for installation and the initial model download; disk space for dependencies, two model assets, and generated audio.

No paid hosted API or API key is required. Narration runs locally after setup. Installation and model downloads contact their package/model hosts; the tool does not upload your source text to a speech service. Output files contain your input and should be stored appropriately.

Install

Extract the ZIP and open a terminal inside the extracted project folder containing pyproject.toml. Create a virtual environment, activate it, then install the speech extra:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install '.[tts]'
ffmpeg -version

On Windows PowerShell, use py -3.12 -m venv .venv and .venv\Scripts\Activate.ps1. Platform wheel availability varies. Install FFmpeg from an official route if the final command is unavailable. For transcript preparation only, python -m pip install . installs the lighter core package without speech dependencies.

Make your first recording

Prepare the included example:

text-to-narration prepare examples/article.md \
  --output output \
  --pronunciations examples/pronunciations.json

Review output/transcript.txt before generating audio. Then download the model and voices, render the narration, and inspect the validation report:

text-to-narration download-models --models models
text-to-narration render --output output --models models \
  --voice af_heart --speed 0.98 --threads 4
text-to-narration validate --output output

Listen to output/narration.mp3. The WAV master, source snapshot, source-line audit, and validation reports remain in output/. Use a fresh output directory for each run; existing artifacts are not overwritten.

Keep AI unchanged in the pronunciation file: the pinned tokenizer already reads both letters. Replacing it with A I can weaken the first letter. Review names, abbreviations, and numbers by listening.

What to expect

The default voice is American English. Simple Markdown headings, paragraphs, lists, links, and emphasis are supported. Code, tables, images, HTML, and mathematical notation need deliberate spoken descriptions. PDF, Word, and web-page extraction are outside the package’s scope.

Preparation stops at References or Further Reading by default. Add --no-stop to prepare to include the complete document. There is no default duration cap and no silent summarization. Automated checks verify text accounting and audio properties; they cannot prove correct pronunciation or meaning. Interrupted renders do not resume automatically.

License and resources

Project code is MIT-licensed. Upstream identifies the Kokoro model as Apache 2.0; dependencies and voice assets retain their applicable upstream terms. Models, third-party dependencies, and private audio are not bundled in this source ZIP. Consult the third-party notices before redistributing an environment that includes them. Only narrate and distribute material you have permission to use.

• Full instructions and examples
• Third-party notices
• Code license
• Report a problem