l i v e i c e
 ` ` ` ` ` `

Introduction
~~~~~~~~~~~~
LiveIce is a live streaming program that allows input either from your
soundcard's line in or from mp3 files to be mixed and re-encoded and then
streamed to an icecast server.  This means that you can use liveice with
your microphone and do live audio broadcasts, or even use a mp3 playlist
and use the multi channel support to speed up, slow down, adjust volumes,
and mix between the two channels, and then re-encode the data at a lower
bitrate to be sent out to a icecast server.

LiveIce requires mpg123 and an encoder to turn the raw audio stream into
mpeg layer 3 data; the encoder software must be in your path somewhere.
The only way to change the encoder used is to modify liveice.h to switch
between the supported encoders. Currently supported encoders are....
encoder by Andreas Johansson - a hacked up and optimized version of dist10. 
Lame 3.x - The best free encoder - recommended for everyone who doesn't want to
         pay loads of money, or hack around with the kernel module for Xing. 
         A faster, but lower quality enocder called 'GOGO' is also available
L3enc - the old encoder from Fraunhofer
mp3enc - the currently supported encoder from Fraunhofer. - Very Good - Very 
         expensive
XingMp3enc - Xing Technologies' command line encoder - it's not designed for
         streaming, but it's possible to work around this with a kernel
         module.

Some other encoders are supported but these are the best choices.



Usage
~~~~~
Run the program like this 
./liveice  [options] 


Configuration options -

The program tries to read liveice.cfg which can contain simple 
configuration options
I've provided a TK GUI which will generate a configuration file for you
just run liveiceconfigure.tk

# remote server                -s
SERVER 127.0.0.1
# remote port                  -o
# note that in icecast 1.3 the client and source ports are identical
PORT 8000

# Which encoder to use - choose one - you may need to set a suitable
# sampling frequency and birate 
# There are no Command line equivanets for these
# also note that anything apperaing after the command is used as the
# name of the binary to execute
# *MAKE* sure the binary is in you path!!!!!!
USE_AJ_ENCODER
USE_L3ENC
USE_MP3ENC
USE_SCREAMER
# there are subtle differences between these
USE_XING          
USE_XING_BETA 
USE_XING_VBR
# old lame 3 is versions 3.02- 3.11 
USE_OLD_LAME3          
# Lame3 is any version after about 3.22.....
USE_LAME3
# intel optomosed LAME  - not as good but a lot faster
USE_GOGO

# SOUNDCARD is enabled by default - use NO_SOUNDCARD with mixer mode
# if you don't actually have a soundcard in the computer producing the 
# mp3 source 
# NO_SOUNDCARD doesn't work with sime mode.
# *Don't* mess around with the clock on the computer - it'll confuse it
# I'm not looking into a more complicated solution just yet.
#there are no command line equivalents for these
SOUNDCARD
NO_SOUNDCARD

# name                         -n
NAME icy_name
# genre                        -g
GENRE icy_genre
# public flag                  -x
PUBLIC 1
# URL                           -u
URL http://localhost
# Description - x-audiocast login only
DESCRIPTION Cool Tunes
# Mountpoint - multiple streams on a server each need a mountpoint
MOUNTPOINT /live
# Login type - Choose one depending on your server 
# x-audiocast has more features
ICY_LOGIN
X_AUDIOCAST_LOGIN

#password                       -P
PASSWORD foobar
# bitrate
BITRATE 24000                   -b
# VBR quality is the quality factor used with Xing in Variable bitrate mode
VBR_QUALITY 1
# General quality switch which controls all sorts of encoder 
# specific features should work in the range 0-100 although nothing
# nas htis many settings
ENCODING_QUALITY 30

# sample rate
SAMPLE_RATE 22050               -r
# no. of channels
MONO				-c 1
STEREO                          -c 2
#use full duplex mode on soundcard      -f/-h
FULL_DUPLEX 
HALF_DUPLEX

# mp3mixer mode simple/mp3mixer/esd      -m/-M/-E
# enlightenment sound daemon support provided via esdmon  
MIXER                             
NO_MIXER
ESDMON
# or arbitrary command to provide source stream for re-encoding. highest configured BITRATE, SAMPLE_RATE
# and MONO/STEREO will be taken as the settings for the source - these do not have to be the highest
# settings used for output. i.e. you can set SAMPLE_RATE to 44100 (say) in the main section, and then
# override the output stream with ENCODER_STREAM_SET 0.
MIXER_CMD /usr/local/bin/mpg123 -s -y -k 10 -b 1024 http://my.local.server:8000/major_soundz

# playlist    		       -p
PLAYLIST playlist
#debug                            -V
DEBUG		0
VERBOSE         0

# mixer control script file
# this lets you store your mixer actions in a script file and replay them
# later - and perhaps do more.... this is stil in development and the format
# may change
#mode
MIX_CONTROL_AUTO         -k 2     - read commands from the file
MIX_CONTROL_LOGGED       -k 1     - write commands to file for later use
MIX_CONTROL_MANUAL       -k 0     - don't use control file

#use -K to define the file to use for commands 
CONTROL_FILE mix_command

# use decoder command to specify the name you use for mpg123
DECODER_COMMAND mpg123

# use this to log every mp3 as it's played 
TRACK_LOGFILE track.log

#Time limit  -T <seconds>
# if you want the streamer to terminate after a certain amount of time
# then set the number of seconds ike this
DURATION 3600

# time between updates of the title data on the server in minutes
UPDATE_DELAY 1

#stream recording options - may be set on a per stream basis
#dump the audio to a local file
SAVE_FILE local_save.mp3
# use the x-audiocast-dumpfile to tell teh server to 
# record a copy of the file - only works with x-audiocast headers
REMOTE_DUMPFILE remote_save.mp3

