video-use subtitle burn-in failed? Check the FFmpeg subtitles filter

If subtitles were generated but the final render failed, preserve the SRT and transcript first. Identify the exact FFmpeg executable video-use runs, then check its subtitles filter. Replace the build only after confirming the capability is missing; retranscription is not the first fix.

Locate the failed stage

Issue #118 reports a macOS arm64 case with Homebrew FFmpeg 8.1.2: master.srt was generated, but subtitle burn-in failed. One environment report does not establish that every Homebrew version has this problem.

Open the SRT and check that it is nonempty. Preserve the transcript, EDL, available intermediate video and complete error log. If subtitle generation failed, this is a different starting point. If final compositing failed after generation, investigate rendering capability first. An existing SRT still needs content and timing review.

Identify the executable video-use actually runs

Check your installed helpers/render.py, launcher and logs. The upstream code reviewed here invokes the name ffmpeg, making the launching process's PATH relevant.

A terminal's which ffmpeg is a clue, not proof of what an agent, IDE or another launcher used. Resolve the path inside the actual launch environment. If a product wrapper selects a different binary, verify its settings and execution evidence. Do not replace packages while the path remains unknown.

Use that confirmed absolute path for these read-only checks. Replace the placeholder below:

"/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 documents these queries for version, build configuration, available filters and individual filter help. Keep their complete output. A failed query is not by itself proof of a missing filter.

Branch on evidence

Exact subtitles entry plus readable filter help: capability is present. Return to the original FFmpeg stderr and investigate the specific file-path, filter-argument or other error it identifies
Successfully retrieved list without subtitles, corroborated by help reporting an unknown filter: investigate a build missing that capability
Unknown executable, failed probe or conflicting results: resolve the environment before reinstalling anything

The subtitles documentation specifies libass and a build with libavcodec and libavformat. --enable-libass is useful build evidence, but check the actual available filter rather than relying on a version number.

Consider another build only when needed

On macOS, the official Homebrew ffmpeg-full formula includes libass among its dependencies. Building FFmpeg with the documented requirements is another route. Neither route was installed or tested for this article.

The formula is keg-only. Homebrew explains that this means it is not linked into the default prefix: installation alone does not switch video-use. Read brew info ffmpeg-full, then verify whether your launcher supports setting its process PATH. Check a wrapper's documentation before assuming it supports explicit executable selection; do not invent a --ffmpeg-path option.

After configuration, recheck the resolved path and all four queries in the same launch environment. Force-linking over system binaries or changing permissions is unnecessary for this diagnostic.

Before retrying

[ ] Preserve subtitles, transcript, EDL and original media
[ ] Record the failed stage, executable path, version and build configuration
[ ] Verify the exact executable's filter list and subtitles help
[ ] If changing builds, confirm the video-use launcher actually selects it
[ ] Plan only the necessary rendering retry from existing assets; do not assume automatic final-stage resume exists
[ ] Write to a new output filename and review subtitles, picture and sound afterward

For editing and timing review, see the rough-cut and subtitle workflow. For scope and setup context, see the video-use introduction.

Verification scope

Sources and code were reviewed on 2026-10-11. No transcription, installation or rendering test was performed. PR #120 was still Open: its automatic preflight and subtitle_font proposals are not established released features. Recheck that status before publication.