Skip to main content

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

pip install "narra[edge,audio]"     # core + free edge-tts voice + pydub
export GEMINI_API_KEY=...           # default writer

Use

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:

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.0.1 — skeleton. The package installs, imports, and narra --version works; providers and narra generate are stubbed and raise "not implemented yet". 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 (J. Gravelle, MIT), Open Notebook (MIT), and the author's own limn, canturía, and talk-buddy.

Licence

MIT © Michael Borck.

Metadata

Release files for narra 0.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for narra 0.0.1
File Size Uploaded Provenance Actions
narra-0.0.1.tar.gz 280.8 kB Without provenance Details for narra-0.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for narra 0.0.1
File Interpreter ABI Platform Actions
narra-0.0.1-py3-none-any.whl Python 3 none any Details for narra-0.0.1-py3-none-any.whl

Total release size: 306.8 kB

Release files / narra-0.0.1.tar.gz

Download URL narra-0.0.1.tar.gz
Size 280.8 kB
Tags Source
SHA-256 checksum
How to use checksums
2d2de982480c767440af39ccc2b52852f0d8dd00717e0fc9b9f8c96fa81cd813
BLAKE2b-256 checksum
How to use checksums
2ab5abe2b9536321715f80cd6a3849bc40d0fed2b47c53e18955b19bd0f2284b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.0

Release files / narra-0.0.1-py3-none-any.whl

Download URL narra-0.0.1-py3-none-any.whl
Size 25.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a86329ba6946b6e49a53d2185be159a9d764ff5bd568bd575e90555cd2a23fe7
BLAKE2b-256 checksum
How to use checksums
28b5b4e83a9c6ecf3abd5819b0abbd7b41250e0b8bea65fd02ef8c20e2dacfa0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.0

Security for narra 0.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page