StreamVault is a TV-first free IPTV player for Android TV built with Kotlin, Jetpack Compose, Room, Hilt, and Media3.
Kotlin iptv-player
docs: design native Kodi adaptive M3U support
David Nashashfa1444d4c7b8
diff --git a/docs/superpowers/specs/2026-09-18-native-kodi-adaptive-m3u-design.md b/docs/superpowers/specs/2026-09-18-native-kodi-adaptive-m3u-design.mdnew file mode 100644index 00000000..2fd489eb--- /dev/null+++ b/docs/superpowers/specs/2026-09-18-native-kodi-adaptive-m3u-design.md@@ -0,0 +1,230 @@+# Native Kodi Adaptive M3U Support Design++## Summary++StreamVault will import and play the commonly used Kodi `inputstream.adaptive`+metadata embedded in M3U playlists. The feature covers remote-license Widevine,+PlayReady, and ClearKey streams, plus static ClearKey material such as the+`KID:key` form reported in GitHub issue #169.++The implementation will parse only explicitly supported directives, normalize+them into a typed model, persist that model as versioned JSON with each imported+channel or movie, and translate it into the existing `StreamInfo` DRM and HTTP+configuration at playback time. Static ClearKey responses will use Media3's+local DRM callback and will never be placed in URLs or logs.++## Goals++- Play JioTV-style DASH entries whose Kodi properties specify a Widevine license+ URL.+- Play URL-licensed PlayReady and ClearKey entries through the existing Media3+ DRM configuration path.+- Play DASH ClearKey entries whose license value contains hexadecimal, base64,+ JSON-map, or JWK-form static key material.+- Preserve recognized per-entry manifest, stream, common, and license headers.+- Preserve `#EXTVLCOPT` user-agent and referer directives.+- Retain the metadata across sync, application restart, channel grouping, and+ movie classification.+- Reject malformed or excessive metadata without rejecting an otherwise valid+ playlist entry.+- Keep DRM secrets out of URLs, media identifiers, and diagnostic logs.++## Non-goals++- Rewriting or proxying an MPD that lacks usable ClearKey `ContentProtection`,+ `default_KID`, or equivalent initialization data.+- Supporting arbitrary Kodi directives or executing opaque directive content.+- Implementing DRM for external players or Cast receivers.+- Discovering, downloading, or deriving keys that are not already supplied by+ an authorized playlist.+- Changing Xtream, Stalker, Jellyfin, or plugin DRM behavior.++## Accepted M3U directives++The parser will recognize these directives between an `#EXTINF` line and its+media URL:++- `#KODIPROP:inputstream=inputstream.adaptive`+- `#KODIPROP:inputstream.adaptive.manifest_type`+- `#KODIPROP:inputstream.adaptive.license_type`+- `#KODIPROP:inputstream.adaptive.license_key`+- `#KODIPROP:inputstream.adaptive.license_headers`+- `#KODIPROP:inputstream.adaptive.stream_headers`+- `#KODIPROP:inputstream.adaptive.common_headers`+- `#EXTVLCOPT:http-user-agent`+- `#EXTVLCOPT:http-referrer`+- `#EXTVLCOPT:http-referer`++Names will be matched case-insensitively. Unknown directives will continue to be+ignored. A later duplicate of a scalar directive will replace the earlier value;+header maps will merge in encounter order, with later values replacing earlier+values for the same case-insensitive header name.++## Normalized model++The data module will define a focused `M3uPlaybackMetadata` model. It will hold:++- an optional manifest type;+- an optional normalized DRM scheme;+- either a validated remote license URL or validated static ClearKey material;+- manifest, stream, common, and license header maps;+- an optional user-agent;+- an optional referer;+- a serialization version.++Static ClearKey material will be represented structurally as key-ID/key byte+pairs. It will not be represented as a fake license URL. The model will expose+only redacted diagnostics.++The persisted JSON codec will be owned by the data module. Unknown JSON fields+will be ignored for forward compatibility. Unknown serialization versions,+malformed JSON, or invalid values will decode to no playback metadata rather+than preventing catalog access.++## Parsing and validation++`M3uParser` will accumulate supported directives in the pending entry alongside+the existing `#EXTINF` metadata. Parsing remains streaming and bounded.++Validation rules:++- Only `http` and `https` remote license URLs are accepted.+- DRM aliases normalize as follows:+ - `widevine` and `com.widevine.alpha` -> Widevine;+ - `playready` and `com.microsoft.playready` -> PlayReady;+ - `clearkey` and `org.w3.clearkey` -> ClearKey.+- Manifest aliases normalize to DASH, HLS, or SmoothStreaming. Unknown values do+ not override normal stream-type detection.+- Static ClearKey KIDs and keys must decode to exactly 16 bytes.+- Hex pairs, comma-separated pairs, JSON key maps, and JWK `keys` arrays are+ accepted. Duplicate KIDs use the last valid value.+- Header names and values must pass explicit count and length limits. Hop-by-hop+ headers and headers that would override `Host` or content framing are rejected.+- Directive and serialized-payload lengths are bounded through the existing M3U+ ingestion limits or tighter feature-specific limits.+- A DRM scheme without usable license data is discarded. Non-DRM headers and the+ playlist entry remain usable.+- Static key material is accepted only for ClearKey.++The parser will preserve enough information for import warnings and tests, but+will not log raw license values or static keys.++## Persistence++Room will add a nullable `playback_metadata_json` column to both the `channels`+and `movies` tables. Existing rows receive `NULL`. The database version and+migration registry will advance by one version, and exported Room schemas will+be updated through the normal schema-generation task.++M3U synchronization will encode normalized metadata when constructing staged+`ChannelEntity` and `MovieEntity` rows. Sync fingerprints must include a stable,+non-secret digest of the normalized metadata so that metadata-only playlist+changes update the row. Raw DRM key values must not appear in fingerprints or+logs.++Entity/domain mapping will carry the persisted payload through raw and grouped+channel variants. Selecting a grouped variant must select that variant's+playback metadata. Movies must retain the metadata after automatic or manual M3U+classification.++Backup and restore behavior will follow existing database backup semantics. No+new plaintext diagnostics or exported human-readable key fields will be added.++## Playback translation++When an M3U channel or movie is resolved, its decoded metadata will enrich the+resulting `StreamInfo`:++- normalized manifest type supplies an explicit `StreamType`;+- common and stream headers apply to manifest and segment requests;+- user-agent and referer are mapped to the existing request configuration;+- license headers apply only to remote DRM license requests;+- a remote license URL creates the existing `DrmInfo` configuration;+- static ClearKey material creates a separate local ClearKey payload on+ `DrmInfo`.++`DrmInfo` will enforce that exactly one license source is present: a remote URL+or a local ClearKey response. Existing plugin callers remain source-compatible+by retaining the remote-license constructor defaults.++For static ClearKey, the player will:++1. Convert each validated 16-byte KID and key to unpadded base64url.+2. Build a temporary ClearKey JWK response in memory.+3. Create a `DefaultDrmSessionManager` for `C.CLEARKEY_UUID` using+ `LocalMediaDrmCallback`.+4. Install that manager through the selected media-source factory's DRM session+ manager provider.+5. Configure the `MediaItem` for ClearKey without a license URI.++Remote licenses continue through Media3's default HTTP DRM callback. The+media-source cache/preload identity will include only a digest of DRM material,+never the material itself. Existing policy that disables preload, frame+thumbnails, recording, timeshift, and Cast where DRM is unsupported remains in+force.++## Error handling++Malformed adaptive metadata will not abort the full playlist import. The entry+will be imported with every independently valid piece of metadata. If the DRM+combination is unusable, playback proceeds as an ordinary stream and Media3 can+report encryption failure normally.++Parser and codec failures will produce bounded, sanitized warnings containing+the provider and entry identity but no license URL query values, headers, KIDs,+or keys. Playback failures will continue through the existing DRM error+classification.++## Compatibility and rollout++Existing playlists without Kodi properties retain identical behavior. Existing+plugin-provided DRM remains on the remote-license path. Database migration must+be additive and safe for current installations.++Native support is intentionally narrower than Adaptive Bridge. Streams whose+manifests require ClearKey signaling injection remain unsupported natively and+may continue to use the bridge. If device validation shows that otherwise valid+issue #169 streams fail solely because the MPD lacks ClearKey initialization+data, manifest rewriting will be designed as a separate feature.++## Testing++Automated tests will be written before production changes and will cover:++- parsing each supported directive and alias;+- directive ordering and duplicate behavior;+- per-entry user-agent and referer handling;+- remote Widevine, PlayReady, and ClearKey license URLs;+- single and multiple static ClearKey pairs in hex, base64, JSON-map, and JWK+ formats;+- rejection of malformed keys, unsafe URLs, forbidden headers, and oversized+ values;+- codec round trips and unknown/malformed versions;+- Room migration and generated schema validation;+- sync persistence for live channels and movies;+- grouped-channel variant metadata selection;+- repository translation into `StreamInfo`;+- remote DRM `MediaItem` configuration;+- local ClearKey JWK generation and local DRM session-manager selection;+- media identifiers and logs not containing supplied DRM secrets;+- non-DRM M3U regression behavior.++Device validation requires authorized test streams. For each live DRM channel,+capture 61 screenshots at two-second intervals, verify continuing frame-hash+changes, confirm the media session remains `PLAYING` with no error, and inspect+sanitized logs for DRM/player failures. Validate at least one Widevine DASH+channel, one static-ClearKey DASH channel, and one non-DRM regression channel.++## Acceptance criteria++- A direct JioTV-style M3U entry with a Widevine HTTPS license URL plays without+ Adaptive Bridge.+- An issue #169-style DASH entry with a valid static ClearKey `KID:key` reaches+ Media3 through a local DRM callback and plays when its MPD contains compatible+ ClearKey signaling.+- Recognized headers, user-agent, referer, and manifest type survive sync and+ application restart.+- Grouped channels use the selected variant's DRM metadata.+- Invalid DRM metadata cannot crash or reject the complete provider import.+- No test output, production log, media ID, or URL contains raw static keys.+- Existing non-DRM and plugin DRM tests continue to pass.