Skip to main content

🎙️ tts-podcast

PyPI CI Python Gemini TTS License

Turn any article, document, or search query into a two-voice podcast: scraped, researched, scripted, and voiced by Google Gemini.

Feed it URLs, local files, or a topic to search. It scrapes the sources, optionally runs iterative Google-Search-grounded research, writes a back-and-forth dialogue between two hosts, and synthesises an MP3 (or WAV) with Gemini's multi-speaker TTS. An optional folder of Markdown reports comes with it.


✨ Features

Feature Description
🌐 Any URL → podcast Feed one or several article URLs; scraping, dialogue, and audio are handled end to end.
📄 Local documents Include .txt, .md, .html, or .pdf files with -f, with no network request.
🔍 Web-search queries Pass a natural-language topic with -s; the research stage investigates it via Google Search grounding.
🧠 Iterative research --research N runs N sequential grounded rounds, each drilling into the gaps the last one left.
🔗 Follow links --follow-links walks the links inside the inputs (URL heuristic, then an LLM relevance judge); kept pages feed research and dialogue.
🎭 Multi-voice TTS Two distinct Gemini voices. Gemini 3.8 TTS by default, earlier TTS models still supported.
👥 Named voice duos Five built-in pairings (contrast default, warm, explorer, journalist, debate), each a different conversational dynamic. Or define your own from the 30 prebuilt Gemini voices.
🎚️ Per-speaker voice direction Give each host its own register, tempo, articulation, and breathing so the two never render with the same delivery.
🎨 Style & angle control Presets, free-text style, per-episode angle, and per-speaker overlays that leave the baseline voice acting alone.
📑 Report folder Opt-in with --report: writes overview.md, sources.md, script.md, research.md, and summary.md next to the audio.
💸 Token & cost tracking Accumulates per-model token usage and estimates cost from configurable pricing.
🥷 Stealth fallback Optional CloakBrowser retry for pages that block plain scraping (Cloudflare, 403/429, JS-only).
🩹 Truncated-body recovery Detects pages where the article extractor keeps only one section (newsletters, roundups), recovers the rest, and says so in the logs.

🚀 Quickstart

Get a podcast out of a single URL in three steps:

# 1. Get the Gemini API key into your environment
export GEMINI_API_KEY=<your key>

# 2. Make sure ffmpeg is available (audio export needs it)
brew install ffmpeg            # macOS  ·  apt: sudo apt install ffmpeg

# 3. Run it, no install required
uvx tts-podcast run https://blog.example.com/article

You get an .mp3. Add --report for a tts_<stem>/ folder of Markdown reports, or -O out.mp3 / -O - to choose the filename or stream to stdout. To read the script before spending TTS tokens, add -n for a dry run.


📦 Installation

uvx tts-podcast …                # run without installing
uv tool install tts-podcast      # persistent install via uv
pipx install tts-podcast         # via pipx
pip install tts-podcast          # plain pip

The optional stealth-browser fallback pulls a ~200 MB Chromium on first run:

uv tool install "tts-podcast[cloak]"

ffmpeg is required for audio export. You can skip it only if you stick to --no-audio / --dry-run:

brew install ffmpeg          # macOS
sudo apt install ffmpeg      # Debian / Ubuntu

From source

git clone https://github.com/obeone/tts-podcast.git
cd tts-podcast
uv sync                      # Python 3.13+
uv run tts-podcast --help

From a source checkout, prefix every command in this README with uv run (for example uv run tts-podcast run …).


⚙️ Configuration

Scaffold a config file, then export your Gemini API key:

tts-podcast config init
export GEMINI_API_KEY=<your key>

The config lives at $XDG_CONFIG_HOME/tts-podcast/config.yaml (typically ~/.config/tts-podcast/config.yaml). The full schema, with every key commented, is in config.example.yaml. The API key is read at runtime from the env var named by gemini.api_key_env (default GEMINI_API_KEY) and loaded from a local .env automatically.

gemini:
  api_key_env: GEMINI_API_KEY
  text_model: gemini-3.8-flash
  tts_model: gemini-3.8-flash-tts
  default_duo: contrast        # persistent voice pairing
  dialogue:
    target_duration_minutes: 8
