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
Pub: 13 Aug 2023 20:42 UTC
Edit: 12 Sep 2023 17:17 UTC
Views: 155