Autoload external ASS font files for subtitles in mpv

external-assfonts-dir.lua

--[[
  * external-assfonts-dir.lua v.2025-11-07
  * 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
    suffix      = '_attach', -- suffix of the per file fonts folder
}
opt.read_options(o)

-- Exclude URLs
local function is_protocol(p)
    return type(p) == 'string' and (p:find('^%a[%w.+-]-://') or p:find('^%a[%w.+-]-:%?'))
end

-- Load External Fonts
local function load_fonts()
    local path = mp.get_property('path')
    if not path or is_protocol(path) then return end

    local dir          = utils.split_path(path)
    local base_name    = mp.get_property('filename/no-ext')
    local fonts_folder = base_name .. o.suffix
    local fonts_path   = utils.join_path(dir, fonts_folder)
    local info         = utils.file_info(fonts_path)
    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.suffix, 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