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