Index of every page on this site: llms.txt
All skills
dtsola avatar

/video-podcast-maker

@e86893e
by dtsoladtsola/xiaoyaosearch1k stars
54
Run it yourself

Use when the user gives a topic and wants an automated video podcast created, or asks to learn visual design patterns from a reference video/image. Produces 4K video via research → script → TTS → Remotion → MP4 + BGM.

Use this Skill: https://skilld.dev/gh/dtsola/xiaoyaosearch/video-podcast-maker

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencestroubleshooting.md

≈2.6k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Video Podcast Maker — Troubleshooting & Reference

When to load: Load this file when encountering errors, when the user asks about preferences, or when the user asks about BGM options.

Troubleshooting

TTS: Azure API Key Error

Symptoms: Error: Authentication failed, HTTP 401 Unauthorized

Solution:

echo $AZURE_SPEECH_KEY
echo $AZURE_SPEECH_REGION

export AZURE_SPEECH_KEY="your-key-here"
export AZURE_SPEECH_REGION="eastasia"

FFmpeg: BGM Mixing Issues

Symptoms: BGM too loud over voice, BGM ends abruptly

Solution:

# Basic mix (voice primary, BGM lowered)
ffmpeg -i voice.mp3 -i bgm.mp3 \
  -filter_complex "[0:a]volume=1.0[voice];[1:a]volume=0.15[bgm];[voice][bgm]amix=inputs=2:duration=first" \
  -ac 2 output.mp3

# With fade in/out
ffmpeg -i voice.mp3 -i bgm.mp3 \
  -filter_complex "
    [0:a]volume=1.0[voice];
    [1:a]volume=0.15,afade=t=in:st=0:d=2,afade=t=out:st=58:d=2[bgm];
    [voice][bgm]amix=inputs=2:duration=first
  " output.mp3

Remotion: Render Out of Memory

Symptoms: FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed, render crashes at ~50%

Solution:

# Reduce parallelism
npx remotion render ... --concurrency 1

# Or increase Node memory
NODE_OPTIONS="--max-old-space-size=8192" npx remotion render ...

Remotion: Black Screen / No Content

Symptoms: Output video is all black or all white, no visual elements

Solution:

  1. Verify timing.json exists in videos/{name}/ and has correct start_frame/duration_frames
  2. Check composition ID matches: npx remotion render ... CompositionId must match Root.tsx registration
  3. Ensure --public-dir videos/{name}/ is passed to all Remotion commands
  4. Check browser console in npx remotion studio for JS errors

Remotion: Command Not Found

Symptoms: npx: command not found or remotion: not found

Solution:

# Ensure you're in the Remotion project directory
cd your-remotion-project
npm i   # reinstall dependencies
npx remotion --version  # verify

timing.json: Parse Error

Symptoms: SyntaxError: Unexpected token, sections missing or misaligned

Solution:

# Validate JSON
python3 -c "import json; json.load(open('videos/{name}/timing.json'))"

# Check section names match podcast.txt [SECTION:xxx] markers

Common cause: section name in podcast.txt doesn't match the composition code.


SRT: Garbled Chinese Characters

Symptoms: Subtitles show ??? or mojibake

Solution:

# Check encoding
file videos/{name}/podcast_audio.srt
# Should show: UTF-8 Unicode text

# Convert if needed
iconv -f GBK -t UTF-8 videos/{name}/podcast_audio.srt > videos/{name}/podcast_audio_utf8.srt
mv videos/{name}/podcast_audio_utf8.srt videos/{name}/podcast_audio.srt

Disk Space: 4K Render Fails

Symptoms: Render stops partway, No space left on device

Solution: 4K render needs ~10-20GB free space. Check with df -h . before rendering. Clean up old video outputs or use --scale 0.5 for 1080p.


Font Not Found (Linux)

Symptoms: Text renders in fallback font, Chinese characters show as boxes

Solution:

# Install Noto Sans SC
sudo apt install fonts-noto-cjk
# Or download PingFang SC manually

Edge TTS: No Audio Output

Symptoms: Empty or zero-length WAV file, no error message