Key Default What it does
gemini.text_model gemini-3.8-flash Writes the script. Also used for research and link judging unless overridden.
gemini.tts_model gemini-3.8-flash-tts Voices the script. gemini-3.8-flash-lite-tts is the cheaper sibling.
gemini.service_tier (standard) flex or priority, for text and research calls. TTS calls always go out on the standard tier.
gemini.language French Language of the dialogue.
gemini.default_duo contrast Voice pairing, see Voice duos.
gemini.dialogue.target_duration_minutes 8 Episode length. -d overrides it for one run.
gemini.tts_style.audio_tags auto on / off / auto: whether the script may carry inline vocal tags.
research.rounds_default 0 Research rounds when -R is not passed.
scraping.cloak_fallback false Retry blocked pages through CloakBrowser.
output.format mp3 mp3 or wav.
pricing (see example) Per-model rates behind the cost estimate.

A model with no entry under pricing is costed at zero, so the estimate is only as good as that table. Run from a source checkout, config init copies the rates from config.example.yaml and, on a re-run, adds the models you do not have yet without touching the rates you already set. Installed from PyPI, copy the pricing section over by hand. Several Gemini models are on introductory rates with a published end date; the example file notes each one.


🎚️ Usage

# Single URL, no research
tts-podcast run https://blog.example.com/article

# Multiple URLs with two rounds of complementary research
tts-podcast run -R 2 https://blog.example.com/a https://blog.example.com/b

# Local document, no network request
tts-podcast run -n -f paper.pdf

# Web-search query (research is bumped to 1 round when it is the only input)
tts-podcast run -n -s "agentic AI memory systems"

# Follow interesting links found inside the inputs (2 hops deep)
tts-podcast run -L --follow-depth 2 https://blog.example.com/article

# Same, but fetch at most 8 pages in total, 4 per hop
tts-podcast run -L --follow-depth 2 --follow-max-links 8 --follow-max-links-per-hop 4 \
  https://blog.example.com/article

# Mixed: URL + local file + search query in one episode
tts-podcast run -n https://blog.example.com/article -f notes.md -s "follow-up topic"

# Preview the dialogue without calling TTS
tts-podcast run -n https://blog.example.com/article

# Generate the dialogue script but skip audio synthesis (add --report for the folder)
tts-podcast run -A https://blog.example.com/article

# Pick the output filename, or stream the audio straight to stdout
tts-podcast run -O episode.mp3 https://blog.example.com/article
tts-podcast run -O - https://blog.example.com/article > episode.mp3

# Style & angle: nudge tone via preset + free text, focus on one angle
tts-podcast run -R 1 \
    --preset academic \
    --style "extra rigorous, French academic feel" \
    --angle "the regulatory implications" \
    https://blog.example.com/article

# Per-episode speaker overlay (TTS voice acting stays unchanged)
tts-podcast run \
    --speaker1-style "more skeptical than usual" \
    --speaker2-style "extra warm and forgiving" \
    https://blog.example.com/article

# Opposing viewpoints, structured as a debate
tts-podcast run --duo debate --preset debate https://blog.example.com/article

Commands

Command Description
tts-podcast run [INPUTS]… Full pipeline: URLs, -f files, -s search queries.
tts-podcast duos List the voice duos, built-in and config-defined. Needs no API key.
tts-podcast config init Create or update the config file interactively.
tts-podcast config show Print the config file. --resolve shows resolved values with secrets masked.

Key flags of run

Flag Description
-f, --file FILE Local document to include (repeatable). .txt, .md, .html, .pdf.
-s, --search QUERY Web-search query to seed the podcast (repeatable). Bumps research to 1 if search-only.
-R, --research N Number of Google-Search-grounded research rounds (default 0).
-L, --follow-links After scraping inputs, follow interesting links inside them. Fetched pages feed research and dialogue.
--follow-depth N Link-following hops when --follow-links is set (default 1).
--follow-max-links N Cap on the total number of links fetched across all hops (default 20, config follow.max_links_total).
--follow-max-links-per-hop N Cap on the number of links fetched per hop (default 5, config follow.max_links_per_level).
--duo NAME Named voice duo (contrast, warm, explorer, journalist, debate).
--preset NAME Style preset: casual, academic, humorous, debate, vulgarized, or none.
--style TEXT Free-text style guidance (≤ 500 chars). Composes with --preset.
--speaker1-style / --speaker2-style Per-episode overlay for one speaker; baseline voice unchanged.
--angle TEXT Episode angle. Steers the dialogue and the first research round only.
-d, --duration MIN Target episode duration in minutes.
-n, --dry-run Print dialogue to stdout, no TTS.
-A, --no-audio Skip TTS synthesis and audio export.
-o, --output-dir DIR Output directory (overrides config).
-O, --output FILE Output file path or bare name. - streams the audio to stdout.
-r, --report Generate the report folder (off by default).
-v, --verbose Enable DEBUG logging.

