Windows PATH edits only reach processes started afterwards, so a freshly
installed FFmpeg stays invisible to a running ComfyUI, and portable users
often drop ffmpeg.exe next to the run bat without any PATH entry at all.
get_ffmpeg_path now probes, after which() fails: the classic C:\ffmpeg\bin
and %LOCALAPPDATA% locations, winget Links / scoop shims / chocolatey bin,
the ComfyUI base folder and portable root (root, bin/, ffmpeg/bin/), and
finally the ffmpeg binary bundled with ComfyUI's own imageio-ffmpeg
dependency (ffmpeg only - imageio-ffmpeg bundles no ffprobe).
The H3 compose failure message now also points at concrete remedies
instead of only listing search locations.
Verified with scripts/test_merge_failure_reason.py: 19/19 stubbed checks
(portable-layout resolution, imageio-ffmpeg last resort, ffprobe exclusion,
and every compose failure reason).
merge_video_track_with_ffmpeg returned None for every failure mode (FFmpeg
missing, empty timeline, odd canvas, missing segment/locked-audio files,
spawn errors, non-zero exit), which collapsed into the useless
'FFmpeg could not compose the H3 project video' message users saw in the
ComfyUI error dialog.
Add an opt-in failure_reason collector: callers that need to surface the
cause (compose_h3_project_video) now pass a list and receive one specific
human-readable entry per failed precondition, or the FFmpeg stderr tail
(e.g. 'Unknown encoder libx264') when the command itself fails. The
nodes/basic.py tensor-merge fallback still uses the silent None contract
and is unchanged.
Verified with scripts/test_merge_failure_reason.py (16 stubbed checks:
every return-None path records a reason, compose propagates it).