simonmesmith/agent-skills/podcast-generator

Podcast Generator

Overview

Produce reviewable, revision-friendly podcast episodes from source material or an existing script. Default to a two-host conversational format with host_a and host_b, but support one or more hosts when the user's request makes that clear.

Keep the user flow short. Ask at most two setup questions for document-driven work when needed: target length and audience/tone. If the user supplies a script, normalize it directly and ask only when host attribution or source intent is blocking.

Workflow

1. Determine input mode:

• Documents to podcast: extract key claims, source context, and high-risk terminology; draft a conversational script.
• Script to production table: preserve meaning, split long turns, assign IDs, and flag unclear host attribution.

1. Create the script table as the source of truth. Use assets/podcast_script_template.csv or .xlsx when the user needs a review file.
2. Check pronunciation guidance before final script approval:

• Look for files named like pronunciation.csv, glossary.*, brand_terms.*, or brand/medical notes in the source set.
• If no guidance exists, identify high-risk terms such as brands, drug names, acronyms, mechanisms, institutions, and names, then create a lightweight pronunciation glossary for review.
• Prefer ElevenLabs pronunciation dictionaries for approved high-risk terms. Use IPA phoneme rules when the pronunciation must be exact, and alias rules for expansions or simpler spoken substitutions.
• Be conservative with glossary casing and term types for ElevenLabs: uppercase pronunciation cues or marking non-acronym brand/product names as acronyms can cause the model to spell words out as letters. Use lowercase alias cues only when falling back to text replacement, and classify a term as an acronym only when it should actually be read letter-by-letter.
• Do not hardcode medical pronunciations into the skill.

1. Validate the script table with scripts/validate_script.py.
2. After user/client approval, optionally renumber inserted IDs with scripts/renumber_script.py.
3. Generate audio with scripts/generate_audio.py, using ElevenLabs Text to Dialogue chunk mode by default.
4. Use the generated chunk directly when there is only one chunk. Merge ordered chunks with scripts/merge_audio.py only when the episode spans multiple chunks or the user wants a normalized final export.
5. For client edits, compare the revised table against the previous table, regenerate only changed chunks/lines, and preserve prior audio.

Script Table Rules

Required columns:

id,host,text

Recommended columns:

status,notes,pronunciation

Production/revision columns:

production_id,source_id,audio_file,chunk_id

Use 001, 002, 003 for initial IDs. For insertions, use sortable decimal IDs such as 002.5, 002.1, or 002.2. Before final generation, renumber to clean production IDs while preserving source_id.

Use these statuses:

draft
client-edited
approved
generated
regenerate
skip

Load references/script_schema.md for exact schema details and examples.

Audio Generation

Default to ElevenLabs Text to Dialogue with model_id=eleven_v3. Require ELEVENLABS_API_KEY in the environment before live generation. Never ask the user to paste the key into chat.

Prefer chunk mode for natural host interaction. Use line mode only when surgical replacement matters more than conversational flow. Keep each dialogue request under the current reliable generation budget; this skill defaults to 2,000 total text characters per chunk.

Voice IDs must be supplied before live ElevenLabs generation:

python scripts/generate_audio.py script.csv --voice host_a=VOICE_ID_A --voice host_b=VOICE_ID_B

For two-host tests and first drafts, prefer the proven defaults:

python scripts/generate_audio.py script.csv --use-default-voices

Default voices:

host_a: Roger - Laid-Back, Casual, Resonant (CwhRBWXzGAHq8TQ4Fs17)
host_b: Sarah - Mature, Reassuring, Confident (EXAVITQu4vr4xnSDxMaL)

When an approved pronunciation glossary exists, pass it during generation:

python scripts/build_pronunciation_dictionary.py pronunciation_glossary.csv \
  --create \
  --out-manifest pronunciation_dictionary_manifest.json \
  --out-pls pronunciation.pls
 
python scripts/generate_audio.py script.csv \
  --pronunciation-manifest pronunciation_dictionary_manifest.json \
  --voice host_a=VOICE_ID_A \
  --voice host_b=VOICE_ID_B

Use --pronunciation-glossary only as a fallback when an ElevenLabs dictionary locator is unavailable. It rewrites the request payload with text substitutions, which is less precise than IPA phoneme rules and more prone to casing/acronym mistakes.

The script writes ordered audio plus audio_manifest.csv. If the manifest has one generated chunk, that MP3 is already the usable episode segment. Use scripts/merge_audio.py to create the final episode when there are multiple chunks.

Load references/elevenlabs_v3.md when selecting audio tags, pronunciation behavior, chunking, or ElevenLabs request options.

Client Revisions

Use the table IDs to keep revisions stable. Treat edited rows, inserted IDs, skipped rows, and deleted rows as production changes. Regenerate only the affected line or chunk. Preserve previous audio files unless the user explicitly asks to replace them.

Load references/revision_workflow.md before comparing a returned client file to an earlier approved script.

Bundled Resources

• assets/podcast_script_template.csv: client-review CSV template.
• assets/podcast_script_template.xlsx: client-review workbook template.
• scripts/validate_script.py: validate table columns, IDs, hosts, text, statuses, and ordering.
• scripts/renumber_script.py: create clean production IDs while retaining original source IDs.
• scripts/generate_audio.py: generate ElevenLabs dialogue audio and an audio manifest.
• scripts/merge_audio.py: concatenate manifest audio with FFmpeg.
• scripts/compare_revisions.py: compare old and revised script tables and report reuse/regeneration actions.
• scripts/extract_pronunciation_glossary.py: create a review starter glossary from source text.
• scripts/build_pronunciation_dictionary.py: create or update ElevenLabs pronunciation dictionaries from approved glossary rows, and export JSON/PLS review artifacts.