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 模型下載到 Hugging Face 快取(turbo 模型約 1.6 GB);後續執行會重複使用。
輸出結果
寫入至 --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 播放器的 JS "n" 挑戰的情況下下載,因此我們避免使用--remote-components ejs:github(它會擷取並執行遠端程式碼,通常會被沙箱封鎖)。腳本會在 yt-dlp 未安裝時加上uvx前綴,並為目前存在的 JS 執行環境添加--js-runtimes <node|bun|deno>。 - 標準化音訊 — 使用 ffmpeg 轉換為 16 kHz 單聲道 16-bit WAV,若無 ffmpeg 則使用 macOS 的
afconvert。 - 轉錄 — 將 WAV 讀取為 numpy float32 陣列,直接傳給引擎(Apple Silicon 上使用
mlx_whisper.transcribe(...),其他平台使用faster_whisper.WhisperModel.transcribe(...))。兩者產生的標準化結果格式相同(text/language/segments)。將解碼後的陣列交給 Whisper,可避免 Whisper 內部再呼叫 ffmpeg — 這通常是在沒有 ffmpeg 的機器上發生FileNotFoundError: ffmpeg的原因。
疑難排解
has no subtitles但使用者仍需要文字 — 這正是此技能的任務;直接進行音訊轉錄。FileNotFoundError: ffmpeg— 透過此腳本不應發生(它會先轉換),但若你直接對 m4a 檔案呼叫 Whisper 引擎,請先轉換為 WAV。- 在非 Apple Silicon 上轉換失敗 —
afconvert僅限 macOS,請安裝ffmpeg(Linux/Windows 沒有內建備援方案)。 - yt-dlp 警告 JS 挑戰 / "Only images are available" — 請確保
node/bun/deno在 PATH 中;腳本需要一個來進行解析。請勿使用--remote-components ejs:github來解決此問題。 - 輸出亂碼 / 語言錯誤 — 請明確指定
--language參數。