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

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-compressed TTF, 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 by mkvtool. 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

git apply --ignore-space-change needed-chars.patch

Settings/Arguments

Strict mode

mkvtool -n -clean -s container.mkv

Non-Strict mode

mkvtool -n -clean -ncks -s container.mkv
  • -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

Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding

Fail without error

Most cases a font had subset as part of there name.

find -iname "*.subset.*"

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

mkvpropedit "container.mkv" --delete-attachment name:'remove.ttf'

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.

rsync -a ~/font-collection data/fonts

Check if dist.mkv exists + has stubs

1
2
3
4
5
6
7
if [ ! -f "dist.mkv" ]; then
    echo "No mkv generated - retry, look at output/log"
    exit
elif [[ $(mkvmerge -J dist.mkv | jq -r '[.tracks[] | select(.codec == "SubStationAlpha")] | length') -eq 0 ]]; then
    echo "Subs are missing, retry, happens sometimes"
    exit
fi

OR compare track count and not trackCount > 0

$(mkvmerge -J dist.mkv | jq -r '[.tracks[] | select(.codec == "SubStationAlpha")] | length') == $(mkvmerge -J source.mkv | jq -r '[.tracks[] | select(.codec == "SubStationAlpha")] | length')

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)

Edit Report
Pub: 13 Aug 2023 20:42 UTC
Edit: 12 Sep 2023 17:17 UTC
Views: 151