FFmate documentation

Appearance

FFmate Release Notes ​

An overview of new features, enhancements, and bug fixes for each version.

Version 2.1.0 ​

Breaking Changes ​

  • Tray Icon Removed The experimental system tray icon and its --tray flag have been removed. Starting FFmate with --tray now fails with an unknown flag error, so remove the flag from your scripts and services before upgrading.

New Features ​

  • Choose the Network Address The new --host flag sets the network address FFmate listens on. The default stays 0.0.0.0. Use --host 127.0.0.1 to keep FFmate on the local machine. For details, see --host.

  • Basic Authentication The new --basic-auth flag protects the API, the Web UI and all other endpoints with a username and password. For details, see --basic-auth.

  • Labels FFmate instances, tasks, presets and watchfolders can now have labels. An FFmate instance only processes tasks and watchfolders whose labels match its own. For details, see --labels and Clustering.

  • Automatic Retries Tasks and presets have a new retries property. FFmate puts a failed task back into the queue up to that many times. For details, see Task Properties.

  • Interrupted Tasks If an FFmate instance crashes or is stopped while tasks are running, those tasks no longer stay RUNNING forever. They are set to DONE_ERROR when the FFmate instance starts again, or in a cluster by the other FFmate instances after about 60 seconds. For details, see Clustering.

  • Labels and Task Limit per FFmate InstanceGET /api/v1/clients now shows the labels and the maxConcurrentTasks limit of every FFmate instance, so it's easy to see which FFmate instance takes which tasks. For details, see Client Endpoint.

  • Install Development Buildsffmate update --dev updates FFmate to the latest development build, so new features can be tested before they are released. Development builds aren't meant for production. For details, see Update Command.

Changes ​

  • Docker Image The Docker image now ships jellyfin-ffmpeg for more codecs, and it can run as a non-root user. For details, see Running FFmate with Docker.

  • Startup Messages FFmate now logs each startup step, which helps when the database connection is slow.

Bug Fixes ​

  • Canceling During Pre- and Post-Processing A task canceled while its pre- or post-processing script runs now stays canceled. Before, the task ended as DONE_SUCCESSFUL, and a task canceled during pre-processing still ran FFmpeg.

  • Output Wildcards${OUTPUT_FILE_BASE} and ${OUTPUT_FILE_DIR} now resolve the output file instead of the input file, and ${OUTPUT_FILE_EXTENSION} no longer leaves a stray }. For details, see Wildcards.

  • Task Status FilterGET /api/v1/tasks?status=… now filters the list by status. For details, see Monitoring All Tasks.

  • PostgreSQL Connection A PostgreSQL URI with a port, e.g. postgresql://user:pass@db:5433/ffmate, now connects. Before, FFmate stopped on startup with a hostname resolving error. Several options in one URI, e.g. ?sslmode=require&connect_timeout=10, now work too.

  • Telemetry Errors FFmate no longer crashes if sending telemetry fails.

Version 2.0.18 (20-02-2026) ​

Bug Fixes ​

  • PostgreSQL Options Options at the end of the PostgreSQL URI now work. Before, FFmate put an extra ? in front of them, so the database didn't receive them. This matters for example when connecting to a PostgreSQL server without SSL, such as a local Docker container: postgresql://user:pass@localhost/ffmate?sslmode=disable.

Version 2.0.15 (07-10-2025) ​

Bug Fixes ​

  • Preset Scripts Tasks created from a preset now get the preset's pre- and post-processing scripts.

Version 2.0.14 (01-10-2025) ​

Bug Fixes ​

  • Web UI on Windows The Web UI now loads on Windows.

  • PostgreSQL URI FFmate no longer treats a postgresql:// URI as a file path when it prepares the database folder.

Version 2.0.10 (01-10-2025) ​

Bug Fixes ​

  • Database Folder FFmate now creates the folder for the SQLite database on startup if it doesn't exist.

Version 2.0.7 (27-09-2025) ​

Changes ​

  • Telemetry Telemetry now includes the cluster and session IDs.

Bug Fixes ​

  • Watchfolders in the Web UI The Web UI now uses the renamed /watchfolders endpoint.

Version 2.0.2 (26-09-2025) ​

Changes ​

  • Clear Error When the Server Can't Start If FFmate can't start its server, for example because another program already uses port 3000, it now logs failed to start ffmate server with the reason and exits. Before, it kept running without the API and Web UI. To use another port, start FFmate with --port.

Version 2.0.1 (26-09-2025) ​

Breaking Changes ​

  • Endpoint Names The endpoints are now consistently plural: /api/v1/watchfolders and /api/v1/batches. The singular /api/v1/watchfolder and /api/v1/batch from 2.0.0 have been removed.

Version 2.0 (26-09-2025) ​

FFmate 2.0 is a complete rewrite of the project, powered by the amazing Goyave framework. This new version delivers a more structured, maintainable, and efficient codebase, paving the way for community members to get involved and shape FFmate’s future. While we’ve aimed to remain mostly backward-compatible with 1.x, some adjustments to existing setups may be necessary.

