TSDuck Version 3.32-2769 (TSDuck - The MPEG Transport Stream Toolkit)
ts::hls::PlayList Class Reference

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

Inheritance diagram for ts::hls::PlayList:
Collaboration diagram for ts::hls::PlayList:

Public Member Functions

 PlayList ()
 Constructor.
 
bool addPlayList (const MediaPlayList &pl, Report &report=(*(static_cast< ts::Report * >(ts::CerrReport::Instance()))))
 Add a media playlist in a master playlist. More...
 
bool addSegment (const MediaSegment &seg, Report &report=(*(static_cast< ts::Report * >(ts::CerrReport::Instance()))))
 Add a segment in a media playlist. More...
 
void buildURL (MediaElement &media, const UString &uri) const
 Build an URL for a media segment or sub-playlist. More...
 
void clear ()
 Clear the content of the playlist.
 
void deletePlayList (size_t index)
 Delete a media playlist description from a master playlist. More...
 
Time downloadUTC () const
 Get the download UTC time of the playlist. More...
 
bool endList () const
 Get the end of list indicator (in media playlist). More...
 
bool isMaster () const
 Check if the playlist is a master playlist (contains references to media playlists). More...
 
bool isMedia () const
 Check if the playlist is a media playlist (contains references to media segments). More...
 
bool isUpdatable () const
 Check if the playlist can be updated (and must be reloaded later). More...
 
bool isValid () const
 Check if the playlist has been successfully loaded. More...
 
bool loadFile (const UString &filename, bool strict=false, PlayListType type=PlayListType::UNKNOWN, Report &report=(*(static_cast< ts::Report * >(ts::CerrReport::Instance()))))
 Load the playlist from a text file. More...
 
bool loadText (const UString &text, bool strict=false, PlayListType type=PlayListType::UNKNOWN, Report &report=(*(static_cast< ts::Report * >(ts::CerrReport::Instance()))))
 Load the playlist from its text content. More...
 
bool loadURL (const URL &url, bool strict=false, const WebRequestArgs args=WebRequestArgs(), PlayListType type=PlayListType::UNKNOWN, Report &report=(*(static_cast< ts::Report * >(ts::CerrReport::Instance()))))
 Load the playlist from a URL. More...
 
bool loadURL (const UString &url, bool strict=false, const WebRequestArgs args=WebRequestArgs(), PlayListType type=PlayListType::UNKNOWN, Report &report=(*(static_cast< ts::Report * >(ts::CerrReport::Instance()))))
 Load the playlist from a URL. More...
 
size_t mediaSequence () const
 Get the sequence number of first segment (in media playlist). More...
 
const UStringListoriginalLoadedContent () const
 Get the orginal loaded text content of the playlist. More...
 
const MediaPlayListplayList (size_t index) const
 Get a constant reference to a media playlist description (in master playlist). More...
 
size_t playListCount () const
 Get the number of media playlists (in master playlist). More...
 
bool popFirstSegment ()
 Remove the first media segment and do not even return it (in media playlist). More...
 
bool popFirstSegment (MediaSegment &seg)
 Remove the first media segment (in media playlist). More...
 
bool reload (bool strict=false, const WebRequestArgs args=WebRequestArgs(), Report &report=(*(static_cast< ts::Report * >(ts::CerrReport::Instance()))))
 Reload a media playlist with updated content. More...
 
void reset (PlayListType type, const UString &filename, int version=3)
 Reset the content of a playlist. More...
 
bool saveFile (const UString &filename=UString(), Report &report=(*(static_cast< ts::Report * >(ts::CerrReport::Instance())))) const
 Save the playlist to a text file. More...
 
const MediaSegmentsegment (size_t index) const
 Get a constant reference to a media segment (in media playlist). More...
 
size_t segmentCount () const
 Get the number of media segments (in media playlist). More...
 
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. More...
 
size_t selectPlayListHighestBitRate () const
 Select the media playlist with the highest bitrate. More...
 
size_t selectPlayListHighestResolution () const
 Select the media playlist with the highest resolution. More...
 
size_t selectPlayListLowestBitRate () const
 Select the media playlist with the lowest bitrate. More...
 
size_t selectPlayListLowestResolution () const
 Select the media playlist with the lowest resolution. More...
 
void setAutoSaveDirectory (const UString dir)
 Set a directory name where all loaded files or URL are automatically saved. More...
 
bool setEndList (bool end, Report &report=(*(static_cast< ts::Report * >(ts::CerrReport::Instance()))))
 Set the end of list indicator in a media playlist. More...
 
bool setMediaSequence (size_t seq, Report &report=(*(static_cast< ts::Report * >(ts::CerrReport::Instance()))))
 Set the sequence number of first segment in a media playlist. More...
 
bool setTargetDuration (Second duration, Report &report=(*(static_cast< ts::Report * >(ts::CerrReport::Instance()))))
 Set the segment target duration in a media playlist. More...
 
bool setType (PlayListType type, Report &report=(*(static_cast< ts::Report * >(ts::CerrReport::Instance()))), bool forced=false)
 Set the playlist type. More...
 
