nicko1122/auto-subtitle

AutoSubtitle AI - 自动化与智能体技能指南

本技能指导你如何使用 auto-subtitle CLI 和 FastAPI 后端自动化完成字幕提取、语音转文字转录、歌词强制对齐（Luna 管道）、本地 LLM 校对以及 GPU 加速视频硬字幕烧录。

---

📌 工作流决策矩阵

根据输入素材选择适当的命令或管道：

场景/目标	推荐命令	关键参数
歌曲/歌词对齐（媒体 + .txt 歌词）	python src/cli/main.py luna（或 align）	<媒体> <歌词.txt> --llm local/api -o <目录>
演讲/对话/视频字幕（无脚本）	python src/cli/main.py pipeline	<媒体> -d cuda -o <目录>
仅提取音频	python src/cli/main.py extract	<视频> -o <音频.wav> --sr 16000
修复错别字/同音字（使用 Edge LLM）	python src/cli/main.py proofread	<字幕.srt> --gpu-layers -1
将字幕烧录到视频（硬字幕）	python src/cli/main.py burn	<视频> <字幕.srt> --css "..."
管理字体（安装开源/Windows 字体）	python src/cli/main.py fonts	list，install <id/path/url>，remove <文件名>
启动 Web Studio	python src/cli/main.py serve	--host 0.0.0.0 --port 8000

---

🛠️ CLI 命令参考

1. Luna 歌词管道（luna / align）

运行 5 步双验证管道：Whisper 声学特征提取 + stable-ts 对齐 + LLM 决策大脑审计 + +0.16s 可读性填充：

python src/cli/main.py luna inputclip/test_video.mp4 inputclip/audio-org.txt \
    --llm local \
    --output-dir output_luna

--output-dir 中的输出交付物：

• lyrics.srt：标准 SRT 字幕轨道。
• lyrics.vtt：用于网络播放器的 WebVTT 格式。
• lyrics.lrc：增强型 LRC 格式，带毫秒时间戳，适用于音乐播放器。
• lyrics.ass：格式化 ASS 字幕，可直接用于 FFmpeg 烧录。
• cue_evidence.json：每行完整的声学证据和置信度指标。
• review.csv：异常行及 LLM 仲裁决策的详细报告。
• run_manifest.json：源媒体和输出的 SHA-256 完整性哈希。

2. 端到端语音管道（pipeline）

适用于脱口秀、播客和讲座的自动语音管道：

python src/cli/main.py pipeline inputclip/test_video.mp4 \
    --device cuda \
    --prompt "繁體中文" \
    --max-chars 16 \
    --pause 0.45 \
    --output-dir output/

3. Edge LLM 校对（proofread）

运行本地 Qwen2.5-3B-Instruct GGUF，利用 GPU 卸载修复语音识别错误：

python src/cli/main.py proofread output/video.srt \
    --gpu-layers -1 \
    --batch-size 8 \
    --output output/video.proofread.srt

4. GPU 硬字幕视频烧录（burn）

使用 NVIDIA NVENC GPU 加速，直接将样式化 ASS 字幕烧录到视频帧中：

# 使用内联 CSS 字符串（支持不透明度、外描边、字体、盒模型内边距、颜色）
python src/cli/main.py burn inputclip/test_video.mp4 output/lyrics.srt \
    --css "font-family: 'Noto Sans CJK TC'; font-size: 36px; color: #FFD700; opacity: 0.85; -webkit-text-stroke: 3px #000; text-shadow: 2px 2px 3px #000; padding: 40px 40px 60px 40px;" \
    -o output/final_burned.mp4

# 或使用外部 CSS 样式表：
python src/cli/main.py burn inputclip/test_video.mp4 output/lyrics.srt \
    --css-file styles/youtube_style.css \
    -o output/final_burned.mp4

# 或使用显式参数：
python src/cli/main.py burn inputclip/test_video.mp4 output/lyrics.srt \
    --font "jf-openhuninn-2.0" \
    --size 38 \
    --color "#FFFFFF" \
    --opacity 0.9 \
    --outline 3.0 \
    --outline-color "#000000" \
    --direction horizontal \
    --valign bottom \
    --halign center

5. 字体管理（fonts）

# 列出所有可用、已安装和 Windows 系统字体
python src/cli/main.py fonts list

# 按预设 ID 安装流行开源字体：
# 选项：openhuninn（粉圓體），lxgw-wenkai（霞鶩文楷），iansui（芫荽體），win-msjhbd（微軟正黑粗體）
python src/cli/main.py fonts install openhuninn

# 从 URL 或本地文件安装：
python src/cli/main.py fonts install https://example.com/font.ttf
python src/cli/main.py fonts install /path/to/custom_font.otf

---

🤖 自动化配方

配方 1：批量处理目录中的所有视频（Bash）

#!/usr/bin/env bash
set -e
INPUT_DIR="./raw_videos"
OUTPUT_DIR="./dist_videos"
mkdir -p "$OUTPUT_DIR"

