grdev.narrator 0.2.0

Narrator

Narrator is a command-line tool that turns a Markdown script into AI narration, one audio clip per paragraph, using the ElevenLabs API.

The core idea is a content-addressed cache: each paragraph's audio is keyed by its content and voice settings, not its position. Edit one paragraph — even split it into two — and every other clip is reused from cache, so you never re-pay for narration that didn't change.

Related

• Blog post — <PENDING>
• YouTube — <PENDING>

Documentation

• Spec / Brief
• Architecture

Requirements

• .NET SDK 10.0
• An ElevenLabs API key

Install

Narrator is published as a global dotnet tool:

dotnet tool install --global grdev.narrator

Then run it as narrator. For local development from source, use scripts/install-dev-pc.ps1.

Usage

narrator --script .\script.md

Or, from source without installing:

dotnet run --project .\src\Narrator\Narrator.csproj -- --script .\script.md

Options:

Voice configuration (voice id + settings) is read from YAML frontmatter at the top of the script — see the spec.

API key

Narrator reads the ElevenLabs key from, in order:

1. apiKey in the script frontmatter (use for one-offs only).
2. %USERPROFILE%\.narrator.json → { "apiKey": "sk_..." } (recommended).

Never commit a key in frontmatter if the script lives in a repo.

Output

One MP3 per paragraph, named NN - first five words.mp3, in sequence. Audio is meant to be finalized before editing; sequential numbering makes (re-)placement on a timeline obvious.