---
url: /docs/presets.md
description: >-
  Simplify complex FFmpeg tasks with FFmate presets. Define reusable templates
  for commands, output paths, and processing scripts to streamline your media
  encoding and ensure consistency
---

# 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](https://github.com/welovemedia/ffmate-presets), 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](/docs/web-ui.md#presets)

## 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": "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](/docs/webhooks#preset-events-1) and [Direct webhooks](/docs/webhooks#preset-events).

💡 Tip: Prefer a visual approach? You can create new presets directly in the [FFmate Web UI](/docs/web-ui.md) 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](/docs/flags.md#server-command-flags).

* FFmate also implicitly adds the `-stats_period 1` [option](https://ffmpeg.org/ffmpeg-all.html#Advanced-options) 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](/docs/webhooks#task-events-1) and [Direct webhook](/docs/webhooks#task-events) are sent, and
    * how often the job dashboard refreshes progress updates.

* [Wildcards](/docs/wildcards.md) 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](/docs/wildcards.md#ffmpeg-path)).

* If a [task](/docs/tasks.md) references a preset, the `command` defined in the preset will **always** be used—any command provided directly in the [task](/docs/tasks.md) will be ignored.

::: tip Not sure which `FFmpeg` commands to use?

* [OSTechNix – 20+ FFmpeg Commands For Beginners](https://ostechnix.com/20-ffmpeg-commands-beginners/)

* [Abyssale – Top 20 best commands for FFmpeg](https://www.abyssale.com/blog/top-20-best-commands-for-ffmpeg)

* [VideoProc – 31 Must-Haves FFmpeg Commands for Beginners](https://www.videoproc.com/resource/ffmpeg-commands.htm)

* [GorillaSun – A Simple Guide to FFMPEG](https://www.gorillasun.de/blog/a-simple-guide-to-ffmpeg/)

* [Bannerbear – Top 10 FFmpeg Command Options You Need to Know](https://www.bannerbear.com/blog/ffmpeg-101-top-10-command-options-you-need-to-know-with-examples/)

* 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](/docs/wildcards.md) 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`](/docs/flags.md#server-command-flags).

* **`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](/docs/tasks.md#task-properties). Default: `0`.

* **`preProcessing`** *\[optional]* – Defines a [Pre-Processing Script](/docs/pre-post-prcessing.md) 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](/docs/pre-post-prcessing.md#importing-a-task-s-sidecar) JSON after the pre-processing script finishes.

* **`postProcessing`** *\[optional]* – Defines a [Post-Processing Script](/docs/pre-post-prcessing.md) 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](/docs/tasks.md), you can use either an [out-of-the-box preset](/docs/web-ui.md#presets) or one of your custom presets by providing its `uuid` instead of writing a custom command. See [Using a Preset](/docs/tasks.md#using-a-preset) for which settings the task takes from the preset.

**Example: Creating a task with 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": "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

```sh
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](/docs/web-ui.md#presets) 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.

```sh
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](/docs/web-ui.md#presets) 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](#presets-properties) section above.

::: warning `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.
:::

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

FFmate returns the complete JSON object of the updated preset. A `preset.updated` event is also fired via [Global webhooks](/docs/webhooks#preset-events-1) and [Direct webhooks](/docs/webhooks#preset-events).

💡 Tip: Need to tweak an existing preset? You can update it directly in the [FFmate Web UI](/docs/web-ui.md#presets).

## 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.

```sh
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](/docs/webhooks#preset-events-1) and [Direct webhooks](/docs/webhooks#preset-events).

💡 Tip: Presets can be safely deleted from the [FFmate Web UI](/docs/web-ui.md), with helpful context to avoid accidental removals.