


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.



ices 0.4                    July 2004                           1





ices(1)           Icecast media streaming system          ices(1)


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




ices 0.4                    July 2004                           2





ices(1)           Icecast media streaming system          ices(1)


       -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 0.4                    July 2004                           3





ices(1)           Icecast media streaming system          ices(1)


       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                           4


