🎙️ tts-podcast
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_directionplus the activepace. The same style string goes with every turn of a host. personalityandtts_style.sceneare 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>), andtts_style.audio_tags: offremoves 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.
🔗 Following links
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:
- 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.
- After fetching, one Gemini call reads what each page actually says and
labels it
core,supporting, orirrelevantagainst 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 assupporting.
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.