🚀 What's New in v2.21.0

See CHANGELOG.md for the full detail.

• 🏔️ Marigold V2 — depth, surface normals and albedo from a frozen Qwen-Image-Edit-2509 DiT plus a per-task LoRA, VAE and baked conditioning. One deterministic Euler step, no CFG, no seed. Reached through depth (v2) / normals (v2) / albedo (v2) on the existing marigold mode, so nothing already in your workflows changes; also selectable as a depth_backend on the Shader Overlay node. ~22.5 GB for the first task, ~2 GB per task after (the base is shared), at roughly 3–4 s per frame
• 🎚️ Fixes ComfyUI's stock Marigold V2 sampling — the shipped blueprints patch ModelSamplingAuraFlow with sampling="flow", which hands the DiT a half-scale latent and returns 0.5·(z − v). This backend defaults to IMG_TO_IMG_VELOCITY, which yields z − v from an unscaled latent and matches the reference implementation exactly; flow stays selectable to reproduce the stock template
• 🔧 BlockSwap block discovery — the swap budget was sized from model.diffusion_model.blocks only, so any model naming its stack otherwise fell back to an estimate scaled by Wan's 40-block depth. It now also finds transformer_blocks, double_blocks and single_blocks, which matters for 60-block Qwen-Image

📄 See CHANGELOG.md for the complete version history.

NotebookLM Overview: Exploring the features and capabilities of ComfyUI-FFMPEGA. (Click to watch on YouTube)

✨ Features

🎬 Examples

Worked examples: prompts, the pipelines they produce, and the resulting output.

→ docs/EXAMPLES.md

📦 Installation

Requirements

• ComfyUI (latest)
• Python 3.10+
• FFMPEG installed and in PATH (install guide)
• Node.js 18+ (required for CLI tools: Gemini CLI, Claude CLI, Qwen CLI — download)
• Ollama (optional, for local LLM inference — download)

Option 1: ComfyUI Manager (Recommended)

1. Open ComfyUI Manager
2. Search for ComfyUI-FFMPEGA
3. Click Install

Option 2: Manual Install

cd /path/to/ComfyUI/custom_nodes
git clone https://github.com/AEmotionStudio/ComfyUI-FFMPEGA.git
cd ComfyUI-FFMPEGA
pip install -r requirements.txt

cd C:\path\to\ComfyUI\custom_nodes
git clone https://github.com/AEmotionStudio/ComfyUI-FFMPEGA.git
cd ComfyUI-FFMPEGA
pip install -r requirements.txt

Note: Use whichever Python package manager your ComfyUI venv uses (pip, uv pip, etc.). The above commands assume pip is available in your ComfyUI virtual environment.

Restart ComfyUI after installation.

🚀 Quick Start

1. Add an FFMPEG Agent node to your workflow
2. Connect a video path or use the input field
3. Enter a natural language prompt
4. Select your LLM model
5. Run the workflow

💡 Tip: Right-click the FFMPEG Agent node to open the FFMPEGA Presets context menu — 200+ categorized effects you can apply with a single click, no prompt typing needed. Great for quick edits or discovering what's available.

Example Prompts

💬 Prompt Guide

When using an LLM, the AI agent interprets your natural language and maps it to skills with specific parameters. Here's how to get the best results. (For manual editing without an LLM, see the Effects Builder and Text Input sections.)

Specifying Exact Values

You can request specific parameter values and the agent will use them directly:

What Works Well ✅

• Explicit numbers: "brightness 0.2", "speed 1.5x", "CRF 20" — the agent maps these directly
• Named presets: "VHS look", "cinematic style", "noir" — triggers multi-step preset pipelines
• Chaining operations: "Trim first 5 seconds, resize to 720p, add vignette" — executes in order
• Descriptive goals: "Make it look warmer", "Remove the green screen" — the agent picks the right skills
• Technical terms: "denoise", "deband", "normalize audio" — maps to exact FFmpeg filters

What Might Not Work as Expected ⚠️

• Vague intensity words: "Make it very blurry" or "a little brighter" — the agent has to guess what number "very" or "a little" means. Tip: use a specific value instead: "blur with radius 15"
• Out-of-range values: Parameters are auto-clamped to their valid range. If you ask for "brightness 5.0" it caps at the max (1.0)
• Complex compositing: Multi-layer effects with precise timing may need to be broken into separate passes
• Format-dependent features: Some effects (like transparency) require specific output formats. H.264/MP4 doesn't support alpha channels

🧠 AI Models (Auto-Downloaded)

Some skills use AI models that auto-download on first use. You can disable automatic downloads with the allow_model_downloads toggle on the FFMPEG Agent node — runs requiring a missing model will fail with a clear message and a manual download link.

All models are mirrored to first-party AEmotionStudio HuggingFace repos for supply chain resilience. Downloads try the AEmotionStudio mirror first, then fall back to upstream sources.

[!NOTE] Models are only downloaded when you use the corresponding skill for the first time. Core FFmpeg editing skills (200+ of them) require zero model downloads.

🎛️ Nodes

Every node, input and output — the Agent node's widgets, the save/load nodes, the Video Editor and the rest.

→ docs/NODES.md

🎯 Skill System

All 200+ skills by category, their parameters, and how to write your own.

→ docs/SKILLS.md

🤖 LLM Configuration

Ollama, the four CLI connectors (Gemini CLI, Claude Code, Cursor Agent, Qwen Code), model choice and troubleshooting.

→ docs/LLM-SETUP.md

🐛 Troubleshooting

ffmpeg -version

ollama serve

ollama pull qwen2.5:8b

🤝 Contributing

Contributions are welcome! Whether it's bug reports, new skills, or improvements — your help is appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📝 License

This project is licensed under the GPL-3.0 License — see the LICENSE file for details.