Included Features

The following are some LiveIce items that showcase its many positive features. Browse the bulleted entries to determine if LiveIce is right for your streaming needs.

• Encodes MP3 audio from raw audio data as it is created and streams it to an icecast or Shoutcast server.
• Supports icy or x-audiocast headers for connectivity.
• Runs on most UNIX systems including Linux. OSS support may be required in some cases in order to use certain soundcards.
• Curses-based user interface to improve appearance of terminal sessions.
• Supports simple terminals session for those without Curses.
• Compatible with many popular MPEG encoders.
• Configuration options may be set in multiple configurations files as well as on the command line.
• Mixer mode allows the user to play existing audio files as part of a live broadcast.
• Mixer mode also allows the user to mix multiple channels of audio to keep a seamless broadcast running.
• The speed and volume of input files can be independently controlled on a per-channel basis.
• Mixer commands can be recorded to file and replayed at a later time.
• Playlists can be played sequentially or in a random order.
• Any played files can be stored to disk for use by external programs.
• Output can be streamed at multiple bitrates to individual servers.
• Title streaming to icecast servers is based on the loudest channel.

Installing LiveIce

Download the LiveIce source code. This can either be the latest tarred and zipped file provided by Scott Manley via his web page or the most recent CVS release. Not much work has been done on the original LiveIce source code so the latest tarball should be up-to-date. The next few section explain how to install LiveIce and what encoders work with this application.

The current URL for downloading or becoming more acquainted with LiveIce is the following: http://star.arm.ac.uk/~spm/software/liveice.html. There is no version number affixed to this release, so don't look for one.

Save the compressed file to a standard location and build as usual.

# cp liveice.tar.gz /usr/local/src
# gunzip -c liveice.tar.gz | tar xvf -
# cd liveice/
# ./configure && make

When compilation is complete, copy the binary and configuration files to the icecast bin/ directory. These two files, liveice and liveice.conf, are the only items needed to run LiveIce. However, these are not the only files available for use. Be aware that there are two separate interfaces for running the utility; the first is a simple terminal interface displaying the audio levels, and the second is a Curses-based user interface. This latter format allows for easier display of information for beginning users.

Due to the fact that LiveIce is relatively unsupported at the present time, the Curses-based display may not work correctly on most current Linux distributions. The recommended method remains the CLI or terminal interface format. This interface currently uses Linux-specific TTY settings to put it in non-blocking canonical input mode. To customize this interface further, edit the settings in the config.h file should the terminal mode not play well with your system. This file is created after running the configure script.

Again, a minimalist GUI is available, which is written in TK. It simply provides all the buttons in a nice window. It is doubtful whether any more work will be made in this respect. The system also requires the OSS sound drivers. These usually come standard with most Red Hat Linux releases and derivatives as well as with the latest SUSE versions.

Nearly all other options are set via the command line. All configuration settings are stored in a configuration file. The default is saved as /etc/liveice.cfg and ./liveice.cfg. The default /etc/liveice.cfg should be used for all default settings, i.e. the encoder, the decoder, default bitrates and sample rates and so on. The only things that may need to be changed on a per-session basis can be altered using command line options.

Modifying the LiveIce Syntax

LiveIce can be set up to read and encode either streaming audio or static playlists based on MP3 files residing on the system's local or networked drives. Customize the liveice.cfg file to accomplish either of these two formats. Though the file itself is well-commented, beginning users may find the terminology initially confusing. The following section explains how to modify and customize the LiveIce files to stream either format.

The configuration files used by LiveIce are simple text files which set the audio variables. Included with the source code is a liveiceconfigure.tk script; a simple TK-based GUI that allows for customization of nearly all options and writes them to a static file. This script executes a GUI application called the LiveIce Configuration Generator, designed specifically to assist new users. It is normally executed from the command line by typing the following in a terminal window:

# wish liveiceconfigure.tk

Be aware that this application overwrites the default liveice.cfg configuration file. Back up the distribution file, any other customized or previously edited file before using this tool.

Figure 6-1 shows the default settings of the LiveIce Configuration Generator. Be aware that the default settings do not work when initially launched. Some changes must be made in order to get LiveIce to operate correctly. Edit the available settings to suit your environment. This includes modifying the Server (as well as the port number), Name, Genre and URL fields. The Directory, Login Type and Password variables should be changed to accommodate your setup. The PCM Audio Format, Hz, and Soundcard items should also be modified. Be familiar with the settings particular to your sound card. As explained in Chapter 3 under the section titled "Audio Fundamentals," know your soundcard's limitations and your desired duplex and bitrate settings. Choose your encoder of choice. Again, LAME works well in most instances and is the recommended choice. To stream live audio or play static MP3 files, customize the next fields shown within the display.

