liveCaster uses a multicast channel to 'announce' the contents of a file system
directory (i.e., folder).
It runs in one of two modes - "audio" or "attribute" - depending upon
the directory's contents:
- "audio" mode is used to stream "MP3" audio
(i.e. MPEG 1 or 2, layer III audio) data
- "attribute" mode is used to announce textual attributes
(e.g., prices, quotes, weather data)
The remainder of this page describes audio mode.
(A separate page describes how to use
attribute mode.)
Quick instructions, for those in a hurry
Download, install and run liveCaster.
Use the "Choose a directory..." dialog to pick a directory
that contains (or will later contain) ".mp3" files.
Choose the networking parameters for your session (or just
use the values that liveCaster chooses).
Drop ".mp3" files into the directory to play them.
(Or, see below for instructions for how
to take MP3 data from 'stdin', from a HTTP stream, or from a live input
source.)
Important note:
Please respect intellectual property rights.
While we cannot control how liveCaster will be used,
we urge that it not be used to illegally transmit
copyrighted data.
liveCaster users are considered responsible for complying with
applicable law.
Detailed instructions
Specifying a directory to announce
Upon starting liveCaster, you will see a dialog that you can use to navigate to
the directory whose contents you wish to announce.
Once you're inside this directory,
click the "Choose the current directory" button.
(If the directory that you wish to announce does not yet exist, you can create
it - as a subdirectory of the current directory - by clicking the "Create New"
button.)
Alternatively, you can specify the directory to announce by starting liveCaster
with the -d <directory path> command line option.
(<directory path> must be a directory that already exists.)
This option is useful if you wish to launch liveCaster automatically from a script.
Choosing the output mode
If you're announcing a directory for the first time, liveCaster will look at the contents of the directory to attempt to guess
which output mode ("audio" or "attribute") to use.
- If the directory contains one or more files named *.mp3,
*.m3u
or
*.pls,
but no files named *.txt, then "audio" mode is automatically assumed
- If the directory contains one or more files named *.txt, but no files named *.mp3,
m3u
or
pls,
then "attribute" mode is automatically assumed
- If the directory contains neither type of file, or both types of file, you will be presented with a dialog that will let you choose which output mode you want
Once liveCaster is running, you can change the output mode using the "Options" menu.
Setting your maximum outgoing bitrate
Assuming "audio" mode has been chosen, you will next be presented with a
dialog that will let you set the maximum bitrate that liveCaster will use when
multicasting MP3 data.
The available choices correspond to the possible bitrates for MPEG audio.
You should choose a bitrate that is less than that of your outgoing
Internet connection.
If a MP3 file's natural bitrate is less than or equal to liveCaster's maximum
outgoing bitrate, then liveCaster will send the file data 'as is' - without
any translation beyond the usual RTP/UDP packetization. If, however,
the file's natural bitrate is greater than liveCaster's maximum outgoing
bitrate, then liveCaster uses a transcoder to convert this
data to the lower bitrate before multicasting it.
Note that this transcoder, which is built into liveCaster, does not
decode the MPEG data, then re-encode it at the newer bitrate.
Instead, it picks out (a subset of) the already-encoded samples from the
original data, then repackages them into new, smaller MPEG frames.
This has the following consequences:
- The resulting sound quality is noticeably worse than it would be if
the data were decoded/re-encoded - especially at lower bitrates
- The transcoder cannot convert between MPEG 1
and MPEG 2.
Therefore, MPEG 2 data can be transcoded down as low as 8 kbps
(although you probably would not want to listen to it!),
but MPEG 1 data cannot be transcoded below 32 kbps.
If you choose a maximum outgoing bitrate of 24, 16, or 8 kbps,
then MPEG 1 files will be sent at 32 kbps instead.
- One good point, however, is that liveCaster's transcoder
is much more efficient than decoding/re-encoding,
so liveCaster
should consume very little of your computer's CPU.
When liveCaster is running, you can change the maximum output bitrate
using the "Options" menu. Any change will take effect once
the currently-playing file - if any - has finished.
Choosing how to advertise your session
If you want other users on the network to learn about and subscribe to your
session, you can advertise the session in a multicast session directory.
If your directory is being announced for the first time, you will
be presented with a dialog to let you choose whether or not you want
liveCaster to do this for you.
When liveCaster is running, you can change this choice at any time, using
the "Options" menu.
In addition, when liveCaster starts up, it outputs a
file containing a SDP
("Session Description Protocol")
description of the session.
This file (whose name has the suffix ".sdp") can be read by some media
players (e.g., "RealPlayer") to play the session.
Specifying the channel parameters
If the directory is being announced for the first time, you will then
be presented with an additional dialog ("Enter audio channel parameters"),
which will give you the opportunity to set the network parameters
for its multicast channel.
This dialog is preset with default values.
If you're happy with these values, click "OK" (or type the
<Enter> or <Return> key).
The parameters are described below:
liveCaster stores these parameters in a file (named "SELF.txt"),
so you won't have to deal with these dialogs the next time you run the program
(unless you choose a different directory, of course).
In fact, once the "SELF.txt" file has been set up, you may choose
in the future to run
"lc" - a special,
GUI-less version of liveCaster -
instead of the regular "liveCaster" application.
While liveCaster is running
In normal operation (after a directory has been selected and its parameters
set up) liveCaster will display a small window,
indicating the directory that is currently being announced.
As each MP3 file is played, its name and native bitrate will be shown,
and the bitrate at which it's currently being multicast.
This window may be minimized (and liveCaster will continue running
in the background).
liveCaster repeatedly plays through the *.mp3 files in the
directory, in alphabetical order by file name.
You can also add new *.mp3 files to the directory
while liveCaster is running; liveCaster will add these new files
(also in alphabetical order) to the
end of its playlist.
Note that liveCaster will attempt to play only those files whose names have
the ".mp3" extension.
(Also, these files must contain MPEG 1 or 2, layer III audio data
- not layer I or layer II.)
You can also use explicit playlist files - with extension .m3u
or
.pls
- to get more control over which MP3 files are played,
and in which order.
*.m3u files are preferred. These contain a list of MP3
files
(or comment lines - starting with '#' - which are ignored).
HTTP URLs (for MP3 streams) will also be also recognized and played.
If liveCaster sees any playlist files (*.m3u or *.pls)
in the selected directories, then these will be read in alphabetical
order.
In this case, any *.mp3 files in this directory
will be ignored,
unless they are explicitly listed in one of the playlist files.
To exit liveCaster, delete this window, type
<Control>-q,
or use the "Exit" command in the "Options" menu.
Using alternative MP3 sources
As an alternative to reading ".mp3" files from a directory,
liveCaster can also read MP3 data from a single, specific source
(including a HTTP stream -
e.g., from a 'Shoutcast' or 'Icecast' server).
To specify an alternative MP3 source, start liveCaster with the option
-s <source-name>
<source-name>
can be one of the following:
- A file name. (liveCaster will loop through the file repeatedly.)
- The string stdin (or -).
(liveCaster will read from its standard input.)
- The URL of a HTTP stream (i.e., "http://...").
- The name of a directory that contains ".mp3" files (or playlists).
This option is useful only if this is a different directory
from that used to store the "SELF.txt" file
(e.g., if you wish to stream a collection of ".mp3" files stored on
a non-writeable medium such as CD-ROM).
Note that even if you use this option,
you must still specify a directory (either from the GUI dialog, or using the
"-d" option).
(Although this directory will no longer be scanned for ".mp3" files,
it is still used to store the file "SELF.txt", which liveCaster
uses to persistently store the multicast session's parameters.)
You need only use the "-s" option when you run liveCaster for the first time.
Thereafter, this same source will be used automatically (unless you
use "-s" again).
(The source argument is stored in the "SELF.txt" file as an attribute named
"source".)
Advanced options
- The "-a <RTP-payload-format-number>" command-line option
causes liveCaster to use a more loss-tolerant
'ADU-based' RTP payload format
(as defined in RFC 3119).
Any receiver of this session must be capable of interpreting this format.
(<RTP-payload-format-number> is the dynamic RTP payload
type to be used for this session.
It must be in the range [96,127].)
If this option is used, then any SDP session announcements made by
"liveCaster" for this session will automatically contain
a SDP "rtpmap" attribute,
specifying the format name "mpa-robust"
(see RFC 3119).
The "-a" flag also takes an optional second argument: a sequence
of integers representing a permutation of the integers
[0, N] (for some N<256).
This sequence specifies how the sequence of ADUs will be interleaved
within outgoing RTP packets.
(The default behavior, if no such sequence is given, is for the ADUs
to be output in sequential order.)
For example, the command line option
-a 96 "0 2 1 3"
specifies that 96 will be used as the dynamic RTP payload type, and
that a sequence of ADUs
a0, a1, a2, a3, a4, a5, a6, a7, a8, ...
will be output, within RTP packets, in the order
a0, a2, a1, a3, a4, a6, a5, a7, a8, ...
Interleaving can make packet loss sound better, by spreading out the
effect of each lost packet.
For more information about
interleaving (and the ADU-based RTP packet format in general),
see RFC 3119.
When choosing an interleaving sequence, note that each output packet
will usually be 1000-1450 bytes in length.
Therefore, a 24 kbps MP3 stream (in which frames are 108 bytes long)
will usually contain 10 ADUs per packet.
A 128 kbps MP3 stream (in which frames are 417 or 418 bytes long)
will usually contain 3 ADUs per RTP packet.
160 or 192 kbps MP3 streams will usually contain 2 ADUs per RTP packet.
224 kbps (or higher) MP3 streams will usually contain only a single
ADU per RTP packet.
(In this case, interleaving will have no benefit, unless packet loss
typically occurs in bursts.)
In any case, note that because ADUs can vary in size, the number of ADUs
contained within each RTP packet may also vary.
You need only use the "-a" option when you run liveCaster for the first time.
Thereafter, this same payload type (and interleaving, if any) will be used
automatically (unless you use "-a" again).
(These parameters are stored in the "SELF.txt" file as an attribute named
"aduState".)
- If the "-r" command-line option is given, liveCaster will
remove each ".mp3" file after it finishes playing it.
This option can be useful if you're using liveCaster to simulate a jukebox.
In Unix, each ".mp3" file in liveCaster's directory can be a symbolic link.
With the "-r" option, liveCaster will delete each symbolic link once it's been
played.
The "-r" flag also takes an optional integer
argument
<playlist-size>, indicating that a file, after being played,
should be deleted only if the remaining playlist-in-progress would
have at least
<playlist-size> entries.
(The default value is 0: each file is always deleted after being played.)
- Specifying the multicast network interface(s)
- If the "-ssm" command-line option is given, liveCaster will assume that its
session is being
received using source-specific multicast ("SSM").
When run with this option, liveCaster will (i) choose a group address from the
SSM range (232.0.1.0-232.255.255.255), (ii) note in its outgoing SDP announcement (if any) that this is a SSM session, and (iii) will not display any RTCP audience statistics (because it won't expect to receive any RTCP Receiver Reports).
You need only use the "-ssm" option when you run liveCaster for the first time.
(Thereafter, this choice is stored in the "SELF.txt" file, as an attribute named
"useSSM".)
Multicast tunneling
liveCaster has a built-in tunneling mechanism
that you may use to connect to the Multicast Internet
(aka. "MBone"), if you are not already connected.
To set up (or shut down) a multicast tunnel, use the "Options" menu.
The multicast tunneling mechanism
acts as a UMTP client, and
- when operational - connects to a UMTP server
(such as "liveGate")
running on a computer that's already
on the Multicast Internet.
Return to the main liveCaster page