🚀 Getting Started

Setting up FFmate is quick and straightforward. Follow these steps to get up and running in no time.

Installing FFmpeg

FFmate relies on FFmpeg to handle all media processing behind the scenes. If you don’t have FFmpeg installed yet, no worries — just follow the steps below to get it set up on your system.

 macOS

Installing FFmpeg via Homebrew

The easiest way to install FFmpeg on macOS is using Homebrew:

brew install ffmpeg

Homebrew installs FFmpeg and adds it to your system path automatically, so FFmate can find it and start processing tasks right away.

Download and run the static build

If Homebrew isn’t your thing, you can also install FFmpeg manually by downloading a static build.

Go to https://ffmpeg.org/download.html and click the Apple icon.
Choose a trusted static build provider like:
- evermeet.cx
- Gyan.dev
Download the build and unzip it. You’ll find an ffmpeg binary inside.

Move the binary to a directory in your system PATH, for example:

sudo mv ~/Downloads/ffmpeg /usr/local/bin/
sudo chmod +x /usr/local/bin/ffmpeg

The first time you run it, macOS may block it because it’s from an "unidentified developer" To allow it:
- Open System Settings → Privacy & Security
- Look for the FFmpeg block message and click Allow Anyway
- Then run the binary again from your terminal

Once that's done, FFmpeg will be available system-wide, and FFmate will be able to use it automatically.

🖥️ Windows

Install via Windows Package Manager (winget)

If you're on Windows 10 or 11, you can install FFmpeg via the built-in package manager:

powershell

winget install FFmpeg

This installs FFmpeg and automatically adds it to your system PATH, so FFmate can detect it and start processing tasks right away

Download and run the static build

Want full control? Here’s how to install FFmpeg manually with a static build

Go to https://www.gyan.dev/ffmpeg/builds/ and download a static build (e.g., ffmpeg-release-essentials.zip).
Extract the archive to a folder — for example: C:\ffmpeg.
Add C:\ffmpeg\bin to your system PATH:
- Press Win + S, search for Environment Variables, and select Edit the system environment variables
- In the System Properties window, click Environment Variables…
- Under System variables, find and select the Path variable, then click Edit
- Click New and enter: C:\ffmpeg\bin
- Click OK to save and close all windows
Open a new terminal (Command Prompt or PowerShell) and verify the installation:
cmd
```
ffmpeg -version
```

Once installed and added to your path, FFmpeg will be available system-wide — and FFmate will be ready to use it automatically.

🐧 Linux

On Ubuntu or Debian-based systems:

sudo apt update
sudo apt install ffmpeg

🐳 Docker

Running FFmate with Docker? FFmpeg is already included in the image, so there’s nothing else to install. Just run and go 🚀

💡 If FFmpeg is installed in a non-standard location, you can tell FFmate where to find it using the --ffmpeg flag. Learn more 👉 Flags Reference

Downloading & Installing FFmate

FFmate is available for Windows, macOS, and Linux, with multiple installation options:

 macOS via Homebrew

Install FFmate easily using Homebrew:

bash

brew install ffmate

To update FFmate installed via Homebrew, run the following command:

bash

brew update
brew upgrade ffmate

🖥️ Windows (Manual Download)

 macOS (Manual Download)

🐧 Linux (Manual Download)

🐳 Docker

Run FFmate via Docker

Running FFmate

You can run FFmate in one of two ways: natively on Windows, macOS, or Linux, or via a Docker container. Whichever best fits your environment

Windows

After downloading FFmate, open your terminal, navigate to the folder where you saved it, and start the server with:

cmd

ffmate server

macOS & Linux

After downloading FFmate, open your terminal, navigate to the folder where you saved it, and start the server with:

ffmate server

By default, FFmate runs on port 3000 and can be opened at http://localhost:3000. Once it's ready, FFmate prints:

info ffmate version 2.1.0
info connecting to database
info ffmpeg binary found at '/usr/local/bin/ffmpeg'
info server started on port '3000' using driver 'sqlite3'

If port 3000 is already in use, FFmate stops with failed to start ffmate server: … address already in use. Start it on a different port with --port, for example ffmate server --port 8080.

FFmate is reachable from your network by default

