Presets

Presets in FFmate are reusable templates that make it easier to define and run FFmpeg tasks. With a preset, you can preconfigure FFmpeg commands, output patterns, priorities, and even pre- or post-processing scripts, so every task runs the same way without extra setup.

FFmate ships with 20 built-in presets covering the most common media tasks, including format conversion, frame rate adjustment, audio extraction, and platform-specific encodes for YouTube, TikTok, Instagram, Facebook, and Twitch. These ready-to-use presets save you from having to figure out the right FFmpeg command for everyday jobs.

All presets are maintained in an open GitHub repository, where you can suggest changes or contribute new ones through pull requests. You can also create your own custom presets at any time using the API or the web interface

Creating a Preset

To create a preset, send a POST request to the FFmate API:

curl -X POST http://localhost:3000/api/v1/presets \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Analyze and Transcode MP4",
       "description": "Runs an analysis script to determine the best CRF value, which is then used in the transcode command.",
       "command": "-y -stats_period 5 -i ${INPUT_FILE} -c:v libx264 -preset medium -crf ${METADATA_crf_value} -c:a aac -b:a 128k ${OUTPUT_FILE}",
       "outputFile": "${INPUT_FILE_BASENAME}_analyzed.mp4",
       "priority": 5,
       "preProcessing": {
         "scriptPath": "/opt/ffmate/scripts/analyze_bitrate.sh --input ${INPUT_FILE} --sidecar /var/tmp/${INPUT_FILE_BASENAME}.json",
         "sidecarPath": "/var/tmp/${INPUT_FILE_BASENAME}.json",
         "importSidecar": true
       },
       "postProcessing": {
         "scriptPath": "/opt/ffmate/scripts/cleanup.sh --file ${OUTPUT_FILE} --status success"
       },
       "webhooks": [
         {
           "event": "task.updated",
           "url": "https://workflow-engine.example.com/api/ffmate/job-status-update"
         }
       ]
     }'

FFmate returns a JSON object that contains the newly created preset, including its uuid. A preset.created event is also fired via Global webhooks and Direct webhooks.

💡 Tip: Prefer a visual approach? You can create new presets directly in the FFmate Web UI no API calls needed.

Presets properties

When you create a preset, you define parameters that are automatically applied to every task that uses it.

• name [mandatory] - A short, descriptive name to help you quickly identify the preset (e.g., "Convert to MP4 1080p", "Extract Audio as MP3").

• description [optional] – A short note about what the preset is for or how it should be used (e.g., "Converts ProRes to H.264 for review copies").

• command [mandatory] – The custom command FFmate will use to run FFmpeg for this preset. Use this to define exactly how the media should be processed—for example, which codec to use, what resolution to convert to, or which filters to apply.

⚠️ Important details about how command works:

• You don’t need to add ffmpeg at the start of the command. FFmate automatically prepends it. By default, FFmate uses the ffmpeg binary in your system’s PATH. If you want to use a different version, you can override the default with the --ffmpeg <path> command-line flag.

• FFmate also implicitly adds the -stats_period 1 option to every command, which limits FFmpeg’s progress output to one update per second.

  You can override this by explicitly adding your own -stats_period x to the command.

  • This setting directly affects:
    • how often task.updated Global webhook and Direct webhook are sent, and
    • how often the job dashboard refreshes progress updates.

• Wildcards like ${INPUT_FILE} and ${OUTPUT_FILE} can be used inside the command string. FFmate replaces them with the actual file paths when the task runs.

• The command field also supports chaining several FFmpeg commands with &&, for example for two-pass encoding. Start every command after an && with the ${FFMPEG} wildcard (see FFmpeg Path).

• If a task references a preset, the command defined in the preset will always be used—any command provided directly in the task will be ignored.

Not sure which FFmpeg commands to use?

• OSTechNix – 20+ FFmpeg Commands For Beginners
• Abyssale – Top 20 best commands for FFmpeg
• VideoProc – 31 Must-Haves FFmpeg Commands for Beginners
• GorillaSun – A Simple Guide to FFMPEG
• Bannerbear – Top 10 FFmpeg Command Options You Need to Know
• Ask ChatGPT

• outputFile [optional] – The path where the transcoded file should be saved. If the specified directory does not exist, FFmate will create it automatically. This can be a full path or a pattern that includes Wildcards like ${INPUT_FILE_BASENAME} to dynamically generate structured filenames (e.g., /exports/${INPUT_FILE_BASENAME}_1080p.mp4). If a task also includes its own outputFile, that will be used instead of this one. In other words, the task's setting always takes priority over the preset.

• priority [optional] – Sets the task's priority in the processing queue. Higher numbers mean higher priority — for example, a task with priority 100 will be processed before one with 10. If multiple tasks share the same priority, they run in the order they were created. If a task defines its own priority, that will override the preset’s value. If neither is set, 0 is used.

