# narrate-gpt

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

## Usage

```bash
# 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:

```bash
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:

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

## Install

```bash
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

| Tool | Description | Runs on |
| --- | --- | --- |
| [black](https://github.com/psf/black) | Code formatter | - `git commit` (through `pre-commit`) <br> - `git push` <br> - pull requests |
| [ruff](https://github.com/astral-sh/ruff) | Code linter | - `git commit` (through `pre-commit`) <br> - `git push` <br> - pull requests |
| [pytest](https://github.com/pytest-dev/pytest) | Unit testing framework | - `git push` <br> - pull requests |
| [mypy](https://github.com/python/mypy) | Static type checker | - `git push` <br> - pull requests |
| [pre-commit](https://github.com/pre-commit/pre-commit) | Pre-commit hooks | - `git commit` |
| [twine](https://github.com/pypa/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.