FFmate listens on all network interfaces (0.0.0.0), not only localhost, and does not require a password. Anyone who can reach port 3000 on your machine can run commands on it through pre/post-processing scripts.

Only using FFmate on this machine? Start it with ffmate server --host 127.0.0.1.
Other machines need access? Start it with --basic-auth "username:password", and only allow those machines through your firewall.
Never expose FFmate directly to the internet.

See --host and --basic-auth for details.

NOTE

FFmate requires FFmpeg to be installed on Windows, macOS, or Linux. Make sure FFmpeg is available in your system’s PATH before launching FFmate. If FFmpeg is installed in a custom location, use the --ffmpeg flag to specify its path. Learn more

Running FFmate with Docker

FFmate is also available as a Docker image hosted on GitHub Container Registry, for amd64 and arm64. The Docker image comes with jellyfin-ffmpeg, an FFmpeg build with extra codecs, and ffprobe. It also includes bash, jq and curl for pre/post-processing scripts.

You can pull and run FFmate using Docker with a single command:

docker run -it --rm \
  -p 3000:3000 \
  ghcr.io/welovemedia/ffmate:latest

This will start FFmate and expose the web interface at http://localhost:3000

Anyone who can reach the port can run commands in the container

-p 3000:3000 publishes FFmate on every network interface of your Docker host, without a password. Since tasks can run pre/post-processing scripts, anyone who can reach the port can run commands inside the container, which runs as root by default.

Keep it local. Publish the port on the Docker host's localhost only:

docker run -it --rm -p 127.0.0.1:3000:3000 ghcr.io/welovemedia/ffmate:latest

Or enable basic auth. The image has no environment variable for it, so override the start command:

docker run -it --rm \
  -p 3000:3000 \
  -v $(pwd)/ffmate-data:/app/db \
  ghcr.io/welovemedia/ffmate:latest \
  /app/ffmate server --database=/app/db/sqlite.db --basic-auth "admin:a-long-random-password"

Run as a non-root user with --user 1000:1000 (or user: in Docker Compose). The image creates /app/db as root, so a non-root user can't write the database there. Mount a folder that user can write to:

docker run -it --rm --user 1000:1000 \
  -p 127.0.0.1:3000:3000 \
  -v $(pwd)/ffmate-data:/app/db \
  ghcr.io/welovemedia/ffmate:latest

NOTE

By default, data won't persist after the container stops. To preserve your database, map a local folder to **/app/db**. Example: **-v $(pwd)/ffmate-data:/app/db**.

Optional Environment Variables

The Docker image supports these environment variables:

Variable	Description	Default
`PORT`	The port FFmate listens on inside the container. When changing it, change the `-p` mapping too.	`3000`
`DATABASE`	Path to the SQLite database, or a `postgresql://` URI for clustering.	`/app/db/sqlite.db`
`MAX_CONCURRENT_TASKS`	Maximum number of FFmpeg tasks running at the same time.	`3`
`IDENTIFIER`	Name of this FFmate instance, shown in the Web UI and used in a cluster.	Container hostname
`DEBUGO`	Which log messages FFmate prints, e.g. `debug:?` for debug output or `*` for everything. See Debugging.	`info:?,warn:?,error:?`

Other flags, such as --host, --labels or --basic-auth, have no environment variable. To use them, override the start command as shown in the basic auth example above.

Example:

Run FFmate with debug logging and up to 5 tasks at the same time:

docker run -it --rm \
  -p 3000:3000 \
  -v $(pwd)/ffmate-data:/app/db \
  -e DEBUGO="debug:?" \
  -e MAX_CONCURRENT_TASKS=5 \
  ghcr.io/welovemedia/ffmate:latest

Docker Compose

Prefer using Docker Compose? Here's a ready-to-use docker-compose.yml to get FFmate up and running quickly:

yaml

services:
  ffmate:
    image: ghcr.io/welovemedia/ffmate:latest
    ports:
      - "127.0.0.1:3000:3000"
    volumes:
      - ./ffmate-data:/app/db
    environment:
      - PORT=3000
      - DATABASE=/app/db/sqlite.db
      - MAX_CONCURRENT_TASKS=3
      - IDENTIFIER=ffmate-docker

Start FFmate using your docker-compose.yml file:

