INTRODUCTION 
============

poc is a suite of MP3 tools and MP3 streaming programs. It can stream
MP3s over HTTP, RTP (RFC 2250 and RFC 3119) and a special protocol to
enable the use of Forward Error Correction to protect the MP3 stream
against packet loss. It can also stream OGGs over HTTP.

In addition to the streaming programs, poc contains two MP3 tools:
mp3cue and mp3cut. mp3cue can cut a big MP3 file according to a
tracklisting contained in a .cue file. mp3cut can split and
concatenate MP3 files according to time slices given on the command
line.

INSTALLATION
============

All the tools in the poc package can be compiled using GNU make.
The tools have been tested under MacOSX, Cygwin and Linux.

Edit conf.h, edit Makefile, then use:

     make         - produce all binaries
     make servers - produce server binaries
     make clients - produce client binaries
     make mp3cue  - produce mp3cue binary
     make mp3cut  - produce mp3cut binary

STREAMING
=========

RTP is a protocol used mostly on top of UDP to transfer multimedia data. It
can be used over multicast (all the UDP servers use a multicast address as
default). The protocol described in RFC 2250 uses the raw mp3 frames as
packet payloads, which can lead to problems in case of packet loss, as
mp3 frames are not independent of one another (the bit reservoir of a
mp3 frame is stored in previous frames). The protocol described in RFC 3119
fixes this problem by using ADUs (independent mp3 frames) as packet payloads,
but does not protect the stream against packet loss (it does however mitigate
the effects of packet loss).

poc contains a program which uses a homebrown protocol to protect mp3 
streams over UDP against packet loss. Like RFC 3119, it uses ADUs, which are
put together in groups, which are then encoded redundantly using a FEC
method designed by Luigi Rizzo.

The servers are:
    - poc-http to stream over HTTP
    - pogg-http to stream OGGs over HTTP
    - poc-2250 to stream over RTP RFC 2250
    - poc-3119 to stream over RTP RFC 3119
    - poc-fec to stream using FEC

The servers accept a list of MP3 files on the command line and stream them
sequentially. They can also accept input from stdin using - as a filename.

The clients are:
    - pob-2250 to receive a RTP RFC 2250 stream 
    - pob-3119 to receive a RTP RFC 3119 stream 
    - pob-fec to receive a FEC protected stream 

The clients output the mp3 stream to stdout, so it can be piped into a mp3
decoder:
     ./pob-3119 | mpg123 -
with buffering:
     ./pob-3119 | mpg123 -b 2048 -
or it can be sent to a conventional HTTP server:
     ./pob-fec | ./poc-http -

MP3 TOOLS
=========

mp3cue is a tool that can split a big MP3 file according to the
tracklisting in a .cue file. The command line arguments are very
simple. To split the big foobar.mp3 file according to foobar.cue:

     ./mp3cue -c foobar.cue foobar.mp3

This will produce the following mp3 files:

01. dj bl0rg - goa mix.mp3
02. dj m0rf - trance mix.mp3
03. dj neingeist - dnb mix.mp3
...

mp3cue will split foobar.mp3 in multiple mp3 files according to the
cue file, and set their id3 tags to the information contained in the
cue file. mp3cue splits on ADU boundary in order to avoid audio
glitches and cracks.


mp3cut is a command-line tool to split and concatenate mp3 files. The
splitting is done using ADUs to avoid audio glitches and tracks. To
extract the first 10 seconds of file foobar.mp3 and write it into
output.mp3:

     ./mp3cut -o output.mp3 -t -10:00 foobar.mp3

To extract the second minute from bla1.mp3 and concatenate the second
minute of bla2.mp3, and then write the output to output.mp3:

     ./mp3cut -o output.mp3 -t 01:00-02:00 bla1.mp3 -t 01:00-02:00 bla2.mp3
     
NOTE
====

poc is a work in progress, it works for me, but is not nearly finished. If
poc deletes your mp3s, invokes satan or empties your cookie jar, don't hold
me responsible for it. However, you can mail any suggestions, bug reports
and fixes to <manuel-poc@bl0rg.net>.

BUILD
=====

You need a C99 compliant compiler to compile poc. Check conf.h if needed.
It works under Linux, FreeBSD, MacOSX.

TODO
====

Write a real Makefile and check portability.
Test the programs thoroughly.
Write input plugins for common audio players (itunes, xmms, winamp).
Implement feedback into the FEC protocol to allow for autoadaptive FEC.
Scale the mp3 to reduce FEC overhead.