Programming With Libshout 2

Initializes the shout library. Currently this initializes the networking mutexes when the library is built with thread safety. This function must always be called before any other libshout function.

void shout_shutdown();

Releases any resources which may have been allocated by a call to shout_init. An application should call this function after it has finished using libshout.

`const char *shout_version(`	`major`,
	`minor`,
	`patch)`;

int *	`major`;
int *	`minor`;
int *	`patch`;

Returns the version of the libshout library, both as a string via the return value, and as a set of integers corresponding to the major, minor and patch levels of the library. The application must allocate the integer parameters. If any parameter is NULL, libshout will not attempt to set it.

Managing connections

shout_t *shout_new();

Allocates a new shout_t structure. May return NULL if no memory is available. The result should be disposed of with shout_free when you are finished with it.

void shout_free(self);
shout_t *self;

Frees a shout_t allocated by shout_new.

int shout_open(self);
shout_t *self;

Opens a connection to a server. All connection parameters must have been set prior to this call.

Return Values

SHOUTERR_SUCCESS: The connection was successfully opened.
SHOUTERR_INSANE: self is corrupt or incorrect. Possible reasons include an unset host, port, or password.
SHOUTERR_CONNECTED: The connection has already been opened.
SHOUTERR_UNSUPPORTED: The protocol/format combination is unsupported. For instance, Ogg Vorbis may only be sent via the HTTP protocol.
SHOUTERR_NOCONNECT: A connection to the server could not be established.
SHOUTERR_SOCKET: An error occured while talking to the server.
SHOUTERR_NOLOGIN: The server refused login, probably because authentication failed.
SHOUTERR_MALLOC: There wasn't enough memory to complete the operation.

int shout_close(self);
shout_t *self;

Closes a connection to the server.

Return Values

SHOUTERR_SUCCESS: The connection was successfully closed.
SHOUTERR_INSANE: self is not a valid shout_t object.
SHOUTERR_UNCONNECTED: self is not currently connected.

const char *shout_get_error(self);
shout_t *self;

Returns a statically allocated string describing the last shout error that occured in this connection. Only valid until the next call affecting this connection.

int shout_get_errno(self);
shout_t *self;

Returns the shout error code of the last error that occured in this connection.

Sending data

`int shout_send(`	`self`,
	`data>`,
	`len)`;

shout_t *	`self`;
const unsigned char *	`data>`;
size_t	`len`;

Sends len bytes of audio data from the buffer pointed to by data to the server. The connection must already have been established by a successful call to shout_open.

Return Values

SHOUTERR_SUCCESS: The audio data was sent successfully.
SHOUTERR_INSANE: self is not a valid shout_t object.
SHOUTERR_UNCONNECTED: self is not currently connected.
SHOUTERR_MALLOC: There wasn't enough memory to complete the operation.
SHOUTERR_SOCKET: An error occured while talking to the server.

`ssize_t shout_send_raw(`	`self`,
	`data>`,
	`len)`;

shout_t *	`self`;
const unsigned char *	`data>`;
size_t	`len`;

Sends len bytes of audio data from the buffer pointed to by data to the server. The data is not parsed for timing or validity, but sent raw over the connection. The connection must already have been established by a successful call to shout_open.

Warning

This function should not be used unless you know exactly what you are doing. Its use is deprecated and it may be removed in a future version of the library.

Return Values

>= 0: The number of bytes written.
SHOUTERR_INSANE: self is not a valid shout_t object.
SHOUTERR_UNCONNECTED: self is not currently connected.
SHOUTERR_SOCKET: An error occured while talking to the server.

void shout_sync(self);
shout_t *self;

Causes the caller to sleep for the amount of time necessary to play back audio sent since the last call to shout_sync. Should be called before every call to shout_send to ensure that audio data is sent to the server at the correct speed. Alternatively, the caller may use shout_delay to determine the number of milliseconds to wait and delay itself.

int shout_delay(self);
shout_t *self;

Returns the number of milliseconds the caller should wait before calling shout_send again. This function is provided as an alternative to shout_sync for applications that may wish to do other processing in the meantime.

Connection parameters

