ices(1)                 Icecast media streaming system                 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:

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

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

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

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

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

       o      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
       /etc/ices.conf
              Default XML configuration file. May be overriden with -c.

       /usr/local/share/ices/ices.py
              Default path to the python playlist module.

       /usr/local/share/ices/ices.pm
              Default path to the perl playlist module.


AUTHORS
       ices was originally written by Alexander Havang <eel@icecast.org>.

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



ices 0.4                           July 2004                           ices(1)
