Extract visual design patterns from reference videos or images and apply them to new video compositions. Skip this section unless the user provides a reference video/image or asks to save/list/delete style profiles.

→ See references/design-learning.md for commands, reference-library management, style-profile management, and integration with Pre-workflow / Step 9.

Auto Update Check

Agent behavior: Check for updates at most once per day (throttled by timestamp file). Before any shell command that reads files from this skill, resolve SKILL_DIR to the directory containing SKILL.md. If your agent exposes a built-in skill directory variable such as ${CLAUDE_SKILL_DIR}, you may map it to SKILL_DIR.

SKILL_DIR="${SKILL_DIR:-${CLAUDE_SKILL_DIR}}"
STAMP="${SKILL_DIR}/.last_update_check"
NOW=$(date +%s)
LAST=$(cat "$STAMP" 2>/dev/null || echo 0)
if [ ! -d "${SKILL_DIR}/.git" ]; then
  echo "MANUAL_INSTALL"
elif [ $((NOW - LAST)) -gt 86400 ]; then
  timeout 5 git -C "${SKILL_DIR}" fetch --quiet 2>/dev/null || true
  LOCAL=$(git -C "${SKILL_DIR}" rev-parse HEAD 2>/dev/null)
  REMOTE=$(git -C "${SKILL_DIR}" rev-parse origin/main 2>/dev/null)
  echo "$NOW" > "$STAMP"
  if [ -n "$LOCAL" ] && [ -n "$REMOTE" ] && [ "$LOCAL" != "$REMOTE" ]; then
    echo "UPDATE_AVAILABLE"
  else
    echo "UP_TO_DATE"
  fi
else
  echo "SKIPPED_RECENT_CHECK"
fi

• Update available: Ask the user whether to pull updates. Yes → git -C "${SKILL_DIR}" pull. No → continue.
• Up to date / Skipped: Continue silently.
• Manual install (no .git directory — skill was installed via tarball/zip/cp): Continue silently. Auto-update is disabled; the user must reinstall manually to update.

Prerequisites Check

Agent behavior: Run the pre-flight check below before Step 1. SKILL_DIR must already be resolved (see Auto Update Check section above for resolution rules).

SKILL_DIR="${SKILL_DIR:-${CLAUDE_SKILL_DIR}}"
python3 "${SKILL_DIR}/scripts/check_prereqs.py"

If MISSING reported, see README.md for full setup instructions (install commands, API key setup, Remotion project init). The check is backend-aware: backend is resolved as TTS_BACKEND env var → user_prefs.json (global.tts.backend) → edge default, then only env vars required by that backend are validated.

Overview

Automated pipeline for professional Bilibili horizontal knowledge videos from a topic.

Target: Bilibili horizontal video (16:9)

• Resolution: 3840×2160 (4K) or 1920×1080 (1080p)
• Style: Clean white (default)

Tech stack: Coding agent + TTS backend + Remotion + FFmpeg

Output Specs

| Parameter | Horizontal (16:9) | Vertical (9:16) | |-----------|-------------------|-----------------| | Resolution | 3840×2160 (4K) | 2160×3840 (4K) | | Frame rate | 30 fps | 30 fps | | Encoding | H.264, 16Mbps | H.264, 16Mbps | | Audio | AAC, 192kbps | AAC, 192kbps | | Duration | 1-15 min | 60-90s (highlight) |

Execution Modes

Agent behavior: Detect user intent at workflow start:

• "Make a video about..." / no special instructions → Auto Mode
• "I want to control each step" / mentions interactive → Interactive Mode
• Default: Auto Mode

Auto Mode (Default)

Full pipeline with sensible defaults. Mandatory stop at Step 9:

1. Step 9: Launch Remotion Studio — user reviews in real-time, requests changes until satisfied
2. Step 10: Only triggered when user explicitly says "render 4K" / "render final version"

