Playlist for HTTP Live Streaming (HLS). More...

#include <tshlsPlayList.h>

Inheritance diagram for ts::hls::PlayList:

Collaboration diagram for ts::hls::PlayList:

Public Member Functions
	PlayList ()=default
	Constructor.

bool	addAltPlayList (const AltPlayList &pl, Report &report=(ts::CerrReport::Instance()))
	Add an alternative rendition media playlist in a master playlist.

void	addCustomTag (const UString &tag)
	Add a custom tag in the playlist.

bool	addPlayList (const MediaPlayList &pl, Report &report=(ts::CerrReport::Instance()))
	Add a media playlist in a master playlist.

bool	addSegment (const MediaSegment &seg, Report &report=(ts::CerrReport::Instance()))
	Add a segment in a media playlist.

const AltPlayList &	altPlayList (size_t index) const
	Get a constant reference to an alternative rendition playlist description (in master playlist).

size_t	altPlayListCount () const
	Get the number of altenative rendition playlists (in master playlist).

void	buildURL (MediaElement &media, const UString &uri) const
	Build an URL for a media segment or sub-playlist.

void	clear ()
	Clear the content of the playlist.

void	clearCustomTags ()
	Clear all application-specific custom tags.

void	deleteAltPlayList (size_t index)
	Delete an alternative rendition playlist description from a master playlist.

void	deletePlayList (size_t index)
	Delete a media playlist description from a master playlist.

Time	downloadUTC () const
	Get the download UTC time of the playlist.

bool	endList () const
	Get the end of list indicator (in media playlist).

bool	isMaster () const
	Check if the playlist is a master playlist (contains references to media playlists).

bool	isMedia () const
	Check if the playlist is a media playlist (contains references to media segments).

bool	isUpdatable () const
	Check if the playlist can be updated (and must be reloaded later).

bool	isValid () const
	Check if the playlist has been successfully loaded.

bool	loadFile (const UString &filename, bool strict=false, PlayListType type=PlayListType::UNKNOWN, Report &report=(ts::CerrReport::Instance()))
	Load the playlist from a text file.

bool	loadText (const UString &text, bool strict=false, PlayListType type=PlayListType::UNKNOWN, Report &report=(ts::CerrReport::Instance()))
	Load the playlist from its text content.

bool	loadURL (const URL &url, bool strict=false, const WebRequestArgs &args=WebRequestArgs(), PlayListType type=PlayListType::UNKNOWN, Report &report=(ts::CerrReport::Instance()))
	Load the playlist from a URL.

bool	loadURL (const UString &url, bool strict=false, const WebRequestArgs &args=WebRequestArgs(), PlayListType type=PlayListType::UNKNOWN, Report &report=(ts::CerrReport::Instance()))
	Load the playlist from a URL.

size_t	mediaSequence () const
	Get the sequence number of first segment (in media playlist).

const UStringList &	originalLoadedContent () const
	Get the orginal loaded text content of the playlist.

const MediaPlayList &	playList (size_t index) const
	Get a constant reference to a media playlist description (in master playlist).

size_t	playListCount () const
	Get the number of media playlists (in master playlist).

bool	popFirstSegment ()
	Remove the first media segment and do not even return it (in media playlist).

bool	popFirstSegment (MediaSegment &seg)
	Remove the first media segment (in media playlist).

bool	reload (bool strict=false, const WebRequestArgs &args=WebRequestArgs(), Report &report=(ts::CerrReport::Instance()))
	Reload a media playlist with updated content.

void	reset (PlayListType type, const UString &filename, int version=3)
	Reset the content of a playlist.

bool	saveFile (const UString &filename=UString(), Report &report=(ts::CerrReport::Instance())) const
	Save the playlist to a text file.

const MediaSegment &	segment (size_t index) const
	Get a constant reference to a media segment (in media playlist).

size_t	segmentCount () const
	Get the number of media segments (in media playlist).

