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