BASS_StreamCreateURL

Creates a sample stream from an MP3, MP2, MP1, OGG, WAV, AIFF or plugin supported file on the internet, optionally receiving the downloaded data in a callback function.

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

Parameters

urlURL of the file to stream. Should begin with "http://" or "https://" or "ftp://", or another add-on supported protocol. 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").
offsetFile position to start streaming from. This is ignored by some servers, specifically when the length is unknown/undefined.
flagsA combination of these flags.
BASS_SAMPLE_FLOATUse 32-bit floating-point sample data. See Floating-point channels for info.
BASS_SAMPLE_MONODecode/play the file (OGG/MP3/MP2/MP1 only) in mono. This flag is automatically applied if BASS_DEVICE_MONO was specified when calling BASS_Init.
BASS_SAMPLE_3DEnable 3D functionality. The stream must be mono. The SPEAKER flags cannot be used together with this flag.
BASS_SAMPLE_LOOPLoop the file. This flag can be toggled at any time using BASS_ChannelFlags. This flag is ignored when streaming in blocks (BASS_STREAM_BLOCK).
BASS_STREAM_RESTRATERestrict the download rate of the file, according to the BASS_CONFIG_NET_RESTRATE config setting. If this flag is not used then the file will be downloaded as quickly as possible.
BASS_STREAM_BLOCKOnly keep a block of the downloaded file in memory, determined by the BASS_CONFIG_NET_BUFFER config setting, rather than the whole file. This uses a lot less memory than otherwise, but it is not possible to seek or loop the stream. This flag will be applied automatically when the file length is unknown or over 2GB.
BASS_STREAM_STATUSPass status info (HTTP/ICY tags) from the server to the DOWNLOADPROC callback during connection. This can be useful to determine the reason for a failure. If the downloaded data is not needed then the callbacks can be disabled via the BASS_ATTRIB_DOWNLOADPROC attribute after this call returns.
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 cannot be used together with this flag.
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 and UTF-8 on other platforms.
procCallback function to receive the file 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_NOTAVAILThe BASS_STREAM_AUTOFREE flag cannot be combined with the BASS_STREAM_DECODE flag.
BASS_ERROR_NONETNo internet connection could be opened. Can be caused by a bad proxy setting.
BASS_ERROR_ILLPARAMurl is not a valid URL.
BASS_ERROR_PROTOCOLThe protocol in url is not supported.
BASS_ERROR_SSLSSL/HTTPS support is not available. See BASS_CONFIG_LIBSSL.
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_DENIEDA valid username/password is required.
BASS_ERROR_FILEOPENThe file could not be opened.
BASS_ERROR_FILEFORMThe file's format is not recognised/supported.
BASS_ERROR_UNSTREAMABLEThe file cannot be streamed. This could be because an MP4 file's "mdat" atom comes before its "moov" atom.
BASS_ERROR_NOTAUDIOThe file does not contain audio, or it also contains video and videos are disabled.
BASS_ERROR_CODECThe file uses a codec that is not available/supported. This can apply to WAV and AIFF files.
BASS_ERROR_FORMATThe sample format is not supported.
BASS_ERROR_SPEAKERThe specified SPEAKER flags are invalid.
BASS_ERROR_MEMThere is insufficient memory.
BASS_ERROR_NO3DCould not initialize 3D support.
BASS_ERROR_UNKNOWNSome other mystery problem!

Remarks

Use BASS_ChannelGetInfo to retrieve information on the file format and sample format of the stream. The playback length of the stream can be retrieved using BASS_ChannelGetLength.

When playing the stream, BASS will stall the playback if there is insufficient data to continue playing. Playback will automatically be resumed when sufficient data has been downloaded. BASS_ChannelIsActive can be used to check if the playback is stalled, and the progress of the file download can be checked with BASS_StreamGetFilePosition.

If the server supports HTTP range requests (indicated in its response headers), BASS will automatically try to reconnect whenever the connection is lost before the end. Stopping/pausing should otherwise be avoided when the BASS_STREAM_BLOCK flag is set, to reduce the chance of disconnects from timing out.

When streaming from Shoutcast servers, metadata (track titles) may be sent by the server. The data can be retrieved with BASS_ChannelGetTags. A BASS_SYNC_META sync can also be set via BASS_ChannelSetSync to be informed when metadata is received. A BASS_SYNC_OGG_CHANGE sync can be used to be informed of when a new logical bitstream begins in an Icecast/OGG stream.

When using an offset, the file length returned by BASS_StreamGetFilePosition can be used to check that it was successful by comparing it with the original file length. Another way to check is to inspect the HTTP headers retrieved with BASS_ChannelGetTags.

When a plugin is used by a stream, there may be additional flags that are supported by it. Any such flags can be set after stream creation via BASS_ChannelFlags. BASS_ChannelGetInfo can be used to check which, if any, plugin is being used.

Custom HTTP request headers may be ignored by some plugins, notably BASSWMA.

Platform-specific

On Windows, ACM codecs are supported with compressed WAV files. Media Foundation codecs are also supported on Windows 7 and updated versions of Vista, including support for AAC and WMA. On iOS and macOS, CoreAudio codecs are supported, including support for AAC and ALAC. Android's media codecs are also supported, including support for AAC. In all cases, the OS's codecs are only tried after BASS's built-in decoders and any plugins have rejected the file. Built-in support for IMA and Microsoft ADPCM WAV files is provided on Linux/Android, while they are supported via ACM and CoreAudio codecs on Windows and macOS/iOS.

On iOS 7 and above, this function can be used to open files in the iPod Library ("ipod-library://" URLs). The offset and proc and user parameters are ignored then, as are the BASS_STREAM_RESTRATE and BASS_STREAM_BLOCK and BASS_STREAM_STATUS flags. The files are played using CoreAudio codecs and BASS does not have direct access to the files itself, so the only tags available from BASS_ChannelGetTags will be BASS_TAG_CA_CODEC tags; the MPMediaItem properties could be used to get more info.

Example

Stream an MP3 file.
HSTREAM stream = BASS_StreamCreateURL("http://www.asite.com/afile.mp3", 0, 0, NULL, 0);

Stream an MP3 file with a cookie sent to the server.

HSTREAM stream = BASS_StreamCreateURL("http://www.asite.com/afile.mp3\r\nCookie: mycookie=blah\r\n", 0, 0, NULL, 0);

See also

BASS_ChannelGetInfo, BASS_ChannelGetLength, BASS_ChannelGetTags, BASS_ChannelPlay, BASS_ChannelSetAttribute, BASS_ChannelSetDSP, BASS_ChannelSetFX, BASS_StreamCreateFile, BASS_StreamCreateFileUser, BASS_StreamFree, BASS_StreamGetFilePosition, DOWNLOADPROC callback, BASS_ATTRIB_NET_RESUME, BASS_CONFIG_NET_AGENT, BASS_CONFIG_NET_BUFFER, BASS_CONFIG_NET_PASSIVE, BASS_CONFIG_NET_PREBUF, BASS_CONFIG_NET_PROXY, BASS_CONFIG_NET_READTIMEOUT, BASS_CONFIG_NET_TIMEOUT, BASS_CONFIG_VERIFY_NET