size_t	selectAltPlayList (const UString &type=UString(), const UString &name=UString(), const UString &groupId=UString(), const UString &language=UString()) const
	Select the first alternative rendition playlist with specific criteria.

size_t	selectPlayList (const BitRate &minBitrate, const BitRate &maxBitrate, size_t minWidth, size_t maxWidth, size_t minHeight, size_t maxHeight) const
	Select the first media playlist with specific constraints.

size_t	selectPlayListHighestBitRate () const
	Select the media playlist with the highest bitrate.

size_t	selectPlayListHighestResolution () const
	Select the media playlist with the highest resolution.

size_t	selectPlayListLowestBitRate () const
	Select the media playlist with the lowest bitrate.

size_t	selectPlayListLowestResolution () const
	Select the media playlist with the lowest resolution.

void	setAutoSaveDirectory (const UString &dir)
	Set a directory name where all loaded files or URL are automatically saved.

bool	setEndList (bool end, Report &report=(ts::CerrReport::Instance()))
	Set the end of list indicator in a media playlist.

bool	setMediaSequence (size_t seq, Report &report=(ts::CerrReport::Instance()))
	Set the sequence number of first segment in a media playlist.

bool	setTargetDuration (cn::seconds duration, Report &report=(ts::CerrReport::Instance()))
	Set the segment target duration in a media playlist.

bool	setType (PlayListType type, Report &report=(ts::CerrReport::Instance()), bool forced=false)
	Set the playlist type.

bool	setTypeMedia (Report &report=(ts::CerrReport::Instance()))
	Set the playlist type as media playlist.

cn::seconds	targetDuration () const
	Get the segment target duration (informative, in media playlist).

Time	terminationUTC () const
	Get the playout estimated termination UTC time of the playlist (in media playlist).

UString	textContent (Report &report=(ts::CerrReport::Instance())) const
	Build the text content of the playlist.

virtual UString	toString () const override
	Convert to a string object.

PlayListType	type () const
	Get the playlist type.

UString	url () const
	Get the original URL.

int	version () const
	Get the playlist version (EXT-X-VERSION).

Detailed Description

Playlist for HTTP Live Streaming (HLS).

Member Function Documentation

◆ reset()

void ts::hls::PlayList::reset	(	PlayListType	type,
		const UString &	filename,
		int	version = `3`
	)

Reset the content of a playlist.

Should be used before rebuilding a new playlist.

Parameters

[in]	type	Playlist type.
[in]	filename	File path where the playlist will be saved. This required to build relative paths for sub-playlists or media segments.
[in]	version	Playlist format version. The default is 3, the minimum level which is required for playlists which are supported here.

◆ loadURL() [1/2]

bool ts::hls::PlayList::loadURL	(	const UString &	url,
		bool	strict = `false`,
		const WebRequestArgs &	args = `WebRequestArgs()`,
		PlayListType	type = `PlayListType::UNKNOWN`,
		Report &	report = `(ts::CerrReport::Instance())`
	)

Load the playlist from a URL.

Parameters

[in]	url	URL from which to load the playlist.
[in]	strict	If true, perform strict conformance checking. By default, relaxed as long as we can understand the content.
[in]	args	Web request arguments from command line.
[in]	type	Expected playlist type, unknown by default.
[in,out]	report	Where to report errors.

Returns: True on success, false on error.

◆ loadURL() [2/2]

bool ts::hls::PlayList::loadURL	(	const URL &	url,
		bool	strict = `false`,
		const WebRequestArgs &	args = `WebRequestArgs()`,
		PlayListType	type = `PlayListType::UNKNOWN`,
		Report &	report = `(ts::CerrReport::Instance())`
	)

Load the playlist from a URL.

Parameters

[in]	url	URL from which to load the playlist.
[in]	strict	If true, perform strict conformance checking. By default, relaxed as long as we can understand the content.
[in]	args	Web request arguments from command line.
[in]	type	Expected playlist type, unknown by default.
[in,out]	report	Where to report errors.

Returns: True on success, false on error.

◆ loadFile()

