Srt

SRT — 一鍵字幕 Pipeline

將影片或音檔轉成校正後的台灣繁體中文 SRT 字幕。全程自動化，用戶只需提供 YouTube 連結或本地檔案路徑。

Pipeline 總覽

YouTube 連結 或 本地影片/音檔
  ↓ Step 0 (if YouTube): yt-dlp 下載影片
  ↓ Step 0.5 (if 投影片文字): 抽取本集術語補充表
本地影片檔
  ├─ Step 1:  subtitle.sh (Breeze ASR)        ─┐ 平行
  └─ Step 1': vibevoice_asr.py (VV ASR)       ─┘
原始 SRT (.srt) + VV JSON
  ↓ Step 1.5: srt_hallucination_fix.py (幻覺偵測+自動修復)
  ↓ Step 2a: srt_preprocess.py → _2a_preprocessed.srt
  ↓ Step 2b: Agent subagent (Sonnet) 逐段校正 + VV 交叉參考 → _2b_corrected.srt
  ↓ Step 2c: 複查 + srt_postprocess.py → _2c_reviewed.srt → _2c_final.srt
  ↓ Step 3: 術語學習
術語表自動成長
  ↓ Step 4 (if 有影片檔): ffmpeg 合併字幕進影片
字幕影片 (_sub.mkv)

檔案路徑

所有 pipeline 腳本位於：

SUBTITLE_DIR=/Users/fredchu/Documents/For_Claude/scripts/subtitle
CORRECT_DIR=${SUBTITLE_DIR}/srt_correct

${SUBTITLE_DIR}/
├── subtitle.sh                          # Step 1: ASR
├── srt_correct/
│   ├── srt_correct_prompt.txt           # LLM system prompt
│   ├── srt_preprocess.py                # Step 2a: 機械性預處理
│   ├── srt_postprocess.py               # Step 2c: 後處理（強制拆句等）
│   └── terms_austin_v2.txt              # Austin 術語表

執行步驟

解析用戶意圖

從用戶訊息中判斷輸入類型，三種路徑：

| 輸入 | 判斷方式 | 起始步驟 | |------|---------|---------| | YouTube 連結 | 包含 youtube.com 或 youtu.be | Step 0（下載）→ Step 1 → Step 2 | | 本地影片 | .mp4 / .mkv / .mov / .webm 等 | Step 1（ASR）→ Step 2 | | 本地音檔 | .mp3 / .wav / .m4a / .flac 等 | Step 1（ASR，subtitle.sh 自動處理音檔格式）→ Step 2 |

其他參數：

• ASR 模式：預設 Breeze（--breeze）。用戶提到 whisper / 英文內容 / 非中文 → 用 Whisper（不加 --breeze）
• 術語表：預設 terms_austin_v2.txt。用戶指定其他講者 → 尋找對應術語表
• 投影片文字：用戶提供投影片文字檔（.txt）→ 啟用 Step 0.5 抽取本集術語
• 特殊要求：--learn（術語學習）、--bilingual（雙語輸出）
• LLM 模式：預設 Sonnet subagent（雲端）。用戶提到 --local / 「用本地」/ 「離線」→ 用 Ollama gemma4:26b。需要 Ollama 已啟動且 gemma4:26b 已拉取

工作目錄設定（每部影片必做）

所有產出檔案放進 media//，不要散落在根目錄。

1. 從影片標題取一個簡短資料夾名：去掉 YouTube ID、去掉副檔名、截斷過長標題

• 例：20260311-驚不驚喜 [CkzcQfVr5ow].mkv → 20260311-驚不驚喜
• 例：投資組合-2月-03 [DZ5LgiWOPZ8].mkv → 投資組合-2月-03
• 例：YouTube 標題 用Claude Code自动做Skill的万能配方 → 用Claude-Code自动做Skill

1. 建立目錄：

VIDEO_DIR="${SUBTITLE_DIR}/media/"
mkdir -p "${VIDEO_DIR}"

1. 後續所有步驟的 ` 都用 ${VIDEO_DIR}`

Step 0 (YouTube only): 下載影片

只有輸入是 YouTube 連結時才執行這步。本地檔案直接跳到 Step 1。

cd "${VIDEO_DIR}"
yt-dlp -f "bestvideo[height"

