Home | History | Annotate | Download | only in libopus
      1 == Opus audio codec ==
      2 
      3 Opus is a codec for interactive speech and audio transmission over the Internet.
      4 
      5   Opus can handle a wide range of interactive audio applications, including
      6 Voice over IP, videoconferencing, in-game  chat, and even remote live music
      7 performances. It can scale from low bit-rate narrowband speech to very high
      8 quality stereo music.
      9 
     10   Opus, when coupled with an appropriate container format, is also suitable
     11 for non-realtime  stored-file applications such as music distribution, game
     12 soundtracks, portable music players, jukeboxes, and other applications that
     13 have historically used high latency formats such as MP3, AAC, or Vorbis.
     14 
     15                     Opus is specified by IETF RFC 6716:
     16                     http://tools.ietf.org/html/rfc6716
     17 
     18   The Opus format and this implementation of it are subject to the royalty-
     19 free patent and copyright licenses specified in the file COPYING.
     20 
     21 This package implements a shared library for encoding and decoding raw Opus
     22 bitstreams. Raw Opus bitstreams should be used over RTP according to
     23  http://tools.ietf.org/html/draft-spittka-payload-rtp-opus
     24 
     25 The package also includes a number of test  tools used for testing the
     26 correct operation of the library. The bitstreams read/written by these
     27 tools should not be used for Opus file distribution: They include
     28 additional debugging data and cannot support seeking.
     29 
     30 Opus stored in files should use the Ogg encapsulation for Opus which is
     31 described at:
     32  http://wiki.xiph.org/OggOpus
     33 
     34 An opus-tools package is available which provides encoding and decoding of
     35 Ogg encapsulated Opus files and includes a number of useful features.
     36 
     37 Opus-tools can be found at:
     38  https://git.xiph.org/?p=opus-tools.git
     39 or on the main Opus website:
     40  http://opus-codec.org/
     41 
     42 == Compiling libopus ==
     43 
     44 To build from a distribution tarball, you only need to do the following:
     45 
     46 % ./configure
     47 % make
     48 
     49 To build from the git repository, the following steps are necessary:
     50 
     51 1) Clone the repository:
     52 
     53 % git clone git://git.opus-codec.org/opus.git
     54 % cd opus
     55 
     56 2) Compiling the source
     57 
     58 % ./autogen.sh
     59 % ./configure
     60 % make
     61 
     62 3) Install the codec libraries (optional)
     63 
     64 % sudo make install
     65 
     66 Once you have compiled the codec, there will be a opus_demo executable
     67 in the top directory.
     68 
     69 Usage: opus_demo [-e] <application> <sampling rate (Hz)> <channels (1/2)>
     70          <bits per second> [options] <input> <output>
     71        opus_demo -d <sampling rate (Hz)> <channels (1/2)> [options]
     72          <input> <output>
     73 
     74 mode: voip | audio | restricted-lowdelay
     75 options:
     76   -e                : only runs the encoder (output the bit-stream)
     77   -d                : only runs the decoder (reads the bit-stream as input)
     78   -cbr              : enable constant bitrate; default: variable bitrate
     79   -cvbr             : enable constrained variable bitrate; default:
     80                       unconstrained
     81   -bandwidth <NB|MB|WB|SWB|FB>
     82                     : audio bandwidth (from narrowband to fullband);
     83                       default: sampling rate
     84   -framesize <2.5|5|10|20|40|60>
     85                     : frame size in ms; default: 20
     86   -max_payload <bytes>
     87                     : maximum payload size in bytes, default: 1024
     88   -complexity <comp>
     89                     : complexity, 0 (lowest) ... 10 (highest); default: 10
     90   -inbandfec        : enable SILK inband FEC
     91   -forcemono        : force mono encoding, even for stereo input
     92   -dtx              : enable SILK DTX
     93   -loss <perc>      : simulate packet loss, in percent (0-100); default: 0
     94 
     95 input and output are little-endian signed 16-bit PCM files or opus
     96 bitstreams with simple opus_demo proprietary framing.
     97 
     98 == Testing ==
     99 
    100 This package includes a collection of automated unit and system tests
    101 which SHOULD be run after compiling the package especially the first
    102 time it is run on a new platform.
    103 
    104 To run the integrated tests:
    105 % make check
    106 
    107 There is also collection of standard test vectors which are not
    108 included in this package for size reasons but can be obtained from:
    109 http://opus-codec.org/testvectors/opus_testvectors.tar.gz
    110 
    111 To run compare the code to these test vectors:
    112 
    113 % curl -O http://opus-codec.org/testvectors/opus_testvectors.tar.gz
    114 % tar -zxf opus_testvectors.tar.gz
    115 % ./tests/run_vectors.sh ./ opus_testvectors 48000
    116 
    117 == Portability notes ==
    118 
    119 This implementation uses floating-point by default but can be compiled to
    120 use only fixed-point arithmetic by setting --enable-fixed-point (if using
    121 autoconf) or by defining the FIXED_POINT macro (if building manually).
    122 The fixed point implementation has somewhat lower audio quality and is
    123 slower on platforms with fast FPUs, it is normally only used in embedded
    124 environments.
    125 
    126 The implementation can be compiled with either a C89 or a C99 compiler.
    127 While it does not rely on any _undefined behavior_ as defined by C89 or
    128 C99, it relies on common _implementation-defined behavior_ for two's
    129 complement architectures:
    130 
    131 o Right shifts of negative values are consistent with two's
    132   complement arithmetic, so that a>>b is equivalent to
    133   floor(a/(2^b)),
    134 
    135 o For conversion to a signed integer of N bits, the value is reduced
    136   modulo 2^N to be within range of the type,
    137 
    138 o The result of integer division of a negative value is truncated
    139   towards zero, and
    140 
    141 o The compiler provides a 64-bit integer type (a C99 requirement
    142   which is supported by most C89 compilers).
    143