{"id":13835115,"url":"https://github.com/CogentRedTester/mpv-segment-linking","last_synced_at":"2025-07-10T07:31:19.217Z","repository":{"id":113085687,"uuid":"364803793","full_name":"CogentRedTester/mpv-segment-linking","owner":"CogentRedTester","description":"Implements support for Matroska hard segment linking in mpv player","archived":false,"fork":false,"pushed_at":"2022-11-22T07:57:51.000Z","size":88,"stargazers_count":19,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-08T23:11:49.407Z","etag":null,"topics":["matroska-files","matroska-hard-linking","mkv","mkvinfo","mpv","mpv-script"],"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}},"created_at":"2021-05-06T06:13:14.000Z","updated_at":"2025-02-11T05:43:53.000Z","dependencies_parsed_at":"2024-01-15T18:55:16.322Z","dependency_job_id":"5545c29a-457e-4ea4-a728-6cb88ee397f7","html_url":"https://github.com/CogentRedTester/mpv-segment-linking","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/CogentRedTester/mpv-segment-linking","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CogentRedTester%2Fmpv-segment-linking","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CogentRedTester%2Fmpv-segment-linking/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CogentRedTester%2Fmpv-segment-linking/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CogentRedTester%2Fmpv-segment-linking/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CogentRedTester","download_url":"https://codeload.github.com/CogentRedTester/mpv-segment-linking/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CogentRedTester%2Fmpv-segment-linking/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":["matroska-files","matroska-hard-linking","mkv","mkvinfo","mpv","mpv-script"],"created_at":"2024-08-04T14:00:56.903Z","updated_at":"2025-07-10T07:31:14.209Z","avatar_url":"https://github.com/CogentRedTester.png","language":"Lua","funding_links":[],"categories":["Playback"],"sub_categories":[],"readme":"# mpv-segment-linking\n\nImplements support for matroska [hard segment linking](https://www.ietf.org/archive/id/draft-ietf-cellar-matroska-06.html#name-hard-linking) in mpv player.\nThis is **not** the same as [ordered chapters](https://www.ietf.org/archive/id/draft-ietf-cellar-matroska-06.html#name-medium-linking), which mpv already supports natively.\nWhile both features are relatively obscure, ordered chapters are used far more often due to being able to support everything segments do, plus more.\nNevertheless, segment linked files do still exist, so this script can be used to implement limitted support for the feature until such a time as mpv implements it natively.\n\nThis script requires that `mkvinfo`, part of the [mkvtoolnix](https://mkvtoolnix.download/) toolset, be available in the system path.\n\n## Basic Setup\n\nIf you just want to play local hard-linked files like you would ordered chapters, then all you need to do is:\n\n1. Place segment-linking.lua into the mpv [scripts directory](https://mpv.io/manual/master/#files)\n2. Place `mkvinfo` into the system PATH (if in doubt on windows then place in the same directory as `mpv.exe`)\n\nEverything else should be automated.\nAll the advanced information below can be ignored.\n\n## Behaviour\n\nWhen opening a file containing a segment link the script will search the directory for files with matching segment UIDs.\nPrevious UIDs will be prepended before the opened file in the timeline, and next UIDs will be appended after.\nThe script will follow the next and previous segments and continue extending them until it cannot find any more linked segments, a.k.a, it will create a chain of linked segments stretching out from both directions of the opened file.\nPlayback will always start from the beginning of the timeline regardless of which file is opened.\n\nThis should follow the official [specification](https://www.ietf.org/archive/id/draft-ietf-cellar-matroska-06.html#name-hard-linking). Any incorrect behaviour should be reported.\n\n## Options\n\n### mpv-options\n\nThis script respects the `access-references` and `ordered-chapters` options.\nIf either of these options are disabled then so will this script.\nThis is to maintain parity with normal ordered chapters, considering the similarities of the features.\n\nThe `chapter-merge-threshold` option is used to merge chapters that are too close together, as with ordered chapters.\n\n### script-opts\n\nAll script options, and their defaults, are listen in the [segment_linking.conf](segment_linking.conf) file. Most of these options are related to\nthe custom segment-linking [metafiles](#metafiles)\n\n## Metafiles\n\nThis script supports custom segment metafiles, which can allow this script to work across network file systems and on systems without `mkvinfo`.\nBy default, if the current file cannot be read due to being a network file or because `mkvinfo` is not available, then the script will attempt to read\na meta-file from the same directory as the currently playing file. The name of the file is specified by the `default_metafile` script-opt.\nA metafile can be forcibly used by manually setting the `metafile` script-opt; in this case, the script will not even attempt to scan any files directly.\n\nIn order to load network metadata files this script requires that the [mpv-read-file](https://github.com/CogentRedTester/mpv-read-file) API be installed.\nSimply follow the install instructions and make sure to include the `wget` commandline utility in the system path.\n\n### Format\n\nThe first line of the metafiles must be `# mpv-segment-linking v0.1`.\nLines beginning with `#` are treated as comments, empty lines are ignored, and newlines\ncan be LF or CRLF. All other lines are treated as statements.\n\nStatements can consist of:\n\n```conf\n\u003cfilename\u003e\nUID=\u003cuid\u003e\nPREV=\u003cuid\u003e\nNEXT=\u003cuid\u003e\n```\n\nWhere `\u003cfilename\u003e` is the absolute or relative path of the file\nfor which the following `\u003cuids\u003e` apply. Paths must be relative to the metafile.\nThe `UID` field is the segment UID for that matroska file, and the `PREV` and\n`NEXT` fields are the next and previous segment UIDs for that file.\nAll three of these fields are optional and can be in any order, but the\nentry is useless without the `UID` field. There cannot be any whitespace before\nor after the `\u003cfilename\u003e`, `\u003cuid\u003e`, or `UID|PREV|NEXT`.\n\nThe first statement in the file must be a `\u003cfilename\u003e`. If multiple\n`UID|PREV|NEXT` statements are made for the same file then the latest\ntakes preference.\n\nIf you have a file that begins with `UID|PREV|NEXT=` then you can add `./`\nto the front to make it a `\u003cfilename\u003e`.\n\nHere is an example of a simple metafile:\n\n```conf\n# mpv-segment-linking v0.1\n\n01. Cardcaptor Sakura [BD 1080p Hi10P 5.1 AAC][kuchikirukia].mkv\nUID=0xbf 0x8c 0x8d 0x54 0x32 0x4e 0x88 0x21 0x96 0x2e 0x55 0x51 0x53 0x7c 0x34 0xc3\nPREV=0x72 0x77 0xc3 0x31 0xcf 0x62 0xe9 0x55 0xa6 0xd1 0x5d 0x79 0x8c 0x44 0x94 0x60\n\nNCOP1a (for linked mkvs).mkv\nUID=0x72 0x77 0xc3 0x31 0xcf 0x62 0xe9 0x55 0xa6 0xd1 0x5d 0x79 0x8c 0x44 0x94 0x60\n```\n\n### Build Scripts\n\nThe `Build-SegmentMetaFile.ps1` and `build-segment-metafile.sh` build scripts can be used to generate metafiles in the correct format.\nSimply pass a list of files as arguments to the scripts and they will automatically scan them using `mkvinfo` and save a properly formatted\nmetafile into the current folder.\n\n```bash\n./build-segment-metafile.sh *.mkv\n```\n\nThe default output file is `.segment-linking`, which matches the default metafile that this script attempts to load.\nHowever, the output file can be changed using the `-o` flag. For example:\n\n```bash\n./build-segment-metafile.sh *.mkv -o segments.meta\n```\n\n## Limitations\n\nThere are several limitations compared to the native implementation of ordered chapters.\nMost of these limitations can be solved by using the metafiles.\n\n* cannot detect if a network file should contain segments\n\n* does not support the `ordered-chapters-files` option.\n\n## Unclear Behaviour\n\nIt is not clear how this script would react with files that also contain ordered chapters or editions. I do not have any files to test this with.\n\nAll chapters added between segments by the edl specification are removed by the script whether or not they are within the merge threshold of existing chapters.\nThis behaviour matches the VLC implementation of the feature, which is what I'll be replicating.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCogentRedTester%2Fmpv-segment-linking","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FCogentRedTester%2Fmpv-segment-linking","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCogentRedTester%2Fmpv-segment-linking/lists"}