1== Opus audio codec == 2 3Opus 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 6Voice over IP, videoconferencing, in-game chat, and even remote live music 7performances. It can scale from low bit-rate narrowband speech to very high 8quality stereo music. 9 10 Opus, when coupled with an appropriate container format, is also suitable 11for non-realtime stored-file applications such as music distribution, game 12soundtracks, portable music players, jukeboxes, and other applications that 13have historically used high latency formats such as MP3, AAC, or Vorbis. 14 15 Opus is specified by IETF RFC 6716: 16 https://tools.ietf.org/html/rfc6716 17 18 The Opus format and this implementation of it are subject to the royalty- 19free patent and copyright licenses specified in the file COPYING. 20 21This package implements a shared library for encoding and decoding raw Opus 22bitstreams. Raw Opus bitstreams should be used over RTP according to 23 https://tools.ietf.org/html/rfc7587 24 25The package also includes a number of test tools used for testing the 26correct operation of the library. The bitstreams read/written by these 27tools should not be used for Opus file distribution: They include 28additional debugging data and cannot support seeking. 29 30Opus stored in files should use the Ogg encapsulation for Opus which is 31described at: 32 https://tools.ietf.org/html/rfc7845 33 34An opus-tools package is available which provides encoding and decoding of 35Ogg encapsulated Opus files and includes a number of useful features. 36 37Opus-tools can be found at: 38 https://gitlab.xiph.org/xiph/opus-tools.git 39or on the main Opus website: 40 https://opus-codec.org/ 41 42== Deep Learning and Opus == 43 44Lossy networks continue to be a challenge for real-time communications. 45While the original implementation of Opus provides an excellent packet loss 46concealment mechanism, the team has continued to advance the methodology used 47to improve audio quality in challenge network environments. 48 49In Opus 1.5, we added a deep learning based redundancy encoder that enhances 50audio in lossy networks by embedding one second of recovery data in the padding 51data of each packet. The underlying algorithm behind encoding and decoding the 52recovery data is called the deep redundancy (DRED) algorithm. By leveraging 53the padding data within the packet, Opus 1.5 is fully backward compatible with 54prior revisions of Opus. Please see the README under the "dnn" subdirectory to 55understand DRED. 56 57DRED was developed by a team that Amazon Web Services initially sponsored, 58who open-sourced the implementation as well as began the 59standardization process at the IETF: 60 https://datatracker.ietf.org/doc/draft-ietf-mlcodec-opus-extension/ 61The license behind Opus or the intellectual property position of Opus does 62not change with Opus 1.5. 63 64== Compiling libopus == 65 66To build from a distribution tarball, you only need to do the following: 67 68 % ./configure 69 % make 70 71To build from the git repository, the following steps are necessary: 72 730) Set up a development environment: 74 75On an Ubuntu or Debian family Linux distribution: 76 77 % sudo apt-get install git autoconf automake libtool gcc make 78 79On a Fedora/Redhat based Linux: 80 81 % sudo dnf install git autoconf automake libtool gcc make 82 83Or for older Redhat/Centos Linux releases: 84 85 % sudo yum install git autoconf automake libtool gcc make 86 87On Apple macOS, install Xcode and brew.sh, then in the Terminal enter: 88 89 % brew install autoconf automake libtool 90 911) Clone the repository: 92 93 % git clone https://gitlab.xiph.org/xiph/opus.git 94 % cd opus 95 962) Compiling the source 97 98 % ./autogen.sh 99 % ./configure 100 % make 101 102On x86, it's a good idea to use a -march= option that allows the use of AVX2. 103 1043) Install the codec libraries (optional) 105 106 % sudo make install 107 108Once you have compiled the codec, there will be a opus_demo executable 109in the top directory. 110 111Usage: opus_demo [-e] <application> <sampling rate (Hz)> <channels (1/2)> 112 <bits per second> [options] <input> <output> 113 opus_demo -d <sampling rate (Hz)> <channels (1/2)> [options] 114 <input> <output> 115 116mode: voip | audio | restricted-lowdelay 117options: 118 -e : only runs the encoder (output the bit-stream) 119 -d : only runs the decoder (reads the bit-stream as input) 120 -cbr : enable constant bitrate; default: variable bitrate 121 -cvbr : enable constrained variable bitrate; default: 122 unconstrained 123 -bandwidth <NB|MB|WB|SWB|FB> 124 : audio bandwidth (from narrowband to fullband); 125 default: sampling rate 126 -framesize <2.5|5|10|20|40|60> 127 : frame size in ms; default: 20 128 -max_payload <bytes> 129 : maximum payload size in bytes, default: 1024 130 -complexity <comp> 131 : complexity, 0 (lowest) ... 10 (highest); default: 10 132 -inbandfec : enable SILK inband FEC 133 -forcemono : force mono encoding, even for stereo input 134 -dtx : enable SILK DTX 135 -loss <perc> : simulate packet loss, in percent (0-100); default: 0 136 137input and output are little-endian signed 16-bit PCM files or opus 138bitstreams with simple opus_demo proprietary framing. 139 140== Testing == 141 142This package includes a collection of automated unit and system tests 143which SHOULD be run after compiling the package especially the first 144time it is run on a new platform. 145 146To run the integrated tests: 147 148 % make check 149 150There is also collection of standard test vectors which are not 151included in this package for size reasons but can be obtained from: 152https://opus-codec.org/docs/opus_testvectors-rfc8251.tar.gz 153 154To run compare the code to these test vectors: 155 156 % curl -OL https://opus-codec.org/docs/opus_testvectors-rfc8251.tar.gz 157 % tar -zxf opus_testvectors-rfc8251.tar.gz 158 % ./tests/run_vectors.sh ./ opus_newvectors 48000 159 160== Compiling libopus for Windows and alternative build systems == 161 162See cmake/README.md or meson/README.md. 163 164== Portability notes == 165 166This implementation uses floating-point by default but can be compiled to 167use only fixed-point arithmetic by setting --enable-fixed-point (if using 168autoconf) or by defining the FIXED_POINT macro (if building manually). 169The fixed point implementation has somewhat lower audio quality and is 170slower on platforms with fast FPUs, it is normally only used in embedded 171environments. 172 173The implementation can be compiled with either a C89 or a C99 compiler. 174While it does not rely on any _undefined behavior_ as defined by C89 or 175C99, it relies on common _implementation-defined behavior_ for two's 176complement architectures: 177 178o Right shifts of negative values are consistent with two's 179 complement arithmetic, so that a>>b is equivalent to 180 floor(a/(2^b)), 181 182o For conversion to a signed integer of N bits, the value is reduced 183 modulo 2^N to be within range of the type, 184 185o The result of integer division of a negative value is truncated 186 towards zero, and 187 188o The compiler provides a 64-bit integer type (a C99 requirement 189 which is supported by most C89 compilers). 190