Wildcards

Wildcards in FFmate act as placeholders that are automatically replaced with actual values when a FFmate task runs.

You can use wildcards in:

Tasks: inputFile, outputFile, and command
Pre- and post-processing script, and sidecard

Input and Output File Information

Full File Path:

These wildcards return the complete file path, including the directory, filename, and extension.

Wildcard	Description	Example Output
`${INPUT_FILE}`	Full path of the input file	`/source/input.mp4`
`${OUTPUT_FILE}`	Full path of the output file	`/destination/output.mp4`

Example:

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": "/volumes/ffmate/source/input.mp4",
       "outputFile": "/volumes/ffmate/destination/output.mp4"
     }'

Filename Information:

These wildcards return the filename from the full path, either with or without the extension.

Wildcard	Description	Example Output
`${INPUT_FILE_BASE}`	Filename with extension (without the path)	`input.mp4`
`${OUTPUT_FILE_BASE}`	Filename with extension (without the path)	`output.mp4`
`${INPUT_FILE_BASENAME}`	Filename without extension	`input`
`${OUTPUT_FILE_BASENAME}`	Filename without extension	`output`

Example:

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}.mkv",
       "inputFile": "/volumes/ffmate/videos/original_movie.mp4",
       "outputFile": "/volumes/ffmate/converted/${INPUT_FILE_BASENAME}"
     }'

Output Path:

/volumes/ffmate/converted/input.mkv

File Extensions and Directory Path:

These wildcards return the file extension and the directory path.

Wildcard	Description	Example Output
`${INPUT_FILE_EXTENSION}`	File extension of the input file	`.mp4`
`${OUTPUT_FILE_EXTENSION}`	File extension of the output file	`.mp4`
`${INPUT_FILE_DIR}`	Directory path of the input file	`/source`
`${OUTPUT_FILE_DIR}`	Directory path of the output file	`/destination`

Example:

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": "/volumes/ffmate/source/video.mp4",
       "outputFile": "/volumes/ffmate/destination/${INPUT_FILE_BASENAME}_converted${INPUT_FILE_EXTENSION}"
     }'

Output Path:

/volumes/ffmate/destination/input_converted.mp4

Date & Time

These wildcards return the current date and time values when the task runs.

Wildcard	Description	Example Output
`${DATE_YEAR}`	Full year (4 digits)	`2024`
`${DATE_SHORTYEAR}`	Short year (last 2 digits)	`24`
`${DATE_MONTH}`	Month number (01-12)	`01`
`${DATE_DAY}`	Day of the month (01-31)	`15`
`${DATE_WEEK}`	Week number (01-52)	`03`
`${TIME_HOUR}`	Hour (24-hour format, 00-23)	`14`
`${TIME_MINUTE}`	Minute (00-59)	`05`
`${TIME_SECOND}`	Second (00-59)	`32`

Example:

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": "/volumes/ffmate/source/video.mp4",
       "outputFile": "/volumes/ffmate/destination/${DATE_YEAR}/${DATE_MONTH}/${DATE_DAY}/video_${TIME_HOUR}-${TIME_MINUTE}-${TIME_SECOND}.mp4",
       "priority": 2
     }'

Output Path:

/volumes/ffmate/destination/2024/02/15/video_14-30-45.mp4

Timestamps

These wildcards return Unix timestamps based on the current system time.

Wildcard	Description	Example Output
`${TIMESTAMP_SECONDS}`	Unix timestamp in seconds	`1705318712`
`${TIMESTAMP_MILLISECONDS}`	Unix timestamp with milliseconds precision	`1705318712123`
`${TIMESTAMP_MICROSECONDS}`	Unix timestamp with microseconds precision	`1705318712123456`
`${TIMESTAMP_NANOSECONDS}`	Unix timestamp with nanoseconds precision	`1705318712123456789`

Example:

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": "/volumes/ffmate/source/video.mp4",
       "outputFile": "/volumes/ffmate/destination/video_${TIMESTAMP_SECONDS}.mp4"
     }'

Output Path:

/volumes/ffmate/destination/video_1705318712.mp4

Task Metadata

This wildcard lets you insert values from the task’s metadata object. This works in any field where wildcards are supported, including task input and output paths, as well as pre- and post-processing actions.

You can reference any key that was:

Provided during task creation via the metadata object, or
Automatically populated by FFmate (for example, when a task is triggered by a watchfolder).

Wildcard Pattern	Description
`${METADATA_<json-path>}`	Inserts the value from the `metadata` object at the given JSON path

Example: Recreating Watchfolder Structure

When a task is created from a watchfolder, FFmate automatically adds watchfolder file metadata about the file that triggered the task.

This includes fields like relativeDir, which you can use to recreate the original folder structure in your output.

Here’s an example metadata object for a file dropped into /volumes/ffmate/wf/parent/subfolder1/18moo.mov:

json

