#include <tshlsPlayList.h>

Inheritance diagram for ts::hls::PlayList:

[legend]

Collaboration diagram for ts::hls::PlayList:

[legend]

Public Member Functions
	PlayList (Report *report)
	PlayList (ReporterBase *delegate)
virtual	~PlayList () override
bool	addAltPlayList (const AltPlayList &pl)
void	addCustomTag (const UString &tag)
bool	addPlayList (const MediaPlayList &pl)
bool	addSegment (const MediaSegment &seg)
const AltPlayList &	altPlayList (size_t index) const
size_t	altPlayListCount () const
bool	buildURL (MediaElement &media, const UString &uri, bool silent=false) const
void	clear ()
void	clearCustomTags ()
void	deleteAltPlayList (size_t index)
void	deletePlayList (size_t index)
Time	downloadUTC () const
bool	endList () const
bool	isMaster () const
bool	isMedia () const
bool	isPermissiveURL ()
bool	isUpdatable () const
bool	isValid () const
bool	loadFile (const UString &filename, bool strict=false, PlayListType type=PlayListType::UNKNOWN)
bool	loadText (const UString &text, bool strict=false, PlayListType type=PlayListType::UNKNOWN)
bool	loadURL (const URL &url, bool strict=false, const WebRequestArgs &args=WebRequestArgs(), PlayListType type=PlayListType::UNKNOWN)
bool	loadURL (const UString &url, bool strict=false, const WebRequestArgs &args=WebRequestArgs(), PlayListType type=PlayListType::UNKNOWN)
size_t	mediaSequence () const
bool	muteReport (bool mute)
const UStringList &	originalLoadedContent () const
const MediaPlayList &	playList (size_t index) const
size_t	playListCount () const
bool	popFirstSegment (bool silent=false)
bool	popFirstSegment (MediaSegment &seg, bool silent=false)
bool	reload (bool strict=false, const WebRequestArgs &args=WebRequestArgs())
bool	reloadText (const UString &text, bool strict=false)
virtual Report &	report () const override
void	reset (PlayListType type, const UString &filename, int version=3)
bool	saveFile (const UString &filename=UString()) const
const MediaSegment &	segment (size_t index) const
size_t	segmentCount () const
cn::seconds	segmentTargetDuration () const
size_t	selectAltPlayList (const UString &type=UString(), const UString &name=UString(), const UString &group_id=UString(), const UString &language=UString()) const
size_t	selectPlayList (const BitRate &min_bitrate, const BitRate &max_bitrate, size_t min_width, size_t max_width, size_t min_height, size_t max_height) const
size_t	selectPlayListHighestBitRate () const
size_t	selectPlayListHighestResolution () const
size_t	selectPlayListLowestBitRate () const
size_t	selectPlayListLowestResolution () const
void	setAutoSaveDirectory (const UString &dir)
bool	setEndList (bool end)
bool	setFile (const UString &filename, bool silent=false)
bool	setMediaSequence (size_t seq)
void	setPermissiveURL (bool permissive)
Report *	setReport (Report *report)
ReporterBase *	setReport (ReporterBase *delegate)
bool	setSegmentTargetDuration (cn::seconds duration)
bool	setType (PlayListType type, bool forced=false)
bool	setTypeMedia ()
bool	setURL (const URL &url, bool silent=false)
bool	setURL (const UString &url, bool silent=false)
Time	terminationUTC () const
UString	textContent () const
virtual UString	toString () const override
PlayListType	type () const
UString	url () const
int	version () const

Static Public Member Functions
static int	SilentLevel (bool silent, int default_severity=Severity::Error)

Detailed Description

Playlist for HTTP Live Streaming (HLS).

Constructor & Destructor Documentation

◆ PlayList() [1/2]

ts::hls::PlayList::PlayList ( Report * report )

inlineexplicit

Constructor.

Parameters

[in] report Where to report errors. The report object must remain valid as long as this object exists or setReport() is used with another Report object. If report is null, log messages are discarded.

◆ PlayList() [2/2]

ts::hls::PlayList::PlayList ( ReporterBase * delegate )

inlineexplicit

Constructor.

Parameters

[in] delegate Use the report of another ReporterBase. If delegate is null, log messages are discarded.

◆ ~PlayList()

virtual ts::hls::PlayList::~PlayList ( )

overridevirtual

