Move the various version defines to be together.
[opus.git] / README
1 Opus is a codec for interactive speech and audio transmission over the Internet.
2
3   Opus can handle a wide range of interactive audio applications, including
4 Voice over IP, videoconferencing, in-game  chat, and even remote live music
5 performances. It can scale from low bit-rate narrowband speech to very high
6 quality stereo music.
7
8 The IETF draft covering Opus can be found at:
9  http://tools.ietf.org/id/draft-ietf-codec-opus
10
11 Opus is subject to the royalty-free patent and copyright licenses specified
12 in the file COPYING.
13
14 This package implements a shared library for encoding and decoding raw Opus
15 bitstreams. Raw Opus bitstreams should be used over RTP according to
16  http://tools.ietf.org/html/draft-spittka-payload-rtp-opus
17
18 The package also includes a number of test  tools used for testing the
19 correct operation of the library. The bitstreams read/written by these
20 tools should not be used for Opus file distribution: They include
21 additional debugging data and cannot support seeking.
22
23 Opus stored in files should use the Ogg encapsulation for Opus which is
24 described at:
25  http://wiki.xiph.org/OggOpus
26
27 An opus-tools package is available which provides encoding and decoding of
28 Ogg encapsulated Opus files and includes a number of useful features.
29 Opus-tools can be found at:
30  http://git.xiph.org/?p=users/greg/opus-tools.git
31
32 == Compiling libopus ==
33 To build from a distribution tarball, you only need to do the following:
34
35 % ./configure
36 % make
37
38 To build from the git repository, the following steps are necessary:
39
40 1) Clone the repository:
41
42 % git clone git://git.opus-codec.org/opus.git
43 % cd opus
44
45 1) Compiling
46
47 % ./autogen.sh
48 % ./configure
49 % make
50
51 Once you have compiled the codec, there will be a opus_demo executable in
52 the top directory.
53
54 Usage: opus_demo [-e] <application> <sampling rate (Hz)> <channels (1/2)>
55          <bits per second> [options] <input> <output>
56        opus_demo -d <sampling rate (Hz)> <channels (1/2)> [options]
57          <input> <output>
58
59 mode: voip | audio | restricted-lowdelay
60 options:
61 -e                   : only runs the encoder (output the bit-stream)
62 -d                   : only runs the decoder (reads the bit-stream as input)
63 -cbr                 : enable constant bitrate; default: variable bitrate
64 -cvbr                : enable constrained variable bitrate; default: unconstrained
65 -bandwidth <NB|MB|WB|SWB|FB> : audio bandwidth (from narrowband to fullband);
66                                default: sampling rate
67 -framesize <2.5|5|10|20|40|60> : frame size in ms; default: 20
68 -max_payload <bytes> : maximum payload size in bytes, default: 1024
69 -complexity <comp>   : complexity, 0 (lowest) ... 10 (highest); default: 10
70 -inbandfec           : enable SILK inband FEC
71 -forcemono           : force mono encoding, even for stereo input
72 -dtx                 : enable SILK DTX
73 -loss <perc>         : simulate packet loss, in percent (0-100); default: 0
74
75 input and output are little-endian signed 16-bit PCM files or opus bitstreams
76 with simple opus_demo proprietary framing.
77
78 == Testing ==
79
80 This package includes a collection of automated unit and system tests
81 which should be run after compiling the package especially the first
82 time it is run on a new platform.
83
84 To run the integrated tests:
85 % make check
86
87 There is also collection of standard test vectors which are not
88 included in this package for size reasons but can be obtained from:
89 http://opus-codec.org/testvectors/opus_testvectors-draft11.tar.gz
90
91 To run compare the code to these test vectors:
92 % tar -zxf opus_testvectors-draft11.tar.gz
93 % ./tests/run_vectors.sh ./ opus_testvectors 48000
94
95 == Portability notes ==
96
97 This implementation uses floating-point by default but can be compiled to
98 use only fixed-point arithmetic by setting --enable-fixed-point (if using
99 autoconf) or by defining the FIXED_POINT macro (if building manually).
100 The fixed point implementation has somewhat lower audio quality and is
101 slower on platforms with fast FPUs, it is normally only used in embedded
102 environments.
103
104 The implementation can be compiled with either a C89 or a C99 compiler.
105 While it does not rely on any _undefined behavior_ as defined by C89 or
106 C99, it relies on common _implementation-defined behavior_ for two's
107 complement architectures:
108
109 o Right shifts of negative values are consistent with two's
110   complement arithmetic, so that a>>b is equivalent to
111   floor(a/(2^b)),
112
113 o For conversion to a signed integer of N bits, the value is reduced
114   modulo 2^N to be within range of the type,
115
116 o The result of integer division of a negative value is truncated
117   towards zero, and
118
119 o The compiler provides a 64-bit integer type (a C99 requirement
120   which is supported by most C89 compilers).