Run tts-podcast run --help for the full list.


👥 Voice duos

A duo bundles both speakers (name, prebuilt Gemini voice, baseline personality, and per-speaker voice direction) under one slug, so you swap the whole pairing at once instead of editing speaker1 / speaker2 by hand.

tts-podcast duos          # list them (no API key needed)
tts-podcast run --duo journalist https://blog.example.com/article

Built-in duos

Each duo is its own conversational dynamic. The ten voices are all distinct, and inside a duo the two voice directions are opposed on register, tempo, articulation, and breathing.

Slug Speaker 1 Speaker 2 Dynamic
contrast (default) Theo, voice Puck (Upbeat) Nadia, voice Kore (Firm) Tempo flip. An idea machine firing in bursts against an editor who lands it in one sentence. They agree, they just run at different speeds.
warm Vera, voice Gacrux (Mature) Milo, voice Achird (Friendly) Transmission. A settled storyteller hands the thread to the listener's stand-in. Long turn, short reaction, real silence.
explorer Iris, voice Achernar (Soft) Sam, voice Sadachbia (Lively) Co-discovery. Two non-experts approaching the same thing from opposite ends; nobody holds the answer, nobody corrects the other.
journalist Nora, voice Pulcherrima (Forward) Marc, voice Charon (Informative) Role asymmetry. A desk anchor asking short questions, a field correspondent answering long and sourced.
debate Robin, voice Autonoe (Bright) Sasha, voice Algenib (Gravelly) Open conflict. Optimist against skeptic, one escalating up and the other down (pair with --preset debate).

Each duo also ships a scene and a pace matching its dynamic. Those are defaults: anything you set in gemini.tts_style.scene / .pace wins.

Gemini doesn't officially document voice gender; pairings are curated from each voice's official descriptor plus community reports. Audition them in Google AI Studio before committing.

Voice direction

Give a TTS model two personalities and nothing about how each one speaks, and it averages both deliveries into one: the two hosts come out sounding like the same person. voice_direction is an optional per-speaker note covering four axes and nothing else.

  • register (low chest, mid, bright upper, forward placement)
  • tempo (staccato bursts, metronomic, half speed)
  • articulation (hard attacks and clipped endings, legato, rounded vowels)
  • breathing (silent, snatched on the fly, a full beat at every stop)

It is read only by the TTS stage, so it changes how a line sounds and never what the script says. It is the mirror image of style_overlay, which is dialogue-only and never reaches TTS.

Writing your own: pick one host, then make the other the opposite on all four axes. Describe a steady trait ("low and slow") and avoid a trajectory ("starts calm then builds"). Keep each note under ~160 characters, since it travels with every TTS request.

gemini:
  default_duo: my_duo
  duos:
    my_duo:
      description: "my custom pairing"
      scene: "a bare table, two microphones facing each other"
      pace: "quick exchanges, no dead air"
      speaker1:
        name: Robin
        voice: Autonoe     # Bright
        personality: "a techno-optimist who champions the upside"
        voice_direction: >-
          Bright upper register, leaning into the mic. Quick, no gap between
          sentences; pitch climbing through the clause, breath snatched on the fly.
      speaker2:
        name: Sasha
        voice: Algenib     # Gravelly
        personality: "a hard-nosed skeptic who probes risks and costs"
        voice_direction: >-
          Low gravelly register, dropping in volume instead of rising. Slow, a
          long beat before each answer; blunt consonants, falling endings.

The same key works on legacy gemini.speaker1 / speaker2 blocks.

What reaches the TTS model

