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

urlURL of the file to stream. Should begin with "http://" or "https://" or "ftp://".
flagsA combination of these flags.
BASS_SAMPLE_FLOATUse 32-bit floating-point sample data. See Floating-point channels for more info.
BASS_SAMPLE_SOFTWAREForce the stream to not use hardware mixing.
BASS_SAMPLE_3DEnable 3D functionality. This requires that the BASS_DEVICE_3D flag was specified when calling BASS_Init, and the stream must be mono. The SPEAKER flags can not be used together with this flag.
BASS_SAMPLE_FXEnable the old implementation of DirectX 8 effects. See the DX8 effect implementations section for details. Use BASS_ChannelSetFX to add effects to the stream.
BASS_STREAM_AUTOFREEAutomatically free the stream when playback ends.
BASS_STREAM_DECODEDecode the sample data, without playing it. Use BASS_ChannelGetData to retrieve decoded sample data. The BASS_SAMPLE_3D, BASS_STREAM_AUTOFREE and SPEAKER flags can not be used together with this flag. The BASS_SAMPLE_SOFTWARE and BASS_SAMPLE_FX flags are also ignored.
BASS_SPEAKER_xxxSpeaker assignment flags. These flags have no effect when the stream is more than stereo.
BASS_UNICODEurl is in UTF-16 form. Otherwise it is ANSI on Windows or Windows CE, and UTF-8 on other platforms.
procCallback function to receive the data as it is downloaded... NULL = no callback.
userUser 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_INITBASS_Init has not been successfully called.
BASS_ERROR_NOTAVAILOnly decoding channels (BASS_STREAM_DECODE) are allowed when using the "no sound" device. The BASS_STREAM_AUTOFREE flag is also unavailable to decoding channels.
BASS_ERROR_NONETNo internet connection could be opened.
BASS_ERROR_ILLPARAMurl is not a valid URL.
BASS_ERROR_SSLSSL/HTTPS support is not available.
BASS_ERROR_TIMEOUTThe server did not respond to the request within the timeout period, as set with the BASS_CONFIG_NET_TIMEOUT config option.
BASS_ERROR_FILEOPENThe file could not be opened.
BASS_ERROR_FILEFORMThe file's format is not recognised/supported.
BASS_ERROR_FORMATThe sample format is not supported by the device/drivers. If the stream is more than stereo or the BASS_SAMPLE_FLOAT flag is used, it could be that they are not supported (ie. no WDM drivers).
BASS_ERROR_SPEAKERThe specified SPEAKER flags are invalid. The device/drivers do not support them, they are attempting to assign a stereo stream to a mono speaker or 3D functionality is enabled.
BASS_ERROR_MEMThere is insufficent memory.
BASS_ERROR_NO3DCould not initialize 3D support.
BASS_ERROR_UNKNOWNSome 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-ENDLIST, EXT-X-KEY, EXT-X-MEDIA-SEQUENCE, EXT-X-PROGRAM-DATE-TIME, EXT-X-STREAM-INF, EXT-X-TARGETDURATION. Details can be found in the HLS spec: https://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, the audio data will be extracted from the container before being passed to the callback function.

Master playlists are supported, but BASSHLS will simply play the first entry from them. If you would like to play a different entry (eg. perhaps for a different bitrate), you could download the master playlist separately and then extract the wanted entry's URL from it and pass that to BASSHLS.

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. 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 is required to reach it, and if that takes a long time then the seeking may stop short even if the BASS_POS_INEXACT flag is not used. BASS_ChannelGetPosition can be used to confirm what the position actually is after seeking, and if required, the BASS_POS_DECODETO flag can be used in additional BASS_ChannelSetPosition calls to reach the wanted position.

Platform-specific

Away from Windows, all mixing is done in software (by BASS), so the BASS_SAMPLE_SOFTWARE flag is unnecessary. The BASS_SAMPLE_FX flag is also ignored.

See also

BASS_HLS_StreamCreateFile

BASS_ChannelGetInfo, BASS_ChannelGetTags, BASS_ChannelPlay, BASS_ChannelSetAttribute, BASS_ChannelSetDSP, BASS_ChannelSetFX, BASS_StreamFree, DOWNLOADPROC callback, BASS_CONFIG_NET_AGENT, BASS_CONFIG_NET_BUFFER, BASS_CONFIG_NET_PREBUF, BASS_CONFIG_NET_PROXY, BASS_CONFIG_NET_TIMEOUT