README

   1 == Opus audio codec ==
   2
   3 Opus 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
   6 Voice over IP, videoconferencing, in-game  chat, and even remote live music
   7 performances. It can scale from low bit-rate narrowband speech to very high
   8 quality stereo music.
   9
  10   Opus, when coupled with an appropriate container format, is also suitable
  11 for non-realtime  stored-file applications such as music distribution, game
  12 soundtracks, portable music players, jukeboxes, and other applications that
  13 have 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-
  19 free patent and copyright licenses specified in the file COPYING.
  20
  21 This package implements a shared library for encoding and decoding raw Opus
  22 bitstreams. Raw Opus bitstreams should be used over RTP according to
  23  https://tools.ietf.org/html/rfc7587
  24
  25 The package also includes a number of test  tools used for testing the
  26 correct operation of the library. The bitstreams read/written by these
  27 tools should not be used for Opus file distribution: They include
  28 additional debugging data and cannot support seeking.
  29
  30 Opus stored in files should use the Ogg encapsulation for Opus which is
  31 described at:
  32  https://wiki.xiph.org/OggOpus
  33
  34 An opus-tools package is available which provides encoding and decoding of
  35 Ogg encapsulated Opus files and includes a number of useful features.
  36
  37 Opus-tools can be found at:
  38  https://git.xiph.org/?p=opus-tools.git
  39 or on the main Opus website:
  40  https://opus-codec.org/
  41
  42 == Compiling libopus ==
  43
  44 To build from a distribution tarball, you only need to do the following:
  45
  46     % ./configure
  47     % make
  48
  49 To build from the git repository, the following steps are necessary:
  50
  51 0) Set up a development environment:
  52
  53 On an Ubuntu or Debian family Linux distribution:
  54
  55     % sudo apt-get install git autoconf automake libtool gcc make
  56
  57 On a Fedora/Redhat based Linux:
  58
  59     % sudo dnf install git autoconf automake libtool gcc make
  60
  61 Or for older Redhat/Centos Linux releases:
  62
  63     % sudo yum install git autoconf automake libtool gcc make
  64
  65 On Apple macOS, install Xcode and brew.sh, then in the Terminal enter:
  66
  67     % brew install autoconf automake libtool
  68
  69 1) Clone the repository:
  70
  71     % git clone https://git.xiph.org/opus.git
  72     % cd opus
  73
  74 2) Compiling the source
  75
  76     % ./autogen.sh
  77     % ./configure
  78     % make
  79
  80 3) Install the codec libraries (optional)
  81
  82     % sudo make install
  83
  84 Once you have compiled the codec, there will be a opus_demo executable
  85 in the top directory.
  86
  87 Usage: 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
  92 mode: voip | audio | restricted-lowdelay
  93 options:
  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
 113 input and output are little-endian signed 16-bit PCM files or opus
 114 bitstreams with simple opus_demo proprietary framing.
 115
 116 == Testing ==
 117
 118 This package includes a collection of automated unit and system tests
 119 which SHOULD be run after compiling the package especially the first
 120 time it is run on a new platform.
 121
 122 To run the integrated tests:
 123
 124     % make check
 125
 126 There is also collection of standard test vectors which are not
 127 included in this package for size reasons but can be obtained from:
 128 https://opus-codec.org/testvectors/opus_testvectors.tar.gz
 129
 130 To run compare the code to these test vectors:
 131
 132     % curl -O https://opus-codec.org/testvectors/opus_testvectors.tar.gz
 133     % tar -zxf opus_testvectors.tar.gz
 134     % ./tests/run_vectors.sh ./ opus_testvectors 48000
 135
 136 == Portability notes ==
 137
 138 This implementation uses floating-point by default but can be compiled to
 139 use only fixed-point arithmetic by setting --enable-fixed-point (if using
 140 autoconf) or by defining the FIXED_POINT macro (if building manually).
 141 The fixed point implementation has somewhat lower audio quality and is
 142 slower on platforms with fast FPUs, it is normally only used in embedded
 143 environments.
 144
 145 The implementation can be compiled with either a C89 or a C99 compiler.
 146 While it does not rely on any _undefined behavior_ as defined by C89 or
 147 C99, it relies on common _implementation-defined behavior_ for two's
 148 complement architectures:
 149
 150 o 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
 154 o 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
 157 o The result of integer division of a negative value is truncated
 158   towards zero, and
 159
 160 o The compiler provides a 64-bit integer type (a C99 requirement
 161   which is supported by most C89 compilers).