#Multiple encoder streams
# You can have up to 8 streams for audio 
# all with different bitrates/formats/destinations etc

# all the parameters up to now have applied to encoder stream 0
# I can now commit those to stream 0 and set some parameters on stream 1
# I only need to set the parameters which are changed
#commit the settings to channel 0 and start setting up channel 1

ENCODER_STREAM_SET 1
# after this I can put the parameters for the second encoder
# most variables can be changed.
# e.g.

ENCODER_STREAM_SET 0
SAMPLE_RATE 44100
BITRATE 128000
STEREO
SERVER high.bandwidth.com
NAME High Bandwidth Mp3 Stream

ENCODER_STREAM_SET 1
SAMPLE_RATE 44100
BITRATE 64000
MONO
SERVER medium.bandwidth.com
NAME medium bandwidth mp3 stream

ENCODER_STREAM_SET 2
SAMPLE_RATE 22050
BITRATE 24000
MONO
SERVER low.bandwidth.com
NAME low bandwidth mp3 stream




Mixer Mode
~~~~~~~~~~

If you select MIXER (-M) as your mode, LiveIce will load your playlist (it
defaults to the file playlist in the current directory) and will open two
channels.  From there it will allow you to select the audio file that you
want to broadcast, which channel it's on, and select things such as the
speed and volume for that track to play at.  This allows you to do many
things a DJ can do.

The interface needs a lot of work right now, and becuase the mp3 decoder isn't
built into the source there's a fair amount of latency, so don't expect to 
be able to beat match things unless your perception of time is unusual. The
internal software supports 8 seperate mpeg channels, and it'd be trivial to 
add more. But the interface right now only lets you control 2, and the 
behaviour needs some serious work.

Each channel supports independent speed and volume settings - in the future I
hope to add effects processing. 

Create a file called playlist - it's just a list of flenames right now - 
bitrates are calculated by the program. 

find / -name "*.mp3" -print > playlist

I've recently added support for Non-mp3 files in the playlist file - 
the type identification is based on the file extension - if it's not recognised
it's considerd to be raw audio in the same format as the output format.
This can be used to take input from other programmes - create a pipe - say
'external.pipe' add that to your playlist file. Then start up your external
programme writing to the pipe, and start liveice... select the relevant
file in the mixer and you're away! This isn't perfect just yet - but it can 
fill some needs which weren't previously addressed.


For .wav/.au/.aiff etc liveice uses sox to do the conversion - perhaps one
of these days I can get rid of this dependence.

Then run liveice with the -M option

Using Mixer Mode
~~~~~~~~~~~~~~~~

Keyboard Controls:

Action				Channel 1 Key	Channel 2 Key
~~~~~~				~~~~~~~~~~~~~	~~~~~~~~~~~~~
Select next track on channel	1		a
Select prev track on channel	q		z
Start/Stop channel		2		s
Reset channel			w		x
Increase volume on channel	3		d
Decrease volume on channel	e		c
Increase speed on channel	4		f
Decrease speed on channel	r		v
Sticky mode On/Random/Off	5		g
Preview channel			t		b
Random Track                    u               m

**hacked mpg123**
Forward                         6               h
Back                            y               n
*****



ReRead Playlist                '#'  - note - big playlists may cause dropouts 
There's a slight problem with this.... but it works....

Spacebar:

turn on/off external soundcard input (note: if you haven't got full duplex
drivers then this will mute the mp3 output to your soundcard. However they
will still be streamed and mixed, even though you can't hear it, you will
have to put up with even more lag echoing.
 
Comressor:

No this is nothing to do with mpeg audio compression, this is a traditional
audio effect which a lot of radio stations use to keep the volume reasonably
high. Basically, when the audio is quiet it turns the volume up, when it's
noisy it turns the volume down a little. This is still in the hack phase
and may not sound great.... anyway  '[' and ']' can be used to change the 
extent of the compression. This is a silly hack....


+ - quit program

Sticky mode basically means that a channel will automatically roll over to the
next track when it finishes - enabling sticky mode twice will make it go into 
random play mode.

Step Forward (1) -> Random Mode (-1) -> Off (0) -> Step Forward (1) ->
 etc etc


Using the TK frontend
~~~~~~~~~~~~~~~~~~~~~

Another work in progress.... the TK script 'frontend.tcl' is intended to 
provide a graphical frontend which should eventually provide more functionality
than can be provvided with the keyboard.

At the moment it merely maps buttons to the various keys which can be used in
mixer mode, the feedback still has to come on the terminal, but you don't
need to rememebr what key does what..

If you want to try this... then run the frontend and pipe it's output into 
liveice e.g.

frontend.tcl | liveice 

yes I know it's ugly... but I'm a hairy Scotsman so I like to think looks 
aren't everything.


Hacked mpg123 bits
~~~~~~~~~~~~~~~~~~
If you want to have the ability to skip back nad forth within tracks then
get mpg123-0.59q and apply the mpg123_liveice.diff patch. Compile this new
version and put it somewhere in your path - preferably with a different name
e.g. mpg123_liveice
This patch probably breaks things right now....
then use the DECODER_COMMAND option in the config file to set the name of this
decoder and run liveice as usual. 
Now, in theory the keys 6,y let you skip backwards and forwards on channel 1
and the keys h,n do teh same for channel 2.

*This is not well tested....*
*I'm going to change this*


Other Questions
~~~~~~~~~~~~~~~

Some people have problems with the Curses interface *even* if they have 
curses on their system. If you have problems with the code dying as soon
as you start it try editing config.h and removing 
#define HAVE_LIBCURSES


Home Page
~~~~~~~~~

The Home page always has the latest version, and instructions on all
those bits and pieces.

http://star.arm.ac.uk/~spm/software/liveice.html

Copyright Scott Manley 1999



