narrate-gpt

A simple TTS CLI tool for narrating text snippets in natural-sounding language.

Usage

# Read from clipboard
narrate-gpt -c

# Provide text directly
narrate-gpt "Hello world"

# Disable automatic cleanup or transcript formatting
narrate-gpt -c --no-clean
narrate-gpt -c --no-format

# Choose an LLM formatter model
narrate-gpt -c --llm-model openai/gpt-5.1

Environment Variables

By default, narrate-gpt uses Inworld for TTS and OpenAI for LLM text formatting, so both keys are required:

export OPENAI_API_KEY="your-openai-api-key"
export INWORLD_API_KEY="your-inworld-api-key"

I very strongly recommend Inworld TTS, as it is very cheap and competitive with SOTA voice realism at the time of writing (Feb 2026). If you only want to use OpenAI for TTS (via the --tts-provider openai flag), you can skip the Inworld key and just set:

export OPENAI_API_KEY="your-openai-api-key"

Install

pip install "narrate-gpt @ git+ssh://git@github.com/fkodom/narrate-gpt.git"

# Install all dev dependencies (tests etc.)
pip install "narrate-gpt[test] @ git+ssh://git@github.com/fkodom/narrate-gpt.git"

# Setup pre-commit hooks
pre-commit install

Tooling

$\dagger$ Requires enabling the publish.yaml workflow. To activate, move the file from .github/disabled-workflows/publish.yaml.disabled to .github/workflows/publish.yaml, and set a valid PyPI token as PYPI_API_TOKEN in the repo secrets.

Then tag a new release of this repo, and GHA will automatically build and publish a Python wheel (.whl) to PyPI.