{"id":13835352,"url":"https://github.com/CogentRedTester/mpv-sub-select","last_synced_at":"2025-07-10T07:31:38.937Z","repository":{"id":44151089,"uuid":"313069059","full_name":"CogentRedTester/mpv-sub-select","owner":"CogentRedTester","description":"An advanced conditional subtitle track selector for mpv player","archived":false,"fork":false,"pushed_at":"2025-04-04T12:21:14.000Z","size":56,"stargazers_count":101,"open_issues_count":4,"forks_count":9,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-05-26T03:10:53.951Z","etag":null,"topics":["language-codes","mpv-player","mpv-script","subtitle-selection","subtitles"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CogentRedTester.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-11-15T16:06:01.000Z","updated_at":"2025-05-23T08:41:52.000Z","dependencies_parsed_at":"2025-02-28T14:16:58.608Z","dependency_job_id":"011343d3-0170-4149-b906-d452582fffcf","html_url":"https://github.com/CogentRedTester/mpv-sub-select","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/CogentRedTester/mpv-sub-select","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CogentRedTester%2Fmpv-sub-select","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CogentRedTester%2Fmpv-sub-select/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CogentRedTester%2Fmpv-sub-select/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CogentRedTester%2Fmpv-sub-select/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CogentRedTester","download_url":"https://codeload.github.com/CogentRedTester/mpv-sub-select/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CogentRedTester%2Fmpv-sub-select/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264545167,"owners_count":23625404,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["language-codes","mpv-player","mpv-script","subtitle-selection","subtitles"],"created_at":"2024-08-04T14:01:00.109Z","updated_at":"2025-07-10T07:31:38.931Z","avatar_url":"https://github.com/CogentRedTester.png","language":"Lua","readme":"# mpv-sub-select\n\nThis 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.\nThere is also experimental mode which allows [audio selection](#audio-selection) as well.\n\n## Configuration\n\nConfiguration is done in the `sub-select.json` file, stored in the `~~/script-opts/` config directory.\n\n### Syntax\n\nThe syntax and available options are as follows:\n\n```json\n[\n    {\n        \"alang\": \"jpn\",\n        \"slang\": \"eng\",\n        \"blacklist\": [ \"sign\" ],                // optional\n        \"whitelist\": [ \"english\", \"song\" ],     // optional\n        \"condition\": \"sub.codec == 'ass'\",      // optional\n        \"id\": \"unique-id\",                      // optional\n        \"inherit\": \"other-id\"                   // optional\n    }\n]\n```\n\n`alang` and `slang` are the language codes of the audio and subtitle tracks,\nwhile `blacklist` and `whitelist` are optional filters that can be used to choose subtitle tracks based on their track names.\nFor a track to be selected it must match any entry in the `whitelist` and must not match any entry in the `blacklist`.\n\n`alang` and `slang` can also be arrays of valid codes to allow matching with multiple language codes.\nIf multiple `slang` languages are included, then the first code to match to a track will be the one used.\n\n**Do not use uppercase characters for any options unless using [patterns](#string-matching).**\n\nAll titles are converted to lowercase automatically to allow more matches.\n\n### String Matching\n\nAll matching is done using the lua `string.find` function, so supports [patterns](https://www.lua.org/manual/5.1/manual.html#5.4.1). For example `eng?` could be used instead of `eng` so that the DVD language code `en` is also matched.\n\n**The characters `^$()%.[]*+-?` have special behaviour and muct be escaped with `%`.**\n\n### Priority\n\nThe 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.\n\n### Special Strings\n\nThere are a number of strings that can be used for the `alang` and `slang` which have special behaviour.\n\n**alang:**\n| String | Action                                  |\n|--------|-----------------------------------------|\n| *      | matches any language                    |\n| no     | matches when no audio track is selected - not included by `*` |\n| default| matches audio with the `default` tag    |\n| forced | matches audio with the `forced` tag     |\n\n**slang:**\n| String  | Action                                        |\n|---------|-----------------------------------------------|\n| *       | matches the first track that passes the filters|\n| no      | disables subs if `alang` matches              |\n| default | selects subtitles with the `default` tag      |\n| forced  | selects subtitles with the `forced` tag       |\n\n### Conditions\n\nConditions are a way to specify advanced, powerful, and custom filters.\nThe `condition` field is a lua expression that can be used to evaluate whether or not the subtitle should be selected.\nThis expression will be run for every subtitle that passes the other filters. The `sub` variable contains the subtitle\ntrack entry and `audio` contains the audio track entry. See the [track-list property](https://mpv.io/manual/master/#command-interface-track-list)\nfor what fields are available. The `mp`, `mp.msg`, and `mp.utils` modules are avaialble as `mp`, `msg`, and `utils`, respectively.\nIf 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`.\n\nIn the following examples the condition requires:\n\n* `\"condition\": \"sub.external\"` - an external subtitle file.\n* `\"condition\": \"audio.default and sub.id == 1\"` - the default audio and the first subtitle in the file.\n* `\"condition\": \"mp.get_property('path', ''):find('Anime') ~= nil\"` - the path of the current file to contain `Anime`.\n\n### Inheritance\n\nTo make it easier to write complex config files you can set the preferences to inherit from each other.\nThis will reduce the need to duplicate the same fields in multiple preferences. Inheritence uses the\n`id` and `inherit` fields. The `id` field must be a string that is unique to that preference\n(no two preferences can have the same ID). The `inherit` field can be used to specify the ID of the preference\nto inherit from. The special (reserved) ID `^` will inherit from the previous preference without it needing an explicit ID.\n\nThe new child preference will inherit all the fields from the parent that have not been explicitly overwritten.\nInheritance can be chained, but make sure not to create circular inheritance.\n\nIn the below example the first preference inherits the `alang` and `slang` fields from the second preference.\nThe first preference adds a `condition` field to prefer external subtitles.\n\n```json\n[\n    {\n        \"inherit\": \"example-id\",\n        \"condition\": \"sub.external\"\n    },\n    {\n        \"alang\": \"*\",\n        \"slang\": \"eng?\",\n        \"id\": \"example-id\",\n    }\n]\n```\n\nIn this more complex example external subtitles are the main preference, followed\nby a preference for ass subtitles. The special `^` ID is used to simplify the config.\nNote the final preference needs to add a superfluous `condition` statement to override\nthe inherited condition from the third preference.\n\n```json\n[\n    {\n        \"alang\": [\"jpn\", \"ja\"],\n        \"slang\": [\"en%-us\", \"eng?\"],\n        \"whitelist\": [ \"sign\", \"song\"],\n        \"condition\": \"sub.codec == 'ass' and sub.external\" \n    },\n    {\n        \"inherit\": \"^\",\n        \"condition\": \"sub.external\" \n    },\n    {\n        \"inherit\": \"^\",\n        \"condition\": \"sub.codec == 'ass'\" \n    },\n    {\n         \"inherit\": \"^\",\n         \"condition\": \"sub.codec ~= 'ass'\"\n    }\n]\n```\n\n## Commands\n\nThe script supports two commands to control subtitle selection.\n\n### `script-message select-subtitles`\n\nThis command will force subtitle selection during runtime based on the current audio track.\n\n### `script-message sub-select [arg]`\n\nThis 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.\n\n## Auto-Switch Mode\n\nThe `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.\nThis 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`.\nThis mode can be disabled during runtime wi the `sub-select` script message shown above.\n\n## Audio Selection\n\nThis is an experimental option to allow advanced selection of pairs of audio and subtitle\ntracks. Controlled by the `select_audio` option.\n\nWhen this option is enabled the script will go through the list\nof preferences as usual, but instead of comparing the sub tracks against the current audio\ntrack it will compare it against all audio tracks. If any audio tracks match the alang\nand there are subs that match the slang and filters, then that audio track will be\nselected.\n\nIf multiple audio tracks match a preference then the track that occurs first in the\ntrack list will be chosen. This option does not break `observe_audio_switches`\nbut will disable the `force_prediction` and `detect_incorrect_predictions` options.\n\nThe `whitelist` and `blacklist` will still only work with subs, but the `condition` filter\ncan be used to implement audio-specific filtering behaviour.\n\n## Examples\n\nThe [sub_select.conf](/sub_select.conf) file contains all of the options for the script and their defaults.\nThe [sub-select.json](/sub-select.json) file contains a decent default configuration for English users.\nThe [wiki page](https://github.com/CogentRedTester/mpv-sub-select/wiki/Example-Configs) provides some more custom examples.\n","funding_links":[],"categories":["Subtitle"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCogentRedTester%2Fmpv-sub-select","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FCogentRedTester%2Fmpv-sub-select","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCogentRedTester%2Fmpv-sub-select/lists"}