iptvnator/docs/superpowers/specs/2026-07-30-structured-hls-diagnostics-design.md

Structured HLS Diagnostics

Context

PR #1314 made native media diagnostics evidence-based, but the HLS path still normalizes type, details, message, and an arbitrary error payload into one string. classifyHlsPlaybackIssue then searches that string for broad fragments such as network, status, and codec. This can misclassify a provider message, and serializing arbitrary values can retain URLs, credentials, response content, loader context, or other provider data.

IPTVnator currently installs hls.js 1.6.16. Its public ErrorData supplies structured type, details, fatal, and an optional response.code. Specific ErrorDetails values also identify the manifest, level, segment, key, or media stage. The same payload contains unsafe or unbounded fields, including error, reason, networkDetails, context, loader, url, and response URL/text/data, which are not needed for classification.

Both the HTML5 player and ArtPlayer subscribe to Hls.Events.ERROR. They currently ignore fatal: false before calling the classifier, but each adapter builds the broad string input independently.

Goals

• Create one structured HLS evidence boundary for the installed hls.js error shape.
• Retain only allowlisted engine type/detail identifiers, the final fatal/recoverable disposition, a stage derived from exact details, a structured failure kind, and a validated HTTP status when present.
• Classify HLS failures from exact engine values rather than substring heuristics.
• Keep insufficient evidence explicitly unknown.
• Ensure recoverable hls.js events never become terminal playback diagnostics.
• Use the same extraction and classification path in HTML5 and ArtPlayer.
• Show only the sanitized evidence in technical diagnostic details.

Non-goals

• Diagnostic history, persistence, correlation, or telemetry.
• Additional manifest or stream probes.
• Automatic player failover.
• A Shaka or mpegts.js diagnostic redesign.
• A cross-player confidence or likelihood matrix.
• Inferring browser access failures from status zero, TypeError, or error message text.
• Changing hls.js retry, level-switch, or recovery behavior.

Approaches Considered

Boundary sanitizer (selected)

Convert hls.js ErrorData into a small HlsPlaybackEvidence value at the adapter boundary. The classifier accepts only that value. This centralizes the allowlist, makes unsafe fields structurally unavailable to classification and UI code, and gives HTML5 and ArtPlayer identical behavior.

Pass ErrorData directly

This would preserve the strongest TypeScript relationship with hls.js, but it would leave every consumer able to read or render URLs, loader state, headers, response payloads, and arbitrary errors. It also makes privacy depend on each future call site remembering the same exclusions.

Keep the broad input and tighten string tests

Exact comparisons could improve classification, but the adapters would still copy arbitrary messages and objects into diagnostics. This would not establish the requested safe evidence contract.

Evidence Contract

HlsPlaybackEvidence contains:

• engineType: one of the installed hls.js ErrorTypes values, otherwise unknown;
• engineDetails: one of the installed hls.js ErrorDetails values, including its existing unknown value;
• disposition: fatal when ErrorData.fatal === true, otherwise recoverable;
• stage: manifest, level, segment, key, media, or unknown;
• failure: http, timeout, network, access, or unknown;
• optional httpStatus: an integer from 100 through 599 copied only from ErrorData.response.code.

The access value is part of the contract but hls.js 1.6.16 does not expose a reliable structured CORS, mixed-content, CSP, or private-network-access code. Status zero and generic fetch failures can also mean DNS, offline, connection, or abort failures. The extractor therefore does not emit access for current runtime shapes; it uses network or unknown and never inspects message text.

The extractor does not copy:

• ErrorData.url;
• context, including request URLs and headers;
• networkDetails or loader instances;
• response.url, response.text, or response.data;
• error, deprecated err, reason, events, fragments, or arbitrary values.

The existing playback metadata still carries the active source URL for the pre-existing Retry, Copy URL, and explicit external-player workflows. No HLS error URL is copied into evidence or shown in technical details.

Stage Mapping

Stages are derived only from exact ErrorDetails values:

