fix: surface the real FFmpeg compose failure instead of a generic error

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).
This commit is contained in:
Z User 2026-09-29 05:52:23 +00:00
parent bc534da34f
commit 4dccb4fb4c
3 changed files with 361 additions and 12 deletions

View File

@ -0,0 +1,295 @@
"""Standalone verification for merge_video_track_with_ffmpeg failure_reason.
Runs without ComfyUI/torch: stubs the heavy imports, then exercises every
``return None`` path of merge_video_track_with_ffmpeg and the
compose_h3_project_video error propagation, asserting each produces a
specific, human-readable reason.
Usage: python scripts/test_merge_failure_reason.py
"""
from __future__ import annotations
import sys
import types
from pathlib import Path
PACKAGE_ROOT = Path(__file__).resolve().parent.parent
def _install_stubs() -> None:
# Minimal torch stub: only attributes evaluated at IMPORT time are needed
# (annotations like `torch.Tensor`, `torch.device`, `torch.dtype` in
# image.py, and `torch.nn.functional` imported by image/audio/multitrack).
# No torch function actually runs on the paths under test.
if "torch" not in sys.modules:
torch = types.ModuleType("torch")
torch.__path__ = [] # mark as package so torch.nn.functional imports resolve
nn = types.ModuleType("torch.nn")
functional = types.ModuleType("torch.nn.functional")
functional.pad = lambda *a, **k: None
nn.functional = functional
torch.nn = nn
torch.Tensor = object
torch.device = object
torch.dtype = object
torch.float32 = object()
torch.float64 = object()
sys.modules["torch"] = torch
sys.modules["torch.nn"] = nn
sys.modules["torch.nn.functional"] = functional
if "folder_paths" not in sys.modules:
fp = types.ModuleType("folder_paths")
temp_dir = PACKAGE_ROOT / ".tmp-temp"
temp_dir.mkdir(exist_ok=True)
fp.get_output_directory = lambda: str(PACKAGE_ROOT / ".tmp-output")
fp.get_temp_directory = lambda: str(PACKAGE_ROOT / ".tmp-temp")
fp.get_input_directory = lambda: ""
fp.get_filename_list = lambda *a, **k: []
fp.get_full_path = lambda *a, **k: None
sys.modules["folder_paths"] = fp
if "server" not in sys.modules:
sys.modules["server"] = types.ModuleType("server")
_install_stubs()
sys.path.insert(0, str(PACKAGE_ROOT))
# Import the REAL utils package: with the stubs above, the eager `from .image
# import *` in utils/__init__.py resolves, so multitrack's `from . import
# FFMPEG_RESIZE_METHODS, ...` also works and h3_project loads untouched.
from utils.video import merge_video_track_with_ffmpeg # noqa: E402
import utils.video as video_mod # noqa: E402
import utils.h3_project as h3_project # noqa: E402
CHECKS: list[tuple[str, bool, str]] = []
def check(name: str, condition: bool, detail: str = "") -> None:
CHECKS.append((name, bool(condition), detail))
# ---------------------------------------------------------------------------
# 1. FFmpeg not found: point PATH lookup at an empty search space.
# ---------------------------------------------------------------------------
import shutil # noqa: E402
_real_which = shutil.which
shutil.which = lambda name, **k: None
try:
reasons: list[str] = []
out = merge_video_track_with_ffmpeg(
[{"source": "whatever.mp4", "start_frame": 0, "end_frame": 10}],
10,
24.0,
64,
64,
failure_reason=reasons,
)
check("ffmpeg-missing returns None", out is None)
check(
"ffmpeg-missing reason mentions FFmpeg executable",
len(reasons) == 1 and "FFmpeg executable not found" in reasons[0],
str(reasons),
)
finally:
shutil.which = _real_which
# ---------------------------------------------------------------------------
# 2. Without failure_reason the function still returns None silently and no
# caller-visible behavior changes (backwards compatibility).
# ---------------------------------------------------------------------------
shutil.which = lambda name, **k: None
try:
out = merge_video_track_with_ffmpeg(
[{"source": "whatever.mp4", "start_frame": 0, "end_frame": 10}],
10,
24.0,
64,
64,
)
check("no-collector path still returns None", out is None)
finally:
shutil.which = _real_which
# ---------------------------------------------------------------------------
# 3. ffmpeg "found": redirect get_ffmpeg_path via monkeypatched shutil.which to
# a real executable so we reach the precondition checks.
# ---------------------------------------------------------------------------
import os # noqa: E402
fake_ffmpeg = Path(PACKAGE_ROOT / ".tmp-fake-ffmpeg")
fake_ffmpeg.write_text("")
os.chmod(fake_ffmpeg, 0o755)
shutil.which = lambda name, **k: str(fake_ffmpeg) if name == "ffmpeg" else None
try:
# Empty timeline
reasons = []
out = merge_video_track_with_ffmpeg([], 0, 24.0, 64, 64, failure_reason=reasons)
check("empty timeline returns None", out is None)
check(
"empty timeline reason",
len(reasons) == 1 and "timeline is empty" in reasons[0],
str(reasons),
)
# Invalid frame rate
reasons = []
out = merge_video_track_with_ffmpeg(
[{"source": "x.mp4", "start_frame": 0, "end_frame": 1}],
1,
0.0,
64,
64,
failure_reason=reasons,
)
check("invalid fps returns None", out is None)
check("invalid fps reason", len(reasons) == 1 and "frame rate" in reasons[0], str(reasons))
# Odd dimensions
reasons = []
out = merge_video_track_with_ffmpeg(
[{"source": "x.mp4", "start_frame": 0, "end_frame": 1}],
1,
24.0,
63,
64,
failure_reason=reasons,
)
check("odd width returns None", out is None)
check(
"odd width reason names size",
len(reasons) == 1 and "63x64" in reasons[0] and "odd" in reasons[0],
str(reasons),
)
# Missing segment sources
reasons = []
out = merge_video_track_with_ffmpeg(
[
{"source": "/definitely/not/here/a.mp4", "start_frame": 0, "end_frame": 4},
{"source": "/definitely/not/here/b.mp4", "start_frame": 4, "end_frame": 8},
{"source": "/definitely/not/here/c.mp4", "start_frame": 8, "end_frame": 12},
],
12,
24.0,
64,
64,
failure_reason=reasons,
)
check("missing sources returns None", out is None)
check(
"missing sources reason lists each file",
len(reasons) == 1
and "a.mp4" in reasons[0]
and "b.mp4" in reasons[0]
and "c.mp4" in reasons[0]
and "missing" in reasons[0],
str(reasons),
)
# Missing locked audio
reasons = []
out = merge_video_track_with_ffmpeg(
[
{
"source": str(fake_ffmpeg),
"audio_source": "/definitely/not/here/locked.wav",
"start_frame": 0,
"end_frame": 4,
}
],
4,
24.0,
64,
64,
failure_reason=reasons,
)
check("missing locked audio returns None", out is None)
check(
"locked audio reason names file",
len(reasons) == 1 and "locked.wav" in reasons[0],
str(reasons),
)
# FFmpeg command failure: run the real (invalid) fake binary -> OSError or
# non-zero return. The fake file is not executable code; on POSIX exec
# raises OSError (ENOEXEC / format error), on the sandbox it surfaces as
# either the OSError path or a non-zero returncode path. Both must record.
reasons = []
out = merge_video_track_with_ffmpeg(
[{"source": str(fake_ffmpeg), "start_frame": 0, "end_frame": 1}],
1,
24.0,
64,
64,
failure_reason=reasons,
)
check("command failure returns None", out is None)
check(
"command failure records a reason",
len(reasons) == 1
and ("failed to start" in reasons[0] or "exited with code" in reasons[0]),
str(reasons),
)
finally:
shutil.which = _real_which
fake_ffmpeg.unlink(missing_ok=True)
# ---------------------------------------------------------------------------
# 4. compose_h3_project_video propagates the reason into the RuntimeError.
# ---------------------------------------------------------------------------
def _fake_merge(segments, total_length, frame_rate, w, h, **kwargs):
reasons = kwargs.get("failure_reason")
if reasons is not None:
reasons.append("FFmpeg exited with code 1: Unknown encoder 'libx264'")
return None
# compose_h3_project_video imports merge_video_track_with_ffmpeg from the
# `utils.video` module at call time (function-local import), so patch the
# attribute on the already-loaded video module, not on h3_project.
h3_project.load_h3_project_data = lambda *a, **k: {
"width": 848,
"height": 480,
"frame_rate": 24.0,
"clips": [
{
"index": 0,
"enabled": True,
"file_path": "easy_media/projects/p/out/seg_000.mp4",
"updated_at": 1,
"source_frame_count": 16,
"source_start_frame": 0,
"source_end_frame": 16,
"video_files": [],
}
],
}
video_mod.merge_video_track_with_ffmpeg = _fake_merge
try:
h3_project.compose_h3_project_video("proj", None)
check("compose raises on None", False, "no exception raised")
except RuntimeError as error:
message = str(error)
check(
"compose error carries the real reason",
"could not compose the H3 project video" in message
and "Unknown encoder 'libx264'" in message,
message,
)
except Exception as error: # noqa: BLE001
check("compose raises RuntimeError only", False, repr(error))
# ---------------------------------------------------------------------------
passed = sum(1 for _, ok, _ in CHECKS if ok)
failed = len(CHECKS) - passed
for name, ok, detail in CHECKS:
print(f"{'PASS' if ok else 'FAIL'}: {name}" + (f" [{detail}]" if detail and not ok else ""))
print(f"\n{passed}/{len(CHECKS)} checks passed")
sys.exit(1 if failed else 0)

