Table of Contents
libshout is a library for streaming audio to icecast or shoutcast-compatible servers. Currently it supports two audio formats and three protocols.
Audio Formats
Protocols
Table of Contents
shout_init
. An
application should call this function after it has finished using libshout.
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.
shout_free
when you are
finished with it.
Frees a shout_t allocated by
shout_new
.
Opens a connection to a server. All connection parameters must have been
set prior to this call.
Return Values
SHOUTERR_SUCCESS
SHOUTERR_INSANE
self
is corrupt or incorrect. Possible reasons
include an unset host, port, or password.SHOUTERR_CONNECTED
SHOUTERR_UNSUPPORTED
SHOUTERR_NOCONNECT
SHOUTERR_SOCKET
SHOUTERR_NOLOGIN
SHOUTERR_MALLOC
Return Values
SHOUTERR_SUCCESS
SHOUTERR_INSANE
self
is not a valid shout_t
object.SHOUTERR_UNCONNECTED
self
is not currently connected.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
SHOUTERR_INSANE
self
is not a valid shout_t
object.SHOUTERR_UNCONNECTED
self
is not currently connected.SHOUTERR_MALLOC
SHOUTERR_SOCKET
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
.
Return Values
SHOUTERR_INSANE
self
is not a valid shout_t
object.SHOUTERR_UNCONNECTED
self
is not currently connected.SHOUTERR_SOCKET
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.
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.
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.localhost
.
Returns the server hostname or IP address.
Sets the server port. The default is 8000
.
Returns the server port.
Sets the user to authenticate as, for protocols that can use this parameter.
The default is source
.
Returns the user name.
Sets the password to authenticate to the server with. This parameter
must be set. There is no default.
Returns the password.
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).
Returns the protocol used to connect to the server.
Sets the audio format of this stream. The currently supported formats
are listed in Format Constants.
The default is SHOUT_FORMAT_VORBIS
.
Returns the audio format used by this stream.
Sets the mount point for this stream, for protocols that support this option
(SHOUT_PROTOCOL_ICY
doesn't).
Returns the stream mount point.
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.
Returns the dump file, if specified.
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.
Returns the user agent.
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
.
Returns whether or not this stream is public.
Sets the name of the stream.
Returns the stream name.
Sets the URL of a site about this stream.
Returns the stream URL.
Sets the genre (or genres) of the stream. This is usually a keyword list,
eg "pop rock rap".
Returns the stream genre.
Sets the description of this stream.
Returns the stream description.
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.
Returns the value of the audio info field name
, if defined.
self
.
int shout_metadata_add( | self, | |
name, | ||
value) ; |
shout_metadata_t * | self; |
const char * | name; |
const char * | 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
self
.SHOUTERR_INSANE
self
is not a valid shout_metadata_t object.SHOUTERR_MALLOC
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
SHOUTERR_INSANE
self
and/or metadata
is invalid.SHOUTERR_MALLOC
SHOUTERR_NOCONNECT
SHOUTERR_NOLOGIN
SHOUTERR_SOCKET
SHOUTERR_METADATA
Error Codes
SHOUTERR_SUCCESS
SHOUTERR_INSANE
SHOUTERR_MALLOC
SHOUTERR_NOCONNECT
SHOUTERR_NOLOGIN
SHOUTERR_SOCKET
SHOUTERR_METADATA
SHOUTERR_CONNECTED
SHOUTERR_UNCONNECTED
shout_send
) while you were not connected.SHOUTERR_UNSUPPORTED
Formats
SHOUT_FORMAT_VORBIS
SHOUT_FORMAT_MP3
Protocols
SHOUT_PROTOCOL_HTTP
SHOUT_PROTOCOL_XAUDIOCAST
SHOUT_PROTOCOL_ICY
Audio Parameters
SHOUT_AI_BITRATE
SHOUT_AI_SAMPLERATE
SHOUT_AI_CHANNELS
SHOUT_AI_QUALITY