BASS_Encode_ServerInit

Initializes a server to send an encoder's output to connecting clients.

DWORD BASS_Encode_ServerInit(
    HENCODE handle,
    char *port,
    DWORD buffer,
    DWORD burst,
    DWORD flags,
    ENCODECLIENTPROC *proc,
    void *user
);

Parameters

handleThe encoder handle.
portThe IP address and port number to accept client connections on, and a path to accept... "address:port/path", NULL = any path on an available port on all local IP addresses. The IP address should be a local IPv4 or IPv6 address, with an IPv6 address being enclosed in square brackets. If it is omitted then the server will accept connections on all local IPv4 and IPv6 addresses. If only IPv4 or IPv6 is wanted then "0.0.0.0" or "[::]" can be used. The port number should be lower than 65536. If it is "0" or omitted then an available port will be assigned. If a path is included then the server will only accept client requests for that path, otherwise any path will be accepted.
bufferThe server's buffer length in bytes. A per-client download speed cap (in KB/s) can optionally be set in the high 8 bits, which should be greater than the encoder's bitrate.
burstThe amount of buffered data to send to new clients. This will be capped at the size of the buffer.
flagsA combination of these flags.
BASS_ENCODE_SERVER_METASend Shoutcast metadata to clients that request it. The default metadata interval is 16KB (ie. the metadata is refreshed every 16KB), but a different interval (in KB) can be specified in the HIWORD - use MAKEWORD(flags,interval). The Shoutcast metadata can be set with BASS_Encode_CastSetTitle.
BASS_ENCODE_SERVER_NOHTTPDo not read or send HTTP headers.
BASS_ENCODE_SERVER_SSLSupport SSL/TLS encryption but also allow unencrypted connections. This requires the OpenSSL library.
BASS_ENCODE_SERVER_SSLONLYRequire SSL/TLS encryption. This requires the OpenSSL library.
procCallback function to receive notification of clients connecting and disconnecting... NULL = no callback.
userUser instance data to pass to the callback function.

Return value

If successful, the new server's port number is returned, else 0 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLEhandle is not valid.
BASS_ERROR_ALREADYThere is already a server set on the encoder.
BASS_ERROR_ILLPARAMport or flags is not valid. The path and Shoutcast metadata options require HTTP headers.
BASS_ERROR_BUSYThe port is in use.
BASS_ERROR_SSLThe OpenSSL library could not be loaded or initialized.
BASS_ERROR_SERVER_CERTThe SSL certificate and/or key files are missing or invalid.
BASS_ERROR_MEMThere is insufficient memory.
BASS_ERROR_UNKNOWNSome other mystery problem!

Remarks

This function allows remote (or local) clients to receive the encoder's output by setting up a TCP server for them to connect to, using BASS_StreamCreateURL for example. Connections can be refused by the ENCODECLIENTPROC callback function, and already connected clients can be kicked with the BASS_Encode_ServerKick function.

If a path is specified in the port parameter then the server will only handle client requests with exactly the same path. Multiple servers can share the same port by having differing paths. If a new server has the same path as an existing server then new clients will connect to the new server, while existing clients remain connected to the old server.

The server buffers the data that it receives from the encoder, and the data is then sent from the buffer to the connected clients. The buffer should be at least big enough to account for the time that it takes for the clients to receive the data. If a client falls too far behind (beyond the buffer length), it will miss some data. When a client connects, buffered data can be "burst" to the client, allowing it to prebuffer and begin playback more quickly. If a speed cap is set (in the buffer parameter), that will limit the burst speed.

An encoder needs to be started, but with no data yet sent to it, before using this function to setup the 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.

Normally, BASSenc will produce the encoded data (with the help of an encoder) that is sent to a clients, but it is also possible to send already encoded data (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).

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). A certificate and private key are also required, and can be set via the BASS_CONFIG_ENCODE_SERVER_CERT and BASS_CONFIG_ENCODE_SERVER_KEY config options, respectively. If there already is a server on the same port then its certificate and key will be used by the new server too, regardless of those config settings.

Chained OGG streams are supported, which can be used for metadata updates. The server also supports Shoutcast metadata with any audio format, but Shoutcast traditionally only supports MP3 or AAC encoding, so some players might not read the metadata with other formats. BASS (eg. BASS_StreamCreateURL) does support Shoutcast metadata with any audio format.

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 a server on port 8000 with a fully burstable 64KB buffer.
BASS_Encode_ServerInit(encoder, "8000", 64000, 64000, 0, NULL, NULL);

Start a server on port 8000 with a fully burstable 64KB buffer and Shoutcast metadata enabled with an 8KB interval.

BASS_Encode_ServerInit(encoder, "8000", 64000, 64000, MAKELONG(BASS_ENCODE_SERVER_META, 8), NULL, NULL);

Start a server on port 8000 with a fully burstable 64KB buffer and limit the download speed to 32 KB/s (256kb/s).

BASS_Encode_ServerInit(encoder, "8000", 64000 | (32 << 24), 64000, 0, NULL, NULL);

Start a server on any available port on the IPv4 loopback address (127.0.0.1) with a fully burstable 40KB buffer.

DWORD port = BASS_Encode_ServerInit(encoder, "127.0.0.1", 40000, 40000, 0, NULL, NULL);

Start 2 servers on port 8000 with fully burstable 64KB buffers, one with path /stream1 and the other /stream2.

BASS_Encode_ServerInit(encoder1, "8000/stream1", 64000, 64000, 0, NULL, NULL); // start the 1st server
BASS_Encode_ServerInit(encoder2, "8000/stream2", 64000, 64000, 0, NULL, NULL); // start the 2nd server

Setup PCM encoding on a dummy stream to feed pre-encoded data to a server on port 8000 with a 64KB buffer.

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, NULL, NULL); // setup the PCM encoder
BASS_Encode_ServerInit(encoder, "8000", 64000, 64000, 0, NULL, NULL); // start the server
...
BASS_Encode_Write(encoder, data, length); // feed encoded data to the encoder/server (repeat periodically)

See also

BASS_Encode_CastInit, BASS_Encode_ServerKick, BASS_Encode_SetNotify, BASS_Encode_Start, BASS_Encode_StartACM, BASS_Encode_StartCA, BASS_CONFIG_ENCODE_CAST_TIMEOUT