video-use 字幕燒錄失敗？先檢查 FFmpeg subtitles 濾鏡

字幕檔已生成卻在最後輸出失敗，先保留既有字幕與逐字稿，確認工具實際使用的執行檔是否支援字幕濾鏡；只有證實缺少能力才更換版本，不必先重做轉錄。

先判定失敗在哪一段

video-use 的 issue #118 記錄一個 macOS arm64、Homebrew FFmpeg 8.1.2 個案：master.srt 已生成，卻在最後燒錄字幕時失敗。這是一則環境回報，不能推論所有 Homebrew 版本都有相同問題。

先開啟 master.srt，確認不是空檔，並保留逐字稿、EDL、已有中間影片與完整錯誤訊息。若字幕尚未生成，便不屬於本文的排查起點；若已生成且錯在最後合成，先查渲染能力，不要重跑轉錄。檔案存在也不代表內容與時間碼都正確，後續仍需驗收。

查的是 video-use 用的 FFmpeg

核對當地安裝版本的 helpers/render.py、啟動方式與日誌。本次查閱的上游程式使用 ffmpeg 名稱呼叫子程序，因此啟動程序的 PATH 會影響選用的執行檔。

一般終端的 which ffmpeg 只能提供線索，不能證明代理、IDE 或另一個啟動環境用了同一份。請在實際執行 video-use 的相同環境解析路徑；若產品包裝層指定了其他執行檔，則以該設定與執行證據為準。尚未確認路徑時，不要先換套件。

確認完整路徑後，以同一份執行檔做以下唯讀檢查。下列路徑是占位符，須換成已核對的實際路徑：

"/absolute/path/to/ffmpeg" -version
"/absolute/path/to/ffmpeg" -buildconf
"/absolute/path/to/ffmpeg" -hide_banner -filters
"/absolute/path/to/ffmpeg" -hide_banner -h filter=subtitles

FFmpeg 官方文件定義了版本、編譯設定、濾鏡清單及單一濾鏡說明的查詢方式。保存完整輸出；若連查詢都失敗，先處理該錯誤，不能把它直接當成缺濾鏡。

按結果分流，不按錯誤外觀猜

濾鏡清單有名稱完全相符的 subtitles，且專屬說明可讀：能力檢查通過，回看原始 FFmpeg stderr，依訊息核對字幕檔路徑、濾鏡參數或其他失敗項目
查詢正常完成，但清單沒有 subtitles，專屬查詢也指出找不到該濾鏡：才進入缺少能力的處理
路徑不明、查詢無法啟動或結果互相矛盾：先釐清執行環境，不據此重裝

--enable-libass 是編譯資訊中的重要線索；官方 subtitles 文件說明其使用 libass，亦需要 libavcodec 與 libavformat。判斷仍以該執行檔實際提供的濾鏡為主，不只看版本號。

確認缺少濾鏡後，才選完整 build

macOS 使用者可評估 Homebrew 官方的 ffmpeg-full formula，其相依項目包含 libass；另一條路是依 FFmpeg 官方要求建立具所需能力的 build。本文未安裝或實測任一方案。

關鍵是 ffmpeg-full 為 keg-only。Homebrew FAQ說明它不會自動連結到預設 prefix，因此「已安裝」不等於 video-use 已使用。用 brew info ffmpeg-full 查當前指引，再核對自己的啟動方式是否允許設定程序 PATH；若包裝產品聲稱支援指定執行檔，也要先查其文件。不要自行假設有 --ffmpeg-path 參數。

設定後回到相同啟動環境，重新核對路徑及上述四項檢查。不需要強制覆蓋系統連結或任意修改權限。

重試前檢查表

[ ] 字幕、逐字稿、EDL 與原素材已保留
[ ] 已記錄失敗階段、實際 FFmpeg 路徑、版本與編譯資訊
[ ] 同一路徑的 subtitles 濾鏡清單與說明已核對
[ ] 若更換 build，已確認 video-use 的啟動環境確實選用它
[ ] 從既有字幕與剪輯成果安排必要的渲染重試，不承諾工具支援從最後一步自動續跑
[ ] 輸出使用新檔名；成功後再播放核對字幕與聲畫

字幕時間軸與剪輯內容驗收可回看口播粗剪與字幕流程；工具用途與入門需求見 video-use 介紹。

來源與驗證範圍

2026-10-11 查閱上述 issue、原碼與官方文件，沒有執行轉錄、安裝或渲染測試。PR #120 當時仍為 Open；其中的自動 preflight 與 subtitle_font 提案不能當成已發布功能。正式發布本文前需再核對狀態。