Breaking Changes ​

  • Task Batch The endpoint has changed from /api/v1/tasks/batch to /api/v1/batches. For details, see Batch Task.

  • Task Batch Format The batch object format has been updated: it is now an object containing a tasks array instead of being an array itself. This change allows for future enhancements to the Batch feature. For details, see Batch Task.

  • Log Level The --loglevel (-l) argument has been removed in favor of Debugo. Use --debug instead. For details, see Debugging.

  • Short Command-Line Arguments The short versions of command-line arguments, e.g. -p for --port or -b for --database, have been removed. Only -d for --debug remains. Switch to the long versions. This change was made due to the growing number of arguments, which makes it difficult to avoid conflicts with single-letter flags. For details, see CLI.

New Features ​

  • Cluster Mode FFmate can now run in cluster mode with multiple instances sharing the same Postgres database. For details, see Clustering.

  • Clients Endpoint Added an endpoint to list all FFmate instances connected to the cluster. For details, see Listing Cluster Clients.

  • Identifier Argument Added a new CLI argument to set the name for each FFmate instance, making it easier to recognize. For details, see --identifier.

  • Health Endpoint Added a new /health endpoint that orchestration tools like Kubernetes can use to monitor the health of an FFmate instance. For details, see Health Endpoint.

  • Extended Metrics Added new gauges for webhooks and websocket. For details, see Metrics.

  • Direct Webhooks Added support for fine-grained webhooks in tasks and presets. For details, see Global and Direct Webhooks.

  • Webhook Logs & Retries Webhook executions are now persistently stored in the database, and failed deliveries are retried automatically. For details, see Webhook Logs and Webhook Retries.

  • Watchfolder Lock Watchfolders now create .lock files for processed items. These prevent files from being reprocessed after restarts. For details, see Watchfolder Lock.

  • UI Refresh The UI has been modernized as a first step toward a more polished and consistent experience, with more improvements planned. Images in this documentation are temporarily outdated and will be updated once the full UI redesign is complete.

Improvements ​

  • Test Coverage Test coverage has been expanded to cover all major core components of the codebase.

Bug Fixes ​

  • Race Conditions Multiple race conditions have been resolved in watchfolders, tasks, and config handling.

Changes ​

  • FFmpeg Detection In version 2.0, FFmpeg detection stops once FFmpeg has been found, saving resources. If FFmpeg isn't found at startup, FFmate checks again every 10 seconds.

Version 1.2.0 (08-09-2025) ​

New Features ​

  • ${FFMPEG} Wildcard Added a wildcard that resolves to the configured FFmpeg binary path. For details, see the wildcards.

  • FFmpeg Command Chaining with && You can now chain multiple FFmpeg commands in a single task using &&. For details, see the task properties.

  • Task Metadata Wildcard Added ${METADATA_<json-path>} to resolve values from the task’s metadata object across commands, inputs, outputs, and scripts. For details, see the wildcards.

  • Watchfolder Metadata Tasks created by watchfolders now include file information under metadata.ffmate.watchfolder (fields include path, relativeDir, relativePath, and the watchfolder uuid). For details, see the watchfolder.

  • Sidecar Re-Import in Pre-Processing Added the option to re-import the task’s sidecar after the pre-processing script finishes. For details, see the Pre-Post Processing.

  • Webhooks API: Get & Update Added new REST endpoints to retrieve a single webhook and to update an existing webhook. For details, see the webhooks.

  • Webhooks in the Web UI The web UI now supports creating, viewing, and updating webhooks. For details, see the webui.

Changes ​

  • Progress Output Throttling FFmate now adds -stats_period 1 to every FFmpeg command, limiting progress output to one update per second. For details, see the task.

  • Docker Image Tools The Docker image now includes bash and jq.

  • Docker Environment Variable Rename In the Dockerfile, the DB environment variable has been replaced with DATABASE.

  • Go Runtime Update Updated Go to version 1.25.0.

Version 1.1.0 (14-07-2025) ​

New Features ​

  • Automatic Output Folder Creation FFmate now creates output directories automatically if they do not exist.

  • FFmpeg Detection FFmate checks for FFmpeg in the system’s default PATH or the location specified by the --ffmpeg flag, and logs a warning in both the web UI and logs if it’s not found.

Changes ​

  • Docker Debug Mode Disabled by Default The Docker image now ships with debugging turned off by default.

  • Removed AI Endpoint and flag The /ai endpoint and the --ai flag introduced in v1.0.8 have been removed in favor of a future database-driven configuration setting.

Bug Fixes ​

  • Script Error Logging FFmate now logs stderr output when a pre- or post-process script exits with a non-zero code.

Version 1.0.8 (29-05-2025) ​

New Features ​

  • Windows Support FFmate is now fully compatible with Windows. A dedicated installer is available for download — get it here.

  • New API Endpoint: /client Introduced a new endpoint that returns detailed information about the client environment, including system architecture, operating system, and FFmate version.

  • FFmate AI (Preview) Initial support for the upcoming FFmate AI assistant is now available. This release includes:

    • A new --ai flag to enable AI-related features
    • A new /ai REST endpoint to retrieve model-related information

  • Suspend Watchfolder Scanning A suspended flag has been added to enable temporary pausing of active watchfolders without removing or modifying their configuration.

Improvements ​

  • Automatic Update Checks FFmate now performs periodic checks for new releases. When an update is available, a notification appears in the web UI or is printed to the console in headless mode.

Bug Fixes ​

  • Reduced CPU Usage in Queue Processing Resolved an issue where the task update loop executed too frequently, resulting in high CPU usage.