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).