The LiveIce Configuration Generator provides an option to find and create a list of all available MP3 files residing on the local machine. This playlist can be later edited by hand if some files need to be removed. The last few fields are for any other executables required by the configuration. Save the new configuration file when done. Use the default liveice.cfg filename only if you have already backed up the original distribution file. Move this file to the location of your choice when complete.

Sample LiveIce Configuration File

Some users prefer editing the liveive.cfg configuration file by hand. Though this may result in more errors and false startups than successful executions, it is an efficient method of better understanding the LiveIce syntax at the core level. Once you have a functional configuration file, copy the liveice.cfg file and liveice binary over to the /usr/local/icecast/bin directory. Placing both the configuration file and the completed binary in the same location facilitates the execution of LiveIce along with the icecast server.

The following is an edited sample of a liveice.cfg file. The password file should remain unencrypted or readable in plain-text format. This particular configuration is designed for streaming audio use, versus a static file playlist. Examine the comments to see what items must be removed or added in order to stream a static playlist. You may need to download a copy of mpg123 since it no longer comes packaged with some Linux distributions. The drop-in replacement program is mpg321. For further information on what each item accomplishes, either examine the default liveice.cfg file included with the source code along with all the attached comments or continue reading below for a more detail explanation.

# -------- Sample liveice.cfg Config File --------
SERVER 192.168.0.5
# SERVER localhost
PORT 8000
NAME Radio Free Linux
GENRE Live
URL http://icecast.mydomain.com/
PUBLIC 1
X_AUDIOCAST_LOGIN
# ICY_LOGIN
PASSWORD xxxxxxxx
SAMPLE_RATE 44100
MONO
# uncomment the next line to encode a playlist
# NO_SOUNDCARD
# uncomment the next line to encode a live stream
SOUNDCARD
HALF_DUPLEX
USE_LAME3 /usr/local/bin/lame
SOUND_DEVICE /dev/dsp
MOUNTPOINT live
BITRATE 64000
VBR_QUALITY 1
# uncomment the next line to encode a playlist
# MIXER
# uncomment the next line to encode a stream
NO_MIXER
# PLAYLIST playlist
DECODER_COMMAND mpg123
# MIX_CONTROL_MANUAL
# CONTROL_FILE mix_command
# TRACK_LOGFILE track.log
# VERBOSE 10

Explaining the liveice.cfg Syntax

Similar to the standard icecast configuration file, certain options are included that are not readily understood at first glance. This section better clarifies what each item listed under the liveice.cfg file accomplishes. I have included and annotated many of the comments provided by Scott Manley on his web page in order to better explain each item listed under the configuration file. After each definition is an example entry.

Automating the Configuration

The Tcl script included with LiveIce, also known as the LiveIce Configuration Generator, can search local hard drives for any MP3 files for creating a static playlist. Use the Create button within the GUI interface to generate a playlist of files found on the hard drives or any other networked drives. This list is saved to the current working directory. A line referring to the new playlist is added to the configuration file. Copy this playlist file to the same location as your liveice.cfg file and liveice binary. Edit the playlist later for modified listings.

If you prefer not to use the Tcl script, create a custom playlist by hand using the following example:

# find </example/mp3/directory> -name *.mp3 -print > playlist.pl

You may later decide to custom edit the entries here or change the play order depending on your own tastes.

Running LiveIce

Starting the LiveIce streaming program is a fairly simple process. It is designed to run as a Curses application or from the command line interface. If you are managing your system in run level 5 or within an X Window environment, it is as simple as starting a terminal emulator and then calling the LiveIce binary. I recommend starting the process from within a screen session. By that I mean, start up a screen session and then execute the LiveIce binary. What screen does is launch an internal session that can be detached and re-attached elsewhere. In this manner LiveIce can be started anywhere; from a console on the machine itself, or from any other remote networked Linux device from which you can SSH or secure shell back into the icecast server. Once in, re-attach the screened LiveIce session and monitor audio output and performance.

Here is a quick example of the previous description. On the icecast server itself or on the machine using LiveIce, type the following:

# screen

A new session is launched internal to your own terminal session. Start the LiveIce binary after first changing to the proper directory:

# cd /usr/local/icecast/bin
# ./liveice

Once confirming all is running correctly and that your terminal or console window appears similar to that of Figure 6-2, detach the screened session for later use. To do so, type Control-A and then D. Re-attach to this operating screen at some later time and from some other machine. When re-attaching, be sure and use the -r with the screen command in order to connect to the active screen session. Otherwise, you will be launching a new screen session and the LiveIce stream will be present on a separate, non-visible screen. When detached from a screen session, the audio streamer continues to operate and stream the incoming audio to connecting listeners.