| Step | Decision | Auto Default | |------|----------|-------------| | 3 | Title position | top-center | | 5 | Media assets | Skip (text-only animations) | | 7 | Thumbnail method | Remotion-generated (16:9 + 4:3) | | 9 | Outro animation | Pre-made MP4 (white/black by theme) | | 9 | Preview method | Remotion Studio (mandatory) | | 12 | Subtitles | Skip | | 14 | Cleanup | Auto-clean temp files |

Users can override any default in their initial request:

• "make a video about AI, burn subtitles" → auto + subtitles on
• "use dark theme, AI thumbnails" → auto + dark + imagen
• "need screenshots" → auto + media collection enabled

Interactive Mode

Prompts at each decision point. Activated by:

• "interactive mode" / "I want to choose each option"
• User explicitly requests control

Technical Rules

Hard constraints for video production. Visual design remains the agent's creative freedom within these rules:

| Rule | Requirement | |------|-------------| | Single Project | All videos under videos/{name}/ in user's Remotion project. NEVER create a new project per video. | | 4K Output | 3840×2160, use scale(2) wrapper over 1920×1080 design space | | Content Width | ≥85% of screen width | | Bottom Safe Zone | Bottom 100px reserved for subtitles | | Audio Sync | All animations driven by timing.json timestamps | | Thumbnail | MUST generate 16:9 (1920×1080) AND 4:3 (1200×900). Centered layout, title ≥120px, icons ≥120px, fill most of canvas. See design-guide.md. | | Font | PingFang SC / Noto Sans SC for Chinese text | | Studio Before Render | MUST launch remotion studio for user review. NEVER render 4K until user explicitly confirms ("render 4K", "render final"). |

Additional Resources

Load these files on demand — do NOT load all at once:

• references/workflow-steps.md: Index of the 15-step workflow split across three phase files. Load at workflow start to locate which phase file to pull:
  • workflow-script.md — Pre-workflow + Startup + Steps 1-4 (scripting)
  • workflow-production.md — Steps 5-11 (media, TTS, Remotion, render, BGM)
  • workflow-publish.md — Steps 12-15 (subtitles, publish, cleanup, shorts)
• references/design-guide.md: Visual minimums, typography, layout patterns, checklists, animation safety rules. MUST load before Step 9.
• references/design-learning.md: Extracting visual patterns from reference videos/images, style profiles. Load only when the user provides a reference or manages profiles.
• references/azure-tts-pitfalls.md: Voice selection guide, Multilingual gotchas, SSML pitfalls, style support matrix. Load when choosing Azure voice/style or debugging hoarse/missing/glitchy audio.
• references/troubleshooting.md: Error fixes, BGM options, preference commands, preference learning. Load on error or user request.
• templates/presets/kinetic-typography/: Bold type-driven preset (black BG + mint/yellow accents + character-pop animations). Use for opinion / argument / declaration videos. Load README first.
• examples/: Real production video projects. The agent may reference these for composition structure and timing.json format.

Script suite dispatcher (optional)

All scripts in ${SKILL_DIR}/scripts/ are reachable through one hierarchical entry point:

python3 ${SKILL_DIR}/scripts/cli.py --help                 # list resources
python3 ${SKILL_DIR}/scripts/cli.py <resource> --help      # list actions
python3 ${SKILL_DIR}/scripts/cli.py <resource> <action> --help  # forwards to underlying script
python3 ${SKILL_DIR}/scripts/cli.py schema [<method>]      # JSON parameter schema

Routes (all forward to the existing scripts; direct invocations keep working): tts run|validate, verify, audit beats, shorts gen, design list|show|delete|add, prereqs, prefs get|migrate|backend|bgm-path, schema [<method>].

The dispatcher is optional — every snippet in this file uses the direct script path for back-compat. Agents that prefer one entry point with discoverable help should prefer cli.py.

Pre-render audit (recommended)

Before launching Studio for Step 9 review:

