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.

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 Chinese
lines: 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 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 - 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 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:

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
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