bool ts::hls::PlayList::loadFile	(	const UString &	filename,
		bool	strict = `false`,
		PlayListType	type = `PlayListType::UNKNOWN`,
		Report &	report = `(ts::CerrReport::Instance())`
	)

Load the playlist from a text file.

Parameters

[in]	filename	File from which to load the playlist.
[in]	strict	If true, perform strict conformance checking. By default, relaxed as long as we can understand the content.
[in]	type	Expected playlist type, unknown by default.
[in,out]	report	Where to report errors.

Returns: True on success, false on error.

◆ loadText()

bool ts::hls::PlayList::loadText	(	const UString &	text,
		bool	strict = `false`,
		PlayListType	type = `PlayListType::UNKNOWN`,
		Report &	report = `(ts::CerrReport::Instance())`
	)

Load the playlist from its text content.

Parameters

[in]	text	Text of the playlist (multi-lines).
[in]	strict	If true, perform strict conformance checking. By default, relaxed as long as we can understand the content.
[in]	type	Expected playlist type, unknown by default.
[in,out]	report	Where to report errors.

Returns: True on success, false on error.

◆ reload()

bool ts::hls::PlayList::reload	(	bool	strict = `false`,
		const WebRequestArgs &	args = `WebRequestArgs()`,
		Report &	report = `(ts::CerrReport::Instance())`
	)

Reload a media playlist with updated content.

Master playlists or media playlists for which endList() is true are never reloaded. Live playlists (media playlists for which endList() is false) are reloaded from the same URL. New segments are added. If a segment hole is found, all previous content is replaced.

Parameters

[in]	strict	If true, perform strict conformance checking. By default, relaxed as long as we can understand the content.
[in]	args	Web request arguments from command line.
[in,out]	report	Where to report errors.

Returns: True on success, false on error.

◆ setAutoSaveDirectory()

void ts::hls::PlayList::setAutoSaveDirectory ( const UString & dir )

inline

Set a directory name where all loaded files or URL are automatically saved.

Parameters

[in] dir A directory name.

◆ isValid()

bool ts::hls::PlayList::isValid ( ) const

inline

Check if the playlist has been successfully loaded.

Returns: True if the playlist has been successfully loaded.

◆ saveFile()

bool ts::hls::PlayList::saveFile	(	const UString &	filename = `UString()`,
		Report &	report = `(ts::CerrReport::Instance())`
	)		const

Save the playlist to a text file.

Parameters

[in]	filename	File where to save the playlist. By default, use the same file from loadFile() or reset().
[in,out]	report	Where to report errors.

Returns: True on success, false on error.

◆ textContent()

UString ts::hls::PlayList::textContent ( Report & report = (ts::CerrReport::Instance()) ) const

Build the text content of the playlist.

Parameters

[in,out] report Where to report errors.

Returns: The text content on success, an empty string on error.

◆ originalLoadedContent()

const UStringList & ts::hls::PlayList::originalLoadedContent ( ) const

inline

Get the orginal loaded text content of the playlist.

This can be different from the current content of the playlist if the object has been modified.

Returns: A constant reference to the original loaded text lines.

◆ url()

UString ts::hls::PlayList::url ( ) const

inline

Get the original URL.

Returns: The original URL.

◆ buildURL()

void ts::hls::PlayList::buildURL	(	MediaElement &	media,
		const UString &	uri
	)		const

Build an URL for a media segment or sub-playlist.

Parameters

[out]	media	A media element with all fields filled in.
[in]	uri	An URI, typically extracted from the playlist.

◆ type()

PlayListType ts::hls::PlayList::type ( ) const

inline

Get the playlist type.

Returns: The playlist type.

◆ setType()

bool ts::hls::PlayList::setType	(	PlayListType	type,
		Report &	report = `(ts::CerrReport::Instance())`,
		bool	forced = `false`
	)

Set the playlist type.

Parameters

