Using liveCaster

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:

multicast address, port: The IP multicast address and UDP port number to be used for this directory. These are preset with arbitrarily chosen values; you may change these if you wish.
(At present, the preset multicast address is chosen randomly from an infrequently used range, so it is possible (although unlikely) that this address is already being used. LIVE555.COM is working within the IETF to define standard protocols and APIs for allocating multicast addresses. Future versions of liveCaster will use these as they're defined.)
It is also possible to specify a unicast address. In this case liveCaster will send its data (unicast) to the specified address and port (and will also use this port+1 to receive RTCP data).
scope (TTL): This menu can be used to change the scope of your intended audience.
network data format: At present one data format is supported: MPEG layer III audio (i.e., the same as the original files)
transmission protocol: At present, one protocol is supported: RTP (encapsulated in UDP)
outgoing bit rate limit: (See above)
title: A short name for your session. (default value: the name of your directory). This title is used for the banner of liveCaster's main window, and for the title of any session directory advertisements.
description (optional): A brief description of the purpose and content of your session. (This is used in session directory advertisements.)
email address (optional): An email address that receivers may use to contact you (e.g., if there's a problem with the reception of your session). If you enter this, it will be included in session directory advertisements.

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

Streaming from a live input 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.