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