ices(1)

NAME
ices - stream MP3 audio to an icecast server

SYNOPSIS
ices [-BVv] [-c configfile] [-D basedir] [-S builtin [-F playlist] [-r]]|[-S python|perl [-M module]] [-C crossfadesecs] [[-m mount] [-h host] [-p port] [-P password] [-t protocol] [-n name] [-g genre] [-d description] [-u url] [-s] [-b bitrate] [-f dumpfile] [[-R] [-H samplerate] [-N channels]]] ...

DESCRIPTION
ices is a small but powerful and flexible encoder for icecast servers. Its features include:

•   A scripting interface to its playlist engine, using either python or perl as you prefer, in addition to a builtin static file server. Fetch your tracks from a database or update a webpage at each track change in a simple and robust way.

•   ices can read source audio from a FIFO. Between this and the script interface, it should be fairly easy to handle as complicated a media-delivery system as you can think up.

•   On-the-fly reencoding of your source audio to a different bitrate, number of channels and/or sample rate. ices can also decode Ogg Vorbis files and reencode them on the fly as MP3, for the benefit of older listening software. This just in: it can transcode FLAC and MP4 (AAC) files now too. Keep your sources in whatever format you prefer.

•   Crossfading between tracks. This is a new feature, and requires reencoding support.

•   Multiple streams from the same playlist. In conjunction with reencoding this gives you a very easy way to provide the same music for broadband and narrowband listeners at the same time.

•   A constantly-updated cue file containing up to the second information about which track is currently playing, how much has been played, and other details.

OPTIONS

  Execution options

-B  Detach from the console and run in the background.

-c configfile
    Load configuration options from configfile, instead of the default. Command line options will override these.

-D basedir
    Write the log and cue file to basedir.

-V  Show version information and compile-time options and exit.

-v  Run in verbose mode.

  Playlist options

-S interpreter
    Chooses which playlist interpreter ices will use to find source audio files for streaming. May be one of builtin, python, or perl. The default is builtin.

-F playlist
    If using the builtin playlist interpreter, this option specifies the location of the playlist file ices will read to find audio files. This file simply contains the paths to audio files, one per line. If not using the builtin interpreter, this options does nothing.

-r  Select songs from the playlist file in random order. If not using the builtin interpreter, this option does nothing.

-M module
    If using the perl or python playlist modules, load the module named module instead of the default, ices. Otherwise this option does nothing.

-C crossfadesecs
    Crossfade between tracks. The length of the fade is crossfade seconds. This option requires reencoding support.

  Stream options

-m mount
    Create a stream on the icecast server accessible at the mountpoint mount. Clients may access your stream at http://host:port/mount. This option may be specified more than once to create multiple streams out of the same playlist. All stream options following each mount option apply to that mount only.

    If this option is not specified, an implicit mount named ices is implied.

-h host
    Connect to the icecast server on host, instead of the default, localhost.

-p port
    Connect to the icecast server on port, instead of the default, 8000.

-P password
    Log into the icecast server using the password password.

-t protocol
    Connect to the server using the streaming protocol protocol. Protocol should be one of http, xaudiocast, or icy, depending on whether your server is icecast 2, icecast 1, or shoutcast compatible, respectively. The default is http. (Shoutcast would be most compatible but, unfortunately, that protocol does not support multiple mount points).

-n name
    Set the name of this stream to name.

-g genre
    Set the genre of this stream to genre.

-d description
    Set the description of this stream to description.

-u url
    Set the URL of this stream to url.

-s  Do not mark this stream as public. This instructs the icecast server not to update directory servers with information about this stream.

-b bitrate
    Set the bitrate of this stream to bitrate. Unless reencoding is also enabled on this stream, this option is only informational.

-f dumpfile
    Write the contents of the stream to a file named dumpfile on the server. Use this option with care.

-R  Reencode this stream at the bitrate specified with the -b option.

-H samplerate
    If reencoding, set the output sample rate to samplerate.

-N channels
    If reencoding, set the number of output channels to channels. May be 1 for mono output or 2 for stereo output. At low bitrates setting this to 1 is a good way to improve sound quality.

PLAYLIST SCRIPTING
In addition to its simple builtin playlist handler, ices can optionally call out to either a python or perl module for track information. Your module may define the following functions:

ices_init
    This function is called once when ices starts up, giving your module a chance to initialize itself (make database connections etc.). If this function returns a negative result, ices will terminate.

ices_shutdown
    This function is called before ices quits, to give your module a chance to free any resources it may have allocated.

ices_get_next
    This function is called at each track change. Your module should return a string containing the path to the next audio file to be played.

ices_get_metadata
    This function is called after ices_get_next. If it returns a string, ices will use it as the title to be streamed instead of trying to build one from the ID3 or vorbis comment tags, or the filename if neither of those are available.

ices_get_lineno
    This function is also called after ices_get_next. Your module may return a number which will be inserted in the cue file as the current line number in the playlist. It serves no other purpose.

    Your module must at least define the ices_get_next function. All others are optional.

SIGNAL HANDLING
Ices handles the following signals specially:

SIGINT
    Causes ices to perform a clean shutdown.

SIGHUP
    Causes ices to close and reopen the log file and the playlist. It will also reload and restart the playlist script if you're using one.

SIGUSR1
    Causes ices to skip to the next track in the playlist immediately.

FILES

/opt/etc/ices.conf
    Default XML configuration file. May be overriden with -c.

/opt/etc/modules/ices.py
    Default path to the python playlist module.

/opt/etc/modules/ices.pm
    Default path to the perl playlist module.

AUTHORS
ices was originally written by Alexander Haväng <eel@icecast.org>.

It is currently developed by Brendan Cully <brendan@icecast.org>.