The following functions are used to get or set attributes of the shout_t object before calling shout_open. They all work the same way: they operate on one attribute of a shout_t*. The shout_get_* functions return the value of their associated parameter, or 0 on error (that's NULL for those functions that return strings). The shout_set_* functions will return either SHOUTERR_SUCCESS on success, or one of:

SHOUTERR_INSANE - shout_t is invalid.
SHOUTERR_MALLOC - libshout could not allocate enough memory to assign the parameter.
SHOUTERR_CONNECTED - you are attempting to change a connection attribute while the connection is open. Since these parameters are only used when first opening the connection, this operation would be useless.

`int shout_set_host(`	`self`,
	`host)`;

shout_t *	`self`;
const char *	`host`;

Sets the server hostname or IP address. The default is localhost.

const char *shout_get_host(self);
shout_t *self;

Returns the server hostname or IP address.

int shout_set_port(self, port);
shout_t *self;
int port;

Sets the server port. The default is 8000.

int shout_get_port(self);
shout_t *self;

Returns the server port.

`int shout_set_user(`	`self`,
	`user)`;

shout_t *	`self`;
const char *	`user`;

Sets the user to authenticate as, for protocols that can use this parameter. The default is source.

const char *shout_get_user(self);
shout_t *self;

Returns the user name.

`int shout_set_pass(`	`self`,
	`pass)`;

shout_t *	`self`;
const char *	`pass`;

Sets the password to authenticate to the server with. This parameter must be set. There is no default.

const char *shout_get_pass(self);
shout_t *self;

Returns the password.

`int shout_set_protocol(`	`self`,
	`protocol)`;

shout_t *	`self`;
int	`protocol`;

Set the protocol with which to connect to the server. Supported protocols are listed in Protocol Constants. The default is SHOUT_PROTOCOL_HTTP (compatible with Icecast 2).

int shout_get_protocol(self);
shout_t *self;

Returns the protocol used to connect to the server.

`int shout_set_format(`	`self`,
	`format)`;

shout_t *	`self`;
int	`format`;

Sets the audio format of this stream. The currently supported formats are listed in Format Constants. The default is SHOUT_FORMAT_VORBIS.

int shout_get_format(self);
shout_t *self;

Returns the audio format used by this stream.

`int shout_set_mount(`	`self`,
	`mount)`;

shout_t *	`self`;
const char *	`mount`;

Sets the mount point for this stream, for protocols that support this option (SHOUT_PROTOCOL_ICY doesn't).

const char *shout_get_mount(self);
shout_t *self;

Returns the stream mount point.

`int shout_set_dumpfile(`	`self`,
	`dumpfile)`;

shout_t *	`self`;
const char *	`dumpfile`;

If the server supports it, you can request that your stream be archived on the server under the name dumpfile. This can quickly eat a lot of disk space, so think twice before setting it.

const char *shout_get_dumpfile( self);

shout_t *

self;

Returns the dump file, if specified.

`int shout_set_agent(`	`self`,
	`agent)`;

shout_t *	`self`;
const char *	`agent`;

Sets the user agent header. This is libshout/VERSION by default. If you don't know what this function is for, don't use it.

const char *shout_get_agent(self);
shout_t *self;

Returns the user agent.

Directory parameters

The following parameters are optional. They are used to control whether and how your stream will be listed in the server's stream directory (if available).

`int shout_set_public(`	`self`,
	`makepublic)`;

shout_t *	`self`;
int	`makepublic`;

Setting this to 1 asks the server to list the stream in any directories it knows about. To suppress listing, set this to 0. The default is 0.

int shout_get_public(self);
shout_t *self;

Returns whether or not this stream is public.

`int shout_set_name(`	`self`,
	`name)`;

shout_t *	`self`;
const char *	`name`;

Sets the name of the stream.

const char *shout_get_name(self);
shout_t *self;

Returns the stream name.

`int shout_set_url(`	`self`,
	`url)`;

shout_t *	`self`;
const char *	`url`;

Sets the URL of a site about this stream.

const char *shout_get_url(self);
shout_t *self;

Returns the stream URL.

`int shout_set_genre(`	`self`,
	`genre)`;

shout_t *	`self`;
const char *	`genre`;

Sets the genre (or genres) of the stream. This is usually a keyword list, eg "pop rock rap".

const char *shout_get_genre(self);
shout_t *self;

Returns the stream genre.

`int shout_set_description(`	`self`,
	`description)`;

shout_t *	`self`;
const char *	`description`;

Sets the description of this stream.

const char *shout_get_description( self);

shout_t *

self;

Returns the stream description.

`int shout_set_audio_info(`	`self`,
	`name`,
	`value)`;

shout_t *	`self`;
const char *	`name`;
const char *	`value`;

Sets a stream audio parameter (eg bitrate, samplerate, channels or quality). The currently defined parameters are listed in the Audio Info Constants section, but you are free to add additional fields if your directory server understands them.

`const char *shout_get_audio_info(`	`self`,
	`name)`;

shout_t *	`self`;
const char *	`name`;

Returns the value of the audio info field name, if defined.

Metadata

These functions currently only make sense for MP3 streams. Vorbis streams are expected to embed metadata as vorbis comments in the audio stream.

shout_metadata_t *shout_metadata_new();

Allocates a new metadata structure, or returns NULL if no memory is available. The returned structure should be freed with shout_metadata_free when you are done with it.

void shout_metadata_free( self);

shout_metadata_t *

self;

Frees any resources associated with self.

`int shout_metadata_add(`	`self`,
	`name`,
	`value)`;

shout_metadata_t *	`self`;
const char *	`name`;
const char *	`value`;

Add metadata value value to self, under the key name. You'll probably want to set name to "song", though "url" may also be useful.

Return Values

SHOUTERR_SUCCESS: The metadata was copied into self.
SHOUTERR_INSANE: self is not a valid shout_metadata_t object.
SHOUTERR_MALLOC: Couldn't allocate enough memory to copy the metadata.

`int shout_set_metadata(`	`self`,
	`metadata)`;

shout_t *	`self`;
shout_metadata_t *	`metadata`;

Sets metadata on the connection self to metadata. Only MP3 streams support this type of metadata update. You may use this function on defined but closed connections (this is useful if you simply want to set the metadata for a stream provided by another process).

Return Values

SHOUTERR_SUCCESS: Metadata was updated successfully.
SHOUTERR_INSANE: self and/or metadata is invalid.
SHOUTERR_MALLOC: Couldn't allocate enough memory to complete the operation.
SHOUTERR_NOCONNECT: The server refused the connection attempt.
SHOUTERR_NOLOGIN: The server did not accept your authorization credentials.
SHOUTERR_SOCKET: An error occured talking to the server.
SHOUTERR_METADATA: The server returned any other error (eg bad mount point).

Data Types

shout_t: Opaque data type that refers to a single server connection.
shout_metadata_t: Opaque data type that refers to a set of metadata attributes. Currently the only defined attribute is song.

Constants

Error Codes

SHOUTERR_SUCCESS: Indicates success.
SHOUTERR_INSANE: Indicates bad parameters, either nonsense or not applicable due to the current state of the connection.
SHOUTERR_MALLOC: Indicates the function could not allocate the memory it required.
SHOUTERR_NOCONNECT: Indicates a connection with the server could not be established.
SHOUTERR_NOLOGIN: Indicates the server refused to accept a login attempt. This could be caused by a bad user name or password.
SHOUTERR_SOCKET: Indicates an error sending or receiving data.
SHOUTERR_METADATA: Indicates an error updating metadata on the server.
SHOUTERR_CONNECTED: Indicates that, while connected, you attempted to call a function which only makes sense before connection (eg you attempted to set the user name or stream name).
SHOUTERR_UNCONNECTED: Indicates that you attempted to use a function that requires an open connection (for example, shout_send) while you were not connected.
SHOUTERR_UNSUPPORTED: Indicates that you attempted to use a function which is unsupported in the state of your connection. For example, attempting to set metadata while using the Ogg Vorbis format is unsupported.

Formats

SHOUT_FORMAT_VORBIS: The Ogg Vorbis format. This is the default format.
SHOUT_FORMAT_MP3: The MP3 format.

Protocols

SHOUT_PROTOCOL_HTTP: The HTTP protocol. This is the native protocol of the icecast 2 server, and is the default.
SHOUT_PROTOCOL_XAUDIOCAST: The Audiocast format. This is the native protocol of icecast 1.
SHOUT_PROTOCOL_ICY: The ShoutCast format. This is the native protocol of ShoutCast.

Audio Parameters

SHOUT_AI_BITRATE: Used to specify the nominal bitrate of the stream.
SHOUT_AI_SAMPLERATE: Used to specify the samplerate of the stream.
SHOUT_AI_CHANNELS: Used to specify the number of channels (usually one or two).
SHOUT_AI_QUALITY: Used to specify the Ogg Vorbis encoding quality of the stream.