Overview
This node modifies and optionally executes FFmpeg commands for video processing tasks. It is designed to help users customize video encoding, decoding, clipping, merging, and hardware acceleration settings by adjusting an existing FFmpeg command or building one from input parameters.
Common scenarios where this node is beneficial include:
- Changing the input or output file paths in an existing FFmpeg command.
- Switching video or audio codecs with fine control over encoding presets, quality modes, and bitrate.
- Enabling CUDA hardware acceleration for supported GPUs.
- Clipping videos by specifying start and end times.
- Merging multiple video files into one.
- Previewing the modified FFmpeg command before execution.
- Executing the FFmpeg command directly within a workflow and monitoring progress via HTTP callbacks.
Practical examples:
- Transcoding a video from H.264 to HEVC with custom CRF quality settings.
- Extracting a 30-second clip from a longer video.
- Combining several short clips into a single video file.
- Using NVIDIA GPU acceleration to speed up encoding.
- Sending progress updates to a local server during long-running encoding jobs.
Properties
| Name | Meaning |
|---|---|
| 原始FFmpeg命令 (originalCommand) | The original FFmpeg command string to modify. Required. |
| 输入文件路径 (inputPath) | New input file path to replace the one in the original command. Leave empty to keep original. |
| 输出文件路径 (outputPath) | New output file path to replace the one in the original command. Leave empty to keep original. |
| 视频编码器参数 (videoCodec) | Video codec to use. Options: 不修改 (no change), H.264, H.265, HEVC NVIDIA, H.264 NVIDIA, 直接复制 (copy), WebP. |
| 启用高级编码设置 (enableAdvancedEncoding) | Enable advanced encoding parameters like preset, tune, and quality control. Only available for certain video codecs. |
| 编码预设 (encodingPreset) | Encoding speed preset affecting quality/speed tradeoff. Options: 不修改 (unchanged), faster, fast, medium, slow, slower, veryslow. |
| 调优选项 (encodingTune) | Tune option for specific content types. Options: 默认 (default), film, animation, grain, stillimage, psnr, ssim, fastdecode, zerolatency. Only for libx264/libx265 with advanced encoding enabled. |
| 质量控制模式 (qualityMode) | Quality control mode. Options: VBR (variable bitrate), CRF (constant rate factor), CQ (constant quantizer), CBR (constant bitrate), 默认 (default). Available with advanced encoding and certain codecs. |
| CRF 质量值 (crfValue) | CRF quality value (0-51, lower is better quality). Recommended 18-28. Used if qualityMode is CRF and codec supports it. |
| CQ 质量值 (cqValue) | CQ quality value (0-51, lower is better quality). Used if qualityMode is CQ and codec supports it. |
| 目标码率 (bitrate) | Target bitrate in kbps. Used if qualityMode is CBR or VBR. |
| 最大码率 (maxBitrate) | Maximum bitrate limit in kbps. Used if qualityMode is VBR. |
| 音频编码参数 (audioCodec) | Audio codec to use. Options: 不修改 (no change), AAC, MP3, FLAC, 无音频 (none), 直接复制 (copy). |
| 启用CUDA硬件加速 (enableCudaAcceleration) | Enable CUDA hardware acceleration for decoding and encoding (requires CUDA-capable GPU). |
| 启用视频截取 (enableClipping) | Enable video clipping feature. |
| 开始时间 (startTime) | Start time for clipping (format HH:MM:SS or seconds). Shown only if clipping enabled. |
| 结束时间 (endTime) | End time for clipping (format HH:MM:SS or seconds). Shown only if clipping enabled. |
| 启用视频合并 (enableMerging) | Enable merging of multiple video files. |
| 合并文件路径 (mergeInputPaths) | List of video file paths to merge, one per line. Shown only if merging enabled. |
| 执行命令 (executeCommand) | Whether to execute the modified FFmpeg command immediately. If false, only preview the command. |
| 进度回调URL (progressCallbackUrl) | Optional HTTP POST callback URL to receive FFmpeg progress updates. |
| 进度报告间隔 (progressInterval) | Frequency in milliseconds to send progress updates. |
| 任务ID (taskId) | Unique identifier for the FFmpeg task instance, used to distinguish progress callbacks. |
| 任务执行超时时间 (timeout) | Timeout in minutes after which the FFmpeg process will be forcibly terminated. |
| 参数加引号 (quotedCommand) | Whether to add double quotes around all FFmpeg parameters (useful if parameters contain special characters). |
Output
The node outputs an array of JSON objects, each corresponding to an input item processed. Each output object contains:
success: Boolean indicating if the command modification and optional execution succeeded.originalCommand: The original FFmpeg command string provided.command: The modified FFmpeg command string after applying user parameters.modifications: Object summarizing all parameter modifications applied.executed: Boolean indicating whether the command was actually executed.stderr: Standard error output from FFmpeg execution (if executed).outputExists: Boolean indicating if the output file exists after execution.finalStatus: Final status of the FFmpeg task (e.g., completed, failed, cancelled).taskCancelled: Boolean indicating if the task was cancelled.executionError: Error message if execution failed.error: General error message if command modification or execution failed.
If execution is disabled, the output mainly serves as a preview of the modified command and its parameters.
Dependencies
- Requires FFmpeg installed and accessible in the system environment where n8n runs.
- For CUDA acceleration, requires a CUDA-capable GPU and appropriate drivers.
- Optionally uses an HTTP endpoint for progress callbacks if configured.
- No internal credential types are required; however, external API keys or credentials are not applicable here.
Troubleshooting
Common issues:
- Invalid or malformed original FFmpeg command string causing parsing errors.
- Incorrect file paths leading to "file not found" errors.
- Unsupported codec or hardware acceleration options on the host machine.
- Timeout reached if FFmpeg process hangs or takes too long.
- Progress callback URL unreachable or misconfigured, resulting in no progress updates.
Error messages:
- "FFmpeg命令修改失败" (FFmpeg command modification failed): Indicates invalid input parameters or parsing failure. Check the original command and inputs.
- "FFmpeg命令执行失败" (FFmpeg command execution failed): Execution error with details in stderr. Verify command correctness and system FFmpeg installation.
- Output file missing after execution: Check write permissions and output path validity.
Resolutions:
- Validate and test the original FFmpeg command independently before using the node.
- Ensure all file paths exist and are accessible.
- Confirm hardware acceleration support on your system.
- Increase timeout if processing large files.
- Verify network connectivity and correctness of progress callback URL.