From 5ee99a7525baa06d9f2d10bf1676622e5b29bfa7 Mon Sep 17 00:00:00 2001 From: Nicolas Date: Mon, 14 Sep 2026 13:54:54 +0200 Subject: [PATCH] Document subtitle-burn 500's real root cause: Emby's fontconfig, not us Once the hls.js timeout fix stopped masking it, the actual segment request came back with a real 500. Emby's own server log (shared by the user, not from this app) shows exactly why: ffmpeg's subtitles filter failing with "Failed to load fontconfig fonts!" inside StartFfMpeg - a font/fontconfig-cache problem in whatever environment Emby's transcoder runs in, not anything this app's request could cause. No code change: this app deliberately forces SubtitleMethod=Encode (see applyPlaybackOverrides) since it never wires up hls.js's rendition-based subtitle API - dropping that to dodge the 500 would just bring back the original "subtitle picked, never shown" bug instead of fixing anything. Recorded as Round 4 of the player-track-selection saga so this doesn't get re-investigated from scratch later. Co-Authored-By: Claude Sonnet 5 --- docs/architecture.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/architecture.md b/docs/architecture.md index 275978f..698001b 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -510,6 +510,29 @@ real `Hls` instance from the exact pinned CDN build `hls.config.fragLoadingTimeOut` etc. - all four came back as set, not as hls.js's own defaults. +**Round 4: a real 500, once the timeout was no longer masking it - traced +to Emby, not this app.** Exactly what Round 2 said would happen "if +subtitles still don't show once this log line confirms `subtitleMethod= +Encode` really was sent": with Round 3's timeout fix giving Emby enough +rope to actually answer instead of hls.js giving up first, the segment +request came back with a real, fast 500 - and Emby's own server log +(shared directly, not this app's) shows exactly why: `[subtitles@f2] Failed +to load fontconfig fonts!`, thrown out of `StartFfMpeg`/ +`GetDynamicSegment` before a response body ever exists. That's ffmpeg's +`subtitles` filter (burning text into the video via `libass`) failing to +find usable fonts/a fontconfig cache in whatever environment Emby's +transcoder runs in - a deployment/environment issue on the Emby side +(commonly a container image missing font packages, or a fontconfig cache +directory that isn't writable), with nothing in this app's request that +could cause or fix it. Confirmed not a regression to work around here: +this app deliberately forces `SubtitleMethod=Encode` (see +`applyPlaybackOverrides`'s own comment) specifically because it never +wires up `hls.js`'s rendition-based subtitle API - dropping that override +to dodge this 500 would silently bring back the very first version of +this bug (a subtitle picked, never shown) instead of fixing anything. +Nothing to change in this app for this one; it needs fonts/fontconfig +fixed wherever Emby's own container/host runs. + ## Assumptions to verify **Confirmed against the real server** (not a guess — actually exercised,