unlinkmkv - automate the tedious process of unlinking segmented MKV files.
A segmented MKV is an MKV that utilizes external additional MKV files to create a "whole" MKV. A common example is that when an anime series uses the same introduction and ending in every episode, sometimes the encoder will break the introduction and ending into their own MKV files, and then "link" to the segments as chapters in each episode's individual MKV. The problem is that very few players/filters/splitters support this, so this script automates the mkvtoolnix tools to "rebuild" each episode into "complete" MKVs.
When using unlinkmkv to unlink segments, the chapters when viewing the video are retained. The MKV spec requires that the segmented files are in the same directory; so does this. It doesn't matter if you rename the files as long as all required files are in the same directory as the one being processed; segmenting is based on internal IDs. Depending on how the original files were made, you may need to use the --fixaudio and/or --fixvideo options.
By default, unlinkmkv will now use the current directory as a default video directory if a file or directory is not given on the command line. This means that if unlinkmkv is set up and on your path, the majority of the time you can simply enter the directory and run unlinkmkv with no options.
Say we have the files:
princess-resurrection-ep-1.mkv
princess-resurrection-clean-opening.mkv
princess-resurrection-clean-ending.mkvAnd princess-resurrection-ep-1.mkv links the opening and ending files in the "appropriate places."
unlinkmkv princess-resurrection-ep-1.mkvDoing so will generate a new file under a newly created subdirectory, ./UMKV by default. The file will be about the total size of the original+external parts. If --fixaudio or --fixvideo is used, which re-encodes the related parts, about 10% is added to the bitrate by default.
Now, we test the file in a video player. It's important to check for audio or video problems, especially when transitioning between where the segments would have come in. Often times this is the opening/ending and the main show, so seek inside both places and make sure sound is playing in both places, and the video looks fine.
Let's pretend our sound is totally missing in the main video, and the video is corrupt:
unlinkmkv --fixaudio --fixvideo princess-resurrection-ep-1.mkvWhat happens is sometimes encoders use codecs that don't play well with Matroska, and can't be assembled as they were—either the codec (OGG) or the settings (thanks, encoder guy) being the cause. The --fixaudio and --fixvideo options simply re-encode the audio and video into a uniform format that plays nice, with settings that try not to reduce the quality very much (not noticeable), nor make the files hugemassive. See the FFMPEG notes!
You could process them all at once with:
unlinkmkv --fixaudio --fixvideo "/home/user/videos/Princess Resurrection"Clone this repository on Linux or macOS. You can also simply click "Clone or download" > "Download ZIP" on the top right. I'm also told there is an unofficial package for Arch Linux that works well. For Windows, see the next section. Make sure you meet all the dependencies described in the dependency section.
Configuration is done in a YAML file named unlinkmkv.ini that should exist next to the script. An example file is included named unlinkmkv.ini.dist. Copy this to unlinkmkv.ini and make any required changes for your system.
This script has been updated for cross platform compatibility and currently is tested to work on Arch, Debian, Ubuntu, and Windows so long as all required dependencies are met. For Windows, an archive exists in the dist/ directory with a compiled version of the script, the required dependencies, and a pre- configured INI file to use them—this distribution is essentially a "portable" Windows version. After extracting the archive, either add the new path to your environment PATH variable or simply use an absolute path to it on the command line.
This script requires:
Perl >= 5.8.9
MKVToolnix >= 5.1.0
XML::LibXML >= 2.0001
IPC::Run3
File::Which
JSON
String::CRC32
Log::Log4perl
Math::BigFloat
FFMPEG == *real* version of ffmpeg. Recent versions of Ubuntu and Debian come with a prominent ffmpeg fork called libav, which is *not* fully compatible.
Hard drive space, if your temp directory is small, set it to someplace else -- especially if using fixaudio or fixvideo!unlinkmkv {options} {file|path}
Options:
--tmpdir Set a custom temporary/working folder, /tmp/umkv is the default
--outdir Output directory, required!
--fixaudio, -fa Encode audio, not currently customizable; encodes to 320k AAC for the time being.
--fixvideo, -fv Encode video, not currently customizable; encodes to 8-bit h264 at whatever the existing average bitrate was up to 110% higher then that.
--fixsubtitles, -fs Defaults to on. Sometimes groups don't use uniform subtitle styles and fonts in all segments, it's a good idea to leave this enabled.
--playresx Occasionally the original encoder uses different subtitle resolutions in the different segments. When combined, it causes problems. This forcibly
sets the X resolution for subtitle rendering.
--playresy Same as above, but for the Y axis (vertical).
--ignoredefaultflag Occasionally the default chapter flag exists, but *all* chapters are disabled which confuses the script. Enable on those rare occasions.
--(no-)chapters The script does its best to adjust the chapters, but it's not quite perfect. This disables including chapters in the final file.
--edition Manually specify which edition to keep. Must combine with ignoredefaultflag if non-default edition. Yes, this is pointless otherwise.
--ffmpeg [path] Specify a path to the ffmpeg binary to use.
--mkvext [path] Specify a path to the mkvextract binary to use.
--mkvinfo [path] Specify a path to the mkvinfo binary to use.
--mkvmerge [path] Specify a path to the mkvmerge binary to use.
--fixvideotemplate FFMPEG encoding settings for use with --fixvideo. See Template for description.
--fixaudiotemplate FFMPEG encoding settings for use with --fixaudio. See Template for description.While you can specify a custom template string on the command line, I highly recommend you do so via the INI file instead. Variables can be used in templates with the format {var_MYVAR} and will be replaced with their variable when processed. A couple magic variables are always provided, and custom variables can be set for additional maths.
Special variables:
var_bitrate The bitrate of the original file
var_size The size of the original file
var_duration The duration of the original fileVariables themselves are defined by prefixing options with var_ and they themselves can contain other variables and simple math. The current-as-of-this- writing defaults are below:
fixvideotemplate = -c:v libx264 -b:v {var_minrate}k -minrate {var_minrate}k -maxrate {var_maxrate}k -bufsize 1835k -max_muxing_queue_size 4000
fixaudiotemplate = -map 0 -acodec ac3 -ab 320k
var_minrate = (var_size * 1.1) / var_duration
var_maxrate = var_minrate * 2Which takes the original filesize and multiplies it by 1.1, then divides by duration to get the base and minimum bitrates, then max bitrate is simply the minimum multiplied by two. Feel free to use whatever your version of ffmpeg supports, but be mindful that certain codecs don't play well with being joined (OGG Vorbis in particular).
Feel free to contact me via GitHub or by email at garret -at- wrjb.cc.
MIT License
Copyright (c) 2016-2022 Garret C. Noling
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.