Readme updates.
authorGregory Maxwell <greg@xiph.org>
Wed, 25 Apr 2012 17:30:21 +0000 (13:30 -0400)
committerGregory Maxwell <greg@xiph.org>
Sun, 29 Apr 2012 21:19:40 +0000 (17:19 -0400)
COPYING
README

diff --git a/COPYING b/COPYING
index d774506..3167a00 100644 (file)
--- a/COPYING
+++ b/COPYING
@@ -30,3 +30,15 @@ PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+Opus is subject to the royalty-free patent licenses which are
+specified at:
+
+Xiph.Org Foundation:
+https://datatracker.ietf.org/ipr/1524/
+
+Skype Limited:
+https://datatracker.ietf.org/ipr/1602/
+
+Broadcom Corporation:
+https://datatracker.ietf.org/ipr/1526/
diff --git a/README b/README
index c48b91e..16b9b1c 100644 (file)
--- 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).