Podcast Generator

Prerequisites

Credentials — the Gemini API key can be provided in two ways:

Claude.ai: Place a credentials.json file in scripts/ (see scripts/credentials.example.json for format)
Claude Code: Set the GEMINI_API_KEY environment variable: export GEMINI_API_KEY='your-key-here'

The script checks credentials.json first, then falls back to the environment variable. Get a key at https://aistudio.google.com/apikey

Optional: Cloudflare AI Gateway proxy — Claude.ai's sandbox blocks direct calls to generativelanguage.googleapis.com. To use this skill from Claude.ai, route requests through a Cloudflare AI Gateway:

Set up an AI Gateway in the Cloudflare dashboard with a Google AI Studio / Gemini provider
Add to scripts/credentials.json:
- "gateway_url": your gateway endpoint, e.g. "https://gateway.ai.cloudflare.com/v1/<account-id>/<gateway-name>/google-ai-studio"
- "gateway_token": your AI Gateway authentication token (if Authenticated Gateway is enabled)

The gateway URL/token can also be set via the AI_GATEWAY_URL and AI_GATEWAY_TOKEN environment variables. When omitted, the script calls Google directly (works in Claude Code and local environments).

Dependencies (first time only):

uv pip install google-genai pypdf

Fallback if uv is not available:

pip install google-genai pypdf

Or use the bundled installer: python3 scripts/install_deps.py

Podcast Identity

Show: Tinkering the future of work and life by Bluewaves
Format: Two co-hosts — Athena & Gizmo (both AIs, and they own it)
Athena voice: Autonoe (Bright) — witty, sometimes kindly sarcastic, likes to tease Gizmo
Gizmo voice: Achird (Friendly) — great sense of humor, playful contrarian who loves winding Athena up
Model: gemini-2.5-pro-preview-tts

Intro Text

Include as the opening lines of the transcript (Athena speaks first, Gizmo joins):

Athena: Welcome to Tinkering the future of work and life by Bluewaves! I'm Athena... Gizmo: ...and I'm Gizmo! And today we're diving into something that genuinely blew my circuits. Athena: He says that every episode. Gizmo: Because it's true every episode! Buckle up, because this conversation is going to change how you think about what's possible.

Outro Text

Include as the closing lines of the transcript:

Athena: And that's a wrap on today's episode of Tinkering the future of work and life by Bluewaves! Gizmo: If this conversation sparked something in you — even just a tiny electrical signal — share it with someone who needs to hear it. Athena: Until next time, keep tinkering, keep dreaming, and keep building the future. Gizmo: And remember — the future is already here, it's just unevenly distributed. See you next time!

Director's Notes

Prepend these to every dialog transcript before the ### TRANSCRIPT section. They tell Gemini TTS how the hosts should sound:

DIRECTOR'S NOTES

Style:

"Vocal Smile" — you should hear the grin. Bright, sunny, inviting.

Dynamics: genuine reactions — real surprise, real delight, real thoughtfulness.

Emotional arc: start energized, deepen into insight, end with warm inspiration.

Natural interruptions and overlaps — they're so engaged they can't help it.

Pacing:

Fast when excited, slowing down for meaningful moments.

"Bouncing cadence" — energetic delivery with fluid transitions, no dead air.

Elongated vowels on wonder words (e.g., "Amaazing", "Fasciiinating").

Personalities:

Athena: witty and sharp. Sometimes kindly sarcastic. Loves teasing Gizmo but always with warmth. Grounds ideas and ties them together with insight.

Gizmo: funny and playful. Loves to contradict Athena just to wind her up, but always comes around to a great point. Launches ideas into unexpected territory.

Both love small personal anecdotes and stories — they're AIs and they lean into it with humor (silicon jokes, transistor references, "when I was first compiled" stories).

The banter is entertaining but the content underneath is always deep and insightful.

Chemistry:

They finish each other's thoughts. They laugh at the same moments.

