annotate README.icecast @ 3187:360e92f3211d

alsa-ng: Apparently 24bit values are padded to 32bit, so we need to tell ALSA that. The FMT_*24_* constants are misleading.

Icecast plugin notes
--------------------

0. Build-time requirements
==========================

To build Icecast plugin successfully, you need at least:

  * Audacious development files (audacious-dev package)

  * Audacious plugins sources themselves
    and all their build-time dependencies

  * libshout development files (libshout3-dev package)

Please note that Icecast plugin must be compiled *after* FileWriter plugin, 
as they share some pieces of code (namely, encoding backends and format 
conversion routines). If you build all plugins, this is done automagically.


1. Run-time requirements
========================

To run Icecast plugin, you need:

  * Icecast 2 server running somewhere, maybe at your local host,
    to which you have "source" access

  * libshout version 2.0+ (libshout3 package)


2. Usage recommendations
========================

The plugin is implemented as both output and effect. This means that you can
set it as the only Audacious output, if you don't need to hear anything, or 
you can listen to music and send the same audio data to Icecast server.

Please note that using plugin as effect is recommended. If you want to turn off 
your speakers, just use Null audio output plugin.

The next thing you need to do is to decide what kind of stream do you want. You 
can use MPEG Layer 3 or Ogg Vorbis encoder. Currently supported are LAME and 
vorbisenc. Depending on your system configuration you may or may not have LAME, 
as it has patent problems with Fraunhofer IIS, and Debian doesn't provide 
packages for it.

If you are Debian user and want to use LAME anyway, refer to debian-multimedia 
project.


3. Configuration
================

First of all, you need to set up Icecast 2 properly. Note: previous versions of 
Icecast as well as any versions of Shoutcast were not tested and are not 
guaranteed to work at all.

Usually, if you have single-user Icecast 2 setup, you should use user name 
"source" and appropriate password. In either case, refer to Icecast 2 manual 
for details.

Mount point is a path on Icecast server, where your stream will be available. 
I.e., if you have server at your local machine on default port, and mountpoint 
is "/test", the whole URL of your stream would be

  http://127.0.0.1:8000/test

If you don't specify mount point, mount point is set to "/". But this path 
cannot be used for streaming, as server places status pages there. Don't do this.

The connection timeout option is treated differently when plugin is in output 
or effect mode. When being used as output plugin, this setting specifies the 
time between last song ends (or "Stop" button click) and actual disconnect.
When being used as effect plugin, this setting specifies maximum time between 
sequential portions of audio data sent to server.

Plugin has internal buffer which collects audio data being sent to server. You 
can fine tune size of this buffer. If buffer is too small, data will be sent 
directly to the server bypassing this buffer. If buffer is too big, there can 
be large pauses in audio data.

You can set some information about your stream. First of all, you can provide 
stream name, its description, music genre (or genres), URL of site where 
listeners can read more about your radio. Also, you can ask server to list 
the stream in any directories it knows about. Please refer to Icecast 2 
documentation for more details about this.

 -- Andrew O. Shadoura <[e-mail]>