video-lyrics-subtitle

🎵 Video Lyrics Subtitle Generation Skill

Video lyrics subtitle generation engine: from lyrics text + timeline → SRT/ASS subtitles → burned into video via FFmpeg

Trigger Words

Lyrics subtitle, lyrics subtitle, subtitle burning, subtitle generation, SRT, ASS, bilingual subtitle, bilingual subtitles, subtitle file, subtitle creation

Feature Overview

From lyrics text (plain text or LRC format) + timeline information, generate SRT/ASS subtitle files, and burn them into video via FFmpeg.

Core Pipeline

lyrics.txt + audio.mp3
  → generate_srt.py   (生成 SRT 时间轴)
  → generate_ass.py   (可选：生成 ASS 高级样式 / KTV 效果)
  → burn_subtitles.sh (FFmpeg 烧录到视频)
  → final_with_subtitles.mp4

Script Location

All scripts are under the scripts/ subdirectory:

Script	Function
`scripts/generate_srt.py`	Generate SRT subtitles from lyrics text + timeline
`scripts/generate_ass.py`	SRT → ASS conversion (supports KTV highlighting)
`scripts/burn_subtitles.sh`	Burn subtitles into video via FFmpeg

Standard Input

Input	File	Description
Original lyrics	`lyrics/lyrics.txt`	Plain text or LRC format with timestamps
Chinese translation	`lyrics/lyrics_cn.txt`	Optional, for bilingual subtitles
Audio file	`audio/song_final.mp3`	Used to get total duration (for plain text lyrics)
Video file	`video/*.mp4`	Burning target

generate_srt.py — SRT Subtitle Generation

Usage

python3 scripts/generate_srt.py <lyrics_file> [options]

Options

