# Programming With Libshout 2

## Overview

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

## Audio Formats

- Ogg (audio any video with different codecs)
- WebM (audio and video)
- MP3

## Protocols

- HTTP
- RoarAudio
- Audiocast
- ShoutCast

## 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
      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
      shout_t *self

Frees a `shout_t` allocated by `shout_new`.

      int shout_open
      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
      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.

      int shout_get_connected
      shout_t *self

Returns the connection status of the given `shout_t` object.

#### Return Values

`SHOUTERR_INSANE`

- `self` is not a valid `shout_t` object.

`SHOUTERR_UNCONNECTED`

- `self` is not currently connected.

`SHOUTERR_CONNECTED`

- `self` is currently connected.

      const char *shout_get_error
      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
      shout_t *self

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

#### Sending data

      int shout_send
      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
      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`.

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
      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
      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.

      ssize_t shout_queuelen
      shout_t *self

Returns the number of bytes currently on the write queue.

This is only useful in non-blocking mode.

#### 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_nonblocking
      shout_t *self
      unsigned int nonblocking

Sets non-blocking mode. The default is `0`.

      unsigned int shout_get_nonblocking
      shout_t *self

Returns non-blocking mode or `0` in case of error.

      int shout_set_host
      shout_t *self
      const char *host

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

      const char *shout_get_host
      shout_t *self

Returns the server hostname or IP address.

      int shout_set_port
      shout_t *self
      unsigned short port

Sets the server port. The default is `8000`.

      unsigned short shout_get_port
      shout_t *self

Returns the server port.

      int shout_set_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
      shout_t *self

Returns the user name.

      int shout_set_password
      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_password
      shout_t *self

Returns the password.

      int shout_set_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
      shout_t *self

Returns the protocol used to connect to the server.

      int shout_set_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_OGG`.

      int shout_get_format
      shout_t *self

Returns the audio format used by this stream.

      int shout_set_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
      shout_t *self

Returns the stream mount point.

      int shout_set_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
      shout_t *self

Returns the dump file, if specified.

      int shout_set_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
      shout_t *self

Returns the user agent.

      int shout_set_tls
      shout_t *self
      int mode

This function sets the TLS (Transport Layer Security) mode to use. `mode` is a TLS mode. This is `SHOUT_TLS_AUTO` by default.

To force TLS on you should use `SHOUT_TLS_AUTO_NO_PLAIN` and `SHOUT_TLS_DISABLED` to force TLS off.
While `SHOUT_TLS_AUTO` may connect via TLS this is not a secure mode as everybody can do a man in the middle kind of attack and downgrade the connection to plain.

      int shout_get_tls
      shout_t *self

Returns the currently used TLS mode.

      int shout_set_ca_directory
      shout_t *self
      const char *directory

This sets the CA directory used by libshout to verify server certificates. Defaults to system defaults.

      const char *shout_get_ca_directory
      shout_t *self

Returns the currently used CA directory.

      int shout_set_ca_file
      shout_t *self
      const char *file

Sets a file with CA certificates used to verify server certificates. Defaults to system defaults. The file must be in PEM format.

You can use this for self signed server certificates. In this case you point this to the server certificate in PEM format. Keep in mind that this will allow self-signed certificates but other checks such as hostname still needs to verify correctly.

      const char *shout_get_ca_file
      shout_t *self

Returns the currently used CA file.

      int shout_set_allowed_ciphers
      shout_t *self
      const char *ciphers

This sets the list of currently allowed ciphers in OpenSSL format. Defaults to a list of ciphers considerd secure as of day of release.

Setting this to a insecure list may render encryption and authentication useless.
Any application using this call must expose this list to the user. If the user can not alter this list your application will harm security badly by preventing the user to get to a save value by setting it manually or upgrading libshout. Do not use this call if you don't know what you are doing.

      const char *shout_get_allowed_ciphers
      shout_t *self

Returns the currently used list of allowed ciphers.

      int shout_set_client_certificate
      shout_t *self
      const char *certificate