本地檔案的處理：把影片/音檔搬進 ${VIDEO_DIR}（如果已經在裡面就不用搬）：

mv "" "${VIDEO_DIR}/"

說明：

• 下載影片（含影像+音訊），用戶後續還會使用影片檔
• 檔名格式：影片標題 [影片ID].mkv
• 下載完成後，用 ${VIDEO_DIR} 內的 mkv 檔案路徑繼續 Step 1
• 影片檔在 pipeline 結束後保留，不要刪除

Step 0.5 (optional): 從投影片抽取本集術語

只有用戶提供投影片文字檔時才執行。沒有則跳過。

從投影片文字中抽取以下類型的術語，產出一份 per-video 術語補充表：

1. Austin 獨創概念：如「曝險」「場外全壘打」「大象起舞」等非通用金融術語
2. 本集會提到的人名/公司名：如 Howard Marks、NIKE、NFLX、LULU
3. 英文專有名詞及其中文對照：如 Ivy Portfolio→常春藤投資組合、slugging percentage→長打率
4. 本集特定的金融術語：如再平衡、周轉率、13F 持倉報告

抽取規則：

• 只抽 ASR 可能聽錯的詞（冷門術語、英文混搭、Austin 獨創用語）
• 不抽通用常見詞（「股票」「債券」「投資」等 ASR 不會錯的）
• 與 terms_austin_v2.txt 比對，已有的不重複列出
• 產出格式：一行一個術語，附簡短說明（供 LLM 校正時理解語境）

產出存為：/_slide_terms.txt

在 Step 2b 組裝 prompt 時，把這份補充表加在術語表後面，作為額外的「本集投影片術語」區塊。不要合併進通用術語表 terms_austin_v2.txt。

Step 1': VibeVoice 平行 ASR（與 Step 1 同時跑）

VibeVoice 做輔助 ASR，產出供 Step 2b 交叉參考。與 Step 1 用兩個平行 Bash 呼叫同時執行。

短音檔（≤ 55 分鐘）— 直接跑：

python3 /Users/fredchu/dev/vibevoice-poc/vibevoice_asr.py \
    "${VIDEO_DIR}/" \
    --terms "${CORRECT_DIR}/terms_austin_v2.txt" \
    --terms-max 50 \
    --json \
    --output "${VIDEO_DIR}/_vibevoice.srt"

長音檔（> 55 分鐘）— 切段跑再合併 JSON：

mlx_audio 套件硬限制 59 分鐘（MAX_DURATION_SECONDS = 59 * 60），超過會自動 trim 截斷。用 ffmpeg 在靜音點切段，每段 ≤ 50 分鐘（留安全餘量），各自跑 VV 再合併 JSON（時間戳偏移對齊）：

# 1. 偵測靜音點，在最接近 45 分鐘倍數的靜音處切段
ffmpeg -i "${VIDEO_DIR}/" -af silencedetect=noise=-30dB:d=0.5 -f null - 2>&1 | grep silence_end

# 2. 每段各自跑 VV（可平行）
python3 /Users/fredchu/dev/vibevoice-poc/vibevoice_asr.py \
    "${VIDEO_DIR}/_part1.wav" \
    --terms "${CORRECT_DIR}/terms_austin_v2.txt" --terms-max 50 \
    --json --output "${VIDEO_DIR}/_vv_part1.srt"
# ... 同理 part2, part3, ...

# 3. 合併 JSON：偏移每段的 Start/End 時間戳
python3 -c "
import json, sys
offset = 0.0
merged = []
for i in range(1, int(sys.argv[1]) + 1):
    segs = json.load(open(f'${VIDEO_DIR}/_vv_part{i}_vibevoice.json'))
    for s in segs:
        for key in ['Start', 'start', 'start_time']:
            if key in s: s[key] = float(s[key]) + offset
        for key in ['End', 'end', 'end_time']:
            if key in s: s[key] = float(s[key]) + offset
    merged.extend(segs)
    # offset = 該段結束時間（從 ffmpeg 切段記錄取得）
    if segs:
        offset = max(float(s.get('End', s.get('end', s.get('end_time', 0)))) for s in segs)
