Gregory Maxwell | 635b5f2 | 2012-08-21 14:24:38 -0400 | [diff] [blame] | 1 | == Opus audio codec == |
| 2 | |
Gregory Maxwell | 4281577 | 2012-04-25 13:30:21 -0400 | [diff] [blame] | 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 | |
Gregory Maxwell | 635b5f2 | 2012-08-21 14:24:38 -0400 | [diff] [blame] | 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. |
Gregory Maxwell | 4281577 | 2012-04-25 13:30:21 -0400 | [diff] [blame] | 14 | |
Gregory Maxwell | 635b5f2 | 2012-08-21 14:24:38 -0400 | [diff] [blame] | 15 | Opus is specified by IETF RFC 6716: |
Mark Harris | 699b643 | 2015-10-23 13:19:48 -0400 | [diff] [blame] | 16 | https://tools.ietf.org/html/rfc6716 |
Gregory Maxwell | 635b5f2 | 2012-08-21 14:24:38 -0400 | [diff] [blame] | 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. |
Gregory Maxwell | 4281577 | 2012-04-25 13:30:21 -0400 | [diff] [blame] | 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 |
Mark Harris | 699b643 | 2015-10-23 13:19:48 -0400 | [diff] [blame] | 23 | https://tools.ietf.org/html/rfc7587 |
Gregory Maxwell | 4281577 | 2012-04-25 13:30:21 -0400 | [diff] [blame] | 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: |
Mark Harris | 699b643 | 2015-10-23 13:19:48 -0400 | [diff] [blame] | 32 | https://wiki.xiph.org/OggOpus |
Gregory Maxwell | 4281577 | 2012-04-25 13:30:21 -0400 | [diff] [blame] | 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. |
Gregory Maxwell | 635b5f2 | 2012-08-21 14:24:38 -0400 | [diff] [blame] | 36 | |
Gregory Maxwell | 4281577 | 2012-04-25 13:30:21 -0400 | [diff] [blame] | 37 | Opus-tools can be found at: |
Gregory Maxwell | 635b5f2 | 2012-08-21 14:24:38 -0400 | [diff] [blame] | 38 | https://git.xiph.org/?p=opus-tools.git |
| 39 | or on the main Opus website: |
Mark Harris | 699b643 | 2015-10-23 13:19:48 -0400 | [diff] [blame] | 40 | https://opus-codec.org/ |
Gregory Maxwell | 4281577 | 2012-04-25 13:30:21 -0400 | [diff] [blame] | 41 | |
| 42 | == Compiling libopus == |
Gregory Maxwell | 635b5f2 | 2012-08-21 14:24:38 -0400 | [diff] [blame] | 43 | |
Jean-Marc Valin | 4468c75 | 2010-07-08 13:40:07 -0400 | [diff] [blame] | 44 | 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] | 45 | |
Ralph Giles | 1eaa67c | 2017-05-10 10:46:22 -0700 | [diff] [blame] | 46 | % ./configure |
| 47 | % make |
Jean-Marc Valin | 8ba2a77 | 2010-07-05 14:55:02 -0400 | [diff] [blame] | 48 | |
Kat Walsh | 3269dce | 2011-08-15 22:43:51 -0400 | [diff] [blame] | 49 | To build from the git repository, the following steps are necessary: |
Jean-Marc Valin | 4468c75 | 2010-07-08 13:40:07 -0400 | [diff] [blame] | 50 | |
Ralph Giles | badd1e5 | 2017-05-10 10:37:46 -0700 | [diff] [blame] | 51 | 0) Set up a development environment: |
| 52 | |
| 53 | On an Ubuntu or Debian family Linux distribution: |
| 54 | |
Ralph Giles | 1eaa67c | 2017-05-10 10:46:22 -0700 | [diff] [blame] | 55 | % sudo apt-get install git autoconf automake libtool gcc make |
Ralph Giles | badd1e5 | 2017-05-10 10:37:46 -0700 | [diff] [blame] | 56 | |
| 57 | On a Fedora/Redhat based Linux: |
| 58 | |
Ralph Giles | 1eaa67c | 2017-05-10 10:46:22 -0700 | [diff] [blame] | 59 | % sudo dnf install git autoconf automake libtool gcc make |
Ralph Giles | badd1e5 | 2017-05-10 10:37:46 -0700 | [diff] [blame] | 60 | |
| 61 | Or for older Redhat/Centos Linux releases: |
| 62 | |
Ralph Giles | 1eaa67c | 2017-05-10 10:46:22 -0700 | [diff] [blame] | 63 | % sudo yum install git autoconf automake libtool gcc make |
Ralph Giles | badd1e5 | 2017-05-10 10:37:46 -0700 | [diff] [blame] | 64 | |
| 65 | On Apple macOS, install Xcode and brew.sh, then in the Terminal enter: |
| 66 | |
Ralph Giles | 1eaa67c | 2017-05-10 10:46:22 -0700 | [diff] [blame] | 67 | % brew install autoconf automake libtool |
Ralph Giles | badd1e5 | 2017-05-10 10:37:46 -0700 | [diff] [blame] | 68 | |
Jean-Marc Valin | fe74125 | 2011-04-30 14:21:35 -0400 | [diff] [blame] | 69 | 1) Clone the repository: |
Jean-Marc Valin | 4468c75 | 2010-07-08 13:40:07 -0400 | [diff] [blame] | 70 | |
Ralph Giles | 1eaa67c | 2017-05-10 10:46:22 -0700 | [diff] [blame] | 71 | % git clone https://git.xiph.org/opus.git |
| 72 | % cd opus |
Jean-Marc Valin | 4468c75 | 2010-07-08 13:40:07 -0400 | [diff] [blame] | 73 | |
Gregory Maxwell | 635b5f2 | 2012-08-21 14:24:38 -0400 | [diff] [blame] | 74 | 2) Compiling the source |
Jean-Marc Valin | 4468c75 | 2010-07-08 13:40:07 -0400 | [diff] [blame] | 75 | |
Ralph Giles | 1eaa67c | 2017-05-10 10:46:22 -0700 | [diff] [blame] | 76 | % ./autogen.sh |
| 77 | % ./configure |
| 78 | % make |
Jean-Marc Valin | 4468c75 | 2010-07-08 13:40:07 -0400 | [diff] [blame] | 79 | |
Gregory Maxwell | 0a17185 | 2012-09-16 01:07:09 -0400 | [diff] [blame] | 80 | 3) Install the codec libraries (optional) |
| 81 | |
Ralph Giles | 1eaa67c | 2017-05-10 10:46:22 -0700 | [diff] [blame] | 82 | % sudo make install |
Gregory Maxwell | 0a17185 | 2012-09-16 01:07:09 -0400 | [diff] [blame] | 83 | |
Gregory Maxwell | 635b5f2 | 2012-08-21 14:24:38 -0400 | [diff] [blame] | 84 | Once you have compiled the codec, there will be a opus_demo executable |
| 85 | in the top directory. |
Jean-Marc Valin | 4468c75 | 2010-07-08 13:40:07 -0400 | [diff] [blame] | 86 | |
Gregory Maxwell | a5ff49e | 2011-10-26 19:56:00 -0400 | [diff] [blame] | 87 | Usage: opus_demo [-e] <application> <sampling rate (Hz)> <channels (1/2)> |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 88 | <bits per second> [options] <input> <output> |
Gregory Maxwell | a5ff49e | 2011-10-26 19:56:00 -0400 | [diff] [blame] | 89 | opus_demo -d <sampling rate (Hz)> <channels (1/2)> [options] |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 90 | <input> <output> |
Jean-Marc Valin | 4468c75 | 2010-07-08 13:40:07 -0400 | [diff] [blame] | 91 | |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 92 | mode: voip | audio | restricted-lowdelay |
Jean-Marc Valin | 0806200 | 2011-03-09 13:24:24 -0500 | [diff] [blame] | 93 | options: |
Gregory Maxwell | 635b5f2 | 2012-08-21 14:24:38 -0400 | [diff] [blame] | 94 | -e : only runs the encoder (output the bit-stream) |
| 95 | -d : only runs the decoder (reads the bit-stream as input) |
| 96 | -cbr : enable constant bitrate; default: variable bitrate |
| 97 | -cvbr : enable constrained variable bitrate; default: |
| 98 | unconstrained |
| 99 | -bandwidth <NB|MB|WB|SWB|FB> |
| 100 | : audio bandwidth (from narrowband to fullband); |
| 101 | default: sampling rate |
| 102 | -framesize <2.5|5|10|20|40|60> |
| 103 | : frame size in ms; default: 20 |
| 104 | -max_payload <bytes> |
| 105 | : maximum payload size in bytes, default: 1024 |
| 106 | -complexity <comp> |
| 107 | : complexity, 0 (lowest) ... 10 (highest); default: 10 |
| 108 | -inbandfec : enable SILK inband FEC |
| 109 | -forcemono : force mono encoding, even for stereo input |
| 110 | -dtx : enable SILK DTX |
| 111 | -loss <perc> : simulate packet loss, in percent (0-100); default: 0 |
Jean-Marc Valin | 78a4b58 | 2010-07-08 15:51:49 -0400 | [diff] [blame] | 112 | |
Gregory Maxwell | 635b5f2 | 2012-08-21 14:24:38 -0400 | [diff] [blame] | 113 | input and output are little-endian signed 16-bit PCM files or opus |
| 114 | bitstreams with simple opus_demo proprietary framing. |
Gregory Maxwell | 4281577 | 2012-04-25 13:30:21 -0400 | [diff] [blame] | 115 | |
| 116 | == Testing == |
| 117 | |
| 118 | This package includes a collection of automated unit and system tests |
Gregory Maxwell | 635b5f2 | 2012-08-21 14:24:38 -0400 | [diff] [blame] | 119 | which SHOULD be run after compiling the package especially the first |
Gregory Maxwell | 4281577 | 2012-04-25 13:30:21 -0400 | [diff] [blame] | 120 | time it is run on a new platform. |
| 121 | |
| 122 | To run the integrated tests: |
Ralph Giles | 1eaa67c | 2017-05-10 10:46:22 -0700 | [diff] [blame] | 123 | |
| 124 | % make check |
Gregory Maxwell | 4281577 | 2012-04-25 13:30:21 -0400 | [diff] [blame] | 125 | |
| 126 | There is also collection of standard test vectors which are not |
| 127 | included in this package for size reasons but can be obtained from: |
Mark Harris | 699b643 | 2015-10-23 13:19:48 -0400 | [diff] [blame] | 128 | https://opus-codec.org/testvectors/opus_testvectors.tar.gz |
Gregory Maxwell | 4281577 | 2012-04-25 13:30:21 -0400 | [diff] [blame] | 129 | |
| 130 | To run compare the code to these test vectors: |
Gregory Maxwell | 635b5f2 | 2012-08-21 14:24:38 -0400 | [diff] [blame] | 131 | |
Ralph Giles | 1eaa67c | 2017-05-10 10:46:22 -0700 | [diff] [blame] | 132 | % curl -O https://opus-codec.org/testvectors/opus_testvectors.tar.gz |
| 133 | % tar -zxf opus_testvectors.tar.gz |
| 134 | % ./tests/run_vectors.sh ./ opus_testvectors 48000 |
Gregory Maxwell | 4281577 | 2012-04-25 13:30:21 -0400 | [diff] [blame] | 135 | |
| 136 | == Portability notes == |
| 137 | |
| 138 | This implementation uses floating-point by default but can be compiled to |
| 139 | use only fixed-point arithmetic by setting --enable-fixed-point (if using |
| 140 | autoconf) or by defining the FIXED_POINT macro (if building manually). |
| 141 | The fixed point implementation has somewhat lower audio quality and is |
| 142 | slower on platforms with fast FPUs, it is normally only used in embedded |
| 143 | environments. |
| 144 | |
| 145 | The implementation can be compiled with either a C89 or a C99 compiler. |
| 146 | While it does not rely on any _undefined behavior_ as defined by C89 or |
| 147 | C99, it relies on common _implementation-defined behavior_ for two's |
| 148 | complement architectures: |
| 149 | |
| 150 | o Right shifts of negative values are consistent with two's |
| 151 | complement arithmetic, so that a>>b is equivalent to |
| 152 | floor(a/(2^b)), |
| 153 | |
| 154 | o For conversion to a signed integer of N bits, the value is reduced |
| 155 | modulo 2^N to be within range of the type, |
| 156 | |
| 157 | o The result of integer division of a negative value is truncated |
| 158 | towards zero, and |
| 159 | |
| 160 | o The compiler provides a 64-bit integer type (a C99 requirement |
| 161 | which is supported by most C89 compilers). |