[in]	type	The playlist type.
[in,out]	report	Where to report errors.
[in]	forced	When true, unconditionally set the playlist type. When false (the default), check that the playlist type does not change in an inconsistent way. Allowed changes are UNKNOWN to anything and LIVE to VOD or EVENT. The latter case is a playlist which is known to be a media playlist but for which no EXT-X-PLAYLIST-TYPE tag was found so far.

Returns: True on success, false on error.

◆ setTypeMedia()

bool ts::hls::PlayList::setTypeMedia ( Report & report = (ts::CerrReport::Instance()) )

Set the playlist type as media playlist.

If the type is already known and already a media playlist, do nothing. If the type is unknown, set it as LIVE which is a media playlist type without EXT-X-PLAYLIST-TYPE tag and which can be later turned into a VOD or EVENT playlist.

Parameters

[in,out] report Where to report errors.

Returns: True on success, false on error.

◆ addCustomTag()

void ts::hls::PlayList::addCustomTag ( const UString & tag )

inline

Add a custom tag in the playlist.

Parameters

[in] tag A custom tag line to add in the playlist. If does not start with a '#', it will be automatically added.

◆ clearCustomTags()

void ts::hls::PlayList::clearCustomTags ( )

inline

Clear all application-specific custom tags.

See also: addCustomTag()

◆ isUpdatable()

bool ts::hls::PlayList::isUpdatable ( ) const

inline

Check if the playlist can be updated (and must be reloaded later).

Returns: True if the playlist can be updated (and must be reloaded later).

◆ isMedia()

bool ts::hls::PlayList::isMedia ( ) const

inline

Check if the playlist is a media playlist (contains references to media segments).

Returns: True if the playlist is a media playlist.

◆ isMaster()

bool ts::hls::PlayList::isMaster ( ) const

inline

Check if the playlist is a master playlist (contains references to media playlists).

Returns: True if the playlist is a master playlist.

◆ version()

int ts::hls::PlayList::version ( ) const

inline

Get the playlist version (EXT-X-VERSION).

Returns: The playlist version.

◆ targetDuration()

cn::seconds ts::hls::PlayList::targetDuration ( ) const

inline

Get the segment target duration (informative, in media playlist).

Returns: The segment target duration in seconds.

◆ setTargetDuration()

bool ts::hls::PlayList::setTargetDuration	(	cn::seconds	duration,
		Report &	report = `(ts::CerrReport::Instance())`
	)

Set the segment target duration in a media playlist.

Parameters

[in]	duration	The segment target duration in seconds.
[in,out]	report	Where to report errors.

Returns: True on success, false on error.

◆ mediaSequence()

size_t ts::hls::PlayList::mediaSequence ( ) const

inline

Get the sequence number of first segment (in media playlist).

Returns: The sequence number of first segment.

◆ setMediaSequence()

bool ts::hls::PlayList::setMediaSequence	(	size_t	seq,
		Report &	report = `(ts::CerrReport::Instance())`
	)

Set the sequence number of first segment in a media playlist.

Parameters

[in]	seq	The sequence number of first segment.
[in,out]	report	Where to report errors.

Returns: True on success, false on error.

◆ endList()

bool ts::hls::PlayList::endList ( ) const

inline

Get the end of list indicator (in media playlist).

Returns: The end of list indicator. If true, there is no need to reload the playlist, there will not be any new segment.

◆ setEndList()

bool ts::hls::PlayList::setEndList	(	bool	end,
		Report &	report = `(ts::CerrReport::Instance())`
	)

Set the end of list indicator in a media playlist.

Parameters

[in]	end	The end of list indicator.
[in,out]	report	Where to report errors.

Returns: True on success, false on error.

◆ segmentCount()

size_t ts::hls::PlayList::segmentCount ( ) const

inline

Get the number of media segments (in media playlist).

Returns: The number of media segments.

◆ playListCount()

size_t ts::hls::PlayList::playListCount ( ) const

inline

Get the number of media playlists (in master playlist).

Returns: The number of media playlists.

◆ altPlayListCount()

size_t ts::hls::PlayList::altPlayListCount ( ) const