json.dump(merged, open('${VIDEO_DIR}/_vibevoice.json', 'w'), ensure_ascii=False, indent=2)
print(f'Merged {len(merged)} segments')
" 

產出：

• _vibevoice.srt — VV 的 SRT（備用）
• _vibevoice.json — VV 的 segments JSON（Step 2b 用），欄位格式：Start/End/Content/Speaker

注意：

• 如果 VV 執行失敗（模型未安裝等），pipeline 繼續跑，Step 2b 跳過 VV 參考
• 用 --breeze 時才啟用 Step 1'（Whisper 模式不用 VV，因為 VV 底層也是 Whisper 架構）
• mlx_audio 套件硬限制 59 分鐘（MAX_DURATION_SECONDS = 59 * 60），超過會靜默 trim — 必須在 pipeline 端切段，不能依賴 VV 自己處理
• vibevoice_asr.py 的 max_tokens 已改為 32768（原 8192 對 > 30 分鐘音檔不夠，會導致 0 segments）
• generate() 其他可調參數：repetition_penalty（預設 1.2）、prefill_step_size（預設 2048，長音檔可提高以降低記憶體峰值）
• 不要同時跑兩個 VV instance — 會搶 Apple Silicon GPU 記憶體互相 thrash，必須序列執行

Step 1: ASR 語音辨識

cd /Users/fredchu/Documents/For_Claude/scripts/subtitle
./subtitle.sh "${VIDEO_DIR}/" --breeze

如果用戶要求 Whisper：

./subtitle.sh "${VIDEO_DIR}/"

產出：${VIDEO_DIR}/.srt（Breeze）或 ${VIDEO_DIR}/_zh-TW.srt（Whisper + OpenCC）

subtitle.sh 內部還會自動執行 Step 4.5（postprocess_srt.py）：用 sherpa-onnx 模型恢復標點 + terminology_rules.py 術語校正，就地覆寫同一個 .srt。所以拿到的 SRT 已經過標點恢復，不是純 ASR 原始輸出。

這一步耗時最長（約影片長度的 0.05-0.1x），跑完後告知用戶 ASR 完成並繼續。

Step 1.5: ASR 幻覺偵測 + 自動修復

ASR 完成後，自動掃描 SRT 找兩種異常：

1. 重複型幻覺：同一字/詞在單條字幕中重複 ≥ 10 次（如 Whisper 把「漲漲漲」幻覺成 100 個「漲」）
2. 時間軸空白：相鄰字幕間隔 > 10 秒（ASR 跳過整段語音）

偵測到就自動截取該段音檔、用 Breeze ASR 重跑、patch 回 SRT。

CORRECT_DIR=/Users/fredchu/Documents/For_Claude/scripts/subtitle/srt_correct
python3 "${CORRECT_DIR}/srt_hallucination_fix.py" "" "${VIDEO_DIR}/" --breeze

如果是 Whisper ASR，不加 --breeze。

腳本會自動處理，無需人工介入。如果二次 ASR 仍是幻覺，會印 WARNING 跳過。

Fallback：換 Whisper large-v3 重跑。檢查 srthallucinationfix.py 的輸出，如果有「多次重試仍失敗」的 WARNING，不要跳過 — 用 scripts/hallucination_fallback.sh 自動改用 Whisper large-v3 重跑。Breeze 對特定段落會反覆產生相同幻覺，換模型通常能解決。

對每個 WARNING 跳過的幻覺段：

1. 從 SRT 定位幻覺條目的起止時間軸（前後各留 2 秒 buffer）
2. 取幻覺前 2-3 條字幕文字作為 initial prompt
3. 執行 fallback 腳本：

SKILL_DIR="$(dirname "$(readlink -f "$0")")"  # 或直接用 skill 路徑
"${SKILL_DIR}/scripts/hallucination_fallback.sh" \
  "" "" "" "" ""

腳本會自動完成：截取音檔 → Whisper large-v3 重跑 → 時間偏移 → patch 回 SRT → 清理暫存。如果 Whisper 結果仍為幻覺，會印 WARNING 跳過（該段可能真的是靜音/音樂）。

完成後如果已有字幕影片（_sub.mkv），刪掉舊的並用 ffmpeg 重新合併。

Step 2: LLM 校正（三階段）

