video-to-transcript

在 Apple Silicon Mac 上完全本機執行的影音轉逐字稿 pipeline——不經任何 API、不上傳檔案,ASR 由 mlx-whisper 在 Mac 的 GPU(Metal/MLX)上完成。可以當一般命令列工具用,也可以直接安裝成 Claude Code 的 Agent Skill。

特色

• 完全本機:音訊不離開你的電腦,適合會議錄音、內部教育訓練等敏感內容。
• 修復 Whisper 的 repetition loop:mlx_whisper CLI 把 --temperature 硬編碼成單一浮點數,等於停用了原始設計裡「偵測到過度重複就升溫重解」的 fallback 機制,長音檔的靜音、換頁停頓經常整段變成同一句話跳針。本專案改走 Python API 還原 fallback tuple,搭配分段轉錄(loop 被關在自己的 chunk 裡)與收尾去重,三層防線。詳細根因分析見 references/hallucination-loops.md。
• 自動簡轉繁:Whisper 對台灣華語音訊也常輸出簡體;中文轉錄會自動經 OpenCC s2twp(含台灣用語:数据→資料、信息→資訊)轉為繁體。
• 批次可續跑:整個資料夾逐檔轉錄,已有 .vtt 的自動跳過,中斷後重跑即接續;寫檔皆為原子操作,不會留下被誤認為完成的半成品。
• 產出即可摘要:輸出帶時間軸的 .vtt,再用內附的 extract_transcript.py 剝除時間資訊,就是餵給 LLM 做摘要的精簡輸入。

需求

• macOS + Apple Silicon(MLX 依賴 Metal GPU)
• Homebrew

安裝

brew install pipx ffmpeg && pipx ensurepath
pipx install mlx-whisper
pip install --user --break-system-packages opencc   # 選用:簡轉繁
pip install --user webvtt-py                        # 選用:parse/摘要步驟

完整安裝說明(含 yt-dlp、下載版 ffmpeg 的 quarantine 處理)見 references/install.md。

作為 Claude Code skill

git clone git@github.com:twjohnwu/video-to-transcript.git
ln -s "$(pwd)/video-to-transcript" ~/.claude/skills/video-to-transcript

之後在 Claude Code 裡說「幫我把這個影片轉成逐字稿」即可觸發;skill 的決策流程見 SKILL.md。

快速開始

# 單一影音檔(預設模式;講座、會議等長音檔都用這個)
scripts/transcribe_chunked.sh "My Lecture.mp4" "My Lecture.vtt"
#                              [chunk_secs=600] [model] [lang=zh] 可依序附加

# 整個資料夾(循序、可續跑)
scripts/transcribe_dir.sh ~/Movies/lectures

# 網路影片
yt-dlp -x --audio-format wav -o audio.wav "URL"
scripts/transcribe_chunked.sh audio.wav transcript.vtt

# 轉成無時間軸純文字(給 LLM 摘要用)
python3 scripts/extract_transcript.py "My Lecture.vtt" --merge-speakers

模型預設 mlx-community/whisper-large-v3-turbo;首次執行會從 HuggingFace 下載權重並快取。全部 flag 與環境變數(VTT_S2TWP 等)見 references/flags.md。

Pipeline 架構

影音檔
  └─ ffmpeg        依 chunk_secs 切成 16 kHz 單聲道 wav 分段
      └─ mlx_transcribe.py   逐段轉錄(Python API,temperature fallback 開啟)
          └─ merge_vtt.py    平移各段時間軸後串接成單一 VTT
              └─ clean_vtt.py        去除殘餘跳針與 outro 幻覺句
                  └─ to_traditional.py   中文時自動 s2twp 簡轉繁

Scripts 一覽

Script	職責
transcribe_chunked.sh	單檔主入口:切段 → 轉錄 → 合併 → 清理 → 簡轉繁
transcribe_dir.sh	資料夾批次入口,逐檔呼叫上者,可續跑
mlx_transcribe.py	轉錄引擎:mlx-whisper Python API + anti-loop 參數
merge_vtt.py	依 chunk 序號平移時間軸、串接 VTT
clean_vtt.py	幂等去重:連續同文 cue、字元跳針、boilerplate 幻覺
to_traditional.py	OpenCC s2twp 簡轉繁(缺 opencc 時跳過不報錯)
vtt_common.py	共用的 VTT 時間戳文法與原子寫檔
extract_transcript.py	剝除時間軸產出純文字(vendored 第三方,見下)

已知限制

• 固定秒數切段可能把一句話切在段落交界(對有停頓的講座影響很小;加大 chunk_secs 可減少接縫)。
• Chunked 模式只做轉錄,不支援翻譯;要英文輸出請用 mlx_whisper --task translate 的單步流程(見 SKILL.md)。
• 僅支援 macOS + Apple Silicon。

授權

MIT © 2026 twjohnwu。

scripts/extract_transcript.py vendored 自 yaniv-golan/transcription-reader-skill(MIT),全文見 LICENSE-third-party.md。