| == Opus audio codec == |
| |
| Opus is a codec for interactive speech and audio transmission over the Internet. |
| |
| Opus can handle a wide range of interactive audio applications, including |
| Voice over IP, videoconferencing, in-game chat, and even remote live music |
| performances. It can scale from low bit-rate narrowband speech to very high |
| quality stereo music. |
| |
| Opus, when coupled with an appropriate container format, is also suitable |
| for non-realtime stored-file applications such as music distribution, game |
| soundtracks, portable music players, jukeboxes, and other applications that |
| have historically used high latency formats such as MP3, AAC, or Vorbis. |
| |
| Opus is specified by IETF RFC 6716: |
| https://tools.ietf.org/html/rfc6716 |
| |
| The Opus format and this implementation of it are subject to the royalty- |
| free patent and copyright licenses specified in the file COPYING. |
| |
| This package implements a shared library for encoding and decoding raw Opus |
| bitstreams. Raw Opus bitstreams should be used over RTP according to |
| https://tools.ietf.org/html/rfc7587 |
| |
| The package also includes a number of test tools used for testing the |
| correct operation of the library. The bitstreams read/written by these |
| tools should not be used for Opus file distribution: They include |
| additional debugging data and cannot support seeking. |
| |
| Opus stored in files should use the Ogg encapsulation for Opus which is |
| described at: |
| https://wiki.xiph.org/OggOpus |
| |
| An opus-tools package is available which provides encoding and decoding of |
| Ogg encapsulated Opus files and includes a number of useful features. |
| |
| Opus-tools can be found at: |
| https://git.xiph.org/?p=opus-tools.git |
| or on the main Opus website: |
| https://opus-codec.org/ |
| |
| == Compiling libopus == |
| |
| To build from a distribution tarball, you only need to do the following: |
| |
| % ./configure |
| % make |
| |
| To build from the git repository, the following steps are necessary: |
| |
| 0) Set up a development environment: |
| |
| On an Ubuntu or Debian family Linux distribution: |
| |
| % sudo apt-get install git autoconf automake libtool gcc make |
| |
| On a Fedora/Redhat based Linux: |
| |
| % sudo dnf install git autoconf automake libtool gcc make |
| |
| Or for older Redhat/Centos Linux releases: |
| |
| % sudo yum install git autoconf automake libtool gcc make |
| |
| On Apple macOS, install Xcode and brew.sh, then in the Terminal enter: |
| |
| % brew install autoconf automake libtool |
| |
| 1) Clone the repository: |
| |
| % git clone https://git.xiph.org/opus.git |
| % cd opus |
| |
| 2) Compiling the source |
| |
| % ./autogen.sh |
| % ./configure |
| % make |
| |
| 3) Install the codec libraries (optional) |
| |
| % sudo make install |
| |
| Once you have compiled the codec, there will be a opus_demo executable |
| in the top directory. |
| |
| Usage: opus_demo [-e] <application> <sampling rate (Hz)> <channels (1/2)> |
| <bits per second> [options] <input> <output> |
| opus_demo -d <sampling rate (Hz)> <channels (1/2)> [options] |
| <input> <output> |
| |
| mode: voip | audio | restricted-lowdelay |
| options: |
| -e : only runs the encoder (output the bit-stream) |
| -d : only runs the decoder (reads the bit-stream as input) |
| -cbr : enable constant bitrate; default: variable bitrate |
| -cvbr : enable constrained variable bitrate; default: |
| unconstrained |
| -bandwidth <NB|MB|WB|SWB|FB> |
| : audio bandwidth (from narrowband to fullband); |
| default: sampling rate |
| -framesize <2.5|5|10|20|40|60> |
| : frame size in ms; default: 20 |
| -max_payload <bytes> |
| : maximum payload size in bytes, default: 1024 |
| -complexity <comp> |
| : complexity, 0 (lowest) ... 10 (highest); default: 10 |
| -inbandfec : enable SILK inband FEC |
| -forcemono : force mono encoding, even for stereo input |
| -dtx : enable SILK DTX |
| -loss <perc> : simulate packet loss, in percent (0-100); default: 0 |
| |
| input and output are little-endian signed 16-bit PCM files or opus |
| bitstreams with simple opus_demo proprietary framing. |
| |
| == Testing == |
| |
| This package includes a collection of automated unit and system tests |
| which SHOULD be run after compiling the package especially the first |
| time it is run on a new platform. |
| |
| To run the integrated tests: |
| |
| % make check |
| |
| There is also collection of standard test vectors which are not |
| included in this package for size reasons but can be obtained from: |
| https://opus-codec.org/testvectors/opus_testvectors.tar.gz |
| |
| To run compare the code to these test vectors: |
| |
| % curl -O https://opus-codec.org/testvectors/opus_testvectors.tar.gz |
| % tar -zxf opus_testvectors.tar.gz |
| % ./tests/run_vectors.sh ./ opus_testvectors 48000 |
| |
| == Portability notes == |
| |
| This implementation uses floating-point by default but can be compiled to |
| use only fixed-point arithmetic by setting --enable-fixed-point (if using |
| autoconf) or by defining the FIXED_POINT macro (if building manually). |
| The fixed point implementation has somewhat lower audio quality and is |
| slower on platforms with fast FPUs, it is normally only used in embedded |
| environments. |
| |
| The implementation can be compiled with either a C89 or a C99 compiler. |
| While it does not rely on any _undefined behavior_ as defined by C89 or |
| C99, it relies on common _implementation-defined behavior_ for two's |
| complement architectures: |
| |
| o Right shifts of negative values are consistent with two's |
| complement arithmetic, so that a>>b is equivalent to |
| floor(a/(2^b)), |
| |
| o For conversion to a signed integer of N bits, the value is reduced |
| modulo 2^N to be within range of the type, |
| |
| o The result of integer division of a negative value is truncated |
| towards zero, and |
| |
| o The compiler provides a 64-bit integer type (a C99 requirement |
| which is supported by most C89 compilers). |