Bilibili / YouTube 音訊轉字幕
使用名為 codex 的 conda 環境,轉寫原語言。預設模型為 Qwen/Qwen3-ASR-1.7B + Qwen/Qwen3-ForcedAligner-0.6B,透過官方 qwen-asr 工具包呼叫 return_time_stamps=True。ASR 模型本身只產生文字,ForcedAligner 提供詞/字級時間戳。按標點、停頓、約 6 秒和 42 字元組織 SRT,邊界來自真實對齊結果,不等分時長或丟棄文字。
--engine whisper 保留 openai/whisper-large-v3-turbo 的原生長音訊模式,pipeline 使用 return_timestamps=True,不傳 chunk_length_s。Whisper 實驗性外部分塊曾產生五分鐘字幕段和連續重複,不應預設啟用。Qwen 官方 SDK 為對齊按低能量邊界處理最長 180 秒的片段,自動恢復全域時間;這與 Whisper 的實驗性 30 秒 pipeline 分塊是不同實現。
Qwen 時間戳支援中文、英語、粵語、法語、德語、義大利語、日語、韓語、葡萄牙語、俄語和西班牙語;其他語言顯式選擇 Whisper,不因 ASR 支援該語言就假定它支援對齊。預設自動識別,已知語言時傳 --language chinese 或 english;也接受上述語言的常見代碼如 zh/en。
運行與輸出
先記錄使用者當前專案的絕對路徑,不要把 skill 安裝目錄當成專案目錄。將 <skill目錄> 取代為本 SKILL.md 所在目錄,將 <專案目錄> 取代為呼叫時的專案路徑;URL 作為單個帶引號的參數傳入。
conda run --no-capture-output -n codex python "<skill目錄>/scripts/bilibili_audio_subtitles.py" \
'https://www.bilibili.com/video/BV1w88n6uE1X/' \
--project-dir '<專案目錄>'
同一命令也接受 YouTube 連結,例如 'https://youtu.be/jNQXAC9IVRw'。保留原有 skill 名稱與腳本名,已有 $bilibili-audio-subtitles 呼叫可繼續使用。
Bilibili 音訊由 yutto 下載,儲存為 ~/Downloads/<BV號或av號>-p<N>.m4a;YouTube 音訊由 yt-dlp 下載,儲存為 ~/Downloads/youtube-<影片ID>.m4a。專案目錄每次只輸出一份帶時間戳與字幕正文的 SRT,最終只交付這一份推薦字幕,不另交 VTT、TXT、JSON 或模型比較檔案。必要品質告警用簡短說明提示複核,不額外產生交付檔案。原始模型 text/chunks 和復現診斷儲存在 ~/.cache/bilibili-audio-subtitles/runs/ 的獨立 JSON 中,運行日誌會提供路徑;這是內部診斷記錄,不是額外的字幕交付檔案。
已有音訊會重用。已有同名 SRT 時,新結果自動使用包含模式、腳本版本和運行編號的獨立檔名,保留舊版本;不覆蓋或刪除舊字幕。重試後向使用者明確指出推薦使用的 SRT 版本,不僅列出所有路徑。
常用選項:
--audio '/絕對路徑/音訊.m4a':轉寫本地音訊,不同時傳 URL。--language chinese:已知語言時明確指定,預設自動識別。--engine qwen|whisper:預設 Qwen,Whisper 用於對比、優先速度或 Qwen 對齊不支援的語言。--project-dir/--download-dir:覆蓋專案輸出目錄或 Downloads。--device auto|cpu|cuda:0:預設優先 CUDA;不要自動改動系統驅動。--download-only:只下載,之後使用--audio繼續。--output-name '檔案名稱':自訂 SRT 檔名,不含路徑或副檔名。--diagnostics-dir '/絕對路徑':覆蓋內部原始結果及診斷目錄。--auth-file '/絕對路徑':僅用於使用者已提供的 Bilibili/yutto 認證檔案。--cookies-file '/絕對路徑':僅用於使用者已提供的 YouTube Netscape Cookie 檔案,不掃描瀏覽器。--max-cue-seconds 12:超長字幕告警閾值,預設 12 秒。--limit-seconds 30:使用者要求的片段或冒煙測試;檔名標記 sample,報告中明確不是完整轉寫。--threads 8/--batch-size 1:控制執行緒和推理批次大小。--engine whisper --chunk-length-seconds 30:僅在有明確理由且說明實驗性風險時啟用;Qwen 不接受此參數。
支援 Bilibili 標準 /video/BV…、/video/av… 連結和直接 BV/av 號。保留 ?p=N 指定的分 P,移除追蹤參數。預設只處理一 P;多 P 請求逐 P 呼叫。B 站短連結先解析為標準連結。
YouTube 支援 youtube.com/watch?v=…、youtu.be/…、shorts/…、live/… 和 embed/…(包括 www、m、music 子域)。統一為單影片標準連結,移除追蹤、起播和播放清單參數,並顯式使用 --no-playlist;僅有播放清單的連結直接拒絕。下載選擇 bestaudio,經 FFmpeg 提取為 M4A,不下載平台字幕、封面或影片作為交付檔案。不掃描瀏覽器、不列印 Cookie,不擅自擴大到整套合集。
下載失敗優先檢查更新
此規則同時適用於兩種平台。實際下載失敗或下載器回傳成功卻沒有有效音訊時,腳本先查詢對應下載套件的相容穩定版本:Bilibili 檢查 yutto,YouTube 檢查 yt-dlp。用當前 codex Python 的 pip index versions <套件> --json 比較本機和套件索引版本,尊重已有 pip 鏡像配置。
若有新版,腳本只在該環境升級這個下載套件及其必要依賴,然後重試下載一次。yt-dlp 使用 yt-dlp[default],保持 YouTube EJS 依賴匹配。無新版、查詢失敗、升級失敗或第二次下載仍失敗時,儲存原始錯誤與更新事件並停止;不要無限重試或自動切到 nightly/master。檢查套件更新之後,再根據真實錯誤檢查網路、登入、影片是否下架、地區限制和 JS 執行環境。
更新需要聯網和環境寫入權限。權限受限時申請本次必要權限,不更換系統 Python、不為下載問題更新轉寫模型或 PyTorch。更新查詢失敗不等於已經是最新版。已有損壞音訊須明確報告並保留,不直接覆蓋;失敗重試新產生的無效音訊也保留獨立名稱。
結構檢查與品質檢查
兩類檢查必須分別報告:
- 結構檢查:完整音訊解碼時長匹配,非空字幕,時間戳有限、有序、起止有效且不超過轉寫時長。失敗時保留原始診斷,不產生 SRT。
- 品質檢查:字幕超過 12 秒、單條超過 120 個文字字元、文字密度超過 25 字元/秒、持續至少 8 秒但低於 0.5 字元/秒、單條連續重複詞句至少 5 次、連續至少 3 條同文字幕。時間戳需要修正也會標記複核。閾值和告警明細寫入診斷。
退出碼 0 表示結構通過且未發現明顯品質異常;退出碼 2 表示 SRT 已產生但需要複核;退出碼 1 表示運行或結構失敗。不要把退出碼 2 宣稱為檢查成功。品質規則是啟發式提示,不是語音內容正確性的證明;誤報須對照音訊判斷,不為消除告警擅自調高閾值、刪除文字、按等分時長重切或無限重試。
品質異常時給出告警時間窗與診斷路徑。若異常來自顯式 Whisper 外部分塊,可用 --engine whisper 原生模式重試一次,保留兩輪輸出;仍異常時說明需複核,不自動切換模型或無限重試。術語糾正單獨處理,不要憑猜測全域替換「訂單流」「滑鼠」等詞。即使沒有告警,也只稱為機器轉寫草稿,不能稱為逐句校對過的字幕。
診斷 JSON 保留原始 text/chunks、正規化 segments、結構狀態、品質狀態和告警、修正記錄、推薦狀態、腳本版本、轉寫模式、生成參數、模型 GenerationConfig 與 revision、庫版本、裝置、時長和推理耗時。還記錄來源平台、下載套件版本、更新檢查和重試事件。Qwen 額外保留 SDK 後處理前的原始 ASR 字串、完整對齊單位、偵測語言、零時長單位計數、對齊模型 revision 和分段配置;原始輸出的重複和接近生成長度上限也會觸發複核,不能讓 SDK 重複過濾掩蓋異常。量化時間戳中的零時長詞併入鄰近字幕並保留文字,不能偽造詞級時長;整段無有效時長或文字對不上時儲存原始結果並失敗。下載或轉寫失敗也儲存獨立診斷,供復現比較。
環境
檢查 codex 環境的 Python、對應平台下載套件、torch、transformers、accelerate、numpy、qwen-asr,以及 PATH 中的 ffmpeg 和 ffprobe。只將缺少依賴安裝到該環境:
conda run --no-capture-output -n codex python -m pip install yutto 'yt-dlp[default]' 'qwen-asr==0.0.6' numpy
Qwen 工具包固定 Transformers 4.57.6 和 accelerate 1.12.0,避免為此任務升級到 Transformers 5 或安裝 vLLM。保留已有可用的 CUDA PyTorch。本機驗證環境:Python 3.12、qwen-asr 0.0.6、yutto 2.3.1、Transformers 4.57.6、PyTorch 2.14.1+cu130,CUDA 下 Qwen 使用 bfloat16 與 SDPA;不要求編譯 FlashAttention。若需重建本機 GPU 環境:
conda run --no-capture-output -n codex python -m pip install 'torch==2.14.1+cu130' --index-url https://download.pytorch.org/whl/cu130
若 shell 找不到 conda,定位其絕對路徑。本機可使用 /home/leev/miniforge3/bin/conda 或 /home/leev/miniforge3/envs/codex/bin/python。受限沙箱內 GPU 檢測失敗時,先在允許存取 NVIDIA 裝置的環境重新檢測,不直接判斷驅動損壞或改裝 CPU 版。真正無 GPU 的機器才使用匹配的 CPU PyTorch。
YouTube 還需要 yt-dlp 的預設 EJS 支援依賴及受支援的 JS 執行環境。腳本會查詢 PATH 中的 Deno、Node、Bun 或 QuickJS,並顯式傳給 yt-dlp;本機已驗證 Node 24 與 yt-dlp 2026.08.19。找不到執行環境或版本不相容時明確報告,不因下載失敗反覆重裝其他套件。
首次運行會下載模型到 Hugging Face 標準快取,尊重 HF_HOME / HF_HUB_CACHE;已有完整快取且網路不穩定時可設定 HF_HUB_OFFLINE=1。B 站僅用 yutto 下載,停用影片、彈幕、平台字幕、封面和章節資訊;YouTube 僅用 yt-dlp 下載音訊。下載失敗先按更新規則處理再報告真實錯誤;轉寫失敗時保留音訊。權限受限時申請本次必要的目錄和 GPU 執行權限。
回歸驗證
固定範例:BV1w88n6uE1X。用同一音訊運行完整預設 Qwen 轉寫;需要比較時再用 --engine whisper,保留兩輪診斷並呼叫:
python -m unittest discover -s '<skill目錄>/scripts' -p 'test_*.py'
python '<skill目錄>/scripts/check_regression.py' \
--candidate '<新版快取診斷JSON>' --baseline '<舊版JSON>'
重點時間窗為 00:43.240–05:46.060 和 08:10–08:33。實測 Qwen 為 282 段、最長 5.76 秒,Whisper 原生為 438 段、最長 5.18 秒,兩個視窗均無超長和重複告警;不要把固定段數作為其他環境的通過條件。舊版 117 段結果中的 302.82 秒字幕和連續 23 條「好」,應被新版品質檢查標記為需要複核。回歸通過只證明已知分段與重複問題未復現,語義和術語仍需對照音訊。
YouTube 回歸包含 watch/短連結/Shorts 路由、只下載單個影片的音訊、失敗優先查詢更新、升級後最多重試一次、無更新或查詢失敗時停止。實測 jNQXAC9IVRw 的約 19 秒音訊完整下載,Qwen 產生 7 段 SRT(Whisper 為 4 段);已不可用的測試影片也驗證了更新檢查和失敗診斷路徑。
模型選擇、實測耗時和侷限見 references/model-evaluation.md;模型比較或重新評估時讀取。當前預設偏重中文術語識別品質,不能宣稱各語言、各音訊都優於 Whisper。