inline

Get the number of altenative rendition playlists (in master playlist).

Returns: The number of altenative rendition playlists.

◆ segment()

const MediaSegment & ts::hls::PlayList::segment ( size_t index ) const

Get a constant reference to a media segment (in media playlist).

Parameters

[in] index Index of the segment, from 0 to segmentCount().

Returns: A constant reference to the media segment at index.

◆ popFirstSegment() [1/2]

bool ts::hls::PlayList::popFirstSegment ( MediaSegment & seg )

Remove the first media segment (in media playlist).

Parameters

[out] seg Characteristics of the first segment.

Returns: True of a segment was successfully removed, false otherwise.

◆ popFirstSegment() [2/2]

bool ts::hls::PlayList::popFirstSegment ( )

Remove the first media segment and do not even return it (in media playlist).

Returns: True of a segment was successfully removed, false otherwise.

◆ addSegment()

bool ts::hls::PlayList::addSegment	(	const MediaSegment &	seg,
		Report &	report = `(ts::CerrReport::Instance())`
	)

Add a segment in a media playlist.

Parameters

[in]	seg	The new media segment to append. If the playlist's URI is a file name, the URI of the segment is transformed into a relative URI from the playlist's path.
[in,out]	report	Where to report errors.

Returns: True on success, false on error.

◆ downloadUTC()

Time ts::hls::PlayList::downloadUTC ( ) const

inline

Get the download UTC time of the playlist.

Returns: The download UTC time of the playlist.

◆ terminationUTC()

Time ts::hls::PlayList::terminationUTC ( ) const

inline

Get the playout estimated termination UTC time of the playlist (in media playlist).

Returns: The estimated playout UTC time of the playlist. This is the download time of the playlist plus the sum of all segment durations.

◆ playList()

const MediaPlayList & ts::hls::PlayList::playList ( size_t index ) const

Get a constant reference to a media playlist description (in master playlist).

Parameters

[in] index Index of the playlist, from 0 to playListCount()-1.

Returns: A constant reference to the media playlist description at index.

◆ deletePlayList()

void ts::hls::PlayList::deletePlayList ( size_t index )

Delete a media playlist description from a master playlist.

Parameters

[in] index Index of the media playlist to delete, from 0 to playListCount()-1.

◆ addPlayList()

bool ts::hls::PlayList::addPlayList	(	const MediaPlayList &	pl,
		Report &	report = `(ts::CerrReport::Instance())`
	)

Add a media playlist in a master playlist.

Parameters

[in]	pl	The new media playlist to append. If the master playlist's URI is a file name, the URI of the media playlist is transformed into a relative URI from the master playlist's path.
[in,out]	report	Where to report errors.

Returns: True on success, false on error.

◆ selectPlayList()

size_t ts::hls::PlayList::selectPlayList	(	const BitRate &	minBitrate,
		const BitRate &	maxBitrate,
		size_t	minWidth,
		size_t	maxWidth,
		size_t	minHeight,
		size_t	maxHeight
	)		const

Select the first media playlist with specific constraints.

Parameters

[in]	minBitrate	Minimum bitrate. Zero means no minimum.
[in]	maxBitrate	Maximum bitrate. Zero means no maximum.
[in]	minWidth	Minimum width. Zero means no minimum.
[in]	maxWidth	Maximum width. Zero means no maximum.
[in]	minHeight	Minimum height. Zero means no minimum.
[in]	maxHeight	Maximum height. Zero means no maximum.

Returns: Index of the selected media play list or NPOS if there is none. If all criteria are zero, select the first playlist.

◆ selectPlayListLowestBitRate()

size_t ts::hls::PlayList::selectPlayListLowestBitRate ( ) const

Select the media playlist with the lowest bitrate.

Returns: Index of the selected media play list or NPOS if there is none.

◆ selectPlayListHighestBitRate()

size_t ts::hls::PlayList::selectPlayListHighestBitRate ( ) const

Select the media playlist with the highest bitrate.

