BASS_HLS_StreamCreateURL

Creates a sample stream from an HLS playlist on the internet, optionally receiving the downloaded data in a callback.

HSTREAM BASS_HLS_StreamCreateURL(
    char *url,
    DWORD flags,
    DOWNLOADPROC *proc,
    void *user
);

Parameters

url

URL of the file to stream. Should begin with "http://" or "https://" or "ftp://". The URL can be followed by custom HTTP request headers to be sent to the server; the URL and each header should be terminated with a carriage return and line feed ("\r\n").

flags

A combination of these flags.

BASS_SAMPLE_FLOAT	Use 32-bit floating-point sample data. See Floating-point channels for info.
BASS_SAMPLE_3D	Enable 3D functionality. The stream must be mono. The SPEAKER flags cannot be used together with this flag.
BASS_STREAM_STATUS	Pass status info (HTTP tags) from the server to the DOWNLOADPROC callback during connection. This can be useful to determine the reason for a failure.
BASS_STREAM_AUTOFREE	Automatically free the stream when playback ends.
BASS_STREAM_DECODE	Decode the sample data, without playing it. Use BASS_ChannelGetData to retrieve decoded sample data. The BASS_SAMPLE_3D, BASS_STREAM_AUTOFREE and SPEAKER flags cannot be used together with this flag.
BASS_SPEAKER_xxx	Speaker assignment flags. These flags have no effect when the stream is more than stereo.
BASS_UNICODE	url is in UTF-16 form. Otherwise it is ANSI on Windows and UTF-8 on other platforms.

proc

Callback function to receive the file as it is downloaded... NULL = no callback.

user

User instance data to pass to the callback function.

Return value

If successful, the new stream's handle is returned, else 0 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_INIT	BASS_Init has not been successfully called.
BASS_ERROR_NOTAVAIL	The BASS_STREAM_AUTOFREE flag cannot be combined with the BASS_STREAM_DECODE flag.
BASS_ERROR_NONET	No internet connection could be opened.
BASS_ERROR_ILLPARAM	url is not a valid URL.
BASS_ERROR_PROTOCOL	The protocol in url is not supported.
BASS_ERROR_SSL	SSL/HTTPS support is not available. See BASS_CONFIG_LIBSSL.
BASS_ERROR_TIMEOUT	The server did not respond to the request within the timeout period, as set with the BASS_CONFIG_NET_TIMEOUT config option.
BASS_ERROR_DENIED	A valid username/password is required.
BASS_ERROR_FILEOPEN	The file could not be opened.
BASS_ERROR_FILEFORM	The file's format is not recognised/supported.
BASS_ERROR_NOTAUDIO	The file does not contain audio.
BASS_ERROR_FORMAT	The sample format is not supported.
BASS_ERROR_SPEAKER	The specified SPEAKER flags are invalid.
BASS_ERROR_MEM	There is insufficent memory.
BASS_ERROR_NO3D	Could not initialize 3D support.
BASS_ERROR_UNKNOWN	Some other mystery problem!

Remarks

HLS streams consist of a media playlist and segments. The media segments usually contain AAC audio data, but MP3 or AC3 are also possible. AAC support is available as standard with BASS via OS codecs on some platforms, but the BASS_AAC add-on can otherwise be used to provide that support; BASSHLS can make use of any add-on that has been loaded via BASS_PluginLoad. The data will usually be in an MPEG-TS container, but it can also be plain audio data, possibly with ID3v2 tags.

The main parts of the HLS spec are supported. The supported playlist tags are: EXTINF, EXT-X-BYTERANGE, EXT-X-DISCONTINUITY, EXT-X-ENDLIST, EXT-X-KEY, EXT-X-MAP, EXT-X-MEDIA, EXT-X-MEDIA-SEQUENCE, EXT-X-PROGRAM-DATE-TIME, EXT-X-STREAM-INF, EXT-X-TARGETDURATION. Details can be found in the HLS spec: tools.ietf.org/html/draft-pantos-http-live-streaming

As well as possibly ID3v2 tags, additional HLS specific tags may be available from BASS_ChannelGetTags. A sync can be set to be informed of when a new segment starts downloading, which could be used to refresh the per-segment tags. The current segment's sequence number is available from BASS_StreamGetFilePosition with BASS_FILEPOS_HLS_SEGMENT.

A DOWNLOADPROC callback function can be used to receive the downloaded data from all of the segments. When the data is in an MPEG-TS container and/or encrypted, the audio data will be extracted/decrypted before being passed to the callback function. When a stream contains ID3v2 tags, they will also be received by the DOWNLOADPROC callback function if the BASS_CONFIG_HLS_DOWNLOAD_TAGS option is enabled.

Master playlists are supported. By default, BASSHLS will try the variant streams in listed order, but bitrate-based stream selection is available via the BASS_CONFIG_HLS_BANDWIDTH option. More elaborate stream selection is possible by downloading and parsing the master playlist separately for all available options, and then passing the selected stream's URL to this function.

If the media playlist contains an EXT-X-ENDLIST tag to indicate a complete sequence, the length of the sequence (according to the sum of the EXTINF tags) will be available from BASS_ChannelGetLength and seeking will be possible via BASS_ChannelSetPosition. Seeking will be performed asynchronously and playback will be stalled in the meantime. Except for short forward seeks, seeking will involve reconnecting to the server to fetch the media segment containing the requested position, so it may take some time. If the requested position is not on a segment boundary then additional processing will be required to reach it. The BASS_POS_INEXACT flag can be used to stop at a segment boundary and avoid the additional processing. If another position is requested while seeking is in progress, the existing seek will be cancelled for the new one.

A stream's sample format cannot change, so any discontinuities (with EXT-X-DISCONTINUITY tags) must keep the same sample format (the file format/codec can change). The sample rate can change but the following segments will be played at the wrong speed then.

Any cookies that are set by the server for the master/media playlist will be included in the media segment and key requests, to allow authentication.

BASS_HLS_StreamCreateURL

Parameters

Return value

Error codes

Remarks

See also