BASS_Encode_CastInit

Initializes sending an encoder's output to a Shoutcast or Icecast server.

BOOL BASS_Encode_CastInit(
    HENCODE handle,
    char *server,
    char *pass,
    char *content,
    char *name,
    char *url,
    char *genre,
    char *desc,
    char *headers,
    DWORD bitrate,
    DWORD flags
);

Parameters

handleThe encoder handle.
serverThe server to send to, in the form of "address:port" (Shoutcast) or "address:port,streamid" (Shoutcast 2) or "address:port/mount" (Icecast). The address can be a hostname or an IPv4 or IPv6 address. IPv6 addresses should be enclosed in square brackets.
passThe server password. A username can be included in the form of "username:password" when connecting to an Icecast or Shoutcast 2 server.
contentThe MIME type of the encoder output. This can be one of the following.
BASS_ENCODE_TYPE_MP3MP3.
BASS_ENCODE_TYPE_OGGOGG.
BASS_ENCODE_TYPE_AACAAC.
nameThe stream name... NULL = no name.
urlThe URL, for example, of the radio station's webpage... NULL = no URL.
genreThe genre... NULL = no genre.
descDescription... NULL = no description. This applies to Icecast only.
headersOther headers to send to the server... NULL = none. Each header should end with a carriage return and line feed ("\r\n"). The total length of the headers (including those from the other parameters) must not exceed 4KB.
bitrateThe bitrate (in kbps) of the encoder output... 0 = undefined bitrate. In cases where the bitrate is a "quality" (rather than CBR) setting, the headers parameter can be used to communicate that instead, eg. "ice-bitrate: Quality 0\r\n".
flagsA combination of these flags.
BASS_ENCODE_CAST_PUBLICAdd the stream to the public directory at directory.shoutcast.com or dir.xiph.org (or as defined in the server config).
BASS_ENCODE_CAST_PUTUse the PUT method when connecting to an Icecast server, else the SOURCE method is used. This flag has no effect on Shoutcast servers, and is applied automatically when the BASS_ENCODE_CAST_SSL flag is specified.
BASS_ENCODE_CAST_SSLUse SSL/TLS encryption. This requires the OpenSSL library, and that the server is configured to accept encrypted connections.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLEhandle is not valid.
BASS_ERROR_ALREADYThere is already a cast set on the encoder.
BASS_ERROR_ILLPARAMserver does not include a port number and/or the headers are too long.
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_FILEOPENCould not connect to the server.
BASS_ERROR_BUSYAnother source client is already connected to the server. This is only indicated by Icecast and Shoutcast 2.x servers; a busy Shoutcast 1.x server will result in BASS_ERROR_UNKNOWN instead.
BASS_ERROR_SSLThe OpenSSL library could not be loaded or initialized.
BASS_ERROR_CAST_DENIEDpass is not valid.
BASS_ERROR_UNKNOWNSome other mystery problem!

Remarks

This function sets up a Shoutcast/Icecast source client, sending the encoder's output to a server, which listeners can then connect to and receive the data from. The Shoutcast and Icecast server software is available from www.shoutcast.com and www.icecast.org/download, respectively.

An encoder needs to be started, but with no data yet sent to it, before using this function to setup the sending of the encoder's output to a Shoutcast or Icecast server. If BASS_Encode_Start is used, the encoder should be setup to write its output to STDOUT. Due to the length restrictions of WAVE headers/files, the encoder should also be started with the BASS_ENCODE_NOHEAD flag, and the sample format details sent via the command-line.

Unless the BASS_ENCODE_CAST_NOLIMIT flag is set on the encoder, BASSenc automatically limits the rate that data is processed to real-time speed to avoid overflowing the server's buffer, which means that it is safe to simply try to process data as quickly as possible, eg. when the source is a decoding channel. Encoders set on recording channels are automatically exempt from the rate limiting, as they are inherently real-time. With BASS 2.4.6 or above, also exempt are encoders that are fed in a playback buffer update cycle (including BASS_Update and BASS_ChannelUpdate calls), eg. when the source is a playing channel; that is to avoid delaying the update thread, which could result in playback buffer underruns.

SSL/TLS encryption requires the OpenSSL library (libssl) or compatible. A filename for that can be specified via the BASS_CONFIG_LIBSSL config option. If that is unset or fails to load then BASSenc will check if an OpenSSL library has already been loaded into the process with global scope and use that, and if that fails too then it will try some standard filenames for the library (see platform-specific notes below).

Normally, BASSenc will produce the encoded data (with the help of an encoder) that is sent to a Shoutcast/Icecast server, but it is also possible to send already encoded data to a server (without first decoding and re-encoding it) via the PCM encoding option. The encoder can be set on any BASS channel, as rather than feeding on sample data from the channel, BASS_Encode_Write would be used to feed in the already encoded data. BASSenc does not know what the data's bitrate is in that case, so it is up to the user to process the data at the correct rate (real-time speed).

BASS_Encode_ServerInit can be used to setup a server that listeners can connect to directly, without a Shoutcast/Icecast server intermediary.

Platform-specific

The default OpenSSL library filenames checked (in order of preference) on Linux are libssl.so, libssl.so.1.1, libssl.so.10, libssl.so.1.0.0. On Windows, it is bass_ssl.dll (BASS_SSL add-on), libssl-1_1.dll (or libssl-1_1-x64.dll if 64-bit), ssleay32.dll. On macOS, it is libssl.0.9.8.dylib. On Android, it is libbass_ssl.so (BASS_SSL add-on), libssl.so, libboringssl.so. The BASS_SSL add-on is available for Windows and Android from the BASS website. The BASS_CONFIG_LIBSSL config option is normally only available on Linux and Android but BASSenc adds support for it on other platforms too.

This function is not available on Windows CE.

Example

Start encoding a stereo 44100hz channel to 128kb/s MP3, and send the output to a Shoutcast server.
HENCODE encoder = BASS_Encode_Start(channel, "lame -r -s 44100 -b 128 -", BASS_ENCODE_NOHEAD, NULL, 0); // setup the encoder
BASS_Encode_CastInit(encoder, "server.com:8000", "password", BASS_ENCODE_TYPE_MP3, "name", "url",
    "genre", NULL, NULL, 128, BASS_ENCODE_CAST_PUBLIC); // start the cast

Setup PCM encoding on a dummy stream to send pre-encoded MP3 data to a Shoutcast server.

dummy = BASS_StreamCreate(44100, 1, BASS_STREAM_DECODE, STREAMPROC_DUMMY, NULL); // create a dummy stream to host the encoder
encoder = BASS_Encode_Start(dummy, NULL, BASS_ENCODE_PCM | BASS_ENCODE_NOHEAD | BASS_ENCODE_CAST_NOLIMIT, NULL, NULL); // setup the PCM encoder
BASS_Encode_CastInit(encoder, "server.com:8000", "password", BASS_ENCODE_TYPE_MP3, "name", "url",
    "genre", NULL, NULL, 128, BASS_ENCODE_CAST_PUBLIC); // start the cast
...
BASS_Encode_Write(encoder, mp3data, length); // feed MP3 data to the encoder/caster (repeat periodically)

See also

BASS_Encode_CastGetStats, BASS_Encode_CastSetTitle, BASS_Encode_ServerInit, BASS_Encode_SetNotify, BASS_Encode_Start, BASS_Encode_StartACM, BASS_Encode_StartCA, BASS_CONFIG_ENCODE_CAST_BIND, BASS_CONFIG_ENCODE_CAST_PROXY, BASS_CONFIG_ENCODE_CAST_TIMEOUT