Communitygithub.com

chenwei791129/agent-skills

使用本地 Whisper 將 YouTube 影片(或任何本機音訊/影片檔)轉錄為文字稿、SRT 字幕與 JSON。當使用者分享 YouTube 網址並想要字幕、逐字稿,或需要將音檔轉錄成文字時使用。

agent-skills 是什麼?

這項技能提供了一套完整的本機語音轉錄方案,專為 YouTube 影片或本機音訊/影片檔設計。當使用者要求「幫我抓這部 YouTube 的字幕/逐字稿」、「transcribe this video」或「把這段音檔轉成文字」時,AI 代理會自動觸發此技能。其核心優勢在於不依賴 YouTube 提供的字幕(許多影片根本沒有字幕),而是透過下載音訊並使用本機 Whisper 模型進行轉錄。支援多種輸出格式:純文字檔 (.txt)、時間軸字幕 (.srt) 與含逐段時間戳的 JSON。此技能跨平台運作:在 Apple Silicon Mac 上使用 GPU 加速的 mlx-whisper,在其他平台上則使用 faster-whisper。第一次執行時會自動下載 Whisper 模型(約 1.6 GB),之後即可重複使用。轉錄完成後,若為中文內容,AI 代理會將簡體中文轉換為正體中文,並整理出名詞與技術術語,以結構化的摘要呈現給使用者。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/chenwei791129/agent-skills/tree/HEAD/skills/youtube-transcribe

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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)。
  • 需有 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、工具名稱)的明顯誤聽。提供整理過、分段呈現的摘要,而非直接貼上整面牆的文字,並告知使用者完整檔案的位置。

運作原理(及原因)

  1. 下載音訊 — 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>。
  2. 標準化音訊 — 使用 ffmpeg 轉換為 16 kHz 單聲道 16-bit WAV,若無 ffmpeg 則使用 macOS 的 afconvert。
  3. 轉錄 — 將 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 參數。

相關技能