BASS_StreamCreateURL
--------------------------------------------------------------------------------
Creates a sample stream from an MP3, MP2, MP1, OGG or WAV file on the internet, optionally receiving the downloaded data in a callback.
HSTREAM
WINAPI BASS_StreamCreateURL(
char *
url,
DWORD offset,
DWORD flags,
DOWNLOADPROC *proc,
DWORD user
);
Parameters
- url URL of the file to stream (should begin with "http://" or "ftp://").
offset File position to start streaming from. This is ignored by some servers, specifically when the file length is unknown, for example a Shout/Icecast server.
- flags Any combination of these flags.
- BASS_SAMPLE_FLOAT Use 32-bit floating-point sample data. WDM drivers or the BASS_STREAM_DECODE flag are required to use this flag. See Floating-point channels for more info.
- BASS_SAMPLE_MONO Decode/play the stream (MP3/MP2/MP1 only) in mono, reducing the CPU usage (if it was originally stereo). This flag is automatically applied if BASS_DEVICE_MONO was specified when calling BASS_Init.
- BASS_SAMPLE_SOFTWARE Force the stream to not use hardware mixing.
- BASS_SAMPLE_3D Use 3D functionality. This is ignored if BASS_DEVICE_3D wasn't specified when calling BASS_Init. 3D streams must be mono. The SPEAKER flags can not be used together with this flag.
- BASS_SAMPLE_LOOP Loop the file. This flag can be toggled at any time using BASS_ChannelSetFlags. This flag is ignored when streaming in blocks (BASS_STREAM_BLOCK).
- BASS_SAMPLE_FX
requires DirectX 8 or above Enable 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_RESTRATE Restrict the download rate of the file to the rate required to sustain playback. If this flag is not used, then the file will be downloaded as quickly as the user's internet connection allows.
- BASS_STREAM_BLOCK Download and play the file in smaller chunks. Uses a lot less memory than otherwise, but it's not possible to seek or loop the stream - once it's ended, the file must be opened again to play it again. This flag will automatically be applied when the file length is unknown, for example with Shout/Icecast streams. This flag also has the effect of resticting the download rate.
- BASS_STREAM_META Request metadata from the server. The data can be retrieved with BASS_StreamGetTags. A sync can also be set (using BASS_ChannelSetSync) so that you are informed when metadata is received. Note that some Shoutcast servers may require that this flag is used.
- BASS_STREAM_STATUS Pass 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.
- BASS_STREAM_AUTOFREE Automatically free the stream when it ends. This allows you to stream a file and forget about it, as BASS will automatically free the stream's resources when it has reached the end or when BASS_ChannelStop (or BASS_Stop) is called.
- BASS_STREAM_DECODE Decode the sample data, without outputting it. Use BASS_ChannelGetData to retrieve decoded sample data.
- BASS_SAMPLE_SOFTWARE/3D/FX/AUTOFREE are all ignored when using this flag, as are the SPEAKER flags.
- BASS_SPEAKER_xxx Speaker assignment flags.
- 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 Only decoding streams (BASS_STREAM_DECODE) are allowed when using the "no sound" device.
- BASS_ERROR_NONET No internet connection could be opened.
- BASS_ERROR_ILLPARAM url is not a valid URL.
- 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_FILEOPEN The file could not be opened.
- BASS_ERROR_FILEFORM The file's format is not recognised/supported.
- BASS_ERROR_FORMAT The 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_SPEAKER The device/drivers do not support the requested speaker(s), or you're attempting to assign a stereo stream to a mono speaker.
- BASS_ERROR_MEM There is insufficent memory.
- BASS_ERROR_NO3D Couldn't initialize 3D support for the stream.
- BASS_ERROR_UNKNOWN Some other mystery problem!
Remarks
Use BASS_ChannelGetInfo to retrieve information on the format (sample rate, resolution, channels) of the stream. The playback length of the stream can be retrieved using BASS_StreamGetLength.
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.
When streaming in blocks (BASS_STREAM_BLOCK flag), be careful not to stop/pause the stream for too long, otherwise the connection may timeout due to there being no activity and the stream will end prematurely.
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_StreamGetTags.
When using the BASS_STREAM_DECODE flag, it's not possible to play the stream. Because the decoded sample data is not outputted, "decoding channels" can still be used when there is no output device (using the "no sound" device with BASS_Init).
Example
Stream an MP3 file.
HSTREAM stream=BASS_StreamCreateURL("http://www.asite.com/afile.mp3",0,0,NULL,0);
See also
BASS_ChannelGetInfo, BASS_ChannelPlay, BASS_ChannelSetAttributes, BASS_ChannelSetDSP, BASS_ChannelSetFX, BASS_ChannelSetLink, BASS_StreamCreateFile, BASS_StreamCreateFileUser, BASS_StreamFree, BASS_StreamGetFilePosition, BASS_StreamGetLength, BASS_StreamGetTags, DOWNLOADPROC callback, BASS_CONFIG_NET_BUFFER, BASS_CONFIG_NET_NOPROXY, BASS_CONFIG_NET_TIMEOUT