Parameter Replacer

FFmpeg Builder: Parameter Replacer

The FFmpeg Builder: Parameter Replacer flow element modifies FFmpeg command-line parameters by applying configured string replacements.
It is useful for dynamically altering FFmpeg arguments during video processing flows, allowing flexible customization without changing the original command syntax manually.

This flow element scans the FFmpeg argument list and replaces matching keys with new parameters, supporting single or multiple values and even removal of parameters.

---

Purpose

FFmpeg commands can be complex and vary widely depending on the encoding scenario, source file, or target format.
Sometimes you need to programmatically adjust or override specific parameters to optimize encoding, fix incompatibilities, or apply user preferences.

This flow element enables such changes by applying a list of replacement rules to the FFmpeg arguments before execution, making your flows more adaptable and maintainable.

---

Replacements

A list of key-value pairs where:

• The key is a sequence of one or more FFmpeg arguments to match exactly.
• The value is the replacement string which can contain one or more parameters and values.

If the replacement value is empty, the matching parameter(s) are removed from the argument list.

The replacement engine:

• Matches the key against the current argument list token sequence.
• If matched, removes the key tokens and inserts the replacement tokens.
• Supports multiple tokens in keys and values.
• Logs replacements and removals for debugging.

Quotes in Replacements

• The argument list tokens (the args list) should not include quotes around values unless those quotes are part of the actual parameter string.
• When specifying keys and values in replacements, quotes may be included only to clarify grouping or when the FFmpeg parameter itself requires quotes (e.g., filter expressions).
• The replacement engine splits keys and values by spaces into tokens, so any quotes included in the strings become part of the tokens.
• Do not include quotes in keys or values if your actual FFmpeg arguments do not include them.
• Use quotes in the replacement value only if FFmpeg expects the argument to be quoted or contains spaces that must be preserved as a single token.

Examples

Key	Value	Resulting Arguments
-preset medium	-preset fast	Replaces -preset medium with -preset fast
-filter_complex oldval	-filter_complex "val1 val2"	Replaces value with a single quoted token
-filter_complex oldval	-filter_complex val1 val2	Replaces value with two separate tokens val1 and val2
-map	(empty)	Removes the -map parameter entirely

For example, if your argument list contains:

-filter_complex somevalue

and your replacement key is

-filter_complex somevalue

without quotes, but your replacement value is

-filter_complex "new value"

(with quotes around "new value"), the quotes are used to group multiple words into a single argument token passed to FFmpeg, but the quotes themselves are not included in the actual argument value.

---

Outputs

1. One or more parameter replacements or removals were applied.
2. No replacements or removals were made.

---

Use Cases

🎛️ Customize Encoding Parameters
Easily swap presets, codecs, filters, or tuning parameters based on workflow conditions without rewriting entire command lines.

🔄 Adapt to Source or Destination Requirements
Change parameters dynamically to support different input formats, container restrictions, or streaming protocols.

🚫 Remove Unwanted Parameters
Strip out problematic or deprecated parameters on the fly without needing complex scripting.

🧪 Debug and Optimize Workflows
Trace what parameter replacements were made for troubleshooting or performance tuning.

---

Notes

• The replacement keys and values are tokenized on spaces; do not include literal quotes in the argument list unless they are part of the parameter.
• Use quotes in the replacement strings only if the underlying FFmpeg command expects them as part of a parameter.
• The logger provides details on each replacement or removal for transparency.

---

How to Set in JavaScript

You can manage FFmpeg parameter replacements in a Function or Script using these two methods on FfmpegBuilderModel.

---

AddParameterReplacement

Use this method to add a single replacement rule.

/// <summary>
/// Adds a parameter replacer
/// </summary>
/// <param name="original">The original FFmpeg argument(s) to match (space-separated tokens)</param>
/// <param name="replacement">The replacement string (can be multiple tokens, or empty to remove)</param>
void AddParameterReplacement(string original, string replacement);

Example (JavaScript):

builder.AddParameterReplacement("-c:v libx264", "-c:v hevc_nvenc");

---

ClearParameterReplacements

Use this method to remove all existing replacement rules.

/// <summary>
/// Clears the parameter replacements
/// </summary>
void ClearParameterReplacements();

Example (JavaScript):

builder.ClearParameterReplacements();

---

Example 1: Replace Preset Speed

var ffmpegModel = Variables?.FfmpegBuilderModel;
if (!ffmpegModel)
    return Flow.Fail('Run after the FFmpeg Builder: Start flow element');

ffmpegModel.AddParameterReplacement('-preset medium', '-preset fast');

Example 2: Remove Parameter Completely

var ffmpegModel = Variables?.FfmpegBuilderModel;
if (!ffmpegModel)
    return Flow.Fail('Run after the FFmpeg Builder: Start flow element');

ffmpegModel.AddParameterReplacement('-map', '');

Example 3: Insert Parameters Before Input

A common hack to insert extra FFmpeg parameters before the -i input parameter is to replace -i with your parameters plus -i again, e.g.:

var ffmpegModel = Variables?.FfmpegBuilderModel;
if (!ffmpegModel)
    return Flow.Fail('Run after the FFmpeg Builder: Start flow element');

ffmpegModel.AddParameterReplacement('-i', '-hwaccel cuda -i');

This results in the command line:

ffmpeg -hwaccel cuda -i input.mp4 ...

Example 4: Multiple Replacements

var ffmpegModel = Variables?.FfmpegBuilderModel;
if (!ffmpegModel)
    return Flow.Fail('Run after the FFmpeg Builder: Start flow element');

ffmpegModel.AddParameterReplacement('-preset medium', '-preset fast');
ffmpegModel.AddParameterReplacement('-map', '');
ffmpegModel.AddParameterReplacement('-i', '-hwaccel cuda -i');

Example 5: Clear Existing Replacements

var ffmpegModel = Variables?.FfmpegBuilderModel;
if (!ffmpegModel)
    return Flow.Fail('Run after the FFmpeg Builder: Start flow element');

ffmpegModel.ClearParameterReplacements();
ffmpegModel.AddParameterReplacement('-preset medium', '-preset fast');