Skip to content

Module: src/streaming/FairPlay

The FairPlay component handles Apple FairPlay DRM for HLS streams on Safari browsers. It works by setting up a WebKit key session using the webkitneedkey API, obtaining a DRM certificate, creating the SPC message, retrieving the license, and initializing secure playback. The plugin only activates on Safari browsers and registers itself during initialization.

Version
1.0.0
Author
Frank Kudermann - alphanull
License
MIT
Requires
ExtendedMediaError
Source
FairPlay.js, line 59

Constructor

new FairPlay(player, mediaComponent, apiKey)

Creates an instance of the FairPlay plugin.

Parameters:
Name Type Description
player Player

Reference to the player instance.
mediaComponent Media

Reference to the engine (video) instance.
apiKey symbol

Token for extended access to the player API.

Members

Reference to the main player instance.

Type
Player
Source
FairPlay.js, line 65

Reference to the video Element.

Type
HTMLVideoElement
Source
FairPlay.js, line 71

Secret key only known to the player instance and initialized components. Used to be able to restrict access to API methods in conjunction with secure mode.

Type
symbol
Source
FairPlay.js, line 78

License server URL.

Type
string
Source
FairPlay.js, line 84

License request headers.

Type
Object<string, string>
Source
FairPlay.js, line 90

The current MediaKeySession instance.

Type
MediaKeySession
Source
FairPlay.js, line 96

The resolve callback to unblock media.load().

Type
function
Source
FairPlay.js, line 102

Methods

private, static stringToUint16Array(string) → Uint16Array

Converts a string to a Uint16Array.

Parameters:
Name Type Description
string string

Input string.
Returns

Converted array.

Type Uint16Array
Source
FairPlay.js, line 10

private, static uInt16arrayToString(array) → string

Converts a Uint16Array to a string.

Parameters:
Name Type Description
array Uint16Array

Input array.
Returns

Converted string.

Type string
Source
FairPlay.js, line 19

private, static uInt8ArrayToString(array) → string

Converts a Uint8Array to a string.

Parameters:
Name Type Description
array Uint8Array

Input array.
Returns

Converted string.

Type string
Source
FairPlay.js, line 28

private, static base64DecodeUint8Array(input) → Uint8Array

Decodes a base64-encoded string into a Uint8Array.

Parameters:
Name Type Description
input string

Input string.
Returns

Converted array.

Type Uint8Array
Source
FairPlay.js, line 37

private, static base64EncodeUint8Array(input) → string

Encodes a Uint8Array into base64 string.

Parameters:
Name Type Description
input Uint8Array

Input array.
Returns

Converted string.

Type string
Source
FairPlay.js, line 46

canPlay(metaData) → string

Checks if this plugin can handle a given MIME type and DRM system.

Parameters:
Name Type Description
metaData Media~metaData

The data to test.

Parameters:
Name Type Attributes Description
mimeType string

The mime type to test.
drmSystem string optional

Optional DRM system info.
Returns

"maybe" if playable, otherwise an empty string.

Type string
Source
FairPlay.js, line 134

async load(metaData)

Initializes the FairPlay session if the source is HLS and has FairPlay DRM. Loads the certificate if not provided inline, sets up the video src, and waits for "webkitneedkey" event to start encryption handling.

Parameters:
Name Type Description
metaData Media~metaData

metaData to load.

Parameters:
Name Type Description
src string

The HLS URL to load.
Throws

If not Safari or .m3u8 or lacking 'drm.FairPlay'.

Type Error
Source
FairPlay.js, line 147

async, private #encrypted(event, certificate) → Promise<void>

Initializes and prepares the FairPlay key session.

Parameters:
Name Type Description
event Event

The "webkitneedkey" event.
certificate Uint8Array

The DRM certificate.
Returns
Type Promise<void>
Throws

If creating mediaKeys or the key sessions fails for any reason.

Type Error
Source
FairPlay.js, line 192

private #keyMessage(event)

Handles license requests when "webkitkeymessage" event is fired.

Parameters:
Name Type Description
event Event

Event containing the license challenge.
Source
FairPlay.js, line 228

private #keyAdded()

Called when "webkitkeyadded" fires, meaning the DRM session is successfully set up.

Source
FairPlay.js, line 242

private #keyError()

Called when "webkitkeyerror" fires, meaning the DRM session encountered an error.

Throws

If a key session error code is found.

Type Error
Source
FairPlay.js, line 252

destroy()

This method removes all events, subscriptions and DOM nodes created by this component.

Source
FairPlay.js, line 262

async, private, static #loadCertificate(certificateUrl) → Promise<Uint8Array>

Loads the FairPlay DRM certificate from the specified URL.

Parameters:
Name Type Description
certificateUrl string

URL to the DRM certificate.
Returns

The fetched certificate as Uint8Array.

Type Promise<Uint8Array>
Source
FairPlay.js, line 279

private, static #createSpc(contentId, initData, cert) → Uint8Array

Creates the FairPlay "SPC" message to request a license.

Parameters:
Name Type Description
contentId string

Content identifier (from SKD URL).
initData Uint8Array

Initialization data.
cert Uint8Array

DRM certificate.
Returns

SPC request message.

Type Uint8Array
Source
FairPlay.js, line 297

async, private, static #getLicense(event, spcPath, headers) → Promise<Uint8Array>

Fetches the license by sending the SPC message to the DRM license server. Expects a base64-encoded response.

Parameters:
Name Type Description
event Event

The webkitkeymessage event containing the message.
spcPath string

The license server url.
headers Object<string, string>

HTTP headers for the license request.
Returns

The license data.

Type Promise<Uint8Array>
Source
FairPlay.js, line 338