{"id":19592873,"url":"https://github.com/fauu/mpv-sub-pause-advanced","last_synced_at":"2025-10-25T11:02:12.779Z","repository":{"id":72663388,"uuid":"553065728","full_name":"fauu/mpv-sub-pause-advanced","owner":"fauu","description":"A versatile mpv script for pausing playback for subtitles","archived":false,"fork":false,"pushed_at":"2022-11-19T14:09:26.000Z","size":53,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-25T11:01:50.116Z","etag":null,"topics":["language-learning","lua","mpv","mpv-script","pause","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/fauu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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}},"created_at":"2022-10-17T16:56:30.000Z","updated_at":"2025-02-13T02:03:11.000Z","dependencies_parsed_at":null,"dependency_job_id":"462089cc-7a76-4f5c-80f4-5633c25792e5","html_url":"https://github.com/fauu/mpv-sub-pause-advanced","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/fauu/mpv-sub-pause-advanced","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fauu%2Fmpv-sub-pause-advanced","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fauu%2Fmpv-sub-pause-advanced/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fauu%2Fmpv-sub-pause-advanced/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fauu%2Fmpv-sub-pause-advanced/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fauu","download_url":"https://codeload.github.com/fauu/mpv-sub-pause-advanced/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fauu%2Fmpv-sub-pause-advanced/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280943396,"owners_count":26417747,"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","status":"online","status_checked_at":"2025-10-25T02:00:06.499Z","response_time":81,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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-learning","lua","mpv","mpv-script","pause","subtitles"],"created_at":"2024-11-11T08:37:15.279Z","updated_at":"2025-10-25T11:02:12.734Z","avatar_url":"https://github.com/fauu.png","language":"Lua","readme":"\u003c!-- vim: set textwidth=80 colorcolumn=80: --\u003e\n\u003c!-- markdownlint-configure-file\n{\n  \"line-length\": { \"code_blocks\": false },\n  \"no-inline-html\": false,\n  \"fenced-code-language\": false\n}\n--\u003e\n# mpv-sub-pause-advanced\n\n\u003e A versatile [mpv] media player script for pausing video playback for subtitles\n\n\u003c!-- --\u003e\n\n\u003e **Warning**\n\u003e This script has not been thoroughly tested yet with all of its possible\n\u003e configuration combinations. Please feel encouraged to report any suspected\n\u003e issues / incompatibilities / unexpected behaviours by creating a\n\u003e [Github issue][issues].\n\n[issues]: https://github.com/fauu/mpv-sub-pause-advanced/issues\n[mpv]: https://mpv.io/\n\n## Main features\n\n* Independently set up pausing at the start/end of the primary/secondary\n  subtitle track.\n\n* Automatically unpause after a time period dependent on the subtitle\n  length (text length or time duration).\n\n* Pause on request: press a key to request a pause at the end of the current\n  subtitle.\n\n* Skip pausing for subtitles below a specified length threshold.\n\n* Skip pausing for special subtitles, such as karaoke subtitles or sign\n  subtitles.\n\n* Hide a subtitle while playing or when paused for another subtitle track.\n\n## Table of contents\n\n1. [Installation](#installation)\n2. [Basic usage](#basic-usage)\n3. [The setup definition](#the-setup-definition)\n    * [Form](#form)\n    * [All setup parameters](#all-setup-parameters)\n4. [Key bindings](#key-bindings)\n5. [Extra options](#extra-options)\n    * [Option list](#option-list)\n6. [Known issues](#known-issues)\n7. [Credits](#credits)\n\n## Installation\n\nDownload the [script file] (click on the `Raw` button and then press\n\u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e), placing it in the `scripts` subdirectory of the\nmpv configuration directory (see [Script location][mpv-script-location] in mpv\nmanual).\n\n[mpv-script-location]: https://mpv.io/manual/stable/#script-location\n[script file]: https://github.com/fauu/mpv-sub-pause-advanced/blob/master/sub-pause-advanced.lua\n[script file]: https://raw.githubusercontent.com/fauu/mpv-sub-pause-advanced/master/sub-pause-advanced.lua\n\n## Basic usage\n\nTo enable the script, provide a setup definition as a script option to mpv. Here\nis an illustration of different ways to provide the setup definition `2end`, which\ninstructs the script to pause at the end of each *secondary* subtitle:\n\n1. Directly when launching mpv:\n\n    ```sh\n    mpv file.mkv --script-opts=sub-pause-setup=2end\n    ```\n\n1. Globally in [mpv config]:\n\n    ```\n    script-opts=sub-pause-setup=2end\n    ```\n\n1. As a [custom profile] in mpv config:\n\n    ```\n    [my-sub-pause-profile]\n    script-opts=sub-pause-setup=2end\n    ```\n\n    then enable electively when starting mpv:\n\n    ```sh\n    mpv file.mkv --profile=my-sub-pause-profile\n    ```\n\n[mpv config]: https://mpv.io/manual/stable/#configuration-files\n[custom profile]: https://mpv.io/manual/stable/#profiles\n\n---\n\n\u003e **Note**\n\u003e **By default, pausing will be skipped when the subtitle does not met certain\n\u003e conditions:**\n\u003e\n\u003e 1. The subtitle’s time duration is below the default threshold.\n\u003e\n\u003e 1. The subtitle’s text length is above zero but below the default threshold.\n\u003e\n\u003e 1. Auto unpause is enabled and the subtitle’s calculated pause duration is\n\u003e    below the default threshold.\n\u003e\n\u003e The values of these defaults and the way to override them are described in the\n\u003e section [Extra options](#extra-options).\n\n## The setup definition\n\n### Form\n\nThe setup definition is a string of characters that tells the script when to\npause and how to do it. It consists of up to four *parts* separated with the\ncharacters `##`. Those parts each define a pause point in one of four available\npositions: start of primary subtitle, end of primary subtitle, start of\nsecondary subtitle, end of secondary subtitle.\n\nFor example, the following definition enables pause at the start of the\nsecondary subtitle and at the end of the primary subtitle:\n\n```\n2start##end\n```\n\nFurthermore, each of the parts can be modified with extra configuration\ndirectives separated with the `!` character. For example, to extend the\nabove definition with the options:\n\n1. Hide the secondary subtitle while playing.\n\n1. Once paused at the end of a primary subtitle, wait a bit and then\n  automatically unpause.\n\nthe following setup definition should be specified:\n\n```\n2start!hide##end!unpause\n```\n\nMultiple directives can be provided within a single *part*. For example, to make\nit so that, on top of the previous configuration, the pause at the end of a\nprimary subtitle only happens if a specified pause request key is pressed before\nthe end of the subtitle is reached, the definition should read:\n\n```\n2start!hide##end!unpause!request\n```\n\nFinally, some directives can have extra arguments, separated with the `-`\ncharacter, that additionally modify their behaviour. For example, to prolong the\ninterval before the automatic unpause for the end of a primary subtitle by\na factor of 1.5, specify:\n\n```\n2start!hide##end!unpause-1.5!request\n```\n\n### All setup parameters\n\n#### Pause position specifiers\n\n`start` — start of each primary subtitle.\n\n`end` — end of each primary subtitle.\n\n`2start` — start of each secondary subtitle.\n\n`2end` — end of each secondary subtitle.\n\n#### Directives\n\n##### – `unpause`\n\nAutomatically unpause after a time interval calculated on the basis of the\nsubtitle text length. Note that this will not work properly for image-based\nsubtitled—for those, the `-time` argument must be used.\n\n\u003cins\u003eArguments:\u003c/ins\u003e\n\n`unpause-time` — calculate the unpause interval based on the subtitle’s defined\nplayback time instead.\n\n`unpause[-time]-\u003cnumber\u003e` — multiply the calculated unpause interval by\n`\u003cnumber\u003e`. Supports decimal parts, for example `0.75`.\n\nAdvanced modifications to the calculation formula can be made through [Extra\noptions](#extra-options).\n\n##### – `request`\n\n\u003e *Valid only for the `end` position.*\n\nOnly pause if requested through the pause request key binding (see [Key\nbindings](#key-bindings)).\n\n\u003cins\u003eArguments:\u003c/ins\u003e\n\n`request-replay` — after unpause, replay from the start of the subtitle.\n\n##### – `hide`\n\nHide the subtitle during playback, unless it does not qualify for a pause.\n(Only needs to be specified once per subtitle track.)\n\n\u003e **Warning**\n\u003e In mpv 0.34 and earlier, hiding primary subtitles also hides secondary\n\u003e subtitles.\n\n\u003cins\u003eArguments:\u003c/ins\u003e\n\n`hide-more` — hide also while paused for the other subtitle track.\n\n##### – `race`\n\n\u003e *Valid only for the `end` position.*\n\nSkip pause to avoid two consecutive pauses in case when we just recently paused\nfor the end of the subtitle on the other track. In other words, the following\nsetup definition:\n\n```\nend!race##2end!race\n```\n\nprovided the two subtitle tracks are reasonably synchronized, should lead to\nonly one pause at the end of each subtitled line, at time position dependent on\nwhichever track has its subtitle ending earlier.\n\nThe playback time interval, counting from the previous pause, within which this\nskip is active, can be customized through the [extra option](#extra-options)\n`pair-sub-max-delta`.\n\n##### – `special`\n\nAlso pause on subtitles classified as “special”, for example karaoke subtitles\nor subtitles with special positioning that are usually for signs and other text,\nnot spoken lines.\n\n## Key bindings\n\nBelow is a list of key bindings available for the script. To assign a key where\nnone is assigned by default or to assign a different one, add an appropriate\n`script-binding` line to mpv’s [input.conf] file.\n\nFor example, to have the key \u003ckbd\u003eN\u003c/kbd\u003e (i.e., \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003en\u003c/kbd\u003e)\nturn the script off and back on, add the line:\n\n```\nN script-binding sub_pause_advanced/toggle-pausing\n```\n\n(Note the underscores.)\n\nTo set other bindings, replace, in the example above, `N` with the desired key\n(see [Key names] in mpv manual) and `toggle-pausing` with the name of one of\nthe other bindings listed below.\n\n– **`toggle-pausing`** (default: none; recommendation: \u003ckbd\u003eN\u003c/kbd\u003e)\n\nDisable or re-enable pausing and adjacent features (such as subtitle hiding).\n\n– **`override-pausing`** (default: none; recommendation: \u003ckbd\u003en\u003c/kbd\u003e)\n\nUnpause and prevent any pauses *while the key remains pressed*.\n\n– **`request-pause`** (default: none; recommendation: \u003ckbd\u003eMBTN_RIGHT\u003c/kbd\u003e)\n\nWhen the `request` directive is active, queue a pause for the end of the current\nsubtitle. Otherwise, pause immediately. If already paused—unpause.\n\n– **`replay`** (default: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003er\u003c/kbd\u003e)\n\nReplay from the start of the current or previous primary subtitle.\n\n– **`replay-secondary`** (default: none)\n\nReplay from the start of the current or previous secondary subtitle.\n\n[input.conf]: https://mpv.io/manual/stable/#input-conf\n[Key names]: https://mpv.io/manual/stable/#key-names\n\n## Extra options\n\nBesides the setup definition, the script accepts several additional advanced\nconfiguration options. The options should be appended to the same `script-opts`\nmpv property that is used to specify the setup definition.\n\nFor example, to specify custom values for the minimum subtitle time duration and\nthe minimum subtitle text length qualifying for a pause, provide the following\nscript options to mpv:\n\n```\nmpv file.mkv --script-opts=sub-pause-setup=start##end,sub-pause-min-sub-duration=2,sub-pause-min-sub-text-length=10\n```\n\n### Option list\n\n\u003e **Note**\n\u003e All options must be additionally prefixed with `sub-pause-`.\n\n– **`min-sub-duration`** (seconds; default: `1`)\n\nDo not pause for subtitles that are programmed to display for less than this\namount of seconds.\n\n– **`min-sub-text-length`** (characters; default: `5`)\n\nDo not pause for subtitles that are shorter than this amount of characters.\n(Ignored if the length is equal to `0` to not include all image-based\nsubtitles).\n\n– **`min-pause-duration`** (seconds; default: `0.5`)\n\nIf [`unpause`](#directives) is enabled, do not pause unless the calculated pause\nduration is at least this amount of seconds.\n\n– **`unpause-base`** (seconds; default: `0.4`)\n\nBase automatic pause duration in seconds. Extra pause time dependent on the\nlength of the subtitle will be a further addition to this base value.\n\n– **`unpause-text-multiplier`** (default: `0.017`)\n\nA multiplier used to transform the subtitle text length in characters into the\nauto pause duration in `unpause` mode.\n\n– **`unpause-time-multiplier`** (`0.57`)\n\nA multiplier used to transform the subtitle time length in seconds into the auto\npause duration in `unpause-time` mode.\n\n– **`unpause-exponent`** (`1.2`)\n\nAn exponent used to scale the subtitle length (both text and time length,\ndepending on the mode) in the auto pause duration calculation, so that a\nsubtitle that is twice as long is, by default, given more than twice the pause\ntime. To make the scaling linear, set to `1`.\n\n– **`pair-sub-max-delta`** (`0.9`)\n\nIf [`race`](#directives) is enabled, do not pause in case when we already paused\nfor subtitle end on the other track at most this many seconds ago (in terms of\nvideo playback time).\n\n– **`sub-delay`** (`no`)\n\nIf a number is provided, set the mpv sub delay to that many seconds each time\nthe script is initialized with at least one pause point set up.\n\n## Known issues\n\n**I. Not pausing when there is an overlapping sign subtitle present during\ndialogue lines**\n\nMost likely impossible to fix for the `end` position, because in this case we\nreceive a `sub-end` event only for the sign subtitle, and not for the dialogue\nsubtitles that change while the sign subtitle is present.\n\nWe do, however, receive separate `sub-text` events. This could be used to make\nthe `start` position work. But it would only work for text-based subtitles and\nwould therefore have to be implemented as an extra special case, which probably\nis not worth the extra complexity.\n\n\u003cins\u003eReproduction:\u003c/ins\u003e *Hanasaku Iroha - E15* (Doki) `sub-pause-setup=start --start=2:00`\n\n## Credits\n\nInspired by [sub-pause] from @Ben-Kerman.\n\n[sub-pause]: https://github.com/Ben-Kerman/mpv-sub-scripts/\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffauu%2Fmpv-sub-pause-advanced","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffauu%2Fmpv-sub-pause-advanced","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffauu%2Fmpv-sub-pause-advanced/lists"}