Autoload external ASS font files for subtitles in mpv

external-assfonts-dir.lua

--[[
  * external-assfonts-dir.lua v.2026-03-22
  * Autoload external ASS font files for subtitles in mpv
  * Author: natyusha
  * Link: https://gist.github.com/natyusha/96a11b9e29c243c851e92add1ac42744
--]]

local msg   = require 'mp.msg'
local utils = require 'mp.utils'
local opt   = require 'mp.options'

-- Options
local o = {
    autoload    = true,
    osd_message = false,
    fallback    = 'fonts',                -- fallback fonts folder
    suffixes    = '_attach,_attachments', -- per file folder suffixes (comma separated)
}
opt.read_options(o)

-- Load External Fonts
local function load_fonts()
    local path = mp.get_property('path')
    
    -- If the path starts with a single backslash add another to fix UNC paths
    if path:sub(1,1) == '\\' and path:sub(2,2) ~= '\\' then path = '\\' .. path end

    local dir          = utils.split_path(path)
    local base_name    = mp.get_property('filename/no-ext')
    
    local info, fonts_folder, fonts_path
    for s in o.suffixes:gmatch('([^,]+)') do
        fonts_folder = base_name .. s
        fonts_path   = utils.join_path(dir, fonts_folder)
        info         = utils.file_info(fonts_path)
        if info and info.is_dir then break end
    end

    local used_path    = nil
    local used_name    = nil

    if info and info.is_dir then
        used_path = fonts_path
        used_name = fonts_folder
        msg.info('Using per file fonts folder: ' .. fonts_folder)
    else
        local fallback_path = utils.join_path(dir, o.fallback)
        info = utils.file_info(fallback_path)
        if info and info.is_dir then
            used_path = fallback_path
            used_name = o.fallback
            msg.info( ('No %s folder → using fallback: %s'):format(o.suffixes, o.fallback) )
        else
            msg.debug('No font folder found for ' .. base_name)
            return
        end
    end

    mp.set_property('sub-fonts-dir', used_path)
    if o.osd_message then mp.osd_message('External fonts loaded: ' .. used_name) end
end

-- HOOKS -----------------------------------------------------------------------

if o.autoload then mp.add_hook('on_preloaded', 50, load_fonts) end