Parameter	Description
`lyrics_file`	Lyrics file path (LRC or plain text)
`--audio <file>`	Audio file, used to get total duration (required for plain text lyrics)
`--duration <seconds>`	Total duration (seconds), replaces `--audio`
`--bilingual <cn_file>`	Chinese translation file, generates bilingual SRT
`--json-timeline <file>`	JSON file with timeline (e.g., `chloe_lyrics_parsed.json`）
`-o / --output <file>`	Output SRT file path (default stdout)

Input Format Support

1. LRC format (with timestamps)

[00:00.00]（纯音乐前奏）
[00:15.00]樱花落尽时 花瓣纷飞如雪
[00:20.00]你的笑容 在记忆中凋谢

2. Plain text format (evenly spaced allocation)

Requires --audio or --duration to specify total duration; each line of lyrics is allocated time at equal intervals. Blank lines indicate instrumental sections, automatically marked as (纯音乐)。

3. JSON timeline format

Pass in a JSON file with a --json-timeline structure via sections[].lines[] , supports precise start/end times.

SRT Generation Rules

Each line of lyrics corresponds to one SRT entry
Blank lines / instrumental sections automatically marked as (纯音乐)
Bilingual mode: original text line on top, translation line below, separated by \N within the same entry
Time format:HH:MM:SS,mmm(SRT standard)

Example

# LRC 歌词 → SRT
python3 scripts/generate_srt.py lyrics/lyrics.lrc -o subtitles/lyrics.srt

# 纯文本歌词 + 音频时长 → SRT
python3 scripts/generate_srt.py lyrics/lyrics.txt --audio audio/song_final.mp3 -o subtitles/lyrics.srt

# 双语字幕
python3 scripts/generate_srt.py lyrics/lyrics.txt --audio audio/song_final.mp3 \
  --bilingual lyrics/lyrics_cn.txt -o subtitles/lyrics_bilingual.srt

# JSON 时间轴 → SRT
python3 scripts/generate_srt.py lyrics/lyrics.txt \
  --json-timeline script/chloe_lyrics_parsed.json \
  -o subtitles/lyrics.srt

generate_ass.py — ASS Advanced Subtitle Generation

Usage

python3 scripts/generate_ass.py <srt_file> [options]

Options

Parameter	Description
`srt_file`	Input SRT file path
`--style <ktv\|simple>`	Style mode (default `simple`）
`--font <name>`	Font name (default `Noto Sans CJK SC`）
`--fontsize <size>`	Font size (default `48`）
`--primary-color <hex>`	Main text color (default `#FFFFFF`）
`--outline-color <hex>`	Outline color (default `#000000`）
`--back-color <hex>`	Background color (default `#80000000` semi-transparent black)
`-o / --output <file>`	Output ASS file path (default same name `.ass`）

ASS Styles

simple mode

Bottom center display
White text + black outline
Semi-transparent background bar

ktv mode

Word-by-word highlight effect (\kt tag)
Text changes from gray to bright color during playback
Suitable for KTV / karaoke scenarios

Example

# 简单样式
python3 scripts/generate_ass.py subtitles/lyrics.srt -o subtitles/lyrics.ass

# KTV 样式
python3 scripts/generate_ass.py subtitles/lyrics.srt --style ktv -o subtitles/lyrics.ass

# 自定义字体和颜色
python3 scripts/generate_ass.py subtitles/lyrics.srt \
  --font "Source Han Sans CN" --fontsize 52 \
  --primary-color "#FFD700" -o subtitles/lyrics.ass

burn_subtitles.sh — FFmpeg subtitle burning

Usage

bash scripts/burn_subtitles.sh <video_file> <subtitle_file> [output_file]

Features

Automatically detect subtitle format (SRT / ASS)
Call FFmpeg hard subtitle burning
Default output filename:<video>_with_subtitles.mp4
FFmpeg path:~/tools/ffmpeg

FFmpeg command

# SRT 硬字幕
ffmpeg -i video.mp4 -vf "subtitles=lyrics.srt" -c:a copy output.mp4

# ASS 硬字幕
ffmpeg -i video.mp4 -vf "ass=lyrics.ass" -c:a copy output.mp4

Example

# 烧录 SRT 字幕
bash scripts/burn_subtitles.sh video/phase1_preview.mp4 subtitles/lyrics.srt video/final_with_subtitles.mp4

# 烧录 ASS 字幕
bash scripts/burn_subtitles.sh video/phase1_preview.mp4 subtitles/lyrics.ass video/final_with_subtitles.mp4

📁 Standard MV project file structure

All MV projects follow the file structure below:

~/clawd/projects/MediaClaw/output/<project-name>/
├── lyrics/                    # 🎵 歌词（必须有）
│   ├── lyrics.txt             # 歌词原文（纯文本或LRC）
│   ├── lyrics_cn.txt          # 中文翻译（可选）
│   └── lyrics.json            # 带时间轴的JSON（程序生成）
├── subtitles/                 # 📝 字幕文件（程序生成）
│   ├── lyrics.srt             # SRT格式
│   ├── lyrics_bilingual.srt   # 双语SRT
│   └── lyrics.ass             # ASS格式（KTV效果）
├── audio/                     # 🎶 音频
│   └── song_final.mp3         # 最终版音频
├── video/                     # 🎬 视频
│   ├── clips/                 # 各clip片段
│   └── final_with_subtitles.mp4  # 最终带字幕视频
├── frames/                    # 🖼️ 参考帧图片
└── script/                    # 📜 剧本/计划
    ├── mv_script.json         # MV脚本
    └── edit_plan.json         # 剪辑计划

File naming rules ⚠️

Content	Fixed path	Description
Original lyrics	`lyrics/lyrics.txt`	Plain text or LRC
Chinese translation	`lyrics/lyrics_cn.txt`	Optional
SRT subtitles	`subtitles/lyrics.srt`	Monolingual
Bilingual SRT	`subtitles/lyrics_bilingual.srt`	Bilingual
ASS subtitles	`subtitles/lyrics.ass`	KTV effect
Final video	`video/final_with_subtitles.mp4`	Finished product with subtitles

Arbitrary naming is prohibited(e.g. sub01.srt、lyrics_raw_v2.txt、final_v3_new.mp4). All files must follow the naming conventions above.

Complete workflow example

# 设置项目路径
PROJECT=~/clawd/projects/MediaClaw/output/chloe-sakura-mv
SKILL=~/clawd/skills/video-lyrics-subtitle

# 1. 生成 SRT 字幕（从 LRC 歌词）
python3 $SKILL/scripts/generate_srt.py \
  $PROJECT/lyrics/lyrics.txt \
  --json-timeline $PROJECT/script/sakura_mv_final.json \
  -o $PROJECT/subtitles/lyrics.srt

# 2. 生成 ASS 字幕（KTV 风格）
python3 $SKILL/scripts/generate_ass.py \
  $PROJECT/subtitles/lyrics.srt \
  --style ktv \
  -o $PROJECT/subtitles/lyrics.ass

# 3. 烧录字幕到视频
bash $SKILL/scripts/burn_subtitles.sh \
  $PROJECT/video/phase1_preview_sakura_mv.mp4 \
  $PROJECT/subtitles/lyrics.ass \
  $PROJECT/video/final_with_subtitles.mp4

About this skill

Trigger Words

Feature Overview

Core Pipeline

Script Location

Standard Input

generate_srt.py — SRT Subtitle Generation

Usage

Options

Input Format Support

1. LRC format (with timestamps)

2. Plain text format (evenly spaced allocation)

3. JSON timeline format

SRT Generation Rules

Example

generate_ass.py — ASS Advanced Subtitle Generation

Usage

Options

ASS Styles

simple mode

ktv mode

Example

burn_subtitles.sh — FFmpeg subtitle burning

Usage

Features

FFmpeg command

Example

📁 Standard MV project file structure

File naming rules ⚠️

Complete workflow example