自動字幕（語音轉字幕）
把音訊/影片裡的人聲辨識成人聲。基於共享腳本 skills/shared/scripts/asr.py（faster-whisper 封裝），
參數確定、可重現，做中文友好斷句。可選擇把字幕燒錄進影片（複用 skills/shared/scripts/video_ops.py / ffmpeg subtitles 濾鏡）。
只做「語音 → 字幕檔案 (+ 可選燒錄)」。通用影片剪輯見 video-editing；純降噪見 audio-denoise；長影片智慧切片+燒字幕見 clipify。
輸入
| 欄位 | 必填 | 說明 |
|---|---|---|
| input_file | 是 | 音訊或影片檔案路徑（影片自動提取音軌） |
| format | 否 | srt（預設）/ ass / txt / json |
| language | 否 | auto（預設）或 zh/en 等 ISO 639-1 碼 |
| model | 否 | tiny/base（預設）/small/medium/large-v3，越大越準越慢 |
| burn | 否 | 是否將字幕燒錄進影片（需影片輸入） |
支援：mp3/wav/m4a/aac/flac 等音訊；mp4/mkv/mov/webm 等影片。
輸出
- 字幕檔案放入
outputs/主題名/（SRT/ASS/TXT/JSON） - 若燒錄：帶硬字幕的影片（
*-sub.mp4） - 報告：辨識語言、字幕條數、所用模型、輸出路徑
前置
- 首次執行會從 HuggingFace 下載模型，需外網代理。腳本讀取
EASEL_PROXY或http(s)_proxy環境變數作為代理； 都未設則直連。也可先export https_proxy=... http_proxy=...指定。 - CPU 環境用預設
--device cpu --compute-type int8即可。
執行步驟
腳本路徑（相對專案根目錄）：skills/shared/scripts/asr.py、skills/shared/scripts/video_ops.py。
1. 產生字幕檔案
# 影片 → SRT（自動提取音軌 + 自動偵測語言）
python skills/shared/scripts/asr.py transcribe \
-i input.mp4 -o outputs/主題名/input.srt --language zh
# 影片 → ASS（帶樣式，**字型大小/邊距按影片橫豎螢幕自適應**）：影片輸入自動探測寬高
python skills/shared/scripts/asr.py transcribe \
-i input.mp4 -o outputs/主題名/input.ass --format ass --model small
# 純音訊 → ASS：無法探測尺寸，預設豎螢幕 1080x1920；橫螢幕加 --res 1920x1080
python skills/shared/scripts/asr.py transcribe \
-i voice.mp3 -o outputs/主題名/voice.ass --format ass --res 1920x1080
- ASS 樣式按目標影片寬高自適應：字型大小按短邊(min(w,h)*0.05，豎/橫螢幕都≈合適、不再橫螢幕過大)，
底邊距按高、左右邊距按寬，
PlayRes=真實寬高。影片輸入自動探測；純音訊用--res 寬x高指定。 要帶樣式的硬字幕優先燒這份 ASS（下節），比裸 SRT + 手填 force_style 更省心、且自適應。 - 中文預設每行 ~18 字，超長自動斷行/拆條；
--max-line-chars可調。 - 不給
-o時按輸入檔名建專案目錄，例如talk.mp4輸出到outputs/talk/talk.srt；已有專案應顯式-o outputs/主題名/<檔名>.<format>。 - 查看可用模型/語言：
python skills/shared/scripts/asr.py info。
2.（可選）將字幕燒錄進影片
用戶要「硬字幕/燒進影片」時，用 ffmpeg 的 subtitles（SRT）或 ass（ASS）濾鏡：
# 燒 SRT（可訂製樣式）
ffmpeg -y -i input.mp4 \
-vf "subtitles=outputs/主題名/input.srt:force_style='FontName=Noto Sans CJK SC,FontSize=20,PrimaryColour=&H00FFFFFF,OutlineColour=&H80000000,BorderStyle=1,Outline=2'" \
-c:a copy outputs/主題名/input-sub.mp4
# 燒 ASS（樣式已在 ass 檔案裡，保真）
ffmpeg -y -i input.mp4 \
-vf "ass=outputs/主題名/input.ass" \
-c:a copy outputs/主題名/input-sub.mp4
- 路徑含特殊字元時，把
subtitles=的值用單引號包裹並跳脫冒號。 - 需要軟字幕（可關閉）而非燒錄：
ffmpeg -i in.mp4 -i sub.srt -c copy -c:s mov_text out.mp4。
3. 產物與報告
- 字幕檔案、燒錄影片均寫入
outputs/主題名/。 - 向用戶報告：辨識語言、字幕條數、模型、檔案路徑；提示可換
--model/--max-line-chars重跑。
規則
- 影片先提取音軌 — 腳本自動用 ffmpeg 提取 16kHz 單聲道 wav，不改原影片。
- 中文友好斷句 — 按標點/長度斷行，避免一行過長。
- 絕不刪原檔案 — 只產出新檔案到
outputs/。 - 模型選擇 — 求快用
base，求準用small/medium；CPU 用 int8。 - 燒錄需影片輸入 — 純音訊無法燒錄，只出字幕檔案。
- 無 Profile 依賴 — 轉錄不需要帳號畫像。
自研參考
- SYSTRAN/faster-whisper — CTranslate2 加速的 Whisper 推理
- openai/whisper — 原始 Whisper 模型與 ASR 方法
- FFmpeg
subtitles/ass濾鏡（字幕燒錄）