diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 77 |
1 files changed, 76 insertions, 1 deletions
@@ -1,3 +1,35 @@ +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: % ./configure @@ -16,7 +48,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. @@ -43,3 +74,47 @@ options: input and output are little-endian signed 16-bit PCM files or opus bitstreams 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). |