Document more details about audiowmark get.

Signed-off-by: Stefan Westerfeld <stefan@space.twc.de>

README.adoc

@@ -22,16 +22,73 @@ later. The algorithm used here is inspired by
   Martin Steinebach: Digitale Wasserzeichen für Audiodaten.
   Darmstadt University of Technology 2004, ISBN 3-8322-2507-2
 
-== Adding/Retrieving a Watermark
+== Adding a Watermark
 
 To add a watermark to the soundfile in.wav with a 128-bit message (which is
 specified as hex-string):
 
-  audiowmark add in.wav out.wav 0123456789abcdef0011223344556677
+[subs=+quotes]
+....
+  *$ audiowmark add in.wav out.wav 0123456789abcdef0011223344556677*
+  Input:        in.wav
+  Output:       out.wav
+  Message:      0123456789abcdef0011223344556677
+  Strength:     10
+
+  Time:         3:59
+  Sample Rate:  48000
+  Channels:     2
+  Data Blocks:  4
+  Volume Norm:  0.987 (-0.12 dB)
+....
+
+== Retrieving a Watermark
 
 To get the 128-bit message from the watermarked file, use:
 
-  audiowmark get out.wav
+[subs=+quotes]
+....
+  *$ audiowmark get out.wav*
+  pattern  0:05 0123456789abcdef0011223344556677 1.324 0.059 A
+  pattern  0:57 0123456789abcdef0011223344556677 1.413 0.112 B
+  pattern  0:57 0123456789abcdef0011223344556677 1.368 0.086 AB
+  pattern  1:49 0123456789abcdef0011223344556677 1.302 0.098 A
+  pattern  2:40 0123456789abcdef0011223344556677 1.361 0.093 B
+  pattern  2:40 0123456789abcdef0011223344556677 1.331 0.096 AB
+  pattern   all 0123456789abcdef0011223344556677 1.350 0.054
+....
+The output of `audiowmark get` is designed to be machine readable. Each line
+that starts with `pattern` is contains one decoded message. The fields are
+seperated by one or more space characters. The first field is a *timestamp*
+indicating the position of the data block. The second field is the *decoded
+message*. For most purposes this is all you need to know.
+
+The software was designed under the assumption that you - the user - will be
+able to decide whether a message is correct or not. To do this, on watermarking
+song files, you could list each message you embedded in a database. During
+retrieval, you should look up each pattern `audiowmark get` outputs in the
+database. If the message is not found, then you should assume that a decoding
+error occurred.
+
+The third field is the *sync score* (higher is better). The synchronization
+algorithm tries to find valid data blocks in the audio file, that become
+candidates for decoding.
+
+The fourth field is the *decoding error* (lower is better). During message
+decoding, we use convolutional codes for error correction, to make the
+watermarking more robust.
+
+The fifth field is the *block type*. There are two types of data blocks,
+A blocks and B blocks. A single data block can be decoded alone, as it
+contains a complete message. However, if during watermark detection an
+A block followed by a B block was found, these two can be decoded
+together (then this field will be AB), resulting in even higher error
+correction capacity than one block alone would have.
+
+To improve the error correction capacity even further, the `all` pattern
+combines all data blocks that are available. The combined decoded
+message will often be the most reliable result (meaning that even if all
+other patterns were incorrect, this could still be right).
 
 == Watermark Key