重要：不要跑 srt_correct.sh！ 它內部用 claude -p，在 Claude Code 裡會被環境變數阻擋。改用以下三階段流程。

Step 2a: 預處理

CORRECT_DIR=/Users/fredchu/Documents/For_Claude/scripts/subtitle/srt_correct
python3 "${CORRECT_DIR}/srt_preprocess.py" "" "_2a_preprocessed.srt" --stats --breeze

（如果是 Whisper ASR，不加 --breeze）

Step 2b: 分段 + Agent 校正

> Context 節約原則：主 agent 不讀 SRT 內容到自己的 context。切分、prompt 組裝全部在 disk 上用腳本完成，subagent 自己讀檔案。

1. 用 Python 腳本一次完成切分 + prompt 組裝：

在 Bash 中執行以下 Python 腳本（不要用 Read 工具讀 SRT 檔案）：

```python python3 -c " import re, os, json

CORRECTDIR = '${CORRECTDIR}' WORKDIR = '' SRTFILE = '' SLIDETERMS = '' # 沒有就留空 VVJSON = '' # Step 1' 產出的 _vibevoice.json，沒有就留空

# 讀取 prompt 模板和術語表 prompt = open(f'{CORRECTDIR}/srtcorrectprompt.txt').read() terms = open(f'{CORRECTDIR}/termsaustinv2.txt').read()

# 組裝術語區塊 termsection = terms if SLIDETERMS and os.path.exists(SLIDETERMS): slide = open(SLIDETERMS).read() term_section += '\n\n## 本集投影片術語\n' + slide

systemprompt = prompt.replace('{{TERMINOLOGYSECTION}}', term_section)

# 如果有 VV JSON，在 system prompt 末尾加 VV 交叉參考 section vvsegments = [] if VVJSON and os.path.exists(VVJSON): vvsegments = json.load(open(VVJSON)) systemprompt += '''

交叉參考：VibeVoice ASR

以下每段字幕會附帶另一個 ASR 引擎（VibeVoice，有 hotwords 注入）對同一段音檔的辨識結果。 VibeVoice 的英文專有名詞和部分中文財經術語辨識較準確，但語氣詞過多。

使用規則：

1. 英文 ticker / 專有名詞（如 ETF 代碼）→ 以 VibeVoice 版本為準
2. 中文財經術語 → 如果 VibeVoice 的詞彙更合理且語境正確，採用之
3. 語氣詞（哦、呃、嗯）→ 忽略 VibeVoice 多出的部分
4. 已知 VibeVoice 錯誤（不要採用）：

• 「值信」「指信」應為「質性」
• 「MOT」應為「MOAT」
• 「SHD」應為「SPHD」
• 「KVW」應為「KWEB」
• 「BOZ」應為「BOTZ」
• 「QILD」應為「QYLD」
• 「XILP」應為「XLP」
• 「SkyYY」應為「SKYY」

1. 不確定時 → 保留 Breeze（主 ASR）的版本

VibeVoice 參考文字會寫在每段的 vvref.txt 檔案中。 ''' print(f'VV JSON loaded: {len(vvsegments)} segments')

# 寫出 system prompt with open(f'{WORKDIR}/systemprompt.txt', 'w') as f: f.write(systemprompt)

# 切分 SRT content = open(SRTFILE).read() blocks = re.split(r'\n\n+', content.strip()) SEGSIZE = 300 segments = [] for i in range(0, len(blocks), SEGSIZE): segments.append(blocks[i:i+SEGSIZE])

# 輔助函數：從 SRT block 提取時間戳（毫秒） def parsesrttimems(block): lines = block.strip().split('\n') if len(lines) >= 2 and '-->' in lines[1]: tc = lines[1].strip() parts = tc.split(' --> ') def toms(t): h, m, rest = t.split(':') s, ms = rest.split(',') return int(h)3600000 + int(m)60000 + int(s)*1000 + int(ms) return toms(parts[0]), toms(parts[1]) return None, None

# 輔助函數：提取 VV 參考文字 def extractvvreference(segstartms, segendms): parts = [] for seg in vvsegments: vvstart = float(seg.get('Start', seg.get('start', seg.get('starttime', 0)))) 1000 vvend = float(seg.get('End', seg.get('end', seg.get('endtime', 0)))) 1000 if vvend > segstartms and vvstart 0: prevblocks = segments[idx-1][-5:] ctxlines = [] for b in prevblocks: lines = b.strip().split('\n') textlines = [l for l in lines[2:] if not re.match(r'\d+:\d+:\d+', l)] ctxlines.extend(textlines) with open(f'{WORKDIR}/ctx{idx}.txt', 'w') as f: f.write('\n'.join(ctxlines)) # VV 參考：從 VV segments 提取時間重疊的文字 if vvsegments: firststart, = parsesrttimems(seg[0]) , lastend = parsesrttimems(seg[-1]) if firststart is not None and lastend is not None: vvref = extractvvreference(firststart, lastend) with open(f'{WORKDIR}/vvref{idx}.txt', 'w') as f: f.write(vvref if vvref else 'NOVVREFERENCE') else: with open(f'{WORKDIR}/vvref{idx}.txt', 'w') as f: f.write('NOVV_REFERENCE')

print(f'Total blocks: {len(blocks)}') print(f'Number of segments: {len(segments)}') for i, s in enumerate(segments): print(f' Segment {i}: {len(s)} blocks') if vv_segments: print(f'VV reference files written for {len(segments)} segments') " ```

