MKV Tag Generator

Introduction

Using the parameter -GenerateMKVTagFile (or its alias, -CreateTagFile) you can automatically pull, process, and mux custom XML tag files into your encoded output file. This only works for files in the Matroska format (duh), but it's a cool way to add interesting metadata to your container (it's also useful for media agents like Plex and Emby). The metadata is pulled from the TMDB API and requires a valid TMDB API key to work (it's free, you just need to sign up); also, this product is not endorsed by TMDB (had to say that). Currently, there is very little support for TV shows (sorry).

The script will automatically attempt to detect the film's title and year based on the output file path (if that info is included) using regular expressions, so giving your encode an output title that includes this information is recommended. Sometimes, the wrong data is pulled and you will need to specify a title and year via parameters; this is sometimes true for films with multiple releases of the same name (Like Dune, for example) and foreign films.

Requirements

• The MKVToolnix suite, which can be downloaded here or from pretty much any package manager in existence. Specifically, the following tools are used:
  • mkvmerge
  • mkvpropedit
• A valid TMDB API key

Parameter Options

The parameter accepts a hashtable argument which is then splatted to the script MatroskaTagGenerator.ps1 in the scripts directory. The hashtable and script can accept the following parameters, either contained within the hashtable or run as a standalone script:

Parameter	Mandatory	Description
Path	True	Path to the encoded output file - this is already covered by the -OutputPath parameter
APIKey	True	TMDB API Key
Title	False	Specify an optional clean title to use for search
Year	False	Specify the release year (sometimes required for multiple release films)
Properties	False	Pull additional metadata properties from the API by name (not guaranteed to work)
SkipProperties	False	Default properties to skip, like Cast, Directors, Writers, & IMDB ID (this can be customized)
NoMux	False	Creates the XML file, but does not multiplex it into the output file automatically
AllowClobber	False	Switch to enable overwriting of an existing XML file with the same name

Usage

Only the -APIKey parameter is required as the other mandatory parameter -Path is already covered (unless you run the script on its own), but you can include them all if you want. Example:

PS > ./FFEncoder.ps1 ~/Movies/Ex_Machina_remux.mkv -CRF 18 `
>>    -GenerateMKVTagFile @{APIKey='9862555x293fab2551aaffej22n93bb1'; SkipProperties=@('Writers','Directors'); NoMux=$true} `
>>    -o '/Users/patrickenfuego/Movies/Ex.Machina_2014.mkv'

Notice the use of title and year in the output filename - this is recommended if you want an accurate match on the first run. Separator characters like _ and . shouldn't affect the parsing.

Customization

FFEncoder

If you don't want to pass an API key each time you run the script, you can set a default value for -GenerateMKVTagFile (this is what I do). To do this, modify line ~ 550 (this may change in the future, so Ctrl+F for it if you can't find it):

# Modify this line
[hashtable]$GenerateMKVTagFile,
# To this
[hashtable]$GenerateMKVTagFile = @{APIKey='9065557f293dab25q1aabfe822b03bg4'} # Whatever your API key is

Another benefit to this approach is that the script will automatically generate a tag file for each encode.

You can set defaults for other options in the table above in the same fashion. For example, the script pulls the following metadata by default:

• TMDB ID
• IMDb ID
• Writers
• Directors
• Cast

If you want to exclude any of these, set a value for the SkipProperties key:

# Skip getting writers, directors, and cast info
[hashtable]$GenerateMKVTagFile = @{APIKey='9065557f293dab25q1aabfe822b03bg4';SkipProperties=@('Writers', 'Directors', 'Cast')}

Similarly, if you want to include specific metadata properties each time the script is called, set the Properties key. For example, if you wanted genres and tagline information:

[hashtable]$GenerateMKVTagFile = @{APIKey='9065557f293dab25q1aabfe822b03bg4'; Properties=@('genres', 'tagline')}

The script does do a little verification on the requested fields, but you must request valid metadata for this to work.

Standalone Script

NOTE: The make changes, edit the script located at FFEncoder/scripts/MatroskaTagGenerator.ps1 in the project directory structure

If you choose to run the script outside of FFEncoder, you can set your own defaults for most of the parameters, too. To make APIKey non-mandatory and give it a default value like you would with FFEncoder. To do this, change lines 88-90:

# Change this
[Parameter(Mandatory = $True, Position = 1)]
[Alias('Key')]
[string]$APIKey,

# To this
[Parameter(Mandatory = $false, Position = 1)]
[Alias('Key')]
[string]$APIKey = '9862555x293fab2551aaffej22n93bb1', # Whatever your API key is

Other customizations work the same as they would above.

Additional Information

For more info:

PS > Get-Help .\scripts\MatroskaTagGenerator.ps1 -Full