中文文档

A powerful tool to convert audio files into videos with auto-generated, synchronized, and highlighted subtitles (Karaoke style).

• Auto Transcription: Uses faster-whisper for high-accuracy speech-to-text with word-level timestamps.
• Dynamic Backgrounds: Moving multi-color gradient with selectable palettes (plasma/aurora effects).
• Karaoke Subtitles: Real-time highlighting of spoken words.
• Customizable: Adjust font size, color, highlight color, and position.
• Transcript Editing: Export transcripts to JSON for manual correction, then re-import to generate the perfect video.

This project can be installed in two ways:

pip install lyrichroma

This project is managed with uv.

# Install uv if you haven't (https://github.com/astral-sh/uv)
pip install uv

# Clone and sync dependencies
uv sync

Convert audio to video with a black background:

uv run lyrichroma --input audio.mp3 --output video.mp4

Generate a video with a cool moving background:

uv run lyrichroma --input audio.mp3 --output video.mp4 --bg-type dynamic --bg-value aurora

Available palettes: aurora (default), sunset, ocean, cyberpunk, forest.

For cases where automatic transcription isn't perfect, LyriChroma provides a transcript editing workflow:

1. Generate transcript JSON (skip video generation):

   uv run lyrichroma --input audio.mp3 --save-transcript transcript.json

2. Edit transcript.json manually to correct any transcription errors or adjust timing.
3. Generate video from edited transcript:

   uv run lyrichroma --input audio.mp3 --output video.mp4 --load-transcript transcript.json

This workflow is especially useful when you need perfect accuracy for professional use cases, or when dealing with specialized vocabulary, names, or accents that ASR systems might not recognize correctly.

Customize the subtitle appearance:

uv run lyrichroma \
  --input audio.mp3 \
  --output video.mp4 \
  --font-size 60 \
  --font-color "#FFFFFF" \
  --highlight-color "#FF0000" \
  --text-y 0.8

Run unit tests:

uv run pytest

Lyrichroma supports a pluggable ASR architecture. By default, it uses faster-whisper. You can implement your own ASR provider by subclassing lyrichroma.asr.base.ASRProvider and passing it to the Transcriber.

1. Install Dependencies: uv sync
2. Run Tests: uv run pytest
3. Format & Lint:

   uv run ruff check .
   uv run black .