Returns: Index of the selected media play list or NPOS if there is none.

◆ selectPlayListLowestResolution()

size_t ts::hls::PlayList::selectPlayListLowestResolution ( ) const

Select the media playlist with the lowest resolution.

Returns: Index of the selected media play list or NPOS if there is none.

◆ selectPlayListHighestResolution()

size_t ts::hls::PlayList::selectPlayListHighestResolution ( ) const

Select the media playlist with the highest resolution.

Returns: Index of the selected media play list or NPOS if there is none.

◆ altPlayList()

const AltPlayList & ts::hls::PlayList::altPlayList ( size_t index ) const

Get a constant reference to an alternative rendition playlist description (in master playlist).

Parameters

[in] index Index of the playlist, from 0 to altPlayListCount()-1.

Returns: A constant reference to the alternative rendition playlist description at index.

◆ deleteAltPlayList()

void ts::hls::PlayList::deleteAltPlayList ( size_t index )

Delete an alternative rendition playlist description from a master playlist.

Parameters

[in] index Index of the alternative rendition playlist to delete, from 0 to altPlayListCount()-1.

◆ addAltPlayList()

bool ts::hls::PlayList::addAltPlayList	(	const AltPlayList &	pl,
		Report &	report = `(ts::CerrReport::Instance())`
	)

Add an alternative rendition media playlist in a master playlist.

Parameters

[in]	pl	The new alternative rendition playlist to append. If the master playlist's URI is a file name, the URI of the media playlist is transformed into a relative URI from the master playlist's path.
[in,out]	report	Where to report errors.

Returns: True on success, false on error.

◆ selectAltPlayList()

size_t ts::hls::PlayList::selectAltPlayList	(	const UString &	type = `UString()`,
		const UString &	name = `UString()`,
		const UString &	groupId = `UString()`,
		const UString &	language = `UString()`
	)		const

Select the first alternative rendition playlist with specific criteria.

Parameters

[in]	type	The type to match. Ignored if empty.
[in]	name	The name to match. Ignored if empty.
[in]	groupId	The group-id to match. Ignored if empty.
[in]	language	The language to match. Ignored if empty.

Returns: Index of the selected alternative rendition playlist which matches all non-empty criteria or NPOS if there is none. If all criteria are empty, select the first playlist.

◆ toString()

virtual UString ts::hls::PlayList::toString ( ) const

overridevirtual

Convert to a string object.

Returns: This object, converted as a string.

Implements ts::StringifyInterface.

The documentation for this class was generated from the following file:

tshlsPlayList.h

Public Member Functions

Detailed Description

Member Function Documentation

◆ reset()

◆ loadURL() [1/2]

◆ loadURL() [2/2]

◆ loadFile()

◆ loadText()

◆ reload()

◆ setAutoSaveDirectory()

◆ isValid()

◆ saveFile()

◆ textContent()

◆ originalLoadedContent()

◆ url()

◆ buildURL()

◆ type()

◆ setType()

◆ setTypeMedia()

◆ addCustomTag()

◆ clearCustomTags()

◆ isUpdatable()

◆ isMedia()

◆ isMaster()

◆ version()

◆ targetDuration()

◆ setTargetDuration()

◆ mediaSequence()

◆ setMediaSequence()

◆ endList()

◆ setEndList()

◆ segmentCount()

◆ playListCount()

◆ altPlayListCount()

◆ segment()

◆ popFirstSegment() [1/2]

◆ popFirstSegment() [2/2]

◆ addSegment()

◆ downloadUTC()

◆ terminationUTC()

◆ playList()

◆ deletePlayList()

◆ addPlayList()

◆ selectPlayList()

◆ selectPlayListLowestBitRate()

◆ selectPlayListHighestBitRate()

◆ selectPlayListLowestResolution()

◆ selectPlayListHighestResolution()

◆ altPlayList()

◆ deleteAltPlayList()

◆ addAltPlayList()

◆ selectAltPlayList()

◆ toString()