Smart Tags

Smart tags substitute media metadata into job parameters. They are resolved by Job Service when a pipeline becomes a concrete job sequence.

Use a placeholder in a string parameter to insert a metadata value:

file:///library/{{series}}/S{{season}}E{{episode}} - {{title}}.mkv

For tags series:Example, season:2, episode:7, and title Arrival, the path becomes:

file:///library/Example/S2E7 - Arrival.mkv

Available tags

MediaMoth derives these tags from MediaInfo when their source values are present:

Tag	Source
title	media title
year	release year
res_width	video width
res_height	video height
start_chapter	first selected chapter
end_chapter	last selected chapter

Custom media tags use the exact key:value form:

series:Example
season:2
episode:7

Both the key and value must be non-empty, and the parser accepts exactly one colon. title:Part 1:Arrival is therefore ignored rather than split on the first colon.

When keys repeat, the last value wins. Custom tags are appended after derived tags, so a valid custom title:... can override the derived title.

Where substitution occurs

Job Service renders {{key}} placeholders recursively in:

• input and output file-source fields;
• legacy additional_parameters JSON strings;
• string values inside structured parameters, including nested objects and lists.

Non-string values are unchanged. Unknown placeholders remain in the string; substitution itself does not fail the job. A later URI, schema, or worker validation step may reject the unresolved value.

Keys are case-sensitive. {{Title}} and {{title}} are different placeholders.

Execution snapshot

After rendering, Job Service stores an independent smart-tag map on every queued job. Video Service passes that snapshot to the FFmpeg renderer. This keeps a running or retried job tied to the metadata it was created with instead of silently reading later media changes.

Two template layers

MediaMoth has two distinct syntaxes:

1. Job parameters use direct smart tags such as {{title}}.
2. FFmpeg preset files use Go template functions such as {{ tag "title" }} and {{ chapter 0 2 }}.

Job Service resolves the first layer before queueing. Video Service resolves the second layer after staging input and output files.

{
  "name": "tagged-output",
  "description": "Write the title into container metadata",
  "template": [
    "-i", "{{ input 0 }}",
    "-metadata", "title={{ tag \"title\" }}",
    "{{ output 0 }}"
  ]
}

Unlike direct job substitution, the FFmpeg tag function returns an error if the requested key is absent.

Related guides

• Pipeline Templates
• File Sources
• Video Encoding Presets