Recover a stalled player startup
without guessing.

Player appears to "do nothing" for several seconds before throwing MediaError. curl from the same edge returns the master playlist in <300ms; no JS-level error fires.

player.network.manifest_fetch → fail (timed out at 5000ms); player.network.tls_handshake → fail; player.network.cors_preflight → fail. Decode and init probes are pending because the manifest never returned.

Verify the manifest URL from the failing edge IP block (NOT a healthy POP). Confirm preflight headers are present on segment-init and that the CDN does not 304 the master on the cold first-request. The agent never starts the probe cascade without a 200 from manifest_fetch.

Console shows two "destroying MediaSource" logs before BUFFER_APPENDED; the player never reaches FIRST_FRAME. manifest fetch, TLS, and CORS preflight all return green.

player.network.* → pass (manifest, TLS, CORS); player.init.hls_attached → fail; player.init.sourcebuffer_open → never reached. Decode lane is gated behind init — its probes are pending.

Pin the engine build to a version that handles iOS / Safari 17 MediaSource detach correctly; the typical fix is upgrading hls.js to the latest minor and enabling enableWorker=true in the config. The agent will then run sourcebuffer_open and report its verdict on the next probe.

Player reaches FIRST_FRAME after a short stall then drops back to a black canvas with a "video can't be played" overlay. Audio plays; video is blank or frozen.

player.network.* → pass; player.init.* → pass (hls_attached + sourcebuffer_open both green); player.decode.codec_negotiation → fail; player.decode.first_frame_ms → fail at t=4631ms.

Confirm the variant CODECS string covers every referenced audio group ("avc1.640028" alone is the common culprit — full string is "mp4a.40.2,avc1.640028"). codec_negotiation passes on the next probe once the audio codec is included in every STREAM-INF.

Player attaches, source buffer opens, but the video never starts. Browser has muted the page by autoplay policy; user has not interacted with the document yet.

player.network.* + player.init.* + player.decode.codec_negotiation → pass; player.autoplay.gesture_required → fail (no user gesture on document); player.decode.first_frame_ms → pending (decoded, then muted by policy).

The probe correctly fails on the autoplay gate — do NOT bypass it by setting autoplay=true. Surface the play button with a mute toggle so the first user gesture is captured into the SAME gesture token the browser consumes; autoplay will flip to pass on the next probe after the gesture fires.

Player attaches, MSE opens, codec negotiation passes, but the decoded first frame never paints. Network stalls at first-frame.ts — players that poll for it more than once will dead-lock.

player.network.manifest_fetch + player.init.* → pass; player.decode.codec_negotiation → pass; player.decode.first_frame_ms → fail at t=4972ms (timeout 4500ms).

Confirm the first-frame segment is reachable from the same edge IP block — usually a CDN miss on /init/segments/0001.ts. Pull a manual HEAD request to verify; once the segment serves green, first_frame_ms will return a value under 2500ms.

Console logs "Failed to execute appendBuffer on SourceBuffer" with the MIME the source buffer was opened with. Player rolls back to the start of the preroll after a hard stall.

player.network.* + player.init.* → pass; player.decode.codec_negotiation → fail; the codec mismatch is the smoking gun — STREAM-INF declares avc1 but init.mp4 is mp4v.

Align the init.mp4 ftyp brand with the variant CODECS string. Once the MIME on the source buffer matches the bytes appended, codec_negotiation will pass.

Player plays for ~30s, then throws "QuotaExceededError: Upgrading in-flight MSE storage" and stalls. The buffer is configured but the actual bytes-on-the-wire exceed the source-buffer quota for the platform.

player.network.* + player.init.* → pass; player.decode.codec_negotiation → pass; player.decode.first_frame_ms → pass; player.decode.sourcebuffer_quota → fail (peak_bytes=1.4GB > quota=1.1GB).

Reduce the maximum buffer length (maxBufferLength=120 in hls.js config) OR raise the platform MSE quota; the probe will flip to pass when peak_bytes stays under quota for one cycle.

Player replays the buffer after a 3-second stall at the discontinuity, then drops a "decode error" and aborts the rendition. Media tracks come back inconsistent for a brief window.

player.network.* + player.init.* → pass; player.decode.first_frame_ms → pass; player.decode.discontinuity_decode → fail; player.decode.sourcebuffer_quota → pass.

Inspect the segment before / after the discontinuity boundary; in CMAF packaging, the ftyp brand set must match across the boundary. Force the packager to re-emit the segment pair and the discontinuity_decode probe will flip to pass.

Long-running live session jumps backwards by exactly 26.5 hours at the PTS wrap point. Player restarts the timeline but the source buffer is now out-of-order.

player.network.* + player.init.* → pass; player.decode.* → fail around the wrap; decoder re-syncs but ABR ladder mis-orders the variants until the next refresh.

Wrap-safe PTS handling on the packager + a refresh that lands the new PDT within the segment.tail_window; the decoder_recovery probe will flip to pass when wrap is recognized.

Widevine / PlayReady attach hangs past 4500ms; player renders black and waits. Manifest, init, and decode are otherwise fine — but the DRM envelope never opened.

player.network.* → pass; player.init.hls_attached → pass; player.init.drm_attach → fail at t=4872ms; player.init.sourcebuffer_open → pending (gate on EME).

Verify the keyserver from the failing edge; the EME attach requires the keyserver URL to be reachable on the same path as the segment-init. If keyserver reachability is the cause, fix the network path; if it is a license-server-side slow response, raise the EME attach timeout — the agent flags the value as a parameter to tune.