This module is available to use in your EdgeWorkers code bundle to parse and modify HTTP Live Streaming (HLS) playlist files.

The protocols for transferring unbounded streams of multimedia data, as described in RFC 8216, were applied when creating this EdgeWorkers module.

Currently the HLS parser only accepts complete UTF-8 encoded m3u8 playlist file contents and does not work in streaming mode to parse chunks of data.

👍 Refer to Import a JavaScript module for instructions on how to load an external JavaScript module into the EdgeWorkers main.js file.

Code samples and use cases

Go to the the EdgeWorkers GitHub repo for access to the HLS module, the main helper class you need to import into your main.js file and the TypeScript definition file.

To help you learn more about how to use the HLS Parser module, we’ve added the following use cases to this guide. You can also find the code samples in the EdgeWorkers GitHub repo.

Manifest and Playlist Manipulation
Dynamically create personalized renditions of available Video on demand (VOD) playlists.
Live program replacement
Dynamically replace a live stream or linear program with a blackout slate during a time period and within specific geographic locations.
Content insertion
Dynamically add auxiliary media content to an existing Video on Demand (VOD) asset using Pre-Roll, Mid-Roll, and Post-Roll operations.

Manifest Parsing

parseManifest()

Parses and creates an internal object using the input text manifest. Returns a Playlist Object.

parseManifest(text)

Parameter	Type	Description
text	UTF8 String	UTF-8 encoded string representation of the manifest input.

stringifyManifest()

Creates the manifest from the playlistObject passed from parseManifest(). Returns a string.

stringifyManifest(playlistObject)

Parameter	Type	Description
playlistObject	Object	Instance of the playListObject, MasterPlaylist, or MediaPlaylist. For more information, refer to the npm documentation on this external module.

getManifestType()

Indicates the type of playlist that was requested such as, master, media, or invalid playlist. Returns a MANIFEST_TYPE enum.

getManifestType(playlistObject)

Parameter	Type	Description
playlistObject	Object	Instance of the playList Object, MasterPlaylist, or MediaPlaylist. For more information, refer to the npm documentation on this external module.

Variant Manipulation

preserveVariantsByBitrate()

Removes all variants with specified bitrates from the playlist. Returns true if a variant is deleted by this function, false otherwise.

preserveVariantsByBitrate(playlistObject, bitrate, tolerance=100000)

Parameter	Type	Description
playlistObject	Object	Instance of the playlist Object, MasterPlaylist, or MediaPlaylist. For more information, refer to the npm documentation on this external module.
bitrate	Array of strings	Represents the bitrates. For example, 100000, 10000-20000, 20000-300000. The value is a decimal-integer of bits per second. It represents the average segment bitrate of the Variant Stream.
tolerance=100000	Number	Bitrate tolerance. By default, bitrate filtering uses a tolerance of ±100,000 bps for comparisons. For example, a parameter value of 2200000 bps will match any bitrate value within ”: “tolerance=1000” such as, 2185000. Note: Tolerance is not considered for bitrate ranges such as, 10000-20000.

preserveVariantsByResolution()

Removes all resolutions higher than the specified maximum supported resolution. It accepts a single resolution as a string in the format <width>x<height>. Returns true if a variant is deleted by this function, false otherwise.

preserveVariantsByResolution(playlistObject, maxSupportedResolution)

Parameter	Type	Description
playlistObject	Object	Instance of the playList Object, MasterPlaylist, or MediaPlaylist. For more information, refer to the npm documentation on this external module.
maxSupportedResolution	String	String representation for resolution in the format `<width>x<height>`.

moveVariantToIndex()

Moves the metadata of a variant with a given resolution to the newIndex. Returns the last index where the variant is updated. Its value can differ from the value of newIndex provided there can be repetition of the same resolution in a master playlist.

moveVariantToIndex(playlistObject, resolution, newIndex = 0)

Parameter	Type	Description
playlistObject	Object	Instance of the playList Object, MasterPlaylist, or MediaPlaylist. For more information, refer to the npm documentation on this external module.
resolution	String	String representation for resolution in format `<width>x<height>`.
newIndex = 0	Number	Index in the manifest’s variant list where the variant with the resolution needs to be moved.

updateResolutionOrder()

Moves the metadata of all variants with specified resolutions to the top. The order of these variants is preserved as provided in the array of resolutions. Providing multiple entries of the same resolution can cause undesired results. This function internally uses the moveVariantToIndex to move the respective variants. Returns true if the resolution order is updated by this function, false otherwise.

updateResolutionOrder(playlistObject, resolutions[])

Parameter	Type	Description
playlistObject	Object	Instance of the playList Object, MasterPlaylist, or MediaPlaylist. For more information, refer to the npm documentation on this external module.
resolutions[]	String	Array of string representation for resolution in format `<width>x<height>`.

Rendition Manipulation

preserveAudioRenditionByLanguage()