這個腳本產出：

• _system_prompt.txt：組裝好的完整 system prompt（含 VV 交叉參考規則，如有）
• _seg_0.srt ~ _seg_N.srt：每段 SRT
• _ctx_1.txt ~ _ctx_N.txt：每段的上文參考（第一段沒有）
• _vv_ref_0.txt ~ _vv_ref_N.txt：每段的 VV 參考文字（如有 VV JSON）

1. 平行發起所有 subagent：用單一訊息同時發起所有 Agent tool 呼叫：

``` Agent tool 參數：

• model: "sonnet"
• mode: "bypassPermissions"
• prompt: 見下方

```

每段 prompt 格式（subagent 自己讀檔案，主 agent 不 inline 內容）： ``` 你是字幕校正 subagent。請完成以下步驟：

1. 用 Read 工具讀取 system prompt：/systemprompt.txt
2. 用 Read 工具讀取待校正字幕：/seg.srt
3. [如果 N > 0] 用 Read 工具讀取上文參考：/ctx.txt
4. [如果檔案存在] 用 Read 工具讀取 VibeVoice 參考：/vvref_.txt

• 如果內容是 NOVVREFERENCE 則跳過
• 否則交叉參考 VibeVoice 結果，特別注意英文名詞和財經術語

1. 依照 system prompt 的規則校正字幕
2. 用 Write 工具把校正結果寫入：/seg_corrected.srt

重要：

• 上文參考僅供理解語境，不要輸出這些內容
• VibeVoice 參考僅供交叉比對，不要直接複製其語氣詞
• 輸出必須是完整的 SRT 格式（含序號、時間軸、字幕文字）
• 完成後回報修改了多少條

```

重要：所有 Agent 呼叫必須在同一個訊息中發出，才能真正平行執行。

驗證：subagent 完成後，主 agent 檢查 _seg__corrected.srt 檔案是否存在且包含 SRT 時間軸格式。如果沒有，重試。

Step 2b 替代路徑：本地 LLM（--local 模式）

用戶指定 --local 時，用 ollama_llm.py 取代 Sonnet subagent。逐段序列執行（Ollama 單 GPU 不支援平行）。

OLLAMA_LLM="${CORRECT_DIR}/ollama_llm.py"

for seg_file in "${WORK_DIR}"/_seg_*.srt; do
    N=$(echo "$seg_file" | grep -oP '_seg_\K\d+')

    # 組裝 user input：上文參考 + VV 參考 + SRT 段落
    USER_INPUT=""
    if [ -f "${WORK_DIR}/_ctx_${N}.txt" ]; then
        USER_INPUT="【上文參考】\n$(cat "${WORK_DIR}/_ctx_${N}.txt")\n\n"
    fi
    if [ -f "${WORK_DIR}/_vv_ref_${N}.txt" ] && ! grep -q "NO_VV_REFERENCE" "${WORK_DIR}/_vv_ref_${N}.txt"; then
        USER_INPUT="${USER_INPUT}【VibeVoice 參考】\n$(cat "${WORK_DIR}/_vv_ref_${N}.txt")\n\n"
    fi
    USER_INPUT="${USER_INPUT}$(cat "$seg_file")"
    echo -e "$USER_INPUT" > "${WORK_DIR}/_user_${N}.txt"

    python3 "$OLLAMA_LLM" \
        --system "${WORK_DIR}/_system_prompt.txt" \
        --user "${WORK_DIR}/_user_${N}.txt" \
        --output "${WORK_DIR}/_seg_${N}_corrected.srt" \
        --max-tokens 8192

    echo "Segment $N corrected"