• manifest: manifest load, timeout, parsing, and incompatible-codec details;
• level: level load, timeout, parsing, empty, and switch details, plus audio/subtitle track playlist load details;
• segment: fragment load, timeout, parsing, decrypt, and gap details;
• key: key load/timeout and key-system details;
• media: buffer, mux/remux, attach-media, and playback-stall details;
• unknown: internal, aborted, interstitial, unrecognized, or otherwise unmapped details.

This mapping describes the engine stage, not root-cause likelihood. For example, a segment-stage timeout is still classified as a network timeout.

Failure Mapping

Failure kind uses this precedence:

1. Exact timeout details produce timeout.
2. A validated 4xx or 5xx response.code produces http.
3. Exact network load-error details, or the exact networkError engine type, produce network.
4. No current hls.js 1.6.16 field independently proves access.
5. Everything else is unknown.

A 1xx, 2xx, or 3xx status remains retained as factual response metadata but does not by itself produce an HTTP-failure kind.

Classification

classifyHlsPlaybackIssue returns PlaybackDiagnostic | null:

1. recoverable returns null before classification.
2. Exact incompatible/add-codec details produce unsupported-codec.
3. Exact key-system or fragment-decrypt evidence produces drm-or-encryption.
4. Exact network type, load/timeout details, or HTTP failure evidence produces network-error.
5. Exact media or mux type produces media-decode-error.
6. Everything else produces unknown-playback-error.

The HLS path does not emit browser-access-error without structured access evidence. It also does not classify keyLoadError as DRM: failure to fetch an encryption key is network evidence, while fragDecryptError and key-system details are encryption/DRM evidence.

The normalized PlaybackDiagnostic retains the sanitized HLS evidence and copies its validated HTTP status into the existing top-level httpStatus field. External fallback recommendations continue to derive from the final diagnostic code.

Adapter Flow

HTML5 and ArtPlayer both use:

1. createHlsPlaybackEvidence(data);
2. classifyHlsPlaybackIssue(evidence, sourceMetadata);
3. emit only when the classifier returns a diagnostic.

The fatal gate therefore lives in the shared classifier rather than being duplicated in the two adapters. hls.js registers its final error-controller listener during construction, before IPTVnator subscribes, so the application observes the final fatal value after retry/alternate handling has had a chance to update it.

User Interface

The existing technical “Error details” row renders a deterministic, safe HLS summary made only from the evidence fields, for example:

stage=manifest · failure=http · type=networkError · details=manifestLoadError · disposition=fatal · HTTP 404

No HLS error message, URL, header, body, response text, or arbitrary provider payload appears. HLS startup development logs are event-only and omit provider-supplied channel names and source URLs. Existing title/description and HTTP metadata rendering remain unchanged, so no new translation keys or layout changes are required.

Testing

Use test-driven development:

• Add extractor tests using hls.js 1.6.16-shaped manifest, level, segment, key, media, HTTP, timeout, and unknown payloads.
• Prove unrecognized runtime values become unknown.
• Prove response URLs/text/data, request context/headers, error messages, network details, and credential-shaped payloads do not appear in evidence or rendered details.
• Add classifier tests for exact codec, DRM, network, media, and unknown values.
• Prove misleading strings cannot override structured engine values.
• Prove recoverable events return null.
• Update HTML5 and ArtPlayer integration tests to cover fatal HTTP evidence and recoverable suppression through the shared path.
• Add a focused view test for the deterministic safe HLS summary.

Run the complete ui-playback unit target, its lint target, the web typecheck, i18n drift validation, and release-note validation. No E2E is required because the player workflow and diagnostic controls are unchanged; adapter, classifier, and rendered-detail behavior are covered at their closest unit/component boundaries.

Documentation And Release Note

Update docs/architecture/embedded-inline-playback.md, the canonical playback diagnostic description, to replace raw HLS details with the structured contract. Add a fix(playback) release note because users receive more accurate HLS diagnoses and safer technical details.