podcast-generation ยท diff
git:20260126.9f5658f to git:20260126.dddd745
94 added, 33 removed. Audit A to A.
---
name: podcast-generation
description: Use this skill when the user requests to generate, create, or produce podcasts from text content. Converts written content into a two-host conversational podcast audio format with natural dialogue.
---
# Podcast Generation Skill
## Overview
- This skill generates high-quality podcast audio from text content using a multi-stage pipeline. The workflow includes script generation (converting input to conversational dialogue), text-to-speech synthesis, and audio mixing to produce the final podcast.
+ This skill generates high-quality podcast audio from text content. The workflow includes creating a structured JSON script (conversational dialogue) and executing audio generation through text-to-speech synthesis.
## Core Capabilities
- Convert any text content (articles, reports, documentation) into podcast scripts
- Generate natural two-host conversational dialogue (male and female hosts)
- Synthesize speech audio using text-to-speech
- Mix audio chunks into a final podcast MP3 file
- Support both English and Chinese content
## Workflow
### Step 1: Understand Requirements
When a user requests podcast generation, identify:
- Source content: The text/article/report to convert into a podcast
- - Language: English or Chinese (auto-detected from content)
+ - Language: English or Chinese (based on content)
- Output location: Where to save the generated podcast
- You don't need to check the folder under `/mnt/user-data`
- ### Step 2: Prepare Input Content
+ ### Step 2: Create Structured Script JSON
- The input content should be plain text or markdown. Save it to a text file in `/mnt/user-data/workspace/` with naming pattern: `{descriptive-name}-content.md`
+ Generate a structured JSON script file in `/mnt/user-data/workspace/` with naming pattern: `{descriptive-name}-script.json`
- ### Step 3: Execute Generation
+ The JSON structure:
+ ```json
+ {
+ "locale": "en",
+ "lines": [
+ {"speaker": "male", "paragraph": "dialogue text"},
+ {"speaker": "female", "paragraph": "dialogue text"}
+ ]
+ }
+ ```
- Call the Python script directly without any concerns about timeout or the need for pre-testing:
+ ### Step 3: Execute Generation
+ Call the Python script:
```bash
python /mnt/skills/public/podcast-generation/scripts/generate.py \
- --input-file /mnt/user-data/workspace/content-file.md \
+ --script-file /mnt/user-data/workspace/script-file.json \
--output-file /mnt/user-data/outputs/generated-podcast.mp3 \
- --locale en
+ --transcript-file /mnt/user-data/outputs/generated-podcast-transcript.md
```
Parameters:
- - `--input-file`: Absolute path to input text/markdown file (required)
+ - `--script-file`: Absolute path to JSON script file (required)
- `--output-file`: Absolute path to output MP3 file (required)
- - `--locale`: Language locale - "en" for English or "zh" for Chinese (optional, auto-detected if not specified)
+ - `--transcript-file`: Absolute path to output transcript markdown file (optional, but recommended)
> [!IMPORTANT]
- > - Execute the script in one complete call. Do NOT split the workflow into separate steps (e.g., testing script generation first, then TTS).
- > - The script handles all external API calls and audio generation internally with proper timeout management.
+ > - Execute the script in one complete call. Do NOT split the workflow into separate steps.
+ > - The script handles all TTS API calls and audio generation internally.
> - Do NOT read the Python file, just call it with the parameters.
+ > - Always include `--transcript-file` to generate a readable transcript for the user.
- ## Podcast Generation Example
+ ## Script JSON Format
- User request: "Generate a podcast about the history of artificial intelligence"
+ The script JSON file must follow this structure:
- Step 1: Create content file `/mnt/user-data/workspace/ai-history-content.md` with the source text:
- ```markdown
- # The History of Artificial Intelligence
+ ```json
+ {
+ "title": "The History of Artificial Intelligence",
+ "locale": "en",
+ "lines": [
+ {"speaker": "male", "paragraph": "Hello Deer! Welcome back to another episode."},
+ {"speaker": "female", "paragraph": "Hey everyone! Today we have an exciting topic to discuss."},
+ {"speaker": "male", "paragraph": "That's right! We're going to talk about..."}
+ ]
+ }
+ ```
- Artificial intelligence has a rich history spanning over seven decades...
+ Fields:
+ - `title`: Title of the podcast episode (optional, used as heading in transcript)
+ - `locale`: Language code - "en" for English or "zh" for Chinese
+ - `lines`: Array of dialogue lines
+ - `speaker`: Either "male" or "female"
+ - `paragraph`: The dialogue text for this speaker
- ## Early Beginnings (1950s)
- The term "artificial intelligence" was coined by John McCarthy in 1956...
+ ## Script Writing Guidelines
- ## The First AI Winter (1970s)
- After initial enthusiasm, AI research faced significant setbacks...
+ When creating the script JSON, follow these guidelines:
- ## Modern Era (2010s-Present)
- Deep learning revolutionized the field with breakthrough results...
+ ### Format Requirements
+ - Only two hosts: male and female, alternating naturally
+ - Target runtime: approximately 10 minutes of dialogue (around 40-60 lines)
+ - Start with the male host saying a greeting that includes "Hello Deer"
+
+ ### Tone & Style
+ - Natural, conversational dialogue - like two friends chatting
+ - Use casual expressions and conversational transitions
+ - Avoid overly formal language or academic tone
+ - Include reactions, follow-up questions, and natural interjections
+
+ ### Content Guidelines
+ - Frequent back-and-forth between hosts
+ - Keep sentences short and easy to follow when spoken
+ - Plain text only - no markdown formatting in the output
+ - Translate technical concepts into accessible language
+ - No mathematical formulas, code, or complex notation
+ - Make content engaging and accessible for audio-only listeners
+ - Exclude meta information like dates, author names, or document structure
+
+ ## Podcast Generation Example
+
+ User request: "Generate a podcast about the history of artificial intelligence"
+
+ Step 1: Create script file `/mnt/user-data/workspace/ai-history-script.json`:
+ ```json
+ {
+ "title": "The History of Artificial Intelligence",
+ "locale": "en",
+ "lines": [
+ {"speaker": "male", "paragraph": "Hello Deer! Welcome back to another fascinating episode. Today we're diving into something that's literally shaping our future - the history of artificial intelligence."},
+ {"speaker": "female", "paragraph": "Oh, I love this topic! You know, AI feels so modern, but it actually has roots going back over seventy years."},
+ {"speaker": "male", "paragraph": "Exactly! It all started back in the 1950s. The term artificial intelligence was actually coined by John McCarthy in 1956 at a famous conference at Dartmouth."},
+ {"speaker": "female", "paragraph": "Wait, so they were already thinking about machines that could think back then? That's incredible!"},
+ {"speaker": "male", "paragraph": "Right? The early pioneers were so optimistic. They thought we'd have human-level AI within a generation."},
+ {"speaker": "female", "paragraph": "But things didn't quite work out that way, did they?"},
+ {"speaker": "male", "paragraph": "No, not at all. The 1970s brought what's called the first AI winter..."}
+ ]
+ }
```
Step 2: Execute generation:
```bash
python /mnt/skills/public/podcast-generation/scripts/generate.py \
- --input-file /mnt/user-data/workspace/ai-history-content.md \
+ --script-file /mnt/user-data/workspace/ai-history-script.json \
--output-file /mnt/user-data/outputs/ai-history-podcast.mp3 \
- --locale en
+ --transcript-file /mnt/user-data/outputs/ai-history-transcript.md
```
+ This will generate:
+ - `ai-history-podcast.mp3`: The audio podcast file
+ - `ai-history-transcript.md`: A readable markdown transcript of the podcast
+
## Specific Templates
Read the following template file only when matching the user request.
- [Tech Explainer](templates/tech-explainer.md) - For converting technical documentation and tutorials
## Output Format
The generated podcast follows the "Hello Deer" format:
- Two hosts: one male, one female
- Natural conversational dialogue
- Starts with "Hello Deer" greeting
- Target duration: approximately 10 minutes
- Alternating speakers for engaging flow
## Output Handling
After generation:
- - Podcasts are saved in `/mnt/user-data/outputs/`
- - Share generated podcast with user using `present_files` tool
+ - Podcasts and transcripts are saved in `/mnt/user-data/outputs/`
+ - Share both the podcast MP3 and transcript MD with user using `present_files` tool
- Provide brief description of the generation result (topic, duration, hosts)
- Offer to regenerate if adjustments needed
## Requirements
The following environment variables must be set:
- - `OPENAI_API_KEY` or equivalent LLM API key for script generation
- `VOLCENGINE_TTS_APPID`: Volcengine TTS application ID
- `VOLCENGINE_TTS_ACCESS_TOKEN`: Volcengine TTS access token
- `VOLCENGINE_TTS_CLUSTER`: Volcengine TTS cluster (optional, defaults to "volcano_tts")
## Notes
- **Always execute the full pipeline in one call** - no need to test individual steps or worry about timeouts
- - Input content language is auto-detected and matched in output
- - The script generation uses LLM to create natural conversational dialogue
- - Technical content is automatically simplified for audio accessibility
- - Complex notations (formulas, code) are translated to plain language
+ - The script JSON should match the content language (en or zh)
+ - Technical content should be simplified for audio accessibility in the script
+ - Complex notations (formulas, code) should be translated to plain language in the script
- Long content may result in longer podcasts