YouTube / 音訊轉錄
將 YouTube 影片(或任何本機音訊/視訊檔案)轉錄為文字稿,不依賴 YouTube 提供的字幕。許多影片(尤其是重新上傳的影片和某些中文內容)沒有字幕或沒有自動產生的字幕,因此使用 yt-dlp --write-subs 下載字幕會一無所獲。這項技能繞過這個限制,直接下載音訊並使用平台自動選取的 Whisper 引擎在本機轉錄。
何時使用此技能
- 使用者提供 YouTube 網址並要求取得 字幕 / 逐字稿 / transcript / captions。
yt-dlp --list-subs回報has no subtitles/has no automatic captions。- 使用者有一個本機的
.m4a/.mp3/.mp4/等檔案需要轉錄。
先決條件
- 已安裝
uv(用於執行yt-dlp和轉錄腳本,不會污染全域環境)。腳本會自動選取 Whisper 引擎,uv只會安裝平台所需的套件:- Apple Silicon Mac →
mlx-whisper(MLX/Metal,GPU 加速)。 - Intel Mac / Linux / Windows →
faster-whisper(CTranslate2,CPU 或 NVIDIA CUDA)。
- Apple Silicon Mac →
- 一個 JavaScript 執行環境 —
node、bun或deno— 位於 PATH 環境變數中。較新的 yt-dlp 需要 JS 執行環境來處理 YouTube;腳本會自動偵測可用的環境。 - 建議安裝 ffmpeg,但非必要:若缺少 ffmpeg,腳本會改用 macOS 內建的
afconvert(在非 macOS 系統上,請安裝 ffmpeg)。
使用方法
整個流程由一個自包含的腳本完成。使用 uv run 執行,相依套件會自動安裝:
uv run ~/.claude/skills/youtube-transcribe/scripts/yt_transcribe.py \
"https://www.youtube.com/watch?v=VIDEO_ID" \
--output-dir /tmp/whisper_out
常用選項:
--language zh— 強制指定語言而非自動偵測(速度更快,避免雙語開場時誤判)。--model mlx-community/whisper-large-v3-turbo— 預設模型;在 Apple Silicon 上速度與品質表現良好。可替換為mlx-community/whisper-large-v3以獲得最高品質,或使用較小模型以加快速度。--output-name my-video— 輸出檔案的基本名稱(預設為影片 ID)。--formats txt,srt— 選擇要輸出的格式(預設為txt,srt,json)。
本機檔案的使用方式相同 — 只需傳入檔案路徑而非網址:
uv run ~/.claude/skills/youtube-transcribe/scripts/yt_transcribe.py /path/to/talk.m4a --language en
第一次執行時會將 Whisper 模型(turbo 模型約 1.6 GB)下載到 Hugging Face 快取中;後續執行會直接重複使用。
輸出檔案
輸出檔案寫入 --output-dir 指定的目錄(預設為目前目錄),檔案名稱以影片 ID(或 --output-name 指定的名稱)命名:
<name>.txt— 純文字轉錄稿(整份文件)。<name>.srt— 含時間戳記的字幕檔。<name>.json— 完整結果,包含每個區段的時間戳記和偵測到的語言。
轉錄後處理
Whisper 的原始輸出會忠實反映口語內容。如果音訊是中文(普通話),Whisper 會輸出簡體中文。根據使用者的全域規則,在聊天中呈現轉錄稿時,應轉換為正體中文,並修正對專有名詞/技術術語(模型名稱、CVE ID、工具名稱)的明顯誤聽。提供整理過且分段清晰的摘要,而非直接貼出整面文字,並告知使用者完整檔案所在位置。
運作原理(及原因)
- 下載音訊 —
yt-dlp -f "bestaudio[ext=m4a]/bestaudio"。格式 140(128 kbps m4a)不需要解決 YouTube 的 player JS "n" 挑戰即可下載,因此我們避免使用--remote-components ejs:github(它會從遠端獲取並執行程式碼,通常會被沙盒封鎖)。如果yt-dlp未安裝,腳本會自動加上uvx前綴,並根據可用的 JS 執行環境加入--js-runtimes <node|bun|deno>。 - 標準化音訊 — 使用 ffmpeg 轉換為 16 kHz 單聲道 16 位元 WAV 格式,若缺少 ffmpeg 則改用 macOS 的
afconvert。 - 轉錄 — 將 WAV 讀取為 numpy float32 陣列,直接傳遞給引擎(Apple Silicon 使用
mlx_whisper.transcribe(...),其他平台使用faster_whisper.WhisperModel.transcribe(...))。兩者產生的結果結構相同(text/language/segments)。將解碼後的陣列傳給 Whisper 意味著它永遠不會在內部呼叫 ffmpeg,這正是缺少 ffmpeg 的機器上發生FileNotFoundError: ffmpeg的常見原因。
疑難排解
has no subtitles但你仍需要文字 — 這正是此技能的用途;直接進行音訊轉錄。FileNotFoundError: ffmpeg— 使用此腳本不應發生此問題(它會先進行轉換),但如果你直接對 m4a 檔案呼叫 Whisper 引擎,請先轉換為 WAV。- 在非 Apple Silicon 且轉換失敗時 —
afconvert僅限 macOS,請安裝ffmpeg(Linux/Windows 沒有內建的替代方案)。 - yt-dlp 警告 JS challenge / "Only images are available" — 確保
node/bun/deno在 PATH 環境變數中;腳本需要一個 JS 執行環境來進行解析。不要使用--remote-components ejs:github來解決此問題。 - 輸出內容混亂/語言錯誤 — 明確指定
--language參數。