FFmate FAQ
Getting Started
What is FFmate?
FFmate is an automation layer built on top of FFmpeg to simplify media transcoding workflows.
Learn more → What is FFmate?
What platforms does FFmate support?
FFmate runs on Windows, macOS, Linux, and Docker.
Learn more → Downloading & Installing FFmate
How do I install FFmate on macOS?
The quickest path is Homebrew:
brew install ffmateLearn more → Downloading & Installing FFmate
Does FFmate need FFmpeg to be installed?
Yes. FFmate runs every task with FFmpeg. By default, it looks for ffmpeg in the system PATH. If FFmpeg isn't found, FFmate still starts, but tasks stay QUEUED. FFmate checks again every 10 seconds and starts processing as soon as FFmpeg is available.
The Docker image already includes FFmpeg.
Learn more → Installing FFmpeg
What port does FFmate run on, and how do I change it?
FFmate’s API & Web UI listen on port 3000 by default. Add --port <number> when you start the server, e.g. ffmate server --port 8080. In Docker, set the PORT environment variable and change the -p port mapping to match.
Learn more → Server Command Flags
How do I point FFmate to a custom FFmpeg binary?
Use --ffmpeg "/full/path/to/ffmpeg" when launching ffmate server. FFmate will call that binary for every task.
Learn more → Server Command Flags
How do I stop FFmate from opening the Web UI on startup?
Start the server with --no-ui. The Web UI is still available at http://localhost:3000/ui; FFmate just doesn't open it in the browser. In Docker, FFmate never opens a browser.
Learn more → Server Command Flags
Where does FFmate store its data?
In a SQLite database. By default it's created at:
- Windows:
%APPDATA%\ffmate\db.sql - macOS/Linux:
~/.ffmate/db.sqlite - Docker:
/app/db/sqlite.db
Use --database to choose another file, or a postgresql:// URI to run several FFmate instances as a cluster.
Learn more → Server Command Flags
Security
Is it safe to make FFmate reachable from the network?
Only with protection. By default, FFmate listens on all network interfaces (0.0.0.0) and has no password. Anyone who can reach its port can create tasks and presets, and their pre- and post-processing scripts can run any command on the computer FFmate runs on.
- To keep FFmate on the local machine, start it with
--host 127.0.0.1. - To share it on a network, start it with
--basic-authand limit access with a firewall. - Run FFmate as a user without admin or
rootrights.
Learn more → Server Command Flags
How do I protect FFmate with a username and password?
Start the server with --basic-auth, e.g. ffmate server --basic-auth="admin:secret". Every request then needs the username and password: the API, the Web UI, the Swagger UI, /health and /metrics. The browser asks for them when opening the Web UI.
Learn more → Server Command Flags
Tasks
How do I create a transcoding task via the API?
Send a POST to /api/v1/tasks with at least a name, plus a command or a preset. Example:
curl -X POST http://localhost:3000/api/v1/tasks \
-H "Content-Type: application/json" \
-d '{
"name": "Convert input.mp4",
"command": "-y -i ${INPUT_FILE} -c:v libx264 -crf 23 ${OUTPUT_FILE}",
"inputFile": "/videos/input.mp4",
"outputFile": "/videos/output.mp4",
"priority": 50
}'FFmate queues the task, returns it with its uuid, and fires a task.created webhook.
Learn more → Creating a Task
How can I monitor the status of a task?
GET /api/v1/tasks/{uuid} returns a JSON payload including status, progress, and timestamps. You can also check the Web UI’s Tasks tab for live updates.
Learn more → Monitoring a Task
Why does my task stay in QUEUED?
The most common reasons:
- FFmate can't find FFmpeg. Check the startup log, and set the path with
--ffmpegif needed. - FFmate is already running as many tasks as
--max-concurrent-tasksallows. The task starts when one of them finishes. - The task has labels, but no FFmate instance has a matching label.
Learn more → Tasks
How do I cancel a running task?
PATCH /api/v1/tasks/{uuid}/cancel marks a queued or running task DONE_CANCELED right away. A running FFmpeg command is stopped. The Web UI offers a one‑click “Cancel” button too.
Learn more → Canceling a Task
How do I restart a failed task?
PATCH /api/v1/tasks/{uuid}/restart resets the task to QUEUED, clears its error, progress and retry count, and puts it back in the processing queue.
Learn more → Restarting a Task
Can FFmate retry failed tasks automatically?
Yes. Set retries on the task or its preset, e.g. "retries": 2. If the task fails, FFmate puts it back into QUEUED after 3 seconds, up to that many times. Canceled tasks are not retried.
Learn more → Task Properties
What happens to running tasks when FFmate stops or crashes?
When FFmate starts again, it sets the tasks it was running to DONE_ERROR with the error client disconnected during execution. In a cluster, the other FFmate instances do this after about 60 seconds. Restart those tasks to run them again.
Learn more → Clustering
How do I submit a batch of tasks?
POST to /api/v1/batches with the tasks in a tasks array: {"tasks": [ … ]}. FFmate assigns a shared batch ID so you can track them as a group while each task still runs independently.
Learn more → Submitting Multiple Tasks as a Batch
Can one task run several FFmpeg commands, e.g. for two-pass encoding?
Yes. Chain the commands with && and start every command after an && with the ${FFMPEG} wildcard:
-y -i ${INPUT_FILE} -c:v libx264 -b:v 2M -pass 1 -f null /dev/null && ${FFMPEG} -y -i ${INPUT_FILE} -c:v libx264 -b:v 2M -pass 2 ${OUTPUT_FILE}Learn more → Task Properties
Why don't pipes or redirects work in my command or script?
FFmate runs commands and scripts directly, not through a shell. Shell features such as pipes (|), redirects (>) or $VARIABLES don't work. To use them, put them inside a script and call that script.
Learn more → Pre and Post Processing
How do I run tasks only on certain FFmate instances, e.g. ones with a GPU?
Give those FFmate instances a label with --labels, e.g. ffmate server --labels="gpu", and add the same label to the tasks or presets: "labels": ["gpu"]. Tasks with labels only run on FFmate instances with a matching label. Tasks without labels run on any FFmate instance.
Learn more → Server Command Flags
Presets, Wildcards and Scripts
How do I use presets to simplify recurring tasks?
Create a preset (Web UI or /api/v1/presets) once, then reference its UUID in future tasks or watchfolders using "preset": "<uuid>". The command and settings are then managed in one place.
Learn more → Presets
How can I use wildcards to include timestamps in output file names?
Embed placeholders like ${TIMESTAMP_SECONDS} inside your outputFile or preset path. FFmate expands them at runtime so clip_${TIMESTAMP_SECONDS}.mp4 becomes clip_1717065600.mp4.
Learn more → Wildcards
How do I run a custom script before or after transcoding?
Add a preProcessing or postProcessing when creating a task or preset:
"preProcessing": { "scriptPath": "/scripts/prepare.sh" },
"postProcessing": { "scriptPath": "/scripts/cleanup.sh" }FFmate runs the script before or after FFmpeg. Add a sidecarPath to have FFmate write a JSON file with all task details that the script can read.
Learn more → Pre and Post Processing
Watchfolders
How do I create a watchfolder that processes only .mov files?
POST to /api/v1/watchfolders with a filter:
"filter": { "extensions": { "include": ["mov"] } }Learn more → Creating a Watchfolder
How does FFmate ensure a file is fully copied before processing?
Each detected file passes through growth checks: FFmate compares the file size across growthChecks successive scans. Only when the size remains constant does the task start. This way, FFmate never starts a task on a half-copied file.
Learn more → How Watchfolders Work
Why wasn't a file in my watchfolder picked up?
Check these:
- A
.lockfile with the same name exists next to it, so FFmate has already processed it. - The file name starts with
.. Hidden files are skipped. - The file's extension doesn't pass the watchfolder's
filter. - The file is still growing, or the
growthChecksscans haven't finished yet. - The watchfolder is
suspended. - The watchfolder has
labels, and no FFmate instance has a matching label.
Learn more → Watchfolders
How do I process a file from a watchfolder again?
Delete its .lock file, e.g. movie.mp4.lock. At the next scan, FFmate treats the file as new and creates a task for it.
Learn more → How Watchfolders Work
Server, Monitoring and Debugging
How do I run FFmate on a different port with five concurrent tasks?
ffmate server --port 8080 --max-concurrent-tasks 5Learn more → Server Command Flags
How do I enable detailed debug logs for the task queue?
Start the FFmate server with --debug="debug:task". To change the logs while FFmate is running, send PATCH /api/v1/debug/debug:task.
Learn more → Debugging
How do I check that FFmate is running, e.g. from Kubernetes or a load balancer?
Use GET /health. It returns 200 with {"status":"ok"} once FFmate is ready, and 500 otherwise. For Prometheus, FFmate also provides counters at GET /metrics.
Learn more → Health Endpoint
How do I see whether my webhooks were delivered?
GET /api/v1/webhooks/executions lists every webhook delivery, newest first, with the request FFmate sent and the response your server returned.
Learn more → Webhook logs
Does FFmate send telemetry?
Yes, by default FFmate sends anonymous usage data, such as its version, operating system, settings and task counts. Turn it off with --send-telemetry=false.
Learn more → Server Command Flags
Where can I view API docs for FFmate?
Start FFmate and open /swagger in your browser (e.g., http://localhost:3000/swagger/index.html) to access the OpenAPI UI.
Learn more → Swagger
How do I update FFmate to the latest version?
Run ffmate update for native installs. Homebrew users can run brew upgrade ffmate. For Docker, pull the newest image and restart the container, e.g. docker compose pull && docker compose up -d.
Learn more → Updating FFmate
Where can I get help or report bugs?
Join the Discord community, file issues on GitHub, or reach out via the support links in the docs’ Community & Support page. Feedback on docs is welcome—every page has an “Edit this page” link!
Learn more → Community & Support