View File

@ -1327,15 +1327,18 @@ def compose_h3_project_video(project_name: Any, project_data: Any = None) -> Pat
ffprobe_info, ffprobe_info,
) )
failure_reasons: list[str] = []
temporary = merge_video_track_with_ffmpeg( temporary = merge_video_track_with_ffmpeg(
timeline_segments, timeline_segments,
cursor, cursor,
frame_rate, frame_rate,
compose_size[0] if compose_size else width, compose_size[0] if compose_size else width,
compose_size[1] if compose_size else height, compose_size[1] if compose_size else height,
failure_reason=failure_reasons,
) )
if temporary is None: if temporary is None:
raise RuntimeError("FFmpeg could not compose the H3 project video") detail = "; ".join(failure_reasons) if failure_reasons else "no reason was recorded"
raise RuntimeError(f"FFmpeg could not compose the H3 project video: {detail}")
return Path(temporary) return Path(temporary)

View File

@ -307,21 +307,70 @@ def merge_video_track_with_ffmpeg(
width: int, width: int,
height: int, height: int,
resize_method: str | None = None, resize_method: str | None = None,
*,
failure_reason: list[str] | None = None,
) -> str | None: ) -> str | None:
"""Compose file-backed segments on a black full-length timeline.""" """Compose file-backed segments on a black full-length timeline.
Returns ``None`` when composition is impossible so callers can fall back
to another strategy. Callers that need to surface the real cause instead
pass a ``failure_reason`` list, which receives one human-readable entry
per failed precondition (missing FFmpeg, missing source files, ...) or
the FFmpeg stderr tail when the command itself fails.
"""
def record(reason: str) -> None:
if failure_reason is not None:
failure_reason.append(reason)
ffmpeg = get_ffmpeg_path("ffmpeg") ffmpeg = get_ffmpeg_path("ffmpeg")
resize_filter = _ffmpeg_resize_filter(width, height, resize_method) if resize_method else None resize_filter = _ffmpeg_resize_filter(width, height, resize_method) if resize_method else None
if ffmpeg is None or total_length <= 0 or frame_rate <= 0 or width % 2 or height % 2: if ffmpeg is None:
record(
"FFmpeg executable not found (searched PATH for ffmpeg/ffmpeg.exe, "
r"C:\ffmpeg\bin, %LOCALAPPDATA%\Programs\ffmpeg\bin). "
"Install FFmpeg, ensure ffmpeg.exe is on PATH and restart ComfyUI"
)
return None
if total_length <= 0:
record(f"timeline is empty (total_length={total_length} frames)")
return None
if frame_rate <= 0:
record(f"invalid frame rate {frame_rate}")
return None
if width % 2 or height % 2:
record(
f"canvas size {width}x{height} has odd dimensions "
"(video encoders require even width and height)"
)
return None return None
if resize_method is not None and resize_filter is None: if resize_method is not None and resize_filter is None:
record(f"resize method '{resize_method}' is not supported by this FFmpeg build")
return None return None
if any(not os.path.isfile(str(segment.get("source", ""))) for segment in segments): missing_sources = [
return None str(segment.get("source", ""))
if any(
segment.get("audio_source") is not None
and not os.path.isfile(str(segment["audio_source"]))
for segment in segments for segment in segments
): if not os.path.isfile(str(segment.get("source", "")))
]
if missing_sources:
record(
"segment source file(s) missing: "
+ " | ".join(missing_sources[:5])
+ (f" (+{len(missing_sources) - 5} more)" if len(missing_sources) > 5 else "")
)
return None
missing_audio = [
str(segment["audio_source"])
for segment in segments
if segment.get("audio_source") is not None
and not os.path.isfile(str(segment["audio_source"]))
]
if missing_audio:
record(
"locked audio file(s) missing: "
+ " | ".join(missing_audio[:5])
+ (f" (+{len(missing_audio) - 5} more)" if len(missing_audio) > 5 else "")
)
return None return None
total_seconds = total_length / frame_rate total_seconds = total_length / frame_rate
@ -495,6 +544,7 @@ def merge_video_track_with_ffmpeg(
) from exc ) from exc
except OSError as exc: except OSError as exc:
logger.warning("FFmpeg video track merge failed to start: %s", exc) logger.warning("FFmpeg video track merge failed to start: %s", exc)
record(f"FFmpeg failed to start ({exc})")
try: try:
os.unlink(output_path) os.unlink(output_path)
except OSError: except OSError:
@ -503,9 +553,10 @@ def merge_video_track_with_ffmpeg(
if result.returncode == 0: if result.returncode == 0:
return output_path return output_path
logger.warning( stderr_tail = result.stderr.decode(errors="replace")[-600:]
"FFmpeg video track merge failed: %s", logger.warning("FFmpeg video track merge failed: %s", stderr_tail)
result.stderr.decode(errors="replace")[-600:], record(
f"FFmpeg exited with code {result.returncode}: {stderr_tail.strip() or 'no stderr output'}"
) )
try: try:
os.unlink(output_path) os.unlink(output_path)