"metadata": {
  "ffmate": {
    "watchfolder": {
      "path": "/volumes/ffmate/wf",
      "relativeDir": "parent/subfolder1",
      "relativePath": "parent/subfolder1/18moo.mov",
      "uuid": "06bbbe21-8003-41b3-94f4-62508486c482"
    }
  }
}

With ${METADATA_}, you can reference relativeDir and automatically recreate the same folder structure from the watchfolder in your output.

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": "/volumes/ffmate/wf/parent/subfolder1/18moo.mov",
    "outputFile": "/volumes/ffmate/processed/${METADATA_ffmate.watchfolder.relativeDir}/${INPUT_FILE_BASENAME}.mp4"
  }
'

Output Path:

/volumes/ffmate/processed/parent/subfolder1/18moo.mp4

Task Source

This wildcard returns the source of the task: either api or watchfolder.

Wildcard	Description	Example Output
`${SOURCE}`	Returns the source that triggered the task (either API or watchfolder)	`api` or `watchfolder`

Example

Use ${SOURCE} in a Bash script to apply different behavior depending on the task’s origin.

bash

#!/usr/bin/env bash

# Pre-processing script example
# Adjusts logic based on the source of the task

case "$SOURCE" in
  api)
    echo "Task originated from API. Applying API-specific logic."
    # Add API-specific pre-processing commands here
    ;;
  watchfolder)
    echo "Task originated from Watchfolder. Applying Watchfolder-specific logic."
    # Add Watchfolder-specific pre-processing commands here
    ;;
  *)
    echo "Unknown task source. Applying default logic."
    # Add fallback logic here
    ;;
esac

FFmpeg Path

This wildcard returns the full, resolved path to the FFmpeg executable as configured in FFmate (see command-line flags). It is particularly useful for advanced workflows that require chaining multiple ffmpeg calls within a single command, such as two-pass encoding.

Wildcard	Description	Example Output
`${FFMPEG}`	Returns the full path to the FFmpeg executable	`/usr/bin/ffmpeg`

Example: Two-Pass VP9 Encoding

curl -X POST http://localhost:3000/api/v1/tasks \
     -H "Content-Type: application/json" \
     -d '{
       "command": "-i ${INPUT_FILE} -c:v libvpx-vp9 -b:v 2M -pass 1 -an -f null - && ${FFMPEG} -i ${INPUT_FILE} -c:v libvpx-vp9 -b:v 2M -pass 2 -c:a libopus ${OUTPUT_FILE}",
       "inputFile": "/volumes/ffmate/source/video.mp4",
       "outputFile": "/volumes/ffmate/destination/video.webm"
     }'

This command performs a two-pass VP9 encode. FFmate automatically prepends the configured ffmpeg path to the beginning of the command for the first pass. When chaining commands with &&, you must explicitly use the ${FFMPEG} wildcard for any subsequent ffmpeg calls to ensure the correct executable is used in each chained command.

Unique Identifier

This wildcard generates random unique identifiers.

Wildcard	Description	Example Output
`${UUID}`	Randomly generated UUID (v4)	`550e8400-e29b-41d4-a716-446655440000`

Example:

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": "/volumes/ffmate/source/video.mp4",
       "outputFile": "/volumes/ffmate/processed/${UUID}_video.mp4"
     }'

Output Path:

/volumes/ffmate/processed/550e8400-e29b-41d4-a716-446655440000_video.mp4

System Information

These wildcards return the operating system name and CPU architecture.

Wildcard	Description	Example Output
`${OS_NAME}`	Operating system name	`linux`
`${OS_ARCH}`	CPU architecture	`amd64`

Example:

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": "/volumes/ffmate/source/video.mp4",
       "outputFile": "/volumes/ffmate/processed/${OS_NAME}/${OS_ARCH}/video.mp4"
     }'

Output Path:

/volumes/ffmate/processed/linux/amd64/video.mp4

Wildcards ​

Input and Output File Information ​

Full File Path: ​

Example: ​

Filename Information: ​

Example: ​

Output Path: ​

File Extensions and Directory Path: ​

Example: ​

Output Path: ​

Date & Time ​

Example: ​

Output Path: ​

Timestamps ​

Example: ​

Output Path: ​

Task Metadata ​

Example: Recreating Watchfolder Structure ​

Output Path: ​

Task Source ​

Example ​

FFmpeg Path ​

Example: Two-Pass VP9 Encoding ​

Unique Identifier ​

Example: ​

Output Path: ​

System Information ​

Example: ​

Output Path: ​

Wildcards

Input and Output File Information

Full File Path:

Example:

Filename Information:

Example:

Output Path:

File Extensions and Directory Path:

Example:

Output Path:

Date & Time

Example:

Output Path:

Timestamps

Example:

Output Path:

Task Metadata

Example: Recreating Watchfolder Structure

Output Path:

Task Source

Example

FFmpeg Path

Example: Two-Pass VP9 Encoding

Unique Identifier

Example:

Output Path:

System Information

Example:

Output Path: