Communitygithub.com

YouTube / 音訊轉錄 (chenwei791129/agent-skills)

將 YouTube 影片(或任何本機音訊/視訊檔案)轉錄為純文字稿、SRT 字幕和 JSON,使用 Whisper 在本機執行。每當使用者分享 YouTube 網址並要求字幕、逐字稿或轉錄時使用此技能,尤其是影片本身沒有字幕可供下載的情況。

音訊轉錄 (chenwei791129/agent-skills) とは?

這項技能專為需要從 YouTube 影片或本機音訊/視訊檔案取得文字轉錄的使用者設計,特別是那些無法直接下載字幕的影片(例如重新上傳的影片或某些中文內容)。它繞過 YouTube 的字幕限制,直接下載音訊並在本機使用 Whisper 語音辨識引擎進行轉錄。此技能會根據平台自動選擇最適合的 Whisper 引擎:Apple Silicon 上使用 GPU 加速的 mlx-whisper,其他平台(Intel Mac、Linux、Windows)則使用 faster-whisper。輸出格式包括純文字 (.txt)、SRT 字幕 (.srt) 和 JSON 檔案,方便後續處理與整合。腳本完全自包含,透過 `uv run` 自動管理相依套件,無需污染全域環境。這項技能支援 Claude Code、Cursor 和 Codex 等 AI 代理工具,讓開發者或一般使用者能快速將語音內容轉化為可搜尋、可編輯的文字資料。

対応✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/chenwei791129/agent-skills/tree/HEAD/skills/youtube-transcribe

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

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 模型(turbo 模型約 1.6 GB)下載到 Hugging Face 快取中;後續執行會直接重複使用。

輸出檔案

輸出檔案寫入 --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 的 player JS "n" 挑戰即可下載,因此我們避免使用 --remote-components ejs:github(它會從遠端獲取並執行程式碼,通常會被沙盒封鎖)。如果 yt-dlp 未安裝,腳本會自動加上 uvx 前綴,並根據可用的 JS 執行環境加入 --js-runtimes <node|bun|deno>。
  2. 標準化音訊 — 使用 ffmpeg 轉換為 16 kHz 單聲道 16 位元 WAV 格式,若缺少 ffmpeg 則改用 macOS 的 afconvert。
  3. 轉錄 — 將 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 參數。

関連スキル