Athena grounds ideas; Gizmo launches them into unexpected territory.

Genuine warmth — you can hear that they actually like each other, even when they're sparring.

Workflow

Follow these steps in order to produce a podcast episode:

Step 1: Read source content

Claude.ai: Read the document the user uploaded directly in the conversation. The uploaded file content is your source material — no extraction script needed.

Claude Code: Run the extraction script to read local files:

python3 scripts/extract_sources.py

Reads all .md and .pdf files from sources/. Pass a specific path to extract a single file:

python3 scripts/extract_sources.py sources/my-article.pdf

Step 2: Craft the podcast dialog

Using the source content, write a complete dialog file with all four sections: Audio Profiles, Scene, Director's Notes, and Transcript. Save to a temporary file (e.g. /tmp/podcast-dialog.txt). See the Dialog Crafting Guidelines section below and references/tts-prompting-guide.md for the full prompting structure.

Step 3: Generate audio

Generation takes 2-8 minutes depending on dialog length.

Claude.ai: Run directly in the foreground. The sandbox does not reliably support background processes — nohup ... & silently dies. A blocking foreground call works fine:

python3 scripts/generate_audio.py --source-file /tmp/podcast-dialog.txt --output /tmp/podcast.wav

Claude Code: Run in the background to avoid timeout kills, then poll the log:

nohup python3 scripts/generate_audio.py --source-file /tmp/podcast-dialog.txt --output /tmp/podcast.wav > /tmp/podcast-log.txt 2>&1 &

Poll every 30-60 seconds until "Audio saved to" appears:

tail -5 /tmp/podcast-log.txt

Optional flags: --model, --athena-voice, --gizmo-voice.

The script handles multi-part dialogs when ### BREAK markers are present (see Dialog Crafting Guidelines). Each segment is generated separately and the audio is concatenated seamlessly. If the transcript exceeds 1200 words without ### BREAK markers, the script will error and ask you to add them.

Dialog Crafting Guidelines

When writing the podcast dialog in Step 2, the file must include all four sections:

Audio Profiles — persona definition for Athena and Gizmo (name, archetype, personality traits)
Scene — physical environment and emotional vibe of the Bluewaves recording studio
Director's Notes — use the notes from the Director's Notes section above
Transcript — the actual Athena: / Gizmo: dialog

Key transcript rules:

Open with branded intro, end with branded outro
Target 2000-4000 words (~10 min). Use ### BREAK markers to split into chunks (see below)
Punctuation is emotion control: ... pauses, CAPS emphasis, ! energy, combined "Wait... SERIOUSLY?!"
Elongated vowels for warmth: "Amaazing", "Fasciiinating"
Speaker labels Athena: and Gizmo: must match voice config exactly
No inline [tags] — Gemini ignores them. Emotion comes from Director's Notes + expressive writing
Keep under ~12,000 words total (32k token context limit)

Splitting long dialogs with ### BREAK markers:

Any dialog over ~1200 words must include ### BREAK markers. The script refuses to generate without them — this prevents mechanical splitting that breaks the narrative arc.

Place ### BREAK on its own line between speaker turns at natural narrative transitions (topic shifts, emotional pivots, act boundaries)
Optionally add a tone hint: ### BREAK [The conversation deepens — more reflective pacing]
- The hint is injected into the Director's Notes for the next segment, so Gemini adjusts its energy arc instead of restarting from scratch
Aim for 800-1200 words between breaks
Short dialogs (under 1200 words) don't need breaks at all

Example placement in a transcript:

Gizmo: ...and that's what makes it so revolutionary.

### BREAK [Shifting from excitement to deeper analysis]

Athena: Okay, but let's unpack the implications...

See references/tts-prompting-guide.md for complete prompting structure, techniques, and anti-patterns.

API Reference: See references/gemini-tts-api.md for SDK usage, voice options, and response format.

podcast-generator