bool setTypeMedia (Report &report=(*(static_cast< ts::Report * >(ts::CerrReport::Instance()))))
 Set the playlist type as media playlist. More...
 
Second targetDuration () const
 Get the segment target duration (informative, in media playlist). More...
 
Time terminationUTC () const
 Get the playout estimated termination UTC time of the playlist (in media playlist). More...
 
UString textContent (Report &report=(*(static_cast< ts::Report * >(ts::CerrReport::Instance())))) const
 Build the text content of the playlist. More...
 
virtual UString toString () const override
 Convert to a string object. More...
 
PlayListType type () const
 Get the playlist type. More...
 
UString url () const
 Get the original URL. More...
 
int version () const
 Get the playlist version (EXT-X-VERSION). More...
 

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]typePlaylist type.
[in]filenameFile path where the playlist will be saved. This required to build relative paths for sub-playlists or media segments.
[in]versionPlaylist 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 = (*(static_cast< ts::Report * >(ts::CerrReport::Instance()))) 
)

Load the playlist from a URL.

Parameters
[in]urlURL from which to load the playlist.
[in]strictIf true, perform strict conformance checking. By default, relaxed as long as we can understand the content.
[in]argsWeb request arguments from command line.
[in]typeExpected playlist type, unknown by default.
[in,out]reportWhere 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 = (*(static_cast< ts::Report * >(ts::CerrReport::Instance()))) 
)

Load the playlist from a URL.

Parameters
[in]urlURL from which to load the playlist.
[in]strictIf true, perform strict conformance checking. By default, relaxed as long as we can understand the content.
[in]argsWeb request arguments from command line.
[in]typeExpected playlist type, unknown by default.
[in,out]reportWhere 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 = (*(static_cast< ts::Report * >(ts::CerrReport::Instance()))) 
)

Load the playlist from a text file.

Parameters
[in]filenameFile from which to load the playlist.
[in]strictIf true, perform strict conformance checking. By default, relaxed as long as we can understand the content.
[in]typeExpected playlist type, unknown by default.
[in,out]reportWhere 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 = (*(static_cast< ts::Report * >(ts::CerrReport::Instance()))) 
)

Load the playlist from its text content.

Parameters
[in]textText of the playlist (multi-lines).
[in]strictIf true, perform strict conformance checking. By default, relaxed as long as we can understand the content.
[in]typeExpected playlist type, unknown by default.
[in,out]reportWhere 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 = (*(static_cast< ts::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]strictIf true, perform strict conformance checking. By default, relaxed as long as we can understand the content.
[in]argsWeb request arguments from command line.
[in,out]reportWhere 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]dirA 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 = (*(static_cast< ts::Report * >(ts::CerrReport::Instance()))) 
) const

Save the playlist to a text file.

Parameters
[in]filenameFile where to save the playlist. By default, use the same file from loadFile() or reset().
[in,out]reportWhere to report errors.
Returns
True on success, false on error.

◆ textContent()

UString ts::hls::PlayList::textContent ( Report report = (*(static_cast< ts::Report * >(ts::CerrReport::Instance())))) const

Build the text content of the playlist.

Parameters
[in,out]reportWhere 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]mediaA media element with all fields filled in.
[in]uriAn 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 = (*(static_cast< ts::Report * >(ts::CerrReport::Instance()))),
bool  forced = false 
)

Set the playlist type.

Parameters
[in]typeThe playlist type.
[in,out]reportWhere to report errors.
[in]forcedWhen 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 = (*(static_cast< ts::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]reportWhere to report errors.
Returns
True on success, false on error.

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

Second 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 ( Second  duration,
Report report = (*(static_cast< ts::Report * >(ts::CerrReport::Instance()))) 
)

Set the segment target duration in a media playlist.

Parameters
[in]durationThe segment target duration in seconds.
[in,out]reportWhere 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 = (*(static_cast< ts::Report * >(ts::CerrReport::Instance()))) 
)

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

Parameters
[in]seqThe sequence number of first segment.
[in,out]reportWhere 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 = (*(static_cast< ts::Report * >(ts::CerrReport::Instance()))) 
)

Set the end of list indicator in a media playlist.

Parameters
[in]endThe end of list indicator.
[in,out]reportWhere 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.

◆ segment()

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

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

Parameters
[in]indexIndex 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]segCharacteristics 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 = (*(static_cast< ts::Report * >(ts::CerrReport::Instance()))) 
)

Add a segment in a media playlist.

Parameters
[in]segThe 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]reportWhere 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]indexIndex 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]indexIndex of the media playlist to delete, from 0 to playListCount()-1.

◆ addPlayList()

bool ts::hls::PlayList::addPlayList ( const MediaPlayList pl,
Report report = (*(static_cast< ts::Report * >(ts::CerrReport::Instance()))) 
)

Add a media playlist in a master playlist.

Parameters
[in]plThe 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]reportWhere 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]minBitrateMinimum bitrate. Zero means no minimum.
[in]maxBitrateMaximum bitrate. Zero means no maximum.
[in]minWidthMinimum width. Zero means no minimum.
[in]maxWidthMaximum width. Zero means no maximum.
[in]minHeightMinimum height. Zero means no minimum.
[in]maxHeightMaximum 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.

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