• labels [optional] – Up to 5 labels, each 1 to 32 characters long. They decide which FFmate instance processes tasks created from this preset. A task without its own labels inherits these. See --labels.

• retries [optional] – How many times a failed task created from this preset is retried. A task without its own retries inherits this value. See task properties. Default: 0.

• preProcessing [optional] – Defines a Pre-Processing Script to run before the task starts. Useful for preparing files, validating input, or setting up the environment. If the task includes its own preProcessing config, FFmate will use that instead of the preset’s.

  • scriptPath: The full path to the script or executable to run.
  • sidecarPath: The full path to the JSON file that contains all task data.
  • importSidecar: Defines if the task will re-import the sidecar JSON after the pre-processing script finishes.

• postProcessing [optional] – Defines a Post-Processing Script to run after the task completes. Useful for cleanup, moving output files, or triggering follow-up actions. If the task includes its own postProcessing config, FFmate will use that instead of the preset’s.

  • scriptPath: The full path to the script or executable to run.
  • sidecarPath: The full path to the JSON file that contains all task data.

• webhooks [optional] – Direct webhook targets for this preset. Each entry needs an event and a url.

  • Entries for preset.created, preset.updated or preset.deleted fire when this preset changes.
  • Entries for task.created, task.updated or task.deleted are copied into every task created from this preset. For example, they can notify a project management tool whenever the task's status changes.

How to Use Presets in Tasks

When creating a new task, you can use either an out-of-the-box preset or one of your custom presets by providing its uuid instead of writing a custom command. See Using a Preset for which settings the task takes from the preset.

Example: Creating a task with a preset via API

curl -X POST http://localhost:3000/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Archive Raw Footage",
    "inputFile": "/path/to/raw_footage_01.mxf",
    "preset": "uuid-of-ProRes-HQ-for-Archive-preset",
    "metadata": {
      "project-id": "project_alpha_123",
      "shot_number": "005"
    }
  }'

Listing Presets

To get a list of all available presets, send a GET request to the FFmate API

curl -X GET 'http://localhost:3000/api/v1/presets?page=0&perPage=10'

FFmate returns a JSON array containing all configured presets. The X-Total response header provides the total number of presets available.

Query Parameters:

• page [optional] – Specifies which page of results to retrieve. Default: 0.
• perPage [optional] – Defines how many presets should be included in each page. Default: 100.

💡 Tip: Want to browse existing presets? The FFmate Web UI lets you view and search through all available presets with ease.

Getting a Single Preset

To retrieve the details of a specific preset, send a GET request to the FFmate API, including the preset's uuid in the path.

curl -X GET 'http://localhost:3000/api/v1/presets/a1b2c3d4-e5f6-7890-1234-567890abcdef'

FFmate returns a JSON object with the full details of the specified preset.

💡 Tip: Want a quick way to check the preset details? You can view preset configurations directly in the FFmate Web UI without using the API.

Updating a Preset

You can update an existing preset by sending a PUT request to the FFmate API, including the preset's uuid in the path. The available properties are listed in the Presets properties section above.

PUT replaces the whole preset

The request body must contain every property the preset should keep, not only the ones that change. Properties left out are cleared. For example, a PUT with only name and command removes the preset's description, outputFile, priority, labels, retries, processing scripts and webhooks.

curl -X PUT http://localhost:3000/api/v1/presets/{presetId} \
     -H "Content-Type: application/json" \
     -d '{
       "name": "MP4 High Quality (Updated)",
       "command": "-y -i ${INPUT_FILE} -c:v libx264 -preset slow -crf 18 -c:a aac -b:a 192k ${OUTPUT_FILE}",
       "description": "Converts video to MP4 with H.264 video and AAC audio, higher quality setting.",
       "outputFile": "${INPUT_FILE_BASENAME}_highquality.mp4",
       "priority": 5,
       "postProcessing": {
         "scriptPath": "/usr/local/bin/notify_completion.sh --file ${OUTPUT_FILE} --status success"
       }
     }'

FFmate returns the complete JSON object of the updated preset. A preset.updated event is also fired via Global webhooks and Direct webhooks.

💡 Tip: Need to tweak an existing preset? You can update it directly in the FFmate Web UI.

Deleting a Preset

To delete an existing preset, send a DELETE request to the FFmate API, replacing {presetId} with the uuid of the preset you want to remove.

curl -X DELETE 'http://localhost:3000/api/v1/presets/{presetId}'

FFmate responds with a 204 No Content status. The preset will be removed from the system. A preset.deleted event is also fired via Global webhooks and Direct webhooks.

💡 Tip: Presets can be safely deleted from the FFmate Web UI, with helpful context to avoid accidental removals.