done

注意事項：

• 本地模式不做 SRT 拆句（26B 測試顯示不具備此能力），依賴 Step 2c 的 srt_postprocess.py 自動拆句
• 速度：每 300 blocks 約 30-60 秒（vs Sonnet 平行 ~10 秒），總時間較長但免費
• 如果 Ollama 回傳 error，印 WARNING 並 fallback 到 Sonnet subagent（該段）

1. 合併：用 Python 腳本合併所有段的校正結果（不要讀入主 context）：

```python python3 -c " import re, glob

WORKDIR = '' files = sorted(glob.glob(f'{WORKDIR}/seg*corrected.srt'), key=lambda f: int(re.search(r'seg_(\d+)', f).group(1)))

merged = [] seq = 1 for fpath in files: content = open(fpath).read().strip() # 解析 SRT blocks blocks = re.split(r'\n\n+', content) for block in blocks: lines = block.strip().split('\n') if len(lines) >= 2: lines[0] = str(seq) merged.append('\n'.join(lines)) seq += 1

output = '2bcorrected.srt' with open(output, 'w') as f: f.write('\n\n'.join(merged) + '\n') print(f'Merged {seq-1} entries to {output}') " ```

Step 2c: 複查 pass + 後處理

> 同樣遵守 Context 節約原則：提取未變動條目、組裝複查 prompt 全部用 Python 腳本在 disk 上完成。

1. 用 Python 腳本提取未變動條目 + 組裝複查 prompt：

```python python3 -c " import re, os, difflib

WORKDIR = '' CORRECTDIR = '${CORRECTDIR}' PREPROCESSED = '' CORRECTEDRAW = ''

# 解析 SRT 為 {timecode: text} 字典 def parse_srt(path): blocks = re.split(r'\n\n+', open(path).read().strip()) result = {} for b in blocks: lines = b.strip().split('\n') if len(lines) >= 2 and '-->' in lines[1]: tc = lines[1].strip() text = '\n'.join(lines[2:]) result[tc] = text return result, blocks

predict, = parsesrt(PREPROCESSED) cordict, corblocks = parsesrt(CORRECTED_RAW)

# 找未變動條目 unchanged = [] for b in corblocks: lines = b.strip().split('\n') if len(lines) >= 2 and '-->' in lines[1]: tc = lines[1].strip() text = '\n'.join(lines[2:]) if tc in predict and pre_dict[tc] == text: unchanged.append(b)

# 找修正範例（前 10 個代表性修正） examples = [] for tc, pretext in predict.items(): if tc in cordict and predict[tc] != cordict[tc]: examples.append(f'{pretext} → {cor_dict[tc]}') if len(examples) >= 10: break

# 組裝複查 prompt terms = open(f'{CORRECTDIR}/termsaustinv2.txt').read() reviewprompt = f'''你是字幕複查員。以下字幕已經過一輪 ASR 校正但未被修改。 請逐條檢查是否有殘留的 ASR 錯誤。

術語表

{terms}

第一輪已發現的錯誤範例（供校準判斷標準）

''' + '\n'.join(examples) + '''

重點檢查項目

• 同音字/近音字錯誤（如「機點」應為「基點」、「教育日」應為「交易日」）
• 術語表中的詞被 ASR 聽成別的詞
• 英文辨識錯誤（大小寫、拼寫）
• 重複字詞未清理

不要改的

• 專有名詞、人名、地名、作品名、時事用語 — 即使你不認識也不要

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: fredchu
• Source: fredchu/claude-dotfiles
• License: MIT

Install and usage instructions live in the source repository linked above.