audiowmark/README.adoc

= audiowmark - Audio Watermarking

== Description

`audiowmark` is an Open Source solution for audio watermarking. A sound file
(typically wav) is read by the software, and a 128-bit message is stored in a
watermark in the output sound file. For human listeners, the files typically
sound the same.

However, the 128-bit message can be retrieved from the output sound file. Our
tests show, that even if the file is converted to mp3 or ogg (with bitrate 128
kbit/s or higher), the watermark usually can be retrieved without problems. The
process of retrieving the message does not need the original audio file (blind
decoding).

Internally, audiowmark is using the patchwork algorithm to hide the data in the
spectrum of the audio file. The signal is split into 1024 sample frames. For
each frame, some pseoudo-randomly selected amplitudes of the frequency bands of
a 1024-value FFTs are increased or decreased slightly, which can be detected
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 a Watermark

To add a watermark to the soundfile in.wav with a 128-bit message (which is
specified as hex-string):

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

The most important options for adding a watermark are:

--key <filename>::
Use watermarking key from file <filename> (see <<key>>).

--strength <s>::
Set the watermarking strength (see <<strength>>).

== Retrieving a Watermark

To get the 128-bit message from the watermarked file, use:

[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` 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. In our example each pattern was decoded correctly, because
the watermark was not damaged at all, but if you for instance use lossy
compression (with a low bitrate), it may happen that only some of the decoded
patterns are correct. Or none, if the watermark was damaged too much.

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

The most important options for getting a watermark are:

--key <filename>::
Use watermarking key from file <filename> (see <<key>>).

--strength <s>::
Set the watermarking strength (see <<strength>>).

[[key]]
== Watermark Key

Since the software is Open Source, a watermarking key should be used to ensure
that the message bits cannot be retrieved by somebody else (which would also
allow removing the watermark without loss of quality). The watermark key
controls all pseudo-random parameters of the algorithm. This means that
it determines which frequency bands are increased or decreased to store a
0 bit or a 1 bit. Without the key, it is impossible to decode the message
bits from the audio file alone.

Our watermarking key is a 128-bit AES key. A key can be generated using

  audiowmark gen-key test.key

and can be used for the add/get commands as follows:

  audiowmark add --key test.key in.wav out.wav 0123456789abcdef0011223344556677
  audiowmark get --key test.key out.wav

[[strength]]
== Watermark Strength

The watermark strength parameter affects how much the watermarking algorithm
modifies the input signal. A stronger watermark is more audible, but also more
robust against modifications. The default strength is 10. A watermark with that
strength is recoverable after mp3/ogg encoding with 128kbit/s or higher. In our
informal listening tests, this setting also has a very good subjective quality.

A higher strength (for instance 15) would be helpful for instance if robustness
against multiple conversions or conversions to low bit rates (i.e. 64kbit/s) is
desired.

A lower strength (for instance 6) makes the watermark less audible, but also
less robust. Strengths below 5 are not recommended. To set the strength, the
same value has to be passed during both, generation and retrieving the
watermark. Fractional strengths (like 7.5) are possible.

  audiowmark add --strength 15 in.wav out.wav 0123456789abcdef0011223344556677
  audiowmark get --strength 15 out.wav

== Dependencies

If you compile from source, audiowmark needs the following libraries:

* libfftw3
* libsndfile
* libgcrypt
* libzita-resampler
* libmpg123

== Building fftw

audiowmark needs the single prevision variant of fftw3.

If you are building fftw3 from source, use the `--enable-float`
configure parameter to build it, e.g.::

	cd ${FFTW3_SOURCE}
	./configure --enable-float --enable-sse && \
	make && \
	sudo make install

or, when building from git

	cd ${FFTW3_GIT}
	./bootstrap.sh --enable-shared --enable-sse --enable-float && \
	make && \
	sudo make install

== Docker Build

You should be able to execute audiowmark via Docker.
Example that outputs the usage message:

  docker build -t audiowmark .
  docker run -v <local-data-directory>:/data -it audiowmark -h