Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
8.1 KiB
@videojs/spf/features/drm
Source: src/playback/features/drm.ts
drmFeature
Plays DRM-protected content through Encrypted Media Extensions: negotiates a key system over the configured license servers, attaches its MediaKeys, and exchanges licenses. Segment loading waits until a source is confirmed clear or its MediaKeys attach.
Requires writers of resolved, selected video or audio renditions, such as videoFeature and audioFeature; without
them, no source is ever confirmed clear and loading stays blocked.
Replaces canPlayTrack and reportUnsupportedTrackConditions with DRM-aware versions, and sets DRM-aware video and
audio constraints. Compose it after the features that set the plain versions, such as videoFeature and
audioFeature, or theirs win and encrypted renditions are refused.
Behaviors
Config
Feature default is the value a feature's defaultConfig supplies. A behavior's own fallback for a key left unset is described under Doc.
| Key | Type | Feature default | Read by | Doc |
|---|---|---|---|---|
audioConstraints |
readonly SwitchAudioTrackRule[] |
[...DEFAULT_AUDIO_CONSTRAINTS, excludeRefusedKeySystems] |
switchAudioTrack | switchAudioTrack's chains, replacing DEFAULT_AUDIO_CONSTRAINTS / DEFAULT_AUDIO_RULES. |
canPlayTrack |
CanPlayTrack |
canPlayTrackWithDrm |
switchAudioTrack, switchVideoTrack | Codec capability probe read by the excludeUnplayableTracks hard constraint — drops renditions this environment can't decode before selection runs. Injected (rather than imported) so the DOM-free behavior never reaches a DOM API directly; the HLS engines default it to the MediaSource.isTypeSupported-backed canPlayTrack, or canPlayTrackWithDrm where they compose DRM. Absent → no codec filtering (the constraint passes everything through). |
drm |
Partial<Record<string, DrmSystemConfig>> & { readonly [keyedBy]?: { readonly source: "keySystems"; readonly id: "keySystem"; } | undefined; } |
No license servers configured ({}) |
exchangeLicenses, setupMediaKeys | License servers keyed by EME key-system id — source.drm's shape, limited to the composed key systems. |
keySystems |
readonly KeySystemModule<string>[] |
DEFAULT_KEY_SYSTEMS |
exchangeLicenses, setupMediaKeys | The key systems this composition can negotiate, most-preferred first. |
reportUnsupportedTrackConditions |
ReportUnsupportedTrackConditions |
reportUnsupportedTrackConditionsWithDrm |
resolveAudioTrack, resolveTextTrack, resolveVideoTrack | Playlist-derived condition reporting (see primitives/report-track-conditions). |
videoConstraints |
readonly SwitchVideoTrackRule[] |
[...DEFAULT_VIDEO_CONSTRAINTS, excludeRefusedKeySystems] |
switchVideoTrack | The hard-constraint pre-pass and rule chain switchVideoTrack runs, replacing DEFAULT_VIDEO_CONSTRAINTS / DEFAULT_VIDEO_RULES outright — the same whole-chain contract as selectVideoTrack's videoConstraints / videoRules. Spread the default to extend it: [...DEFAULT_VIDEO_CONSTRAINTS, excludeRefusedKeySystems] is how the DRM composition prunes on a signal only it carries. Keyed per type because one engine config reaches every variant. |
State
| Key | Type | Initial | Declared by | Doc |
|---|---|---|---|---|
negotiatedKeySystem |
string | undefined |
— | exchangeLicenses, setupMediaKeys | The key system negotiation settled on for the current source, or undefined when none has been (yet, or at all). The negotiation outcome as state, not just as the private detail it once was: exchangeLicenses keys its per-system message shaping and license-server lookup off it, and it is the late fact rendition pruning can't otherwise learn — pruning runs before the CDM has been asked, so a rendition naming a configured server survives it and only negotiation reveals the CDM is absent. |
presentation |
MaybeResolvedPresentation | undefined |
— | exchangeLicenses, setupMediaKeys | The presentation being played. A caller writes { url }; resolvePresentation parses the manifest and populates the rest. (documented on resolvePresentation) |
segmentLoadingBlocked |
boolean | undefined |
— | setupMediaKeys | Segment-load gate: true from each new source until it is confirmed clear or its MediaKeys attach, and still true after a failed negotiation. The loadXSegments dispatchers start no segment loads while it holds. |
Context
| Key | Type | Declared by | Doc |
|---|---|---|---|
mediaElement |
HTMLMediaElement | undefined |
exchangeLicenses, setupMediaKeys | The media element the engine drives. No behavior writes it: an adapter attaches one with engine.context.mediaElement.set(element) and detaches with set(undefined), as SPF's adapters do. (documented on setupMediaSource) |
mediaKeys |
MediaKeys | undefined |
exchangeLicenses, setupMediaKeys | The attached MediaKeys for an encrypted source, owned by setupMediaKeys. |
Composed by
Other functions and constants
| Name | Kind | Description | Source |
|---|---|---|---|
behaviors |
const | The behaviors the feature composes, in setup order. Listed under Behaviors. | src/playback/features/drm.ts |
defaultConfig |
const | The config defaults the feature contributes. Its value: see value below. | src/playback/features/drm.ts |
initialState |
const | The state values the feature seeds. It seeds none ({}). |
src/playback/features/drm.ts |
Types
| Name | Kind | Description | Source |
|---|---|---|---|
Behaviors |
type | The type of behaviors. |
src/playback/features/drm.ts |
Config |
type | Every config key the behaviors read. Listed under Config. | src/playback/features/drm.ts |
Context |
type | Every context key the behaviors declare. Listed under Context. | src/playback/features/drm.ts |
State |
type | Every state key the behaviors and external signals declare. Listed under State. | src/playback/features/drm.ts |
defaultConfig value:
{ drm: noLicenseServers, keySystems: defaultKeySystems, canPlayTrack: canPlayTrackWithDrm, videoConstraints: drmAwareVideoConstraints, audioConstraints: drmAwareAudioConstraints, reportUnsupportedTrackConditions: reportUnsupportedTrackConditionsWithDrm }