From def437f0cb088604d4201b2f334739159b686608 Mon Sep 17 00:00:00 2001 From: Cal Corum Date: Thu, 2 Apr 2026 20:00:04 -0500 Subject: [PATCH] =?UTF-8?q?docs:=20sync=20KB=20=E2=80=94=20troubleshooting?= =?UTF-8?q?.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- media-servers/troubleshooting.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/media-servers/troubleshooting.md b/media-servers/troubleshooting.md index 85a4507..903a103 100644 --- a/media-servers/troubleshooting.md +++ b/media-servers/troubleshooting.md @@ -562,6 +562,20 @@ tar -czf ~/jellyfin-config-backup-$(date +%Y%m%d).tar.gz ~/docker/jellyfin/confi --- +## PGS Subtitle Default Flags Causing Roku Playback Hang (2026-04-01) + +**Severity:** Medium — affects all Roku/Apple TV clients attempting to play remuxes with PGS subtitles + +**Problem:** Playback on Roku hangs at "Loading" and stops at 0 ms. Jellyfin logs show ffmpeg extracting all subtitle streams (including PGS) from the full-length movie before playback can begin. User Staci reported Jurassic Park (1993) taking forever to start on the living room Roku. + +**Root Cause:** PGS (hdmv_pgs_subtitle) tracks flagged as `default` in MKV files cause the Roku client to auto-select them. Roku can't decode PGS natively, so Jellyfin must burn them in — triggering a full subtitle extraction pass and video transcode before any data reaches the client. 178 out of ~400 movies in the library had this flag set, mostly remuxes that predate the Tdarr `clrSubDef` flow plugin. + +**Fix:** +1. **Batch fix (existing library):** Wrote `fix-pgs-defaults.sh` — scans all MKVs with `mkvmerge -J`, finds PGS tracks with `default_track: true`, clears via `mkvpropedit --edit track:N --set flag-default=0`. Key gotcha: mkvpropedit uses 1-indexed track numbers (`track_id + 1`), NOT `track:=ID` (which matches by UID). Script is on manticore at `/tmp/fix-pgs-defaults.sh`. Fixed 178 files, no re-encoding needed. +2. **Going forward (Tdarr):** The flow already has a "Clear Subtitle Default Flags" custom function plugin (`clrSubDef`) that clears default disposition on non-forced subtitle tracks during transcoding. New files processed by Tdarr are handled automatically. + +**Lesson:** Remux files from automated downloaders almost always have PGS defaults set. Any bulk import of remuxes should be followed by a PGS default flag sweep. The CIFS media mount on manticore is read-only inside the Jellyfin container — mkvpropedit must run from the host against `/mnt/truenas/media/Movies`. + ## Related Documentation - **Setup Guide**: `/media-servers/jellyfin-ubuntu-manticore.md` - **NVIDIA Driver Management**: See jellyfin-ubuntu-manticore.md