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[gemini,edge,audio]"   # writer + free voice + stitching
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.1.0 — M1. The core runs end to end: source → script (Gemini or a BYOK/OpenAI-compatible/Ollama writer) → per-line voicing (edge, OpenAI-compatible speech, or Gemini) → stitched MP3 + JSON sidecar. serve (M2), 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 (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.1.0

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.1.0
File Size Uploaded Provenance Actions
narra-0.1.0.tar.gz 291.2 kB Without provenance Details for narra-0.1.0.tar.gz

Built distribution (wheel)

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

Total release size: 322.3 kB

Release files / narra-0.1.0.tar.gz

Download URL narra-0.1.0.tar.gz
Size 291.2 kB
Tags Source
SHA-256 checksum
How to use checksums
5a4dcad080a1e646b3d7b7bbf7d09f1c1ad39e4d485a60d5b0294f2983877044
BLAKE2b-256 checksum
How to use checksums
b20e61d711c4b7e21618919f5b42352c35ac1e453edf1f7ea0ab7843f7555ae2
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.1.0-py3-none-any.whl

Download URL narra-0.1.0-py3-none-any.whl
Size 31.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b8c5d9da938adb794a9bf99b57aac50bf804c291ea74e72dc0e2e563c3b67e7d
BLAKE2b-256 checksum
How to use checksums
de80c676249f735bf3dd5b33d75635604888826f8bedda0168604f14aa55d4f8
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.1.0

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