docker compose up -d

Submitting your first task

To submit a new transcoding task, make a POST request to the API:

curl -X POST http://localhost:3000/api/v1/tasks \
     -H "Content-Type: application/json" \
     -d '{
       "command": "-y -i ${INPUT_FILE} -c:v libx264 -preset fast -crf 23 ${OUTPUT_FILE}",
       "inputFile": "videos/input.mp4",
       "outputFile": "videos/output.mp4",
       "priority": 2
     }'

Monitoring the Task

Check the status of your task by making a GET request:

curl -X GET http://localhost:3000/api/v1/tasks/{taskId}

Replace {taskId} with the actual ID returned when submitting the task.

You can track the status and progress of your FFmate tasks directly in the Web UI. 👉 Learn more

Watchfolders

FFmate can automatically detect and process new files in a watchfolder.

To configure a watchfolder, make a POST request to the API:

curl -X POST http://localhost:3000/api/v1/watchfolders \
     -H "Content-Type: application/json" \
     -d '{
       "name": "My Watchfolder",
       "description": "Automatically processes new media files",
       "interval": 5,
       "growthChecks": 3,
       "preset": "preset-id",
       "path": "/path/to/watchfolder",
       "filter": {
         "extensions": {
           "include": ["mp4", "mov"],
           "exclude": ["tmp", "log"]
         }
       }
     }'

Once configured, any new file matching the criteria will be automatically processed when added to the watchfolder.

Are you more in the mood to configure your watchfolder in a more visual way? No problem! Learn how to configure your first watchfolder using our Web UI 👉 Check it out

Real-Time updates with Webhook notifications

FFmate can notify external systems about task progress, completion, or failure using webhooks.

To configure a webhook, make a POST request to the API:

curl -X POST http://localhost:3000/api/v1/webhooks \
     -H "Content-Type: application/json" \
     -d '{
       "event": "task.created",
       "url": "https://myserver.com/ffmate/webhook.create"
     }'

FFmate will send a POST request to the specified URL when the event occurs.

FFmate supports webhook notifications for tasks, batches, presets, watchfolders. You can react to new events, keep external systems in sync, or trigger automations in real time. Learn how to make the most of FFmate’s webhooks 👉 Learn more

Updating FFmate

Keeping FFmate up to date ensures you have the latest features, bug fixes, and performance improvements.

Update FFmate via CLI

To update FFmate to the latest version, run the following command in your terminal:

ffmate update

This command will check for the latest release and install the update automatically.

Verify the Installed Version

After updating, confirm which version is installed:

ffmate version

FFmate prints the version, for example:

version: 2.0.18

🚀 Getting Started ​

Installing FFmpeg ​

 macOS ​

Installing FFmpeg via Homebrew ​

Download and run the static build ​

🖥️ Windows ​

Install via Windows Package Manager (winget) ​

Download and run the static build ​

🐧 Linux ​

🐳 Docker ​

Downloading & Installing FFmate ​

 macOS via Homebrew ​

🖥️ Windows (Manual Download) ​

 macOS (Manual Download) ​

🐧 Linux (Manual Download) ​

🐳 Docker ​

Running FFmate ​

Windows ​

macOS & Linux ​

Running FFmate with Docker ​

Optional Environment Variables ​

Example: ​

Docker Compose ​

Submitting your first task ​

Monitoring the Task ​

Watchfolders ​

Real-Time updates with Webhook notifications ​

Updating FFmate ​

Update FFmate via CLI ​

Verify the Installed Version ​

🚀 Getting Started

Installing FFmpeg

 macOS

Installing FFmpeg via Homebrew

Download and run the static build

🖥️ Windows

Install via Windows Package Manager (winget)

Download and run the static build

🐧 Linux

🐳 Docker

Downloading & Installing FFmate

 macOS via Homebrew

🖥️ Windows (Manual Download)

 macOS (Manual Download)

🐧 Linux (Manual Download)

🐳 Docker

Running FFmate

Windows

macOS & Linux

Running FFmate with Docker

Optional Environment Variables

Example:

Docker Compose

Submitting your first task

Monitoring the Task

Watchfolders

Real-Time updates with Webhook notifications

Updating FFmate

Update FFmate via CLI

Verify the Installed Version