narrate-gpt 0.2.1

narrate-gpt

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://[e-mail]/fkodom/narrate-gpt.git"

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

# Setup pre-commit hooks
pre-commit install

Tooling

Tool	Description	Runs on
black	Code formatter	- git commit (through pre-commit) - git push - pull requests
ruff	Code linter	- git commit (through pre-commit) - git push - pull requests
pytest	Unit testing framework	- git push - pull requests
mypy	Static type checker	- git push - pull requests
pre-commit	Pre-commit hooks	- git commit
twine $\dagger$	PyPI package uploader	- New release (git tag)

$\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.