Readme updates.

1 files changed, 78 insertions, 3 deletions

diff --git a/README b/README
index c48b91ef..16b9b1cb 100644
--- a/README
+++ b/README
@@ -1,4 +1,36 @@
-This is a prototype codec and for now it has limited functionality.
+
+Opus is a codec for interactive speech and audio transmission over the Internet.
+
+  Opus can handle a wide range of interactive audio applications, including
+Voice over IP, videoconferencing, in-game  chat, and even remote live music
+performances. It can scale from low bit-rate narrowband speech to very high
+quality stereo music.
+
+The IETF draft covering Opus can be found at:
+ http://tools.ietf.org/id/draft-ietf-codec-opus
+
+Opus is subject to the royalty-free patent and copyright licenses specified
+in the file COPYING.
+
+This package implements a shared library for encoding and decoding raw Opus
+bitstreams. Raw Opus bitstreams should be used over RTP according to
+ http://tools.ietf.org/html/draft-spittka-payload-rtp-opus
+
+The package also includes a number of test  tools used for testing the
+correct operation of the library. The bitstreams read/written by these
+tools should not be used for Opus file distribution: They include
+additional debugging data and cannot support seeking.
+
+Opus stored in files should use the Ogg encapsulation for Opus which is
+described at:
+ http://wiki.xiph.org/OggOpus
+
+An opus-tools package is available which provides encoding and decoding of
+Ogg encapsulated Opus files and includes a number of useful features.
+Opus-tools can be found at:
+ http://git.xiph.org/?p=users/greg/opus-tools.git
+
+== Compiling libopus ==
 
 To build from a distribution tarball, you only need to do the following:
 
@@ -18,7 +50,6 @@ To build from the git repository, the following steps are necessary:
 % ./configure
 % make
 
-
 Once you have compiled the codec, there will be a opus_demo executable in
 the top directory.
 
@@ -44,4 +75,48 @@ options:
 -loss <perc>         : simulate packet loss, in percent (0-100); default: 0
 
 input and output are 16-bit PCM files (machine endian) or opus bitstreams
-with simple opus_demo propritary framing.
+with simple opus_demo proprietary framing.
+
+== Testing ==
+
+This package includes a collection of automated unit and system tests
+which should be run after compiling the package especially the first
+time it is run on a new platform.
+
+To run the integrated tests:
+% make check
+
+There is also collection of standard test vectors which are not
+included in this package for size reasons but can be obtained from:
+http://opus-codec.org/testvectors/opus_testvectors-draft11.tar.gz
+
+To run compare the code to these test vectors:
+% tar -zxf opus_testvectors-draft11.tar.gz
+% ./tests/run_vectors.sh ./ opus_testvectors 48000
+
+== Portability notes ==
+
+This implementation uses floating-point by default but can be compiled to
+use only fixed-point arithmetic by setting --enable-fixed-point (if using
+autoconf) or by defining the FIXED_POINT macro (if building manually).
+The fixed point implementation has somewhat lower audio quality and is
+slower on platforms with fast FPUs, it is normally only used in embedded
+environments.
+
+The implementation can be compiled with either a C89 or a C99 compiler.
+While it does not rely on any _undefined behavior_ as defined by C89 or
+C99, it relies on common _implementation-defined behavior_ for two's
+complement architectures:
+
+o Right shifts of negative values are consistent with two's
+  complement arithmetic, so that a>>b is equivalent to
+  floor(a/(2^b)),
+
+o For conversion to a signed integer of N bits, the value is reduced
+  modulo 2^N to be within range of the type,
+
+o The result of integer division of a negative value is truncated
+  towards zero, and
+
+o The compiler provides a 64-bit integer type (a C99 requirement
+  which is supported by most C89 compilers).