Solution: Edge TTS requires internet access (uses Microsoft's online TTS service). Check network connectivity. No API key needed.


Quick Checklists

Pre-render:

  • All asset files exist
  • timing.json format correct
  • Audio duration matches timing
  • Environment variables set
  • Disk space sufficient (>20GB for 4K)

Post-render:

  • Video duration correct
  • Audio-video sync
  • Subtitles display correctly
  • No black/blank frames

Background Music Options

Included Tracks

Available at ${SKILL_DIR}/assets/:

Track Mood Best For
perfect-beauty-191271.mp3 Upbeat, positive Tech demos, product intros, tutorials
snow-stevekaldes-piano-397491.mp3 Calm piano Reflective topics, analysis, comparisons

Using Custom BGM

cp /path/to/my-bgm.mp3 videos/{name}/bgm.mp3

If user says "use my own BGM" or provides a file path, skip the default BGM copy in Step 11.

Royalty-Free BGM Sources

Source URL License
Pixabay Music https://pixabay.com/music/ Free, no attribution
Free Music Archive https://freemusicarchive.org/ CC licenses
Incompetech https://incompetech.com/ CC BY (attribution)
Uppbeat https://uppbeat.io/ Free tier available
Chosic https://www.chosic.com/free-music/all/ Various CC

BGM Selection Guide

Video Type Recommended Mood Volume
Tech/coding Lo-fi, ambient 0.03-0.05
Product review Upbeat, corporate 0.05-0.08
News/analysis Neutral, minimal 0.03-0.05
Tutorial Calm, steady 0.04-0.06
Lifestyle Warm, acoustic 0.05-0.08

Agent behavior: In auto mode, select most appropriate included track by topic type. In interactive mode, ask user.


Preference Commands

Users can manage preferences in conversation:

View Preferences

User says: "show preferences" / "显示偏好设置"

The agent outputs the current settings summary (visual, TTS, content, topic patterns, learning history count).

Reset Preferences

User says: "reset preferences" / "重置偏好"

cp ${SKILL_DIR}/user_prefs.template.json ${SKILL_DIR}/user_prefs.json
echo "✓ Preferences reset to defaults"

Save Current Settings

User says: "save this as tech default" / "把这个设置保存为科技类默认"

The agent extracts current visual/TTS/content settings and updates topic_patterns.tech.

Manual Preference Setting

User says: "set speech rate to +10%" / "dark theme as default" / "title always 100px"

The agent directly updates the corresponding field in user_prefs.json.

Platform & Language Commands

User Says Action
"set platform youtube" Update global.platform to "youtube"
"set platform bilibili" Update global.platform to "bilibili"
"set platform xiaohongshu" Update global.platform to "xiaohongshu"
"set platform douyin" Update global.platform to "douyin"
"set platform weixin-channels" Update global.platform to "weixin-channels"
"set language en-US" Update global.language to "en-US"
"set language zh-CN" Update global.language to "zh-CN"
"show platform" Show current platform and language
"disable subtitles" Set global.subtitle.enabled to false
"enable subtitles" Set global.subtitle.enabled to true
"set subtitle font Arial" Set global.subtitle.fontName to "Arial"
"set subtitle size 24" Set global.subtitle.fontSize to 24
"set CTA text" Set global.cta.type to "text"
"set CTA animation" Set global.cta.type to "animation"
"enable chapters" Set global.content.chapters to true
"disable chapters" Set global.content.chapters to false

Preference Learning

Planned feature (not yet implemented). The schema supports learning_history records, but automatic detection of preference changes during Studio sessions is not yet coded. Currently, preferences are set manually via the commands above.

Planned capabilities:

  • Detect repeated style modifications during Studio preview
  • Ask user whether to promote changes to global defaults
  • Track learning history in user_prefs.json

Design Learning Troubleshooting

"ffmpeg not found" when learning from video

Install ffmpeg: brew install ffmpeg (macOS) or use image input instead.

Playwright fails on Bilibili/YouTube

URL extraction is experimental. Fallback options:

  1. Download the video and use: learn ./video.mp4
  2. Take screenshots manually and use: learn ./screenshot1.png ./screenshot2.png

Vision analysis colors look wrong

Color values from image analysis are approximate. After reviewing the report:

  • Adjust colors manually: edit report.json or override when creating the style profile
  • Use a color picker tool on the screenshots for precise hex values

Style profile not applied

Check priority chain: style_profiles only override when explicitly specified by name. Verify: python3 scripts/learn_design.py --list shows the reference exists. Verify: user_prefs.json → style_profiles → your profile name exists with correct props_override.

Orphaned references (deleted directory but still in index)

Run references list — orphaned entries are auto-cleaned on list.


Doubao TTS: Phoneme System Not Supported

Symptoms: Inline phoneme markers 执行器[zhí xíng qì] and phonemes.json entries are ignored when using Doubao backend.

Explanation: Doubao TTS uses a plain-text HTTP API that does not support SSML or phoneme tags. The phoneme system (inline markers, project phonemes.json, global phonemes.json) only works with Azure TTS. CosyVoice and Edge TTS also do not apply phonemes.

Workaround: If pronunciation accuracy is critical, use Azure TTS (TTS_BACKEND=azure).


ElevenLabs / OpenAI / Google TTS Limitations

  • No phoneme support: Inline markers 执行器[zhí xíng qì] and phonemes.json are ignored
  • OpenAI TTS has no word boundaries: Subtitle timing is approximate (evenly distributed across words). For precise subtitles, use Azure, Edge, or ElevenLabs
  • Google Cloud TTS has no word boundaries: Subtitle timing is approximate (same as OpenAI). For precise subtitles, use Azure, Edge, or ElevenLabs
  • Workaround: If subtitle precision is critical, use Azure TTS (TTS_BACKEND=azure), Edge TTS (TTS_BACKEND=edge), or Google Cloud TTS is not recommended for subtitle-critical workflows

Doubao TTS: API Error Codes

Symptoms: Doubao API error code=XXXX

Common codes:

  • code != 3000: Non-success response. Check VOLCENGINE_APPID and VOLCENGINE_ACCESS_TOKEN.
  • HTTP 401/403: Invalid or expired access token. Regenerate at Volcengine Console.
  • Timeout: Increase via VOLCENGINE_TIMEOUT_SEC env var (default: 60s).

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

2 warnings4mo3 checks · Risk SAFE
  • Gen Agent Trust Hub4mo

    The skill is an automated video podcast creation pipeline that handles research, scriptwriting, audio synthesis, and video rendering. It uses industry-standard tools like FFmpeg and Remotion, and integrates with well-known cloud services (Azure, OpenAI, Google, etc.) for Text-to-Speech synthesis. Its operations, including media processing and update checks, are consistent with its functional purpose as a developer-oriented automation tool.

  • Socket4mo

    1 alert: gptAnomaly

  • Snyk4mo

    Risk: MEDIUM · 2 issues

Signed by skilld at e86893e. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated 7 months ago
argument-hint
[topic]
effort
high
author
Agents365-ai
Other metadata
category
Content Creation
version
2.0.0
created
2025-01-27
updated
2026-04-03
bilibili
https://space.bilibili.com/441831884
github
https://github.com/Agents365-ai/video-podcast-maker
dependencies
[
  "remotion-best-practices"
]
metadata
{
  "openclaw": {
    "requires": {
      "bins": [
        "python3",
        "ffmpeg",
        "node",
        "npx"
      ]
    },
    "primaryEnv": "AZURE_SPEECH_KEY",
    "emoji": "🎬",
    "homepage": "https://github.com/Agents365-ai/video-podcast-maker",
    "os": [
      "macos",
      "linux"
    ],
    "install": [
      {
        "kind": "brew",
        "formula": "ffmpeg",
        "bins": [
          "ffmpeg"
        ]
      },
      {
        "kind": "uv",
        "package": "edge-tts",
        "bins": [
          "edge-tts"
        ]
      }
    ]
  }
}

README badge

README badge for dtsola/xiaoyaosearch/video-podcast-maker