Programming With Libshout 2

$Id: libshout.xml 7019 2004-07-06 08:05:47Z brendan $


Table of Contents

1. Overview
2. Reference
Functions
Global functions
Managing connections
Sending data
Connection parameters
Metadata
Data Types
Constants

Chapter 1. Overview

libshout is a library for streaming audio to icecast or shoutcast-compatible servers. Currently it supports two audio formats and three protocols.

Audio Formats

  • Ogg Vorbis
  • MP3

Protocols

  • HTTP
  • Audiocast
  • ShoutCast

Chapter 2. Reference

Functions

Global functions

void shout_init();

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.