Removes audio renditions that use languages not specified in the master playlist. Returns true if a rendition is deleted by this function, false otherwise.

preserveAudioRenditionByLanguage(playlistObject, language)

Parameter	Type	Description
playlistObject	Object	Instance of the playList Object, MasterPlaylist, or MediaPlaylist.For more information, refer to the npm documentation on this external module.
language	String	Contains single or multiple languages to be preserved. For example, [‘EN’,‘FR’]. The value is a quoted-string containing a RFC 5646 language tag that identifies the language of the VALUE. Note: An array of any other characters ([’ ’], [‘abc’]) can remove all subtitle renditions.

preserveSubtitleRenditionByLanguage()

Removes subtitle renditions that use languages not specified in the master playlist. Returns true if a rendition is deleted by this function, false otherwise.

preserveSubtitleRenditionByLanguage(playlistObject, language)

Parameter	Type	Description
playlistObject	Object	Instance of the playList Object, MasterPlaylist, or MediaPlaylist. For more information, refer to the npm documentation on this external module.
language	Array of strings	Contains single or multiple languages to be preserved. For example, [‘EN’,‘FR’]. The value is a quoted-string containing a RFC 5646 language tag that identifies the language of the VALUE. Note: An array of any other characters ([’ ’], [‘abc’]) can remove all subtitle renditions.

Content (bumper) insertion

insertAuxiliaryContent()

Inserts segments from the auxiliary content into the primary media playlist at the specified duration. This auxiliary content:

Must be present on the origin server as individual segments.
Must have its own playlist.
Can be inserted as pre (before), mid (middle), post (after) roll. The roll refers to the primary media playlist segments.
Auxiliary content segments should adhere to the parent stream’s encoding profile such as bitrates, resolutions, and segment duration as the original content.

This function does not return a value.

Exceptions

Throws an {Error} with a message if the argument type checks fails. For example, if the playlist object sent is invalid the following error is thrown.

Error('Received invalid playlist object, expected valid master playlist object.')

insertAuxiliaryContent(playlistObj: Object, bumpers: Bumper[]): void

playlistObj

Instance of the mediaPlaylist that corresponds to the primary media bumpers.

Parameter	Type	Description
playlistObj	Object	Instance of the playList Object, MasterPlaylist, or MediaPlaylist. For more information, refer to the npm documentation on this external module.
bumper	Bumper[] or Array of type Bumper	Holder type for auxiliary media playlist that will be inserted in primary media playlist at specified duration.

Bumper

A holder for an auxiliary media playlist that will be inserted into the primary media playlist at the specified duration.

Bumper: { afterSeconds: number; auxiliaryPlaylist: Object }

Parameter	Type	Description
afterSeconds	Number	Duration in seconds, relative to primary media playlist, where the segments from the `auxiliaryPlaylist` will be inserted. `MAX_VALUE` indicates the segments from the auxiliary media playlist that need to be inserted at the end in the primary media playlist. A value of `0` indicates that the segments from the auxiliary media playlist need to be inserted at the start in the primary media playlist.
auxiliaryPlaylist	Object	Instance of the `mediaPlaylist` Object that corresponds to the auxiliary media playlist.

LiveManifestTransformer

The LiveManifestTransformer class replaces black slate segments in the HLS playlist file.

The window in the HLS file:

Should not contain overlapping windows.
Has at least one HLS_TAG_EXTX_PROGRAM_DATE_TIME tag for the media playlist.

LiveManifestTransformer()

Constructor for the new LiveManifestTransformer Object to initialize the policies. Returns a LiveManifestTransformer Object.

LiveManifestTransformer(input: Policy[])

Parameter	Type	Description
startDate	String	Start date, in ISO 8601 format, of the replacement window.
endDate	String	End date, in ISO 8601 format, of the replacement window.
content	String	Playlist manifest object containing segments to be replaced during the replacement window.

marshalPolicy()

Resolves content of each policy to the media playlist object. Content can be either a URL or media playlist encoded as a string. If a URL is passed as content, the actual blackout slate media playlist is fetched and marshaled to a JavaScript playlist object. Returns a Promise<Policy[]>.

marshalPolicy(input: Policy[]): Promise<Policy[]>

If marshaling fails for the UTF-8 encoded playlistError the following error message is thrown.

Error('Failed to parse blackslate media playlist')

Parameter	Type	Description
startDate	String	Start date, in ISO 8601 format, of the replacement window.
endDate	String	End date, in ISO 8601 format, of the replacement window.
content	String	UTF-8 encoded playlist manifest containing segments to be replaced during the replacement window or playlist URL to fetch from origin.

transform()

Transforms the original playlist with the content to be replaced from the policy for the specified window.
Returns a string - Modified playlist manifest.

transform(manifest: string): string

Parameter	Type	Description
manifest	String	HLS content in UTF-8 format. This needs to be the complete content of the original media playlist.