diff --git a/README b/README.md similarity index 69% rename from README rename to README.md index bcf2376db..c2c1ab16c 100644 --- a/README +++ b/README.md @@ -1,26 +1,24 @@ -== Opus audio codec == +# 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 +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 +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 +`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- +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 +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 @@ -28,18 +26,15 @@ 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://tools.ietf.org/html/rfc7845 +described at: https://tools.ietf.org/html/rfc7845 -An opus-tools package is available which provides encoding and decoding of +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://gitlab.xiph.org/xiph/opus-tools.git -or on the main Opus website: - https://opus-codec.org/ +Opus-tools can be found at: https://gitlab.xiph.org/xiph/opus-tools.git +Or on the main Opus website: https://opus-codec.org/ -== Deep Learning and Opus == +## Deep Learning and Opus Lossy networks continue to be a challenge for real-time communications. While the original implementation of Opus provides an excellent packet loss @@ -55,66 +50,77 @@ prior revisions of Opus. Please see the README under the "dnn" subdirectory to understand DRED. DRED was developed by a team that Amazon Web Services initially sponsored, -who open-sourced the implementation as well as began the -standardization process at the IETF: - https://datatracker.ietf.org/doc/draft-ietf-mlcodec-opus-extension/ +who open-sourced the implementation as well as began the standardization process at the IETF: https://datatracker.ietf.org/doc/draft-ietf-mlcodec-opus-extension/ The license behind Opus or the intellectual property position of Opus does not change with Opus 1.5. -== Compiling libopus == +## Compiling libopus To build from a distribution tarball, you only need to do the following: - % ./configure - % make +```bash +% ./configure +% make +``` -To build from the git repository, the following steps are necessary: +### To build from the git repository, the following steps are necessary: -0) Set up a development environment: +0. Set up a development environment: On an Ubuntu or Debian family Linux distribution: - - % sudo apt-get install git autoconf automake libtool gcc make +```bash +% 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 +```bash +% 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 +```bash +% 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://gitlab.xiph.org/xiph/opus.git - % cd opus - -2) Compiling the source - - % ./autogen.sh - % ./configure - % make - -On x86, it's a good idea to use a -march= option that allows the use of AVX2. - -3) Install the codec libraries (optional) - - % sudo make install +```bash +% brew install autoconf automake libtool +``` + +1. Clone the repository: +```bash +% git clone https://gitlab.xiph.org/xiph/opus.git +% cd opus +``` + +2. Compiling the source +```bash +% ./autogen.sh +% ./configure +% make +``` + +On x86, it's a good idea to use a ```-march=``` option that allows the use of AVX2. + +3. Install the codec libraries (optional) +```bash +% sudo make install +``` Once you have compiled the codec, there will be a opus_demo executable in the top directory. -Usage: opus_demo [-e] - [options] - opus_demo -d [options] - - -mode: voip | audio | restricted-lowdelay -options: +Usage: +``` +opus_demo [-e] + [options] +opus_demo -d [options] + +``` + +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 @@ -133,35 +139,38 @@ options: -forcemono : force mono encoding, even for stereo input -dtx : enable SILK DTX -loss : simulate packet loss, in percent (0-100); default: 0 +``` -input and output are little-endian signed 16-bit PCM files or opus +Input and output are little-endian signed 16-bit PCM files or Opus bitstreams with simple opus_demo proprietary framing. -== Testing == +## 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 +```bash +% 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/docs/opus_testvectors-rfc8251.tar.gz To run compare the code to these test vectors: +```bash +% curl -OL https://opus-codec.org/docs/opus_testvectors-rfc8251.tar.gz +% tar -zxf opus_testvectors-rfc8251.tar.gz +% ./tests/run_vectors.sh ./ opus_newvectors 48000 +``` - % curl -OL https://opus-codec.org/docs/opus_testvectors-rfc8251.tar.gz - % tar -zxf opus_testvectors-rfc8251.tar.gz - % ./tests/run_vectors.sh ./ opus_newvectors 48000 - -== Compiling libopus for Windows and alternative build systems == +## Compiling libopus for Windows and alternative build systems See cmake/README.md or meson/README.md. -== Portability notes == +## 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