From 4dccb4fb4c41e84e498e0bf00b7dfd2047a0d888 Mon Sep 17 00:00:00 2001 From: Z User Date: Tue, 29 Sep 2026 05:52:23 +0000 Subject: [PATCH] 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). --- scripts/test_merge_failure_reason.py | 295 +++++++++++++++++++++++++++ utils/h3_project.py | 5 +- utils/video.py | 73 ++++++- 3 files changed, 361 insertions(+), 12 deletions(-) create mode 100644 scripts/test_merge_failure_reason.py diff --git a/scripts/test_merge_failure_reason.py b/scripts/test_merge_failure_reason.py new file mode 100644 index 0000000..7c1788b --- /dev/null +++ b/scripts/test_merge_failure_reason.py @@ -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) diff --git a/utils/h3_project.py b/utils/h3_project.py index 7c15609..68adbe3 100644 --- a/utils/h3_project.py +++ b/utils/h3_project.py @@ -1327,15 +1327,18 @@ def compose_h3_project_video(project_name: Any, project_data: Any = None) -> Pat ffprobe_info, ) + failure_reasons: list[str] = [] temporary = merge_video_track_with_ffmpeg( timeline_segments, cursor, frame_rate, compose_size[0] if compose_size else width, compose_size[1] if compose_size else height, + failure_reason=failure_reasons, ) 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) diff --git a/utils/video.py b/utils/video.py index 4597fcf..a9c5369 100644 --- a/utils/video.py +++ b/utils/video.py @@ -307,21 +307,70 @@ def merge_video_track_with_ffmpeg( width: int, height: int, resize_method: str | None = None, + *, + failure_reason: list[str] | None = 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") 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 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 - if any(not os.path.isfile(str(segment.get("source", ""))) for segment in segments): - return None - if any( - segment.get("audio_source") is not None - and not os.path.isfile(str(segment["audio_source"])) + missing_sources = [ + str(segment.get("source", "")) 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 total_seconds = total_length / frame_rate @@ -495,6 +544,7 @@ def merge_video_track_with_ffmpeg( ) from exc except OSError as exc: logger.warning("FFmpeg video track merge failed to start: %s", exc) + record(f"FFmpeg failed to start ({exc})") try: os.unlink(output_path) except OSError: @@ -503,9 +553,10 @@ def merge_video_track_with_ffmpeg( if result.returncode == 0: return output_path - logger.warning( - "FFmpeg video track merge failed: %s", - result.stderr.decode(errors="replace")[-600:], + stderr_tail = result.stderr.decode(errors="replace")[-600:] + logger.warning("FFmpeg video track merge failed: %s", stderr_tail) + record( + f"FFmpeg exited with code {result.returncode}: {stderr_tail.strip() or 'no stderr output'}" ) try: os.unlink(output_path)