grdev.narrator-cli 0.3.2

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
• 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-cli

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%\.grdev.narrator-cli\api-key.json → { "apiKey": "sk_..." } (recommended).

Run narrator once without a key and it writes that file as a template for you to paste into.

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.

Versioning

Versions are computed by Nerdbank.GitVersioning from version.json plus the git height — there is no hardcoded version anywhere. version.json holds the major.minor; the patch is the number of commits since that value last changed, so every commit bumps the patch automatically.

Install the CLI once:

dotnet tool install --global nbgv

Viewing the version

nbgv get-version                    # full summary for HEAD
nbgv get-version -v SimpleVersion   # just x.y.z, for scripts
nbgv get-version -f json            # everything, as JSON

Setting the version

The patch bumps on its own with every commit. To change the major or minor, hand-edit the version field in version.json and commit it — the patch count restarts from there:

"version": "1.3"

Do not run nbgv set-version. It rewrites version.json from scratch and silently drops the publicReleaseRefSpec and cloudBuild settings this repo relies on. Never add a <Version> element to Directory.Build.props or a .csproj either — it would override the computed version.

Releases

A build from release/production is a public release and gets a clean version (1.3.4). Every other branch is a prerelease and gets a commit-id suffix (1.3.4-g1a2b3c4). Pushing to release/production triggers the publish workflow.