HLS parser

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

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)
ParameterTypeDescription
textUTF8 StringUTF-8 encoded string representation of the manifest input.

stringifyManifest()

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

stringifyManifest(playlistObject)
ParameterTypeDescription
playlistObjectObjectInstance 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)
ParameterTypeDescription
playlistObjectObjectInstance 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)
ParameterTypeDescription
playlistObjectObjectInstance of the playlist Object, MasterPlaylist, or MediaPlaylist. For more information, refer to the npm documentation on this external module.
bitrateArray of stringsRepresents 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=100000NumberBitrate 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)
ParameterTypeDescription
playlistObjectObjectInstance of the playList Object, MasterPlaylist, or MediaPlaylist. For more information, refer to the npm documentation on this external module.
maxSupportedResolutionStringString 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)
ParameterTypeDescription
playlistObjectObjectInstance of the playList Object, MasterPlaylist, or MediaPlaylist. For more information, refer to the npm documentation on this external module.
resolutionStringString representation for resolution in format <width>x<height>.
newIndex = 0NumberIndex 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[])
ParameterTypeDescription
playlistObjectObjectInstance of the playList Object, MasterPlaylist, or MediaPlaylist. For more information, refer to the npm documentation on this external module.
resolutions[]StringArray 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)
ParameterTypeDescription
playlistObjectObjectInstance of the playList Object, MasterPlaylist, or MediaPlaylist.For more information, refer to the npm documentation on this external module.
languageStringContains 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)
ParameterTypeDescription
playlistObjectObjectInstance of the playList Object, MasterPlaylist, or MediaPlaylist. For more information, refer to the npm documentation on this external module.
languageArray of stringsContains 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.

ParameterTypeDescription
playlistObjObjectInstance of the playList Object, MasterPlaylist, or MediaPlaylist. For more information, refer to the npm documentation on this external module.
bumperBumper[] or Array of type BumperHolder 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 }
ParameterTypeDescription
afterSecondsNumberDuration 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.
auxiliaryPlaylistObjectInstance 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[])
ParameterTypeDescription
startDateStringStart date, in ISO 8601 format, of the replacement window.
endDateStringEnd date, in ISO 8601 format, of the replacement window.
contentStringPlaylist 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')

ParameterTypeDescription
startDateStringStart date, in ISO 8601 format, of the replacement window.
endDateStringEnd date, in ISO 8601 format, of the replacement window.
contentStringUTF-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
ParameterTypeDescription
manifestStringHLS content in UTF-8 format. This needs to be the complete content of the original media playlist.