calesthio/OpenMontage · error · RuntimeError

ffmpeg failed to render preview MP4

Error message

ffmpeg failed to render preview MP4

What it means

Raised after subprocess.run of the ffmpeg encode command when result.returncode != 0. The message is `result.stderr.strip() or 'ffmpeg failed to render preview MP4'` — i.e. the generic text only appears when ffmpeg produced empty stderr; normally you see ffmpeg's own error output. Common underlying causes are a codec/pixel-format mismatch with the output container, an unwritable output path, or ffmpeg builds missing encoders (e.g. static builds without libx264).

Source

Thrown at tools/character/character_animation.py:106

            page.screenshot(path=str(frame_dir / f"frame_{frame:04d}.png"))
        browser.close()

    cmd = [
        "ffmpeg",
        "-y",
        "-framerate",
        str(fps),
        "-i",
        str(frame_dir / "frame_%04d.png"),
        "-r",
        str(fps),
        "-pix_fmt",
        "yuv420p",
        str(video_path),
    ]
    result = subprocess.run(cmd, capture_output=True, text=True)
    if result.returncode != 0:
        raise RuntimeError(result.stderr.strip() or "ffmpeg failed to render preview MP4")


class CharacterSpecGenerator(BaseTool):
    name = "character_spec_generator"
    version = "0.1.0"
    tier = ToolTier.CORE
    capability = "character_animation"
    provider = "openmontage"
    stability = ToolStability.BETA
    execution_mode = ExecutionMode.SYNC
    determinism = Determinism.DETERMINISTIC
    resource_profile = ResourceProfile(cpu_cores=1, ram_mb=128, vram_mb=0, disk_mb=10)
    agent_skills = ["character-rigging", "pose-library-design"]
    capabilities = ["draft_character_design", "normalize_character_specs"]
    best_for = ["Converting approved concepts into structured character_design artifacts"]
    not_good_for = ["Generating artwork pixels or finished animation"]
    input_schema = {
        "type": "object",

View on GitHub (pinned to 95e1c3d0ab)

Solutions

1. Read the stderr captured in the exception message — it names the exact ffmpeg failure (unknown encoder, permission denied, no such file).
2. If stderr says 'Unknown encoder libx264', install a full ffmpeg build (brew/conda/apt mainline build) instead of a stripped static one, or confirm the output is .mp4 with an available encoder.
3. Ensure the output directory exists and is writable: create video_path.parent and check permissions before rendering.
4. Check that the frame directory actually contains frame_0000.png onward with no numbering gaps; re-run capture if screenshots failed silently.

Example fix

# before
video_path = out_dir / f"{name}.mp4"   # out_dir may not exist -> ffmpeg 'No such file or directory'

# after
video_path = out_dir / f"{name}.mp4"
video_path.parent.mkdir(parents=True, exist_ok=True)
result = subprocess.run(cmd, capture_output=True, text=True)
if result.returncode != 0:
    raise RuntimeError(result.stderr.strip() or "ffmpeg failed to render preview MP4")

from pathlib import Path

def validate_encode(video_path: Path, frame_dir: Path) -> None:
    video_path.parent.mkdir(parents=True, exist_ok=True)
    frames = sorted(frame_dir.glob("frame_*.png"))
    assert frames, "no frames captured for ffmpeg"
    assert video_path.parent.is_dir() and os.access(video_path.parent, os.W_OK), "output dir not writable"

try:
    _render_preview_mp4(preview, video, duration, fps)
except RuntimeError as e:
    stderr = str(e)
    if "Unknown encoder" in stderr or "ffmpeg failed" in stderr:
        log.error("ffmpeg encode failed: %s", stderr)
        raise
    raise

When it happens

Trigger: ffmpeg exits non-zero while encoding the captured frame_%04d.png sequence into the preview MP4 (command uses -framerate fps -i frame_%04d.png -r fps -pix_fmt yuv420p <video_path>). Happens when the output path's extension selects a muxer/encoder the build lacks, the output directory does not exist or is not writable, or frames were not actually captured.

Common situations: video_path ending in a container the distro ffmpeg cannot encode (e.g. .mp4 without libx264 on a minimal build), read-only output dirs, disk full, leftover frame directories with gaps in numbering, or an output path whose parent was never created.

Related errors

• Checkpoint artifacts must be a dictionary
• FFmpeg lavfi movie paths containing single quotes are unsupp
• {detail}
• ffmpeg is required to render preview MP4
• Invalid status: {status!r}

AI-assisted analysis of calesthio/OpenMontage@95e1c3d0ab (2026-08-15). Data as JSON: /api/errors/372352f37911c6b8. Report an issue: GitHub.