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== Compiling libopus == 43 44To build from a distribution tarball, you only need to do the following: 45 46 % ./configure 47 % make 48 49To build from the git repository, the following steps are necessary: 50 510) Set up a development environment: 52 53On an Ubuntu or Debian family Linux distribution: 54 55 % sudo apt-get install git autoconf automake libtool gcc make 56 57On a Fedora/Redhat based Linux: 58 59 % sudo dnf install git autoconf automake libtool gcc make 60 61Or for older Redhat/Centos Linux releases: 62 63 % sudo yum install git autoconf automake libtool gcc make 64 65On Apple macOS, install Xcode and brew.sh, then in the Terminal enter: 66 67 % brew install autoconf automake libtool 68 691) Clone the repository: 70 71 % git clone https://gitlab.xiph.org/xiph/opus.git 72 % cd opus 73 742) Compiling the source 75 76 % ./autogen.sh 77 % ./configure 78 % make 79 803) Install the codec libraries (optional) 81 82 % sudo make install 83 84Once you have compiled the codec, there will be a opus_demo executable 85in the top directory. 86 87Usage: opus_demo [-e] <application> <sampling rate (Hz)> <channels (1/2)> 88 <bits per second> [options] <input> <output> 89 opus_demo -d <sampling rate (Hz)> <channels (1/2)> [options] 90 <input> <output> 91 92mode: voip | audio | restricted-lowdelay 93options: 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 112 113input and output are little-endian signed 16-bit PCM files or opus 114bitstreams with simple opus_demo proprietary framing. 115 116== Testing == 117 118This package includes a collection of automated unit and system tests 119which SHOULD be run after compiling the package especially the first 120time it is run on a new platform. 121 122To run the integrated tests: 123 124 % make check 125 126There is also collection of standard test vectors which are not 127included in this package for size reasons but can be obtained from: 128https://opus-codec.org/docs/opus_testvectors-rfc8251.tar.gz 129 130To run compare the code to these test vectors: 131 132 % curl -OL https://opus-codec.org/docs/opus_testvectors-rfc8251.tar.gz 133 % tar -zxf opus_testvectors-rfc8251.tar.gz 134 % ./tests/run_vectors.sh ./ opus_newvectors 48000 135 136== Portability notes == 137 138This implementation uses floating-point by default but can be compiled to 139use only fixed-point arithmetic by setting --enable-fixed-point (if using 140autoconf) or by defining the FIXED_POINT macro (if building manually). 141The fixed point implementation has somewhat lower audio quality and is 142slower on platforms with fast FPUs, it is normally only used in embedded 143environments. 144 145The implementation can be compiled with either a C89 or a C99 compiler. 146While it does not rely on any _undefined behavior_ as defined by C89 or 147C99, it relies on common _implementation-defined behavior_ for two's 148complement architectures: 149 150o 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 154o 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 157o The result of integer division of a negative value is truncated 158 towards zero, and 159 160o The compiler provides a 64-bit integer type (a C99 requirement 161 which is supported by most C89 compilers). 162