Troubleshooting

ffmpeg not found

DemoVoice requires ffmpeg and ffprobe on your PATH.

Solution: Install ffmpeg via your package manager:

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

# Verify installation
ffmpeg -version

Go version too old

DemoVoice requires Go 1.22 or later.

Solution: Update Go to the latest version:

# Check version
go version

# Update via your package manager or download from go.dev

OPENAI_API_KEY not set

DemoVoice requires an OpenAI API key for transcription and TTS.

Solution: Set the environment variable:

export OPENAI_API_KEY=sk-your-key-here

Rate limit exceeded

OpenAI has rate limits on API calls.

Solution: Reduce concurrency in your config:

profiles:
  default:
    segment_concurrency: 2  # Reduce from default 4

Poor transcription accuracy

Whisper may struggle with certain audio conditions.

Possible causes:

• Background noise or music
• Multiple speakers talking simultaneously
• Very fast speech
• Heavy accents or unclear pronunciation

Solutions:

• Re-record in a quieter environment
• Speak more slowly and clearly
• Add commonly misheard terms to your glossary

Missing segments

Some spoken content isn't being detected.

Solution: Check your timing parameters:

profiles:
  default:
    min_segment_seconds: 1.0  # Lower threshold for short segments

Audio sounds too fast/slow

The generated speech doesn't match the original timing well.

Solution: Adjust stretch/compress limits:

profiles:
  default:
    max_segment_stretch: 1.20   # Allow 20% slower
    max_segment_compress: 0.85  # Allow 15% faster

Audio clips or cuts off

Segments end abruptly before the speech completes.

Solution: Increase silence padding:

profiles:
  default:
    silence_padding_ms: 500  # Increase from default 350

Output file won't play

The rendered video is corrupted or unplayable.

Solution: Check ffmpeg output for errors by running with the verbose flag:

demovoice render demo.mp4 --verbose --output demo.demovoice.mp4

Audio/video out of sync

The new audio track doesn't align with the video.

Solution: This usually indicates a timing calculation issue. Try:

• Run demovoice inspect to verify segment boundaries
• Ensure preserve_timing: true is set
• Check for variable frame rate in source video