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.mp3Remotion: 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:
- Verify
timing.jsonexists invideos/{name}/and has correctstart_frame/duration_frames - Check composition ID matches:
npx remotion render ... CompositionIdmust match Root.tsx registration - Ensure
--public-dir videos/{name}/is passed to all Remotion commands - Check browser console in
npx remotion studiofor 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 # verifytiming.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] markersCommon 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.srtDisk 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 manuallyEdge 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.mp3If 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_historyrecords, 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:
- Download the video and use:
learn ./video.mp4 - 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ì]andphonemes.jsonare 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_SECenv var (default: 60s).