for video in "$INPUT_DIR"/*.mp4; do
  [ -f "$video" ] || continue
  filename=$(basename "$video")
  stem="${filename%.*}"
  lyrics="$INPUT_DIR/$stem.txt"
  
  echo "🚀 正在处理：$filename"
  
  if [ -f "$lyrics" ]; then
    # 带脚本歌词的管道
    python3 src/cli/main.py luna "$video" "$lyrics" --output-dir "$OUTPUT_DIR/$stem" --llm local
    sub_file="$OUTPUT_DIR/$stem/lyrics.srt"
  else
    # 无脚本语音管道
    python3 src/cli/main.py pipeline "$video" -d cuda --output-dir "$OUTPUT_DIR/$stem"
    sub_file="$OUTPUT_DIR/$stem/$stem.srt"
  fi
  
  # 使用品牌样式烧录硬字幕
  python3 src/cli/main.py burn "$video" "$sub_file" \
    --css "font-size: 34px; color: #FFFFFF; opacity: 0.9; -webkit-text-stroke: 2.5px #000; text-shadow: 2px 2px #000;" \
    -o "$OUTPUT_DIR/${stem}_subtitled.mp4"
    
  echo "✔ 完成：$stem"
done

配方 2：Python 字幕生成脚本

from pathlib import Path
from src.core.luna_pipeline import run_luna_pipeline
from src.core.video_burner import burn_subtitles_to_video
from src.schemas.subtitle import SubtitleStyle

media_file = "inputclip/test_video.mp4"
lyrics_file = "inputclip/audio-org.txt"
out_dir = Path("output_automation")

# 1. 运行 Luna 双验证管道
track = run_luna_pipeline(
    audio_path=media_file,
    lyrics_source=lyrics_file,
    output_dir=str(out_dir),
    llm_provider="local"
)

# 2. 定义带不透明度和外描边的字幕样式
style = SubtitleStyle.from_css(
    "font-size: 36px; color: #FFD700; opacity: 0.85; -webkit-text-stroke: 3px #000;"
)

# 3. 直接使用 NVENC GPU 烧录字幕
burned_mp4 = burn_subtitles_to_video(
    video_path=media_file,
    subtitles_source=str(out_dir / "lyrics.srt"),
    output_path=str(out_dir / "burned_output.mp4"),
    style=style,
    use_gpu=True
)
print(f"烧录视频已创建：{burned_mp4}")

配方 3：REST API 集成（FastAPI）

服务器运行在 http://localhost:8000：

• 转录/无脚本：POST /api/ai/transcribe，携带 Form 字段 media_path=...，auto_proofread=true
• 对齐/Luna 管道：POST /api/ai/align，携带 JSON {"media_path": "...", "script_text": "...", "script_mode": "reference", "llm_provider": "local"}
• 解析 CSS：POST /api/style/parse-css，携带 JSON {"css": "font-size: 36px; opacity: 0.8;"}
• 烧录视频：POST /api/burn，携带 JSON {"video_path": "...", "subtitle_path": "...", "css": "..."}

---

🎨 CSS 盒模型与 ASS 样式映射

使用 --css 设计字幕样式时：

CSS 属性	ASS 格式转换	说明
opacity: 0.85	反转 alpha 十六进制 &H26FFFFFF&	Alpha = round((1 - opacity) * 255)。0=不透明，255=透明。
-webkit-text-stroke: 4px #000	Outline: 2.0，OutlineColour: &H00000000&	配合 paint-order: stroke fill;，描边仅向外扩展。
text-shadow: 2px 2px 3px #000	Shadow: 2.0，BackColour: &H80000000&	使用较大的绝对轴偏移；等轴 CSS 可无漂移地往返。
writing-mode: vertical-rl	垂直列布局，使用 \N 换行	超出视口高度时自动从右向左换行。
text-align: center/left/right	九宫格对齐映射（1~9）	底部居中 = 2，顶部居中 = 8，中间居中 = 5。
padding: 50px 40px 60px 40px	MarginV，MarginL，MarginR	转换为相对于 PlayRes 分辨率的 ASS 像素边距。

---

⚠️ 重要实现说明

1. GPU 加速：
   • Whisper：所有脚本化、非脚本化和锁定时间线推理均使用原生 Whisper large-v3-turbo。模型和后端是固定的；请勿传递模型或计算类型选项。
   • 视频烧录：默认 use_gpu=True 尝试 FFmpeg h264_nvenc。在运行时 NVENC 不可用时，使用 CLI --cpu 切换到 libx264。
2. 歌词多行字符串与文件路径：
   • run_luna_pipeline 接受文件路径（.txt）或原始多行歌词字符串；CLI 接受 TXT 路径。多行字符串直接解析，不执行文件系统路径检查。
3. 不覆盖源字幕：
   • 生成 .srt 或 .vtt 时，输出写入目标输出目录；如果同名文件已存在，则添加 .generated.srt 后缀。