Gemini 3.8 TTS (gemini-3.8-flash-tts, the default, and gemini-3.8-flash-lite-tts) reads its input as a verbatim transcript: anything written in it gets spoken, a speaker label or a stage direction included. So the request is structured:

  • Each speaker turn is sent on its own, tagged with its speaker and a short delivery style made of that host's voice_direction plus the active pace. The same style string goes with every turn of a host.
  • personality and tts_style.scene are not sent to the TTS model. They still shape the script. Google's guidance for these models is that persona prose in the request is what makes a voice drift.
  • The script carries no emotional cue. The only inline markup is a short list of vocal tags (<laugh>, <chuckle>, <sigh>, <gasp>, <breath>, <short pause>, <long pause>), and tts_style.audio_tags: off removes those too.

Earlier TTS models

gemini-3.1-flash-tts-preview and the gemini-2.5-*-preview-tts models are detected from the model name and keep the older request shape: one text block per chunk, opening with a preamble that holds the personalities, the voice directions, the scene and the pace. The script then carries bracketed tags such as [curiosity] (3.1) or parenthetical cues in the target language (2.5).

That preamble costs room. The tool measures the one your config actually renders and sizes the dialogue chunks against what is left. As long as it stays at or under 800 bytes, chunks keep their full size, so the request count and the number of audio joins are unchanged. Past that, chunks shrink byte for byte and an episode is cut into a few more pieces. A long scene alone can cross the line; when a config really does run out, the tool logs a warning naming the fields to trim. Gemini 3.8 has no preamble, so none of this applies there.

Custom duos

Duos defined under gemini.duos merge over the built-ins: the same slug overrides one, a new slug adds one. Only name and voice are required per speaker; personality, voice_direction, description, scene, and pace are all optional.

Write personality as a noun phrase starting with a / an / the. The preamble of the earlier TTS models renders it as <name> is <personality>., so a bare job title ("desk anchor; presses with short questions") ships broken English to the model.

Resolution precedence: --duo › gemini.default_duo › legacy gemini.speaker1 / speaker2 blocks › built-in contrast. A config that defines only the legacy speakerN blocks keeps working unchanged.


With -L / --follow-links, your inputs are where the corpus starts: once they are scraped, the tool walks the hyperlinks inside them, keeps the pages that turn out to be on topic, and feeds those into both the research stage and the dialogue.

tts-podcast run -L https://blog.example.com/article
tts-podcast run -L --follow-depth 2 --follow-max-links 8 https://blog.example.com/article

Selection happens twice, because guessing from a URL is cheap and guessing from the content is accurate:

  1. Before fetching, a URL heuristic drops the obvious noise (asset files, anchors, trackers, social buttons, login and checkout paths) and keeps anything that could be real content.
  2. After fetching, one Gemini call reads what each page actually says and labels it core, supporting, or irrelevant against your topic. The first two are kept, and their verdict follows them into the dialogue prompt, the research prompt, and the report. The judge fails open: if the call fails, pages are kept as supporting.

Every hop costs one Gemini call on top of the fetches, so the traversal is capped on both axes:

Cap Default CLI Config
Hops 1 --follow-depth (none)
Links per hop 5 --follow-max-links-per-hop follow.max_links_per_level
Links in total 20 --follow-max-links follow.max_links_total

The total cap overrides depth × per-hop, so it is the single number to lower when a run feels expensive. A cap of zero is rejected up front: downstream it would make the whole stage fetch nothing without a word.


📂 Output layout

<output_dir>/
├── <stem>.mp3
└── tts_<stem>/            # only with --report
    ├── overview.md       # metadata, link breakdown, token/cost summary
    ├── sources.md        # per-source content (title, URL, summary, full text)
    ├── script.md         # full two-host dialogue
    ├── research.md       # only when --research >= 1
    └── summary.md        # synthetic reference sheet with categorised links

The stem combines the first URL's hostname, a 6-char digest of the URL list, and today's date, for example arxiv.org-a1b2c3-2026-06-07.mp3. Override the whole filename with -O NAME (a bare name lands in <output_dir>), or pass -O - to stream the audio to stdout.


💸 Cost

Token usage is tracked per model as the run goes, and the cost estimate shown next to the progress is computed from the pricing section of your config.

Each --research round is a separate Gemini call with Google Search grounding enabled, which adds search overhead to the input-token cost. The tool logs the cumulative cost after each round.

--follow-links bills on top of that: one relevance-judging call per hop, plus the pages it feeds into research and dialogue as extra input tokens. Keep --follow-max-links low on a first run and raise it once you know a source is worth mining.


🧪 Development