Destructor.

Member Function Documentation

◆ clear()

void ts::hls::PlayList::clear ( )

Clear the content of the playlist.

◆ 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 )

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.

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 )

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.

Returns: True on success, false on error.

◆ loadFile()

bool ts::hls::PlayList::loadFile	(	const UString &	filename,
		bool	strict = false,
		PlayListType	type = PlayListType::UNKNOWN )

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.

Returns: True on success, false on error.

◆ loadText()

bool ts::hls::PlayList::loadText	(	const UString &	text,
		bool	strict = false,
		PlayListType	type = PlayListType::UNKNOWN )

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.

Returns: True on success, false on error.

◆ setURL() [1/2]

bool ts::hls::PlayList::setURL	(	const UString &	url,
		bool	silent = false )

Update the URL of the playlist.

Parameters

[in]	url	URL from which to load the playlist.
[in]	silent	When true, do not report an error message in case of error.

Returns: True on success, false on invalid URL string or incompatible embedded URLs.

◆ setURL() [2/2]

bool ts::hls::PlayList::setURL	(	const URL &	url,
		bool	silent = false )

Update the URL of the playlist.

Parameters

[in]	url	URL from which to load the playlist.
[in]	silent	When true, do not report an error message in case of error.

Returns: True on success, false on invalid URL string or incompatible embedded URLs.

◆ setFile()

bool ts::hls::PlayList::setFile	(	const UString &	filename,
		bool	silent = false )

Update the file name of the playlist.

Parameters

[in]	filename	File from which to load the playlist.
[in]	silent	When true, do not report an error message in case of error.

Returns: True on success, false on invalid URL string or incompatible embedded URLs.

◆ reload()

bool ts::hls::PlayList::reload	(	bool	strict = false,
		const WebRequestArgs &	args = WebRequestArgs() )

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.

Returns: True on success, false on error.

◆ reloadText()

bool ts::hls::PlayList::reloadText	(	const UString &	text,
		bool	strict = false )

Reload a media playlist with updated text content. Master playlists or media playlists for which endList() is true are never reloaded. New segments are added. If a segment hole is found, all previous content is replaced.

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.

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. This property is preserved when the playlist is cleared or reloaded.

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() ) 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().

Returns: True on success, false on error.

◆ textContent()

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

Build the text content of the playlist.

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

◆ originalLoadedContent()

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

inline

Get the original 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()

bool ts::hls::PlayList::buildURL	(	MediaElement &	media,
		const UString &	uri,
		bool	silent = false ) 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.
[in]	silent	When true, do not report an error message in case of error.

Returns: True on success, false on invalid URL string or incompatible embedded URLs.

◆ type()

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

inline

Get the playlist type.

Returns: The playlist type.

◆ setType()

bool ts::hls::PlayList::setType	(	PlayListType	type,
		bool	forced = false )

Set the playlist type.

Parameters

[in]	type	The playlist type.
[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 ( )

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.

Returns: True on success, false on error.

◆ setPermissiveURL()

void ts::hls::PlayList::setPermissiveURL ( bool permissive )

inline

Allow permissive URL resolution. By default, for security reasons, http: and https: playlist can only contain segments or media playlists with http: or https: URLs. If an http: or https: contains a segment file a file: URL, for instance, an error is generated. Use this method to relax this rule. This property is preserved when the playlist is cleared or reloaded.

Parameters

[in] permissive When true, the playlist allows permissive URL resolution.

◆ isPermissiveURL()

bool ts::hls::PlayList::isPermissiveURL ( )

inline

Check if the playlist allows permissive URL resolution.

Returns: True if the playlist allows permissive URL resolution, false otherwise.

See also: setPermissiveURL()

◆ 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.

◆ segmentTargetDuration()

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

inline

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

Returns: The segment target duration in seconds.

◆ setSegmentTargetDuration()

bool ts::hls::PlayList::setSegmentTargetDuration ( cn::seconds duration )

Set the segment target duration in a media playlist.

Parameters

[in] duration The segment target duration in seconds.

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 )

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

Parameters

[in] seq The sequence number of first segment.

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 )

Set the end of list indicator in a media playlist.

Parameters

[in] end The end of list indicator.

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,
		bool	silent = false )

Remove the first media segment (in media playlist).

Parameters

[out]	seg	Characteristics of the first segment.
[in]	silent	When true, do not report an error message in case of error.

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

