FFmate documentation

Appearance

Presets ​

Presets in FFmate are powerful, reusable templates that simplify how you define and run FFmpeg tasks. They allow you to preconfigure FFmpeg commands, output patterns, priorities, and even automated pre/post-processing scripts, streamlining your entire transcoding workflow.

Think of a preset as a named, shareable "recipe" for media processing. Presets help streamline task creation, reduce errors, and ensure that jobs follow a standardized workflow every time they're run.

Creating a Preset ​

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

sh
curl -X POST http://localhost:3000/api/v1/presets \
     -H "Content-Type: application/json" \
     -d '{
       "name": "MP4 Standard Quality",
       "command": "-y -i ${INPUT_FILE} -c:v libx264 -preset medium -crf 23 -c:a aac -b:a 128k ${OUTPUT_FILE}",
       "description": "Converts video to MP4 with H.264 video and AAC audio, good balance of quality and size.",
       "outputFile": "${INPUT_FILE_BASENAME}_standard.mp4",
       "priority": 1,
       "postProcessing": {
         "scriptPath": "/usr/local/bin/notify_completion.sh --file ${OUTPUT_FILE} --status success"
       }
     }'

FFmate returns a JSON object that contains the newly created preset including its ID. An preset.created event is also fired via webhooks

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

Updating a Preset ​

You can update an existing preset by sending a PUT request to the FFmate API, including the preset's ID in the path. The request body should contain the updated properties for the preset. You can find a list of all available properties in the Presets properties section below.

sh
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"
       }
     }'

Fmate returns the complete JSON object of the updated preset. An preset.updated event is also fired via webhooks.

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

Presets properties ​

When creating a preset, you define a set of parameters that will be automatically applied to any task that uses it.

  • name [optional] - 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").

  • FFmpeg command [optional] – 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. Note that 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.

💡 Tip: You can use wildcards like ${INPUT_FILE} and ${OUTPUT_FILE} inside the command string. FFmate will automatically replace them with the actual file paths when the task runs.

Not sure which FFmpeg commands to use?

  • output file path [optional] – Specifies where the output file should be saved. 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’ll generally run in the order they were created (FIFO for that priority level). If a task defines its own priority, that will override the preset’s value. If neither is set, a default (usually 0) is used.

  • pre-processing [optional] – Defines a script that runs before the main ffmpeg command. If the task includes its own preProcessing config, FFmate will use that instead of the preset’s.

    • scriptPath – The command or path to the script to run. You can use Wildcards to insert dynamic values.

      Example: python /opt/scripts/validate_input.py --input ${INPUT_FILE} --metadata_out ${INPUT_FILE_BASENAME}.json

    • sidecarPath [optional] – Path where FFmate will write a JSON file with task details (input/output paths, metadata, etc.) before running the script. Your script can then read this file to make decisions. Wildcards are supported.

      Example: ${INPUT_FILE_DIR}/${INPUT_FILE_BASENAME}_ffmate_task.json

  • post-processing [optional] – Defines a script that runs after the ffmpeg command completes successfully. If the task includes its own postProcessing config, FFmate will use that instead of the preset’s.

    • scriptPath [mandatory] – The command or path to the script to run. You can use Wildcards to insert dynamic values.

      Example: bash /opt/scripts/archive_and_notify.sh --source ${OUTPUT_FILE} --original ${INPUT_FILE}

    • sidecarPath [optional] – Path where FFmate will write a JSON file with task details (including the final output path) before running the script. Your script can then read this file to make decisions. Wildcards are supported.

      Example: ${OUTPUT_FILE_DIR}/${OUTPUT_FILE_BASENAME}_ffmate_task_complete.json

Listing Presets ​

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

sh
curl -X GET 'http://localhost:3000/api/v1/presets?page=0&perPage=10' \
     -H 'accept: application/json'

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 tasks should be included in each page. Default: 50.

💡 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 ID in the path.

sh
curl -X GET 'http://localhost:3000/api/v1/presets/a1b2c3d4-e5f6-7890-1234-567890abcdef' \
     -H 'accept: application/json'

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.

Deleting a Preset ​

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

sh
curl -X DELETE 'http://localhost:3000/api/v1/presets/{presetId}' \
     -H 'accept: application/json'

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

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

How to Use Presets When Creating Tasks ​

When you create a new task, you can simply reference the ID of an existing preset.

Example: Creating a Task using a Preset via API

sh
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": "id-of-ProRes-HQ-for-Archive-preset",
    "metadata": {
      "project-id": "project_alpha_123",
      "shot_number": "005"
    }
  }'

FFmate will then automatically:

  1. Use the command defined in the "ProRes HQ for Archive" preset.
  2. Generate the output file path based on the preset’s outputFile pattern.
  3. Assign the preset’s priority value (50) to the task.
  4. After ffmpeg finishes successfully, ffmate will
    • Run the postProcessing script (e.g., notify_completion.sh).