This sets the client certificate to be used. Defaults to none. The file must be in PEM format and must contain both the certificate as well as the private key for that certificate.

      const char *shout_get_client_certificate
      shout_t *self

Returns the currently used client certificate.

#### 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
      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
      shout_t *self

Returns whether or not this stream is public.

      int shout_set_meta
      shout_t *self
      const char *name
      const char *value

This function sets the meta data for the stream.

      const char *shout_get_meta
      shout_t *self
      const char *name

This function gets the meta data for the stream.

      int shout_set_audio_info
      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
      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
      shout_metadata_t *self

Frees any resources associated with `self`.

      int shout_metadata_add
      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
      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).

#### Obsolate metadata Interface

All those functions have been replaced by `shout_set_meta` and `shout_get_meta`. They may be removed by newer versions of this library.

      int shout_set_name
      shout_t *self
      const char *name

Sets the name of the stream.

      const char *shout_get_name
      shout_t *self

Returns the stream name.

      int shout_set_url
      shout_t *self
      const char *url

Sets the URL of a site about this stream.

      const char *shout_get_url
      shout_t *self

Returns the stream URL.

      int shout_set_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
      shout_t *self

Returns the stream genre.

      int shout_set_description
      shout_t *self
      const char *description

Sets the description of this stream.

      const char *shout_get_description
      shout_t *self

Returns the stream description.

### 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.

`SHOUTERR_BUSY`

- Indicates that the socket is busy. The funtion returning this should be called again later. This is likely to happen in non-blocking mode but may also happen in blocking mode.

`SHOUTERR_NOTLS`

- TLS (Transport Layer Security) was requested via `shout_set_tls` but is not supported by the server.

`SHOUTERR_TLSBADCERT`

- A TLS (Transport Layer Security) connection has been established but the server returned a certificate which failed the check. The certificate may be invalid or is not signed by a trusted CA. See `shout_set_tls`.

`SHOUTERR_RETRY`

- The caller should retry this call later.

### Formats

`SHOUT_FORMAT_OGG`

- The Ogg Format. Vorbis or any codec may be used. This is the default format.

`SHOUT_FORMAT_WEBM`

- The WebM format.

`SHOUT_FORMAT_WEBMAUDIO`

- The WebM format, audio only streams.

`SHOUT_FORMAT_VORBIS`

- This is deprecated. It is an alias to `SHOUT_FORMAT_OGG`. Please migrate your code.

`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_ROARAUDIO`

- The RoarAudio protocol. This is the native protocol for RoarAudio servers.

`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.

### Stream Metadata Parameters

`SHOUT_META_NAME`

- Sets stream name.

`SHOUT_META_URL`

- Sets stream URL.

`SHOUT_META_GENRE`

- Sets stream genre.

`SHOUT_META_DESCRIPTION`

- Sets stream description.

`SHOUT_META_IRC`

- Sets IRC contact information for stream.

`SHOUT_META_AIM`

- Sets AIM contact information for stream.

`SHOUT_META_ICQ`

- Sets ICQ contact information for stream.

### TLS modes

`SHOUT_TLS_DISABLED`

- TLS (Transport Layer Security) is disabled. Passwords and data will be sent unencrypted.

`SHOUT_TLS_AUTO`

- TLS (Transport Layer Security) support by the server will be autodetected. This is the default. In this mode TLS is used if supported by the server.
  Please note that this is not a secure mode as it will not prevent any downgrade attacks. `SHOUT_TLS_AUTO_NO_PLAIN` is a more secure version of this mode.

`SHOUT_TLS_AUTO_NO_PLAIN`

- TLS (Transport Layer Security) is used. Autodetection is used to find out about which modes are supported by the server. This mode should be used for secure connections.

`SHOUT_TLS_RFC2818`

- TLS (Transport Layer Security) is used as defined by RFC2818. In this mode libshout expects a TLS socket on the server side and will begin with a TLS handshake prior to any other communication.

`SHOUT_TLS_RFC2817`

- TLS (Transport Layer Security) is used as defined by RFC2817. In this mode libshout will use HTTP/1.1's Upgrade:-process to switch to TLS. This allows to use TLS on a non-TLS socket of the server.