◆ popFirstSegment() [2/2]

bool ts::hls::PlayList::popFirstSegment ( bool silent = false )

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

Parameters

[in] silent When true, do not report an error message in case of error.

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

◆ addSegment()

bool ts::hls::PlayList::addSegment ( const MediaSegment & seg )

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.

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 )

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.

Returns: True on success, false on error.

◆ selectPlayList()

size_t ts::hls::PlayList::selectPlayList	(	const BitRate &	min_bitrate,
		const BitRate &	max_bitrate,
		size_t	min_width,
		size_t	max_width,
		size_t	min_height,
		size_t	max_height ) const

Select the first media playlist with specific constraints.

Parameters

[in]	min_bitrate	Minimum bitrate. Zero means no minimum.
[in]	max_bitrate	Maximum bitrate. Zero means no maximum.
[in]	min_width	Minimum width. Zero means no minimum.
[in]	max_width	Maximum width. Zero means no maximum.
[in]	min_height	Minimum height. Zero means no minimum.
[in]	max_height	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 )

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.

Returns: True on success, false on error.

◆ selectAltPlayList()

size_t ts::hls::PlayList::selectAltPlayList	(	const UString &	type = UString(),
		const UString &	name = UString(),
		const UString &	group_id = 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]	group_id	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.

◆ report()

virtual Report & ts::ReporterBase::report ( ) const

overridevirtualinherited

Access the Report which is associated with this object. Can be called from another thread only if the Report object is thread-safe.

Returns: A reference to the associated report.

Implements ts::ReporterInterface.

◆ setReport() [1/2]

Report * ts::ReporterBase::setReport ( Report * report )

inherited

Associate this object with another Report to log errors.

Parameters

[in] report Where to report errors. The report object must remain valid as long as this object exists or setReport() is used with another Report object. If report is null, log messages are discarded.

Returns: The address of the previous Report object or a null pointer if there was none.

◆ setReport() [2/2]

ReporterBase * ts::ReporterBase::setReport ( ReporterBase * delegate )

inherited

Associate this object with another ReporterBase to log errors.

Parameters

[in] delegate Use the report of another ReporterBase. If delegate is null, the previous explicit Report is used..

Returns: The address of the previous ReporterBase object or a null pointer if there was none.

◆ muteReport()

bool ts::ReporterBase::muteReport ( bool mute )

inherited

Temporarily mute the associated report.

Parameters

[in] mute It true, report() will return a null report (log messages are discarded), until muteReport() is invoked again with mute set to false.

Returns: Previous state of the mute field.

◆ SilentLevel()

int ts::ReporterBase::SilentLevel	(	bool	silent,
		int	default_severity = Severity::Error )

inlinestaticinherited

Compute a log severity level from a "silent" parameter. Some subclass methods have a "silent" parameter to avoid reporting errors which may be insignificant, typically when closing a device after an error, in which case the close operation may produce other errors if the previous error left the device in an inconsistent state. While those errors should not be displayed as errors, we still display them at debug level.

Parameters

[in]	silent	If true, do not report errors, report debug messages instead.
[in]	default_severity	Default severity, in non-silent mode (error by default).

Returns: Error when silent is false, Debug otherwise.

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

tshlsPlayList.h

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ PlayList() [1/2]

◆ PlayList() [2/2]

◆ ~PlayList()

Member Function Documentation

◆ clear()

◆ reset()

◆ loadURL() [1/2]

◆ loadURL() [2/2]

◆ loadFile()

◆ loadText()

◆ setURL() [1/2]

◆ setURL() [2/2]

◆ setFile()

◆ reload()

◆ reloadText()

◆ setAutoSaveDirectory()

◆ isValid()

◆ saveFile()

◆ textContent()

◆ originalLoadedContent()

◆ url()

◆ buildURL()

◆ type()

◆ setType()

◆ setTypeMedia()

◆ setPermissiveURL()

◆ isPermissiveURL()

◆ addCustomTag()

◆ clearCustomTags()

◆ isUpdatable()

◆ isMedia()

◆ isMaster()

◆ version()

◆ segmentTargetDuration()

◆ setSegmentTargetDuration()

◆ 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()

◆ report()

◆ setReport() [1/2]

◆ setReport() [2/2]

◆ muteReport()

◆ SilentLevel()