[Bug]: Some Plex videos fail HLS playback and fall back to direct media

[KyleTryon]

Impacted media sources

• Plex
• Jellyfin

Cliparr version

Current development branch while investigating Plex HLS diagnostics. Related PR: #161

Browser type and version

Observed from Chrome playback diagnostics in local development logs.

What happened?

Some Plex videos appear to start through the expected HLS path, but the HLS segment fetches fail and Cliparr falls back to direct media instead.

From the Rick and Morty example in /tmp/cliparr.log:

• Cliparr created an HLS media handle for the currently playing Plex item.
• Plex returned 200 for /video/:/transcode/universal/start.m3u8.
• Plex returned 200 for the nested session playlist, e.g. /video/:/transcode/universal/session/.../base/index.m3u8.
• Cliparr rewrote the nested playlist successfully, including 133 HLS entries.
• The first segment request, e.g. /video/:/transcode/universal/session/.../base/00000.ts, returned 404 after retry attempts.
• Cliparr then fell back to direct media, which succeeded with 206 video/x-matroska.

This suggests the failure is not simply "Cliparr chooses direct media first." HLS is attempted, but Plex appears to provide playlists whose referenced segment files are unavailable by the time Cliparr asks for them.

Subtitles may be a separate issue. The failing examples had embedded subtitle tracks that Cliparr/Mediabunny do not currently support, but the logged HLS request path used subtitles=none, and the segment 404 still occurred. Based on current evidence, subtitles do not appear to be the cause of the HLS fallback.

Steps to reproduce

1. Start playback for an affected Plex item.
2. Open Cliparr and load the currently playing media.
3. Request a clip/editor preview that should use the HLS media URL.
4. Watch server logs around HLS playlist fetches and segment fetches.
5. Observe that HLS playlist requests succeed, the first segment request fails with 404, and Cliparr falls back to direct media.

Expected behavior

When Plex can provide HLS for a currently playing item, Cliparr should continue using the HLS stream instead of falling back to direct media.

If Plex cannot provide usable HLS segments for that item, Cliparr should expose a clear diagnostic reason so the UI can eventually explain that HLS failed and direct media was used as a fallback.

Extra details / investigation notes

Potential correlations to investigate:

• MKV container vs MP4 or other containers.
• Specific codec combinations, e.g. H.264 video with EAC3 audio.
• Plex remote/direct connection behavior.
• Whether the active Plex playback session id affects segment availability.
• Whether Plex behaves differently when Cliparr supplies its own transcode session identifier vs reusing the active playback session identifier vs omitting the session identifier.

Suggested next debugging:

• Fetch the raw Plex HLS root playlist, nested playlist, and first segment outside Cliparr with the same token and request headers.
• Compare X-Plex-Session-Identifier variants: active Plex playback session, no session identifier, and a Cliparr-owned preview/transcode identifier.
• Inspect Plex Transcoder logs for the internal session id from the failing segment path.
• Collect more examples, especially a matrix of working and failing MKV/MP4 files with codec, subtitle, and connection metadata.
• Add tests for the observed fallback shape once the Plex behavior is better understood. PR chore(server): add HLS proxy diagnostics #161 adds diagnostic context and a small metadata unit test, but does not yet emulate Plex returning valid playlists followed by missing segment files.