Video Podcast Maker — Workflow Phase 1: Scripting
When to load: Load at workflow start, or when the user asks about research, topic definition, or narration script writing.
Covers: Pre-workflow (optional design reference extraction) → Startup (load user preferences) → Steps 1-4 (topic → research → sections → script).
Next phase: See
workflow-production.mdfor Steps 5-11 (media, TTS, Remotion, render, BGM).
Pre-workflow: Design Reference (Optional)
When the user provides a reference video/image with their video creation request:
- Run extraction:
python3 scripts/learn_design.py <input> - Read extracted frames using your agent's image/file inspection capability
- Analyze against design-guide.md component vocabulary
- Present design analysis report to user
- User confirms/adjusts extracted attributes
- Apply as session overrides for this video (do NOT save to library unless user asks)
Startup: Load User Preferences
Agent behavior: Auto-execute before Step 1, no user interaction needed.
Run the migrator — it creates user_prefs.json from the template if absent, deep-merges any new template fields into existing prefs, and applies structural rewrites for old versions. Idempotent (no-op when already current).
SKILL_DIR="${SKILL_DIR:-${CLAUDE_SKILL_DIR}}"
python3 "${SKILL_DIR}/scripts/migrate_prefs.py"Then read ${SKILL_DIR}/user_prefs.json and apply settings in subsequent steps. Use --dry-run first if you want to preview changes without writing.
The script prints one of: already at v1.6 — no migration needed, Created user_prefs.json at v1.6 from template, or Migrated from v{old} to v1.6 with a per-change list. To inspect what each version added, see the inline _structural_migrate table in scripts/migrate_prefs.py.
At Step 1 start, inform the user of active preferences (if customized):
"Based on your preferences:
- Platform: [platform] | Language: [language]
- TTS: [tts.backend] / [tts.voices[backend]]
- Speech rate: [tts.rate]
- BGM: [bgm.track] at volume [bgm.volume]
- Subtitles: [enabled/disabled] | CTA: [cta.type]
Say 'set platform youtube' or 'set language en-US' to change.
Say 'show preferences' to see all details."Step 1: Define Topic Direction
Auto mode: Infer all decisions from the user's topic description. Use sensible defaults (audience: general, style: educational intro, tone: professional-casual, duration: medium 3-7min). Save directly to videos/{name}/topic_definition.md.
Interactive mode: Confirm each item (use brainstorming skill if available, otherwise ask directly):
- Target audience: developers / general / students / professionals
- Video style: educational intro / deep analysis / news brief / hands-on tutorial
- Content scope: background / technical principles / usage / comparison
- Tone: serious / casual / fast-paced
- Duration: short (1-3min) / medium (3-7min) / long (7-15min)
Save to videos/{name}/topic_definition.md
Step 2: Research Topic
Use your agent's web search and fetch capabilities. Save to videos/{name}/topic_research.md.
Step 3: Design Video Sections
Design 5-7 sections:
- Hero/Intro (15-25s)
- Core concepts (30-45s each)
- Demo/Examples (30-60s)
- Comparison/Analysis (30-45s)
- Summary (20-30s)
Content Density Selection
Assign each section a density tier:
| Tier | Items | Best For |
|---|---|---|
| Impact | 1 | Hook, hero, CTA, brand moment — largest text |
| Standard | 2-3 | Features, comparison, demo |
| Compact | 4-6 | Feature grid, ecosystem |
| Dense | 6+ | Data tables, detailed comparisons — smallest text |
Topic Type Detection
Planned feature. Currently, topic-specific styles are applied manually via
user_prefs.jsonundertopic_patterns. Auto-detection from keywords is not yet implemented.
Title Position
Auto mode: Use top-center (default).
Interactive mode: Ask user: top-center (recommended) / top-left / full-center.
Rule: Keep title position consistent within a single video.
Step 4: Write Narration Script
Preference application: Adjust script style from user_prefs.content:
tone: professional→ formal languagetone: casual→ conversational, interjections okverbosity: concise→ 50-80 chars per paragraphverbosity: detailed→ 100-150 chars per paragraphheroOpening(if set) → use as fixed hero opening lineoutroClosing(if set) → use as fixed outro closing line
Create videos/{name}/podcast.txt with section markers:
[SECTION:hero]
{heroOpening}(话题引入)...
[SECTION:features]
它有以下功能...
[SECTION:demo]
让我演示一下...
[SECTION:summary]
总结一下,xxx是目前最xxx的xxx。
[SECTION:references]
本期视频参考了官方文档和技术博客。
[SECTION:outro]
{outroClosing}Number formatting for TTS
Modern TTS backends (Azure, Edge, Doubao, CosyVoice) handle most everyday numbers correctly when written in ASCII digits. Spell out only the forms TTS engines read ambiguously.
✅ Safe to write as digits (TTS reads them correctly):
| Type | Example | Read as |
|---|---|---|
| Integer with Chinese unit | 2900万, 5亿, 300块 |
二千九百万 / 五亿 / 三百块 |
| Simple percentage | 15%, 90%, -10% |
百分之十五 / 百分之九十 / 负百分之十 |
| Simple decimal | 1.2, 3.5 |
一点二 / 三点五 |
| English unit (tech) | 128GB, 16核, 4K |
一百二十八G / 十六核 / 四K |
| Small integer (<100) | 29, 50 |
二十九 / 五十 |
⚠ Must spell out in Chinese (TTS reads ambiguously or wrong):
| Type | Wrong | Correct |
|---|---|---|
| Date | 2025-01-15 |
二零二五年一月十五日 |
| Year (when stressing "零" reading) | 2025年 |
二零二五年 |
| Version number | v1.2.3, 4.6 |
一点二点三 / 四点六 |
| Phone / ID string | 400-123-4567 |
四零零 一二三 四五六七 |
| Long bare integer (no unit) | 3999999 |
三百九十九万九千九百九十九 (or add 万) |
Rule of thumb: if a number has a Chinese unit after it (万/亿/%/GB/块/点…) or is naturally pronounced in one way, leave it as digits. If it's a date, code, or unitless large integer, write it in Chinese.
Section notes:
- hero: MUST start with
content.heroOpeningif set in user_prefs, followed by the topic hook - summary: Pure content summary, no interaction prompts
- references (optional): One sentence about sources
- outro: MUST use
content.outroClosingif set in user_prefs. Fallback: platform-specific CTA - Empty
[SECTION:xxx]= silent section
Script Template Selection
Copy the script template based on language:
zh-CN→${SKILL_DIR}/templates/podcast_zh.txten-US→${SKILL_DIR}/templates/podcast_en.txt
Outro Text by Platform + Language
| Platform | zh-CN | en-US |
|---|---|---|
| bilibili | "一键三连!评论区留言,下期再见!" | "Like, coin, and favorite! Leave a comment, see you next time!" |
| youtube | "点赞订阅转发!评论区留言,下期再见!" | "Like, subscribe, and share! Leave a comment, see you next time!" |
| xiaohongshu | "点赞收藏加关注,评论区见!" | "Like, save & follow! See you in comments!" |
| douyin | "点赞关注,评论区见!" | "Like & follow! See you in comments!" |
| weixin-channels | "点赞关注,转发给朋友!" | "Like, follow & share with friends!" |
Duration Estimation (Dry Run)
After writing podcast.txt, automatically run:
python3 ${SKILL_DIR}/scripts/generate_tts.py --input videos/{name}/podcast.txt --output-dir videos/{name} --dry-runReport estimated duration. If >12min or <3min, suggest adjustments.
Step 4.5: Pronunciation Pre-Flight (zh-CN only)
Skip if user_prefs.global.language != "zh-CN".
Why an LLM step, not code: Polyphone disambiguation needs sentence-level context (一行 → háng for "a line", xíng for "execute"). A regex or static dict can't substitute for reading the script. The phonemes.json system is the output channel; choosing entries is the LLM's job.
Inputs
videos/{name}/podcast.txt— the script just written${SKILL_DIR}/phonemes.json— global dict (already-covered words; do NOT duplicate)videos/{name}/phonemes.json— project dict (create if missing)
Pass 1 — Polyphone scan
Read podcast.txt sentence by sentence. For every Chinese polyphone risk, pick the pronunciation from context.
Reference table: the common-polyphone checklist and pinyin format rules live in references/zh-polyphones.md — load that file now if this is your first pre-flight pass, then return here for Pass 2.
Pass 2 — English term review
mark_english_terms (in scripts/tts/ssml.py) auto-wraps ASCII runs in <lang xml:lang="en-US">, but has known gaps:
- Hyphenated names:
tldraw-cli→ onlyclimay get wrapped;tldrawreads through the voice's default Chinese pronunciation of letters. - Initialisms:
API,URL,MCPare wrapped as words. If you intend letter-by-letter reading, add an inline marker in podcast.txt:配置 API[ei pi ai] 后... - Versioned names:
GPT-4,Claude 4.6— verify the digit reads as digit and the dash reads as space.
For each risky term, prefer editing podcast.txt:
- Inline marker form:
tldraw-cli[tldraw c l i]or rewrite astldraw 命令行工具 - Multi-word phrases already covered by allowlist:
Claude Code,Final Cut Pro,Visual Studio Code,VS Code,Google Chrome,Open AI,OpenAI,GPT 4,GPT-4
Pass 3 — English brand names with Chinese pronunciation
Some products are spelled in English in scripts/code/papers but have an established Chinese pronunciation that listeners expect. The phoneme system handles this cleanly: SSML <phoneme> tag overrides voice pronunciation while leaving the subtitle text unchanged (still shows "Qwen", audio says "千问").
Add to videos/{name}/phonemes.json (or global if it's a stable choice):
{
"Qwen": "qiān wèn",
"Bilibili": "bì lì bì lì"
}Decision rule:
- Has a widely-recognized Chinese name and the script says it in a Chinese-language sentence → add phoneme entry to read it in Chinese.
- Is a code identifier, paper title term, or quoted English brand → leave it as English (don't add).
- Examples to leave alone:
Claude,Gemini,Llama,Mistral,OpenAI,Anthropic,GitHub,Docker,Python— these are read in English in Chinese tech speech.
Use judgment per script. Don't over-translate.
Output
- Updated
videos/{name}/phonemes.json— pretty-printed JSON, longest-key entries first. - (Optional) Edits to
videos/{name}/podcast.txtfor inline English markers or rewrites. - Console summary:
Pronunciation pre-flight: N polyphone entries added, M English terms flagged.If both 0:No issues found.
Re-run behavior
Always re-scan when this step runs. Existing project-level entries that are still correct should be preserved; new findings get appended. Stale entries (word no longer in podcast.txt) can be left as-is — unused entries cost nothing.