update README.md

3 files changed, 60 insertions, 36 deletions

diff --git a/MODULE_LICENSE_FRAUNHOFER b/MODULE_LICENSE_FRAUNHOFER
deleted file mode 100644
index e69de29..0000000
--- a/MODULE_LICENSE_FRAUNHOFER
+++ /dev/null
diff --git a/Makefile.am b/Makefile.am
index 767b5f7..9e2e164 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -213,6 +213,7 @@ libfdk_aac_la_SOURCES = \
 EXTRA_DIST = \
     $(top_srcdir)/bootstrap \
     $(top_srcdir)/NOTICE \
+    $(top_srcdir)/README.md \
     $(top_srcdir)/Android.mk \
     $(top_srcdir)/fdk-aac.sym \
     $(top_srcdir)/documentation/*.pdf \
diff --git a/README.md b/README.md
index 93e1190..aaf8bf8 100644
--- a/README.md
+++ b/README.md
@@ -1,34 +1,32 @@
-fdk-aac-dabplus
-===============
+fdk-aac-dabplus Package
+=======================
 
-A standalone library of the Fraunhofer FDK AAC code from Android, patched for
-960-transform. Used for DAB+ broadcast encoding.
+This package contains several tools that use the standalone library
+of the Fraunhofer FDK AAC code from Android, patched for
+960-transform to do DAB+ broadcast encoding.
 
-Also includes a version with a ODR-DabMux compatible ZeroMQ output.
+The first tool, *dabplus-enc-file* can encode from a file or pipe
+source, and encode into a file or pipe. There is no PAD support.
 
-There is experimental support for DAB MOT Slideshow and DLS, written by
-CSP http://rd.csp.it
+The *dabplus-enc-file-zmq* can encode from a file or pipe source,
+and encode to a ZeroMQ output compatible with ODR-DabMux.
 
+The *dabplus-enc-alsa-zmq* can encode from an ALSA soundcard,
+and encode to a ZeroMQ output compatible with ODR-DabMux. It supports
+experimental sound card clock drift compensation, that can compensate
+for imprecise sound card clocks.
 
-Usage:
+*dabplus-enc-file-zmq* and *dabplus-enc-alsa-zmq* include experimental
+support for DAB MOT Slideshow and DLS, written by [CSP](http://rd.csp.it).
 
-    aac-enc-dabplus [OPTION...]
-    
-    -b, --bitrate={ 8, 16, ..., 192 }    Output bitrate in kbps. Must be multiple of 8.
-    -i, --input=FILENAME                 Input filename (default: stdin).
-    -o, --output=FILENAME                Output filename (default: stdout).
-    -a, --afterburner                    Turn on AAC encoder quality increaser.
-    -f, --format={ wav, raw }            Set input file format (default: wav).
-    -c, --channels={ 1, 2 }              Nb of input channels for raw input (default: 2).
-    -r, --rate={ 32000, 48000 }          Sample rate for raw input (default: 48000).
+To encode DLS and Slideshow data, the *mot-encoder* tool reads images
+from a folder, and DLS text from a file, and generates the PAD data
+for the encoder.
 
+For detailed usage, see the usage screen of the different tools.
 
-The encoder with ZeroMQ output has the same options as above,
-but takes a zmq destination url as output
-
-See
-    aac-enc-dabplus-zmq -h
-
+More information is available on the
+[Opendigitalradio wiki](http://opendigitalradio.org)
 
 How to build
 =============
@@ -40,50 +38,75 @@ Requirements:
 * Download code and unpack it.
 * Download and install libfec from https://github.com/Opendigitalradio/ka9q-fec
 * do "./configure", then "make" and "make install"
-* use aac-enc-dabplus or aac-enc-dabplus-zmq to encode live stream or file.
+* See the possible scenarios below on how to use the tools
 * use mot-encoder to encode images into MOT Slideshow
 
 
 How to use
 ==========
 
+We assume:
+
+    ALSASRC="default"
+    DST="tcp://yourserver:9000"
+    BITRATE=64
+
 Scenario 1
 ----------
 
+Live Stream from ALSA sound card at 32kHz, with ZMQ output for ODR-DabMux:
+
+    dabplus-enc-alsa-zmq -d $ALSASRC -c 2 -r 32000 -b $BITRATE -o $DST
+
+To enable sound card drift compensation, add the option **-D**:
+
+    dabplus-enc-alsa-zmq -d $ALSASRC -c 2 -r 32000 -b $BITRATE -o $DST -D
+
+You might see **U** and **O<number>** appearing on the terminal. They correspond
+to audio underruns and overruns that happen due to the different speeds at which
+the audio is captured from the soundcard, and encoded into HE-AACv2.
+
+High occurrence of these will lead to audible artifacts.
+
+
+Scenario 2
+----------
 Live Stream encoding and preparing for DAB muxer, with ZMQ output, at 32kHz, using sox.
+This illustrates the fifo input of *dabplus-enc-file-zmq*.
 
-    ALSASRC="default"
-    DST="tcp://yourserver:9000"
-    BITRATE=64
 
     sox -t alsa $ALSASRC -b 16 -t raw - rate 32k channels 2 | \
-    ../fdk-aac-dabplus/aac-enc-dabplus-zmq -r 32000 \
+    dabplus-enc-file-zmq -r 32000 \
     -i /dev/stdin -b $BITRATE -f raw -a -o $DST -p 4
 
-Scenario 2
+
+Scenario 3
 ----------
 Live Stream encoding and preparing for DAB muxer, with FIFO to odr-dabmux, 48kHz, using
 arecord.
 
     arecord -t raw -f S16_LE -c 2 -r 48000 -D plughw:CARD=Loopback,DEV=0,SUBDEV=0 | \
-    aac-enc-dabplus -b 24 -f raw -c 2 -r 48000 -i /dev/stdin -o /dev/stdout 2>/dev/null | \
+    dabplus-enc-file -a -b 24 -f raw -c 2 -r 48000 -i /dev/stdin -o /dev/stdout 2>/dev/null | \
     mbuffer -q -m 10k -P 100 -s 360 > station1.fifo
 
+Here we are also using the ALSA plughw feature.
 
-Scenario 3
+Scenario 4
 ----------
 Wave file encoding, for non-realtime processing
 
-    aac-enc-dabplus -a -b 64 -i wave_file.wav -o station1.dabp
+    dabplus-enc-file -a -b 64 -i wave_file.wav -o station1.dabp
+
 
 Usage of MOT Slideshow
 ======================
 
-MOT Slideshow is an experimental feature. The mot-encoder reads images in the specified folder,
-and generates the PAD data for the encoder. This is communicated through a unique fifo in /tmp,
-therefore only one instance can run on a single machine.
+MOT Slideshow is an experimental feature. The *mot-encoder* reads images from
+the specified folder, and generates the PAD data for the encoder. This is
+communicated through a fifo to the encoder.
 
-Only aac-enc-dabplus-zmq inserts the PAD data from mot-encoder into the bitstream.
+Only *dabplus-enc-file-zmq* and *dabplus-enc-alsa-zmq* insert the PAD data from
+mot-encoder into the bitstream.
 
 This is an ongoing development.