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