Command Description
uv sync Install dependencies (Python 3.13+).
uv run pytest tests/ -q Run the test suite.
uv run ruff check src/ tests/ Lint.
uv run tts-podcast run -n <URL> Dry run from the checkout: script only, no TTS.

A release is a tag: once the version bump is merged, pushing vX.Y.Z builds the package, publishes it to PyPI and creates the GitHub Release. The tag must match the version in pyproject.toml.

Tests mock the Gemini SDK and never hit the network. See AGENTS.md for the architecture notes and the invariants worth knowing before changing the pipeline.


🔊 How it works

flowchart TB
    subgraph IN[" Inputs "]
        U[🌐 URLs]
        F[📄 Files<br/>txt · md · html · pdf]
        S[🔍 Search queries]
    end

    U --> SC[web_scraper]
    F --> LL[local_loader]
    S --> SY[synthetic source]

    SC --> FL{🔗 Follow links?<br/>--follow-links}
    LL --> FL
    SY --> FL

    FL -->|optional| FF[Fetch + relevance judge<br/>core · supporting · irrelevant]
    FL --> R{🧠 Research?<br/>--research N}
    FF --> R

    R -->|optional| RR[Google Search<br/>grounded rounds]
    R --> D[💬 llm_summarizer<br/>two-host dialogue]
    RR --> D

    D --> T[🎙️ Gemini multi-speaker TTS<br/>parallel chunks]
    T --> A[🎧 audio_exporter<br/>MP3 / WAV]
    D --> REP[📑 report_generator<br/>Markdown folder]

The pipeline is strictly linear: each stage hands typed data to the next, with no hidden shared state. A failed scrape does not abort the run, which carries on with whatever succeeded and stops only when every input failed.

Truncated article bodies

An article extractor has to decide which part of a page is the article. On a page assembled from several sibling sections (a newsletter, an aggregator, a link roundup) that decision can go badly wrong: one section is designated as the body and the others are dropped, with nothing in the result saying so. The episode then gets written from a fragment, sponsor copy and all.

Every scrape (and every local HTML file) is therefore cross-checked against a second, structure-blind extraction pass. When that pass finds at least 1.5x more text, the page is treated as truncated: the fuller text is used and a warning naming both lengths is logged.

WARNING Article body looks truncated for https://example.com/digest:
        trafilatura kept 2324 chars, but a baseline pass over the same HTML
        yields 4072 (1.8x more). Using the baseline text instead.

Pages that extract cleanly keep their exact body text: the second pass normally finds the same content or less, and the threshold sits above the range measured on healthy pages. Recovered text is cruder (block elements are separated less carefully and some page furniture survives), which is why it is used only when the alternative is losing most of the article.


📝 License

MIT © Grégoire Compagnon

Made by Grégoire Compagnon (obeone)

Metadata

Release files for tts-podcast 0.8.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 tts-podcast 0.8.0
File Size Uploaded Provenance Actions
tts_podcast-0.8.0.tar.gz 152.1 kB With provenance Details for tts_podcast-0.8.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tts-podcast 0.8.0
File Interpreter ABI Platform Actions
tts_podcast-0.8.0-py3-none-any.whl Python 3 none any Details for tts_podcast-0.8.0-py3-none-any.whl

Total release size: 254.8 kB

Release files / tts_podcast-0.8.0.tar.gz

Download URL tts_podcast-0.8.0.tar.gz
Size 152.1 kB
Tags Source
SHA-256 checksum
How to use checksums
967279054fa43d09d7da121dbbcba754e8775a47000ad0c313cbb35c7563dcaa
BLAKE2b-256 checksum
How to use checksums
20345901f9a8c4b0dd52c1280b9932cfabe1bf68f70631be2376031677947b0c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / tts_podcast-0.8.0-py3-none-any.whl

Download URL tts_podcast-0.8.0-py3-none-any.whl
Size 102.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ff170d0be8721af8747fb2aafe4cf133c10ab33419b65729229923d74d9acf89
BLAKE2b-256 checksum
How to use checksums
8d2689db6d1b7f02cfe706976da2405fa09c46575bca5b60ace6ebdd9e9ee07b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Security for tts-podcast 0.8.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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for tts_podcast-0.8.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

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.

Release history Release notifications | RSS feed

This release

0.8.0 This release

2 release files Full provenance

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