python3 ${SKILL_DIR}/scripts/audit_beat_sync.py <Video.tsx> <timing.json>

Prints a beat-vs-narration alignment table and flags drift > 1.5s. Especially important for kinetic-typography style where each beat must hit a specific narration moment.

End-of-pipeline acceptance gate (MANDATORY)

After Step 13, before declaring the video done:

python3 ${SKILL_DIR}/scripts/verify_output.py videos/{name}/

Auto-fixes common omissions (creates final_video.mp4 if missing; disable with --no-fix), validates resolution/codec/duration, checks audio-timing drift, sanity-checks publish_info.md. Exit 0 = green light to publish; exit 2 = warnings only, still publishable. For machine-readable output add --format json (auto when piped). Full flag reference in references/workflow-publish.md.

Directory Structure

project-root/                           # Remotion project root
├── src/remotion/                       # Remotion source
│   ├── compositions/                   # Video composition definitions
│   ├── Root.tsx                        # Remotion entry
│   └── index.ts                        # Exports
│
├── public/                             # Remotion default (unused — use --public-dir videos/{name}/)
│
├── videos/{video-name}/                # Video project assets
│   ├── topic_definition.md             # Step 1
│   ├── topic_research.md               # Step 2
│   ├── podcast.txt                     # Step 4: narration script
│   ├── podcast_audio.wav               # Step 8: TTS audio
│   ├── podcast_audio.srt               # Step 8: subtitles
│   ├── timing.json                     # Step 8: timeline
│   ├── thumbnail_*.png                 # Step 7
│   ├── output.mp4                      # Step 10
│   ├── video_with_bgm.mp4             # Step 11
│   ├── final_video.mp4                 # Step 12: final output
│   └── bgm.mp3                         # Background music
│
└── remotion.config.ts

Important: Always use --public-dir and full output path for Remotion render:

npx remotion render src/remotion/index.ts CompositionId videos/{name}/output.mp4 --public-dir videos/{name}/

Naming Rules

Video name {video-name}: lowercase English, hyphen-separated (e.g., reference-manager-comparison)

Section name {section}: lowercase English, underscore-separated, matches [SECTION:xxx]

Thumbnail naming (16:9 AND 4:3 both required): | Type | 16:9 | 4:3 | |------|------|-----| | Remotion | thumbnail_remotion_16x9.png | thumbnail_remotion_4x3.png | | AI | thumbnail_ai_16x9.png | thumbnail_ai_4x3.png |

Public Directory

Use --public-dir videos/{name}/ for all Remotion commands. Each video's assets (timing.json, podcast_audio.wav, bgm.mp3) stay in its own directory — no copying to public/ needed. This enables parallel renders of different videos.

# All render/studio/still commands use --public-dir
npx remotion studio src/remotion/index.ts --public-dir videos/{name}/
npx remotion render src/remotion/index.ts CompositionId videos/{name}/output.mp4 --public-dir videos/{name}/ --video-bitrate 16M
npx remotion still src/remotion/index.ts Thumbnail16x9 videos/{name}/thumbnail.png --public-dir videos/{name}/

Workflow

Progress Tracking

At Step 1 start, use your agent's task tracker (Claude Code TaskCreate / Codex todo list / equivalent) to create one task per step. Mark in_progress on start, completed on finish. Files in videos/{name}/ (e.g. podcast.txt, timing.json, output.mp4) act as the durable record of what completed — if a session is interrupted, inspect the directory to determine where to resume.

 1. Define topic direction → topic_definition.md
 2. Research topic → topic_research.md
 3. Design video sections (5-7 chapters)
 4. Write narration script → podcast.txt
 4.5. Pronunciation pre-flight (zh-CN only) → videos/{name}/phonemes.json
 5. Collect media assets → media_manifest.json
 6. Generate publish info (Part 1) → publish_info.md
 7. Generate thumbnails (16:9 + 4:3) → thumbnail_*.png
 8. Generate TTS audio → podcast_audio.wav, timing.json
 9. Create Remotion composition + Studio preview (mandatory stop)
