From 4281577b52b2f7ef45397829c7059a9314a246ad Mon Sep 17 00:00:00 2001 From: Gregory Maxwell Date: Wed, 25 Apr 2012 13:30:21 -0400 Subject: Readme updates. --- README | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 78 insertions(+), 3 deletions(-) (limited to 'README') 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 : 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). -- cgit v1.2.1