Metadata-Version: 2.5
Name: narra
Version: 0.2.0
Summary: A small, privacy-first source-to-podcast tool: a PDF or text file in, a multi-speaker episode out. Bring your own writer and voice.
Project-URL: Homepage, https://github.com/michael-borck/narra
Project-URL: Repository, https://github.com/michael-borck/narra
Project-URL: Issues, https://github.com/michael-borck/narra/issues
Author-email: Michael Borck <michael.borck@curtin.edu.au>
License: MIT
License-File: LICENSE
Keywords: ai,audio,cli,notebooklm,podcast,text-to-speech,tts
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio
Requires-Python: >=3.10
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.9.0
Provides-Extra: audio
Requires-Dist: audioop-lts>=0.2.1; (python_version >= '3.13') and extra == 'audio'
Requires-Dist: pydub>=0.25.1; extra == 'audio'
Provides-Extra: edge
Requires-Dist: edge-tts>=6.1.0; extra == 'edge'
Provides-Extra: gemini
Requires-Dist: google-genai>=0.3.0; extra == 'gemini'
Provides-Extra: local
Requires-Dist: kokoro-onnx>=0.4.0; extra == 'local'
Requires-Dist: numpy>=1.24.0; extra == 'local'
Requires-Dist: piper-tts>=1.2.0; extra == 'local'
Provides-Extra: serve
Requires-Dist: fastapi>=0.110.0; extra == 'serve'
Requires-Dist: python-multipart>=0.0.9; extra == 'serve'
Requires-Dist: uvicorn>=0.29.0; extra == 'serve'
Description-Content-Type: text/markdown

# Narra — tell it into a podcast

> *narra (Spanish): "tell!" / "narrate!"*

A small, privacy-first tool that turns a source document into a two (or more)
speaker podcast episode. Give it a PDF or text file, pick a format, choose who
writes the script and which voices speak it, and get an MP3. No account, no
telemetry, bring your own providers.

## Install

```bash
pip install "narra[gemini,edge,audio]"   # writer + free voice + stitching
export GEMINI_API_KEY=...                # default writer
```

## Use

```bash
narra "paper.pdf" --format deep-dive --out episode.mp3
narra "notes.txt" --format brief --voice edge
narra init-config                   # write an example narra.yaml
narra serve                         # local web UI (pip install "narra[serve]")
```

Or as a library:

```python
from narra.config import load_config
from narra import core

settings = load_config()
episode = core.generate("paper.pdf", settings, format="deep-dive")
```

## Providers

- **Writer** (writes the script): `gemini` (default), `openai-compatible` (BYOK,
  any `/v1/chat/completions`), `ollama` (local).
- **Voice** (speaks each line): `edge` (free, default), `openai` /
  `openai-compatible` (OpenAI standard `/v1/audio/speech`), `gemini` (native
  TTS), `piper` (local CPU), `kokoro` (local CPU).

Keys live in `~/.narra.yaml` (or `${VAR}` references), never in the browser.

## Status

**0.2.0 — M2.** The core runs end to end (source → script → voicing → MP3 +
sidecar), and `narra serve` adds a local web UI: paste or upload a source, pick a
format and speakers, **write the script, edit it, then speak it** — with an
in-memory gallery and Save. `piper`/`kokoro` (M3) and the desktop app (M4) are
still to come. See `SPEC.md` for the full design and milestones.

## Privacy

No account. No telemetry. The only network egress is the request to the writer
and voice providers you configure. Piper and Kokoro run locally; Ollama is
local. Audio saves to `~/Podcasts/Narra` with a JSON sidecar.

## Credits

Narra borrows ideas, with acknowledgment, from
[GroqCasters](https://github.com/jgravelle/GroqCasters) (J. Gravelle, MIT),
[Open Notebook](https://github.com/lfnovo/open-notebook) (MIT), and the author's
own [limn](https://github.com/michael-borck/limn),
[canturía](https://github.com/michael-borck/canturia), and
[talk-buddy](https://github.com/michael-borck/talk-buddy).

## Licence

MIT © Michael Borck.