Fix entropy coder doc
[opus.git] / README
diff --git a/README b/README
index 73a2292..9a06811 100644 (file)
--- a/README
+++ b/README
-CELT is a very low delay audio codec designed for high-quality communications.
-
-Traditional full-bandwidth  codecs such as Vorbis and AAC can offer high
-quality but they require codec delays of hundreds of milliseconds, which
-makes them unsuitable  for real-time interactive applications like tele-
-conferencing. Speech targeted codecs, such as Speex or G.722, have lower
-20-40ms delays but their speech focus and limited sampling rates 
-restricts their quality, especially for music.
-
-Additionally, the other mandatory components of a full network audio system—
-audio interfaces, routers, jitter buffers— each add their own delay. For lower
-speed networks the time it takes to serialize a  packet onto the network cable
-takes considerable time, and over the long distances the speed of light
-imposes a significant delay.
-
-In teleconferencing— it is important to keep delay low so that the participants
-can communicate fluidly without talking on top of each  other and so that their
-own voices don't return after a round trip as an annoying echo.
-
-For network music performance— research has show that the total one way delay
-must be kept under 25ms to avoid degrading the musicians performance. 
-
-Since many of the sources of delay in a complete system are outside of the
-user's control (such as the  speed of light) it is often  only possible to
-reduce the total delay by reducing the codec delay. 
-
-Low delay has traditionally been considered a challenging area in audio codec
-design, because as a codec is forced to work on the smaller chunks of audio
-required for low delay it has access to less redundancy and less perceptual
-information which it can use to reduce the size of the transmitted audio.
-
-CELT is designed to bridge the gap between "music" and "speech" codecs,
-permitting new very high quality teleconferencing applications, and to go
-further, permitting latencies much lower than speech codecs normally provide
-to enable applications such as remote musical collaboration even over long
-distances.  
-
-In keeping with the Xiph.Org mission—  CELT is also designed to accomplish
-this without copyright or patent encumbrance. Only by keeping the formats
-that drive our Internet communication free and unencumbered can we maximize
-innovation, collaboration, and interoperability.  Fortunately, CELT is ahead
-of the adoption curve in its target application space, so there should be 
-no reason for someone who needs what CELT provides to go with a proprietary
-codec.
-
-CELT has been tested on x86, x86_64, ARM, and the TI C55x DSPs, and should
-be portable to any platform with a working C compiler and on the order of
-100 MIPS of processing power. 
-
-The code is still in early stage, so it may be broken from time to time, and
-the bit-stream is not frozen yet, so it is different from one version to 
-another. Oh, and don't complain if it sets your house on fire.
-
-Complaints and accolades can be directed to the CELT mailing list:
-http://lists.xiph.org/mailman/listinfo/celt-dev/
-
-To compile:
-% ./configure
-% make
-
-For platforms without fast floating point support (such as ARM) use the
---enable-fixed argument to configure to build a fixed-point version of CELT.
-
-There are Ogg-based encode/decode tools in tools/. These are quite similar to
-the speexenc/speexdec tools. Use the --help option for details.
-
-There is also a basic tool for testing the encoder and decoder called
-"testcelt" located in libcelt/: 
-
-% testcelt <rate> <channels> <frame size> <bytes per packet> input.sw output.sw
-
-where input.sw is a 16-bit (machine endian) audio file sampled at 32000 Hz to 
-96000 Hz. The output file is already decompressed.  
-
-For example, for a 44.1 kHz mono stream at ~64kbit/sec and with 256 sample
-frames:
-
-% testcelt 44100 1 256 46 intput.sw output.sw 
-
-Since 44100/256*46*8 = 63393.74 bits/sec.
-
-All even frame sizes from 64 to 512 are currently supported, although
-power-of-two sizes are recommended  and most CELT development is done
-using a size of 256.  The delay imposed by CELT is  1.25x - 1.5x  the 
-frame duration depending on the frame size and some details of CELT's
-internal operation.  For 256 sample frames the delay is 1.5x  or  384
-samples, so the total codec delay in the above example is 8.70ms 
-(1000/(44100/384)).   
+== 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 -OL 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).