Podcast Generation Skill
Overview
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 (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: Create Structured Script JSON
Generate a structured JSON script file in /mnt/user-data/workspace/ with naming pattern: {descriptive-name}-script.json
The JSON structure:
{
"locale": "en",
"lines": [
{"speaker": "male", "paragraph": "dialogue text"},
{"speaker": "female", "paragraph": "dialogue text"}
]
}
Step 3: Execute Generation
Call the Python script:
python /mnt/skills/public/podcast-generation/scripts/generate.py \
--script-file /mnt/user-data/workspace/script-file.json \
--output-file /mnt/user-data/outputs/generated-podcast.mp3 \
--transcript-file /mnt/user-data/outputs/generated-podcast-transcript.md
Parameters:
--script-file: Absolute path to JSON script file (required)--output-file: Absolute path to output MP3 file (required)--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.
- 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.
- The TTS provider and its concurrency are selected automatically from environment variables — you do not choose or tune them.
Script JSON Format
The script JSON file must follow this structure:
{
"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..."}
]
}
Fields:
title: Title of the podcast episode (optional, used as heading in transcript)locale: Language code - "en" for English or "zh" for Chineselines: Array of dialogue lines
speaker: Either "male" or "female"paragraph: The dialogue text for this speaker
Script Writing Guidelines
When creating the script JSON, follow these guidelines:
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:
{
"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:
python /mnt/skills/public/podcast-generation/scripts/generate.py \
--script-file /mnt/user-data/workspace/ai-history-script.json \
--output-file /mnt/user-data/outputs/ai-history-podcast.mp3 \
--transcript-file /mnt/user-data/outputs/ai-history-transcript.md
This will generate:
ai-history-podcast.mp3: The audio podcast fileai-history-transcript.md: A readable markdown transcript of the podcast
Specific Templates
Read the following template file only when matching the user request.
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 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:
- For Volcengine:
VOLCENGINE_TTS_APPID and VOLCENGINE_TTS_ACCESS_TOKEN
- For MiniMax:
MINIMAX_API_KEY
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
- 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
Providers (Volcengine / MiniMax)
Auto-selected by environment variables:
VOLCENGINE_TTS_APPID + VOLCENGINE_TTS_ACCESS_TOKEN set → Volcengine TTS (default).- Only
MINIMAX_API_KEY set → MiniMax TTS (/v1/t2a_v2).
- Force with
PODCAST_GENERATION_PROVIDER=volcengine|minimax.
MiniMax overrides: MINIMAX_API_HOST (default https://api.minimaxi.com),
MINIMAX_TTS_MODEL (default speech-2.6-hd), MINIMAX_TTS_VOICE_MALE
(default male-qn-qingse), MINIMAX_TTS_VOICE_FEMALE (default female-tianmei).
Concurrency is owned by each provider internally — MiniMax runs single-threaded
to reduce rate-limit failures, Volcengine uses 4 workers. There is no
caller-facing concurrency knob; transient rate limits are handled by automatic
retry with backoff.
