mpv-sub-select

This script allows you to configure advanced subtitle track selection based on the current audio track and the names and language of the subtitle tracks. The script will automatically disable itself when mpv is started with --sid not set to auto, or when --track-auto-selection is disabled. There is also experimental mode which allows audio selection as well.

Configuration

Configuration is done in the sub-select.json file, stored in the ~~/script-opts/ config directory.

Syntax

The syntax and available options are as follows:

[
    {
        "alang": "jpn",
        "slang": "eng",
        "blacklist": [ "sign" ],                // optional
        "whitelist": [ "english", "song" ],     // optional
        "condition": "sub.codec == 'ass'",      // optional
        "id": "unique-id",                      // optional
        "inherit": "other-id"                   // optional
    }
]

alang and slang are the language codes of the audio and subtitle tracks, while blacklist and whitelist are optional filters that can be used to choose subtitle tracks based on their track names. For a track to be selected it must match any entry in the whitelist and must not match any entry in the blacklist.

alang and slang can also be arrays of valid codes to allow matching with multiple language codes. If multiple slang languages are included, then the first code to match to a track will be the one used.

Do not use uppercase characters for any options unless using patterns.

All titles are converted to lowercase automatically to allow more matches.

String Matching

All matching is done using the lua string.find function, so supports patterns. For example eng? could be used instead of eng so that the DVD language code en is also matched.

The characters ^$()%.[]*+-? have special behaviour and muct be escaped with %.

Priority

The script moves down the list of track preferences until any valid pair of audio and subtitle tracks are found. Once this happens the script immediately sets the subtitle track and terminates. If none of the tracks match then track selection is deferred to mpv.

Special Strings

There are a number of strings that can be used for the alang and slang which have special behaviour.

alang:

String	Action
*	matches any language
no	matches when no audio track is selected - not included by *
default	matches audio with the default tag
forced	matches audio with the forced tag

slang:

String	Action
*	matches the first track that passes the filters
no	disables subs if alang matches
default	selects subtitles with the default tag
forced	selects subtitles with the forced tag

Conditions

Conditions are a way to specify advanced, powerful, and custom filters. The condition field is a lua expression that can be used to evaluate whether or not the subtitle should be selected. This expression will be run for every subtitle that passes the other filters. The sub variable contains the subtitle track entry and audio contains the audio track entry. See the track-list property for what fields are available. The mp, mp.msg, and mp.utils modules are avaialble as mp, msg, and utils, respectively. If no audio or sub track is being compared (which only happens if you set alang or slang to no) then audio or sub will evaluate to nil.

In the following examples the condition requires:

• "condition": "sub.external" - an external subtitle file.
• "condition": "audio.default and sub.id == 1" - the default audio and the first subtitle in the file.
• "condition": "mp.get_property('path', ''):find('Anime') ~= nil" - the path of the current file to contain Anime.

Inheritance

To make it easier to write complex config files you can set the preferences to inherit from each other. This will reduce the need to duplicate the same fields in multiple preferences. Inheritence uses the id and inherit fields. The id field must be a string that is unique to that preference (no two preferences can have the same ID). The inherit field can be used to specify the ID of the preference to inherit from. The special (reserved) ID ^ will inherit from the previous preference without it needing an explicit ID.

The new child preference will inherit all the fields from the parent that have not been explicitly overwritten. Inheritance can be chained, but make sure not to create circular inheritance.

In the below example the first preference inherits the alang and slang fields from the second preference. The first preference adds a condition field to prefer external subtitles.

[
    {
        "inherit": "example-id",
        "condition": "sub.external"
    },
    {
        "alang": "*",
        "slang": "eng?",
        "id": "example-id",
    }
]

In this more complex example external subtitles are the main preference, followed by a preference for ass subtitles. The special ^ ID is used to simplify the config. Note the final preference needs to add a superfluous condition statement to override the inherited condition from the third preference.

[
    {
        "alang": ["jpn", "ja"],
        "slang": ["en%-us", "eng?"],
        "whitelist": [ "sign", "song"],
        "condition": "sub.codec == 'ass' and sub.external" 
    },
    {
        "inherit": "^",
        "condition": "sub.external" 
    },
    {
        "inherit": "^",
        "condition": "sub.codec == 'ass'" 
    },
    {
         "inherit": "^",
         "condition": "sub.codec ~= 'ass'"
    }
]

Commands

The script supports two commands to control subtitle selection.

script-message select-subtitles

This command will force subtitle selection during runtime based on the current audio track.

script-message sub-select [arg]

This command will enable/disable the script. Valid arguments are enable, disable, and toggle. If the script gets enabled then the current subtitle track will be reselected.

Auto-Switch Mode

The detect_audio_switches script-opt allows one to enable Auto-Switch Mode. In this mode the script will automatically reselect the subtitles when the script detects that the audio language has changed. This setting ignores --sid=auto, but when using synchronous mode the script will not change the original sid until the first audio switch. This feature still respects --track-auto-selection. This mode can be disabled during runtime wi the sub-select script message shown above.

Audio Selection

This is an experimental option to allow advanced selection of pairs of audio and subtitle tracks. Controlled by the select_audio option.

When this option is enabled the script will go through the list of preferences as usual, but instead of comparing the sub tracks against the current audio track it will compare it against all audio tracks. If any audio tracks match the alang and there are subs that match the slang and filters, then that audio track will be selected.

If multiple audio tracks match a preference then the track that occurs first in the track list will be chosen. This option does not break observe_audio_switches but will disable the force_prediction and detect_incorrect_predictions options.

The whitelist and blacklist will still only work with subs, but the condition filter can be used to implement audio-specific filtering behaviour.

Examples

The sub_select.conf file contains all of the options for the script and their defaults. The sub-select.json file contains a decent default configuration for English users. The wiki page provides some more custom examples.