AutoSubtitle AI - 自動化與代理技能指南
此技能指導您如何使用 auto-subtitle CLI 和 FastAPI 後端，自動化字幕提取、語音轉文字轉錄、歌詞強制對齊（Luna 管線）、本機 LLM 校對以及 GPU 加速影片硬字幕燒錄。
📌 工作流程決策矩陣
根據輸入素材選擇合適的指令或管線：
| 情境 / 目標 | 建議指令 | 關鍵引數 |
|---|---|---|
歌唱 / 歌詞對齊（媒體 + .txt 歌詞） | python src/cli/main.py luna（或 align） | <media> <lyrics.txt> --llm local/api -o <dir> |
| 語音 / 談話 / 影片轉字幕（無腳本） | python src/cli/main.py pipeline | <media> -d cuda -o <dir> |
| 僅提取音訊 | python src/cli/main.py extract | <video> -o <audio.wav> --sr 16000 |
| 修正錯字 / 同音字（使用 Edge LLM） | python src/cli/main.py proofread | <subtitles.srt> --gpu-layers -1 |
| 將字幕燒入影片（硬字幕） | python src/cli/main.py burn | <video> <subtitles.srt> --css "..." |
| 管理字型（安裝開源 / Windows 字型） | python src/cli/main.py fonts | list，install <id/path/url>，remove <filename> |
| 啟動網頁工作室 | python src/cli/main.py serve | --host 0.0.0.0 --port 8000 |
🛠️ CLI 指令參考
1. Luna 歌詞管線（luna / align）
執行 5 步驟雙重驗證管線：Whisper 聲學特徵提取 + stable-ts 對齊 + LLM 決策腦審計 + +0.16 秒可讀性填充：
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）
適用於談話節目、Podcast 和講座的自動語音管線：
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）
使用 GPU 卸載執行本機 Qwen2.5-3B-Instruct GGUF 以修正語音辨識錯誤：
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 "🚀 Processing: $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 "✔ Finished: $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 video created: {burned_mp4}")
配方 3：REST API 整合（FastAPI）
伺服器執行於 http://localhost:8000：
- 轉錄 / 無腳本：
POST /api/ai/transcribe，使用表單欄位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 像素邊距。 |
⚠️ 重要實作注意事項
- GPU 加速：
- Whisper：所有有腳本、無腳本及鎖定時間軸推論皆使用原生 Whisper
large-v3-turbo。模型與後端已固定，請勿傳遞模型或計算類型選項。 - 影片燒錄：預設
use_gpu=True會嘗試 FFmpegh264_nvenc。若執行時期 NVENC 不可用，請使用 CLI--cpu改用libx264。
- Whisper：所有有腳本、無腳本及鎖定時間軸推論皆使用原生 Whisper
- 歌詞多行字串與檔案路徑：
run_luna_pipeline接受檔案路徑（.txt）或原始多行歌詞字串；CLI 僅接受 TXT 路徑。多行字串會直接被解析，不進行檔案系統路徑檢查。
- 不覆寫來源字幕：
- 產生
.srt或.vtt時，輸出會寫入目標輸出目錄；若同名檔案已存在，則會加上.generated.srt後綴。
- 產生