mkvtool-doc
Help/FAQ with mkvtool aka MkvAutoSubset usage (https://github.com/MkvAutoSubset/MkvAutoSubset)
mkvtool has multiple features like PGS creation. This document only focuses on font subsetting for subs. Recommended for a final version of a MKV after last content change.
TOC
- mkvtool-doc
- General information
- Patches
- Settings/Arguments
- Errors / Warnings
- font name missing normal char(s) characters
- Failed to parse the ass file: "data/....ass" [astisub: style redText not found]
- Failed to parse the ass file: "data/....ass" [astisub: building new ssa event failed: astisub: content has 1 items whereas style format has 10 items]
- Not found item in the ass file(s): "1"
- Fail without error
- Failed to subset: ...ttf
- Failed to subset font
- Failed ... write filename.ass
- Tricks
General information
- Avoid TTC fonts. TTC is a font collections, so multiple styles in one file
- No need for WOFF2. The ASS spec only define TTF as supported font type and OFT works as well. WOFF2 is a
brotli
-compressedTTF
, but with few glyphs remaining. - Savings depends on fonts. In case the container has one or more fonts with 10000 glyphs/characters or more and normal subs only need a few, you will get massive savings. Usually the fonts will be around few KB and probably 600 KB max for all the subs together.
Advantages
- Fonts are only a few KB. Easy to playback or stream and less storage used.
- Subs need to be clean, no missing fonts, syntax errors or missing styles (sometimes annoying, but often easy to fix)
Disadvantages
- Characters are gone, in case the sub gets changed and new characters are used, they will be missing.
- "Broken" fonts, fonts that
fonttool
can't read and subset.
Known issues/behavior
- Sometimes the attachments are missing - maybe 1/500 and it works on second try<br>
Check attachments after usage
- Attached fonts with
.subset.
int here name will cause issues. Rename the attachment. - Will remove unused attachments like
cover.jpg
or unused fonts - Some font won't subset. Regenerating with
fontforge
resolves the issues in most cases - Font Regular is attached, but Bold is defined in style and you add Bold font style into cache, it will be used.
- MKV was smaller before i used mkvtool ->
mkvtool
applies no compression. Add zlib compression to ASS subs and it will be smaller. mkvtool
is case-sensitive, so the font name needs to be correct. Fonts have multiple names and are supported bymkvtool
. Filename of a font is not the font name- LG webOS has no default fonts for Unicode. A font uses a character or emoji it will fallback to another included font and no behavior like mpv that uses a Unicode fallback system font.
Patches
Most patches are nice2have
Only one patch left, others are merged into mkvtool
- Remove required characters
- If a single number found, all the numbers a added (didn't understand the reasoning)
- Space and non breaking space. Some fonts contain no space or no breaking space and will fail in strict mode
Patches on Gist
https://gist.github.com/enter-a-random-username/f1ac53268c00b4c90f82406314073174
Apply patches
Source uses tab and no .editorconfig
and i use spaces per default. Ignore spaces is needed to apply the patches
Settings/Arguments
Strict mode
Non-Strict mode
-clean
is related to caches-s
argument for your mkv-n
keeps font name in attachment-clean
cleans related caches (works so far)-ncks
non-strict, allows missing characters. Special chars (incl Emoji) are used or small fonts with missing chars.
Errors / Warnings
font name
missing normal char(s) characters
A font has missing characters. Maybe it is subsetted and you
Failed to parse the ass file: "data/....ass" [astisub: style redText not found]
This means the subs have a style in use that isn't defined in the style section. Often best solution is to replace it with a defined style OR look in other episodes for the definition OR if the fansub got updated.
Failed to parse the ass file: "data/....ass" [astisub: building new ssa event failed: astisub: content has 1 items whereas style format has 10 items]
Layer is sometimes often undefined.
Dialogue: ,
to Dialogue: 0,
Not found item in the ass file(s): "1"
Often missing style, look in style column or a \r
also defined style e.g. {\r1}
.
OR
Header line is missing
Fail without error
Most cases a font had subset
as part of there name.
Failed to subset: ...ttf
Some fonts can't be read/handled by fonttool
. Saving them with fontforge
resolves issue in most cases.
Failed to subset font
Check Font Info
OS/2 OS/2 Version. Value 5 isn't supported. Set it to automatic or 4.
Differences: https://learn.microsoft.com/en-us/typography/opentype/spec/os2
Failed ... write filename.ass
(uncommon - need to add the excat error message).
No Dialogue
, only Comment
asFormat:
in ASS file in [Events]
-section.
Notice that ometimes with Signs
- Set them to Dialogue
Tricks
Remove a font with mkvpropedit
You added a replacement font for number of reasons like missing characters or font failed to subset
Use a font pool/cache (add missing fonts)
Create a folder with fonts often used and throw it into data/fonts
incase a font is missing. Sub-folders will be searched as well.
Check if dist.mkv exists + has stubs
OR compare track count and not trackCount > 0
Default Fallback
ASS default fallback in specs is Arial. So any missing font could be replaced with Arial (or Arial Unicode in case non Latin characters are needed)