10. Render 4K video (only on user request) → output.mp4
11. Mix background music → video_with_bgm.mp4
12. Add subtitles (optional) → final_video.mp4
13. Complete publish info (Part 2) → chapter timestamps
14. Verify output & cleanup
15. Generate vertical shorts (optional) → shorts/

Validation Checkpoints

After Step 8 (TTS):

• [ ] podcast_audio.wav exists and plays correctly
• [ ] timing.json has all sections with correct timestamps
• [ ] podcast_audio.srt encoding is UTF-8

After Step 10 (Render):

• [ ] output.mp4 resolution is 3840x2160
• [ ] Audio-video sync verified
• [ ] No black frames

Key Commands Reference

See CLAUDE.md for the full command reference (TTS, Remotion, FFmpeg, shorts generation).

User Preference System

Skill learns and applies preferences automatically. See references/troubleshooting.md for commands and learning details.

Storage Files

| File | Purpose | |------|---------| | user_prefs.json | Learned preferences (auto-created from template) | | user_prefs.template.json | Default values | | prefs_schema.json | JSON schema definition |

Priority

Final = merge(Root.tsx defaults < global < topic_patterns[type] < current instructions)

User Commands

| Command | Effect | |---------|--------| | "show preferences" | Show current preferences | | "reset preferences" | Reset to defaults | | "save as X default" | Save to topic_patterns |

Troubleshooting & Preferences

Full reference: Read references/troubleshooting.md on errors, preference questions, or BGM options.

Platform Optimizations

Bilibili:

• Script Structure - Welcome intro + call-to-action outro (一键三连)
• Chapter Timestamps - Auto-generated MM:SS format for B站 chapters
• Thumbnail Generation - AI (imagen/imagenty) or Remotion, auto-generates 16:9 + 4:3 versions
• Visual Style - Bold text, minimal whitespace, high information density
• Publish Info - Title formulas, tag strategies, description templates

YouTube:

• SEO Optimization - Title <70 chars, keyword-rich description, tags and hashtags
• Chapters - Auto-generated YouTube chapter timestamps (first line at 0:00)
• CTA - "Like, Subscribe & Share" text animation or custom

Xiaohongshu (小红书):

• Title - Max 20 chars, punchy and emoji-friendly
• Description - 200-500 chars, 种草/knowledge-sharing style with emoji
• Hashtags - #话题# format (double hash), 5-10 tags
• Thumbnail - 3:4 (1080x1440) for feed optimization
• CTA - "点赞收藏加关注" text animation

Douyin (抖音):

• Format - Vertical shorts only (9:16), no horizontal long-form
• Description - 100-200 chars, casual and conversational with emoji
• Hashtags - #话题 format (single hash), 3-8 tags
• CTA - "点赞关注" text only (no animation)

WeChat Channels (微信视频号):

• Format - Vertical shorts only (9:16), no horizontal long-form
• Description - 100-300 chars, knowledge-sharing style for forwarding
• Hashtags - #话题 format (single hash), 3-8 tags
• CTA - "点赞关注，转发给朋友" text only (no animation)

Workflow

⚠️ For the human reading this (not the AI): manually polish podcast.txt, repeatedly

This section is for you, the human — not the agent. Every downstream step — TTS narration, subtitles, section transitions, animation timing, final cut — is derived from this single podcast.txt. A weak script renders into 4K garbage. No amount of polish downstream saves it.

The AI-generated draft is a starting point, nothing more. Do these yourself — don't hand them off to the AI:

1. Mentally read it as the narrator. Treat each sentence as one breath — if a line forces you to "catch your breath" or backtrack to parse, fix it. Where you stumble silently is where TTS stumbles audibly.
2. Revise at least three times.
   • Pass 1: typos, awkward phrasing, tongue-twisters
   • Pass 2: cut filler, cut throat-clearing intros ("So today we're going to talk about…"), cut redundancy
   • Pass 3: tune rhythm — where to pause, where to break a long sentence, which word carries the stress
3. Read each [SECTION:xxx] block end-to-end. Confirm each section opens with a hook and lands a clean transition into the next — not a bullet-point dump.
4. Audit numbers, proper nouns, and English terms separately. ~90% of TTS mispronunciations live here. If pronunciation is wrong, add it to phonemes.json; if it just sounds awkward, rewrite it.
5. Know your length budget. Estimate ~280 zh-CN chars/min or ~150 en words/min. A 5–10 min video means ~1400–2800 chars / 750–1500 words. Don't pad to fill time.

The only acceptance test: read through it once in your head — does any line make you wince? If yes, don't move on to Step 8 (TTS) yet. Otherwise you're just rendering 4K of something even you don't want to hear.

Related Skills

This skill depends on remotion-best-practices and works alongside other optional skills:

• remotion-best-practices - Official Remotion best practices (required, provides core Remotion patterns and guidelines)
• find-skills - Official skill discovery tool (optional, helps find and install additional skills)
• ffmpeg - Advanced audio/video processing (optional)
• imagen / imagenty - AI thumbnail generation (optional)

Requirements

System Requirements

| Software | Version | Purpose | |----------|---------|---------| | macOS / Linux | - | Tested on macOS, Linux compatible | | Python | 3.8+ | TTS script, automation | | Node.js | 18+ | Remotion video rendering | | FFmpeg | 4.0+ | Audio/video processing |

Installation

# macOS
brew install ffmpeg node python3

# Ubuntu/Debian
sudo apt install ffmpeg nodejs python3 python3-pip

# Python dependencies
pip install azure-cognitiveservices-speech dashscope edge-tts requests

Project Setup (Required)

Important: This skill requires a Remotion project as the foundation.

Understanding the components:

| Component | Source | Purpose | |-----------|--------|---------| | Remotion Project | npx create-video | Base framework with src/, public/, package.json | | video-podcast-maker | SKILL.md workflow | Workflow orchestration (this skill) |

# Step 1: Create a new Remotion project (base framework)
npx create-video@latest my-video-project
cd my-video-project
npm i  # Install Remotion dependencies

# Step 2: Verify installation
npx remotion studio  # Should open browser preview

If you already have a Remotion project:

cd your-existing-project
npm install remotion @remotion/cli @remotion/player zod

API Keys Required

| Service | Purpose | Get Key | |---------|---------|---------| | Azure Speech | TTS audio generation (high quality) | Azure Portal → Speech Services | | Volcengine Doubao Speech | TTS audio generation (alternative backend) | Volcengine Console | | Aliyun CosyVoice | TTS audio generation (alternative backend) | Aliyun Bailian | | Edge TTS | TTS audio generation (default, free, no key needed) | pip install edge-tts | | ElevenLabs | TTS audio generation (highest quality English) | ElevenLabs | | Google Cloud TTS | TTS audio generation (wide language support) | Google Cloud Console | | OpenAI | TTS audio generation (simple API) | OpenAI Platform | | Google Gemini | AI thumbnail generation (optional) | AI Studio | | Aliyun Dashscope | AI thumbnail - Chinese optimized (optional) | Aliyun Bailian |

Environment Variables

Add to ~/.zshrc or ~/.bashrc:

# TTS Backend: edge (default, free), azure, doubao, cosyvoice, elevenlabs, google, openai
export TTS_BACKEND="edge"                            # Default (free), or "azure" / "doubao" / "cosyvoice" / "elevenlabs" / "google" / "openai"

# Azure TTS (high quality)
export AZURE_SPEECH_KEY="your-azure-speech-key"
export AZURE_SPEECH_REGION="eastasia"

# Volcengine Doubao TTS (alternative backend)
export VOLCENGINE_APPID="your-volcen