Documentation updates.
[opus.git] / src / opus.h
1 /* Copyright (c) 2010-2011 Xiph.Org Foundation, Skype Limited
2    Written by Jean-Marc Valin and Koen Vos */
3 /*
4    Redistribution and use in source and binary forms, with or without
5    modification, are permitted provided that the following conditions
6    are met:
7
8    - Redistributions of source code must retain the above copyright
9    notice, this list of conditions and the following disclaimer.
10
11    - Redistributions in binary form must reproduce the above copyright
12    notice, this list of conditions and the following disclaimer in the
13    documentation and/or other materials provided with the distribution.
14
15    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
16    ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
17    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
18    A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
19    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
20    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
21    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
22    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
23    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
24    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26 */
27
28 /**
29  * @file opus.h
30  * @brief Opus reference implementation API
31  */
32
33 #ifndef OPUS_H
34 #define OPUS_H
35
36 #include "opus_types.h"
37 #include "opus_defines.h"
38
39 #ifdef __cplusplus
40 extern "C" {
41 #endif
42
43 /** @defgroup opusencoder Opus Encoder
44   * @{
45   */
46
47 /** Opus encoder state.
48   * This contains the complete state of an Opus encoder.
49   * It is position independent and can be freely copied.
50   * @see opus_encoder_create,opus_encoder_init
51   */
52 typedef struct OpusEncoder OpusEncoder;
53
54 OPUS_EXPORT int opus_encoder_get_size(int channels);
55
56 /**
57  */
58
59 /** Allocates and initializes an encoder state.
60  * There are three coding modes:
61  * OPUS_APPLICATION_VOIP gives best quality at a given bitrate for voice
62  *    signals. It enhances the  input signal by high-pass filtering and
63  *    emphasizing formants and harmonics. Optionally  it includes in-band
64  *    forward error correction to protect against packet loss. Use this
65  *    mode for typical VoIP applications. Because of the enhancement,
66  *    even at high bitrates the output may sound different from the input.
67  * OPUS_APPLICATION_AUDIO gives best quality at a given bitrate for most
68  *    non-voice signals like music. Use this mode for music and mixed
69  *    (music/voice) content, broadcast, and applications requiring less
70  *    than 15 ms of coding delay.
71  * OPUS_APPLICATION_RESTRICTED_LOWDELAY configures low-delay mode that
72  *    disables the speech-optimized mode in exchange for slightly reduced delay.
73  * This is useful when the caller knows that the speech-optimized modes will not be needed (use with caution).
74  * @param [in] Fs <tt>opus_int32</tt>: Sampling rate of input signal (Hz)
75  * @param [in] channels <tt>int</tt>: Number of channels (1/2) in input signal
76  * @param [in] application <tt>int</tt>: Coding mode (OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO/OPUS_APPLICATION_RESTRICTED_LOWDELAY)
77  * @param [out] error <tt>int*</tt>: Error code
78  */
79 OPUS_EXPORT OpusEncoder *opus_encoder_create(
80     opus_int32 Fs,
81     int channels,
82     int application,
83     int *error
84 );
85
86 /** Initializes a previously allocated encoder state
87   * The memory pointed to by st must be the size returned by opus_encoder_get_size.
88   * This is intended for applications which use their own allocator instead of malloc. @see opus_encoder_create,opus_encoder_get_size
89   * To reset a previously initialized state use the OPUS_RESET_STATE CTL.
90   * @param [in] st <tt>OpusEncoder*</tt>: Encoder state
91   * @param [in] Fs <tt>opus_int32</tt>: Sampling rate of input signal (Hz)
92   * @param [in] channels <tt>int</tt>: Number of channels (1/2) in input signal
93   * @param [in] application <tt>int</tt>: Coding mode (OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO/OPUS_APPLICATION_RESTRICTED_LOWDELAY)
94   * @retval OPUS_OK Success.
95   */
96 OPUS_EXPORT int opus_encoder_init(
97     OpusEncoder *st,
98     opus_int32 Fs,
99     int channels,
100     int application
101 );
102
103 /** Encodes an Opus frame.
104   * The passed frame_size must an opus frame size for the encoder's sampling rate.
105   * For example, at 48kHz the permitted values are 120, 240, 480, or 960.
106   * Passing in a duration of less than 10ms (480 samples at 48kHz) will
107   * prevent the encoder from using the LPC or hybrid modes.
108   * @param [in] st <tt>OpusEncoder*</tt>: Encoder state
109   * @param [in] pcm <tt>opus_int16*</tt>: Input signal (interleaved if 2 channels). length is frame_size*channels*sizeof(opus_int16)
110   * @param [in] frame_size <tt>int</tt>: Number of samples per frame of input signal
111   * @param [out] data <tt>char*</tt>: Output payload (at least max_data_bytes long)
112   * @param [in] max_data_bytes <tt>int</tt>: Allocated memory for payload; don't use for controlling bitrate
113   * @returns length of the data payload (in bytes)
114   */
115 OPUS_EXPORT int opus_encode(
116     OpusEncoder *st,
117     const opus_int16 *pcm,
118     int frame_size,
119     unsigned char *data,
120     int max_data_bytes
121 );
122
123 /** Encodes an Opus frame from floating point input.
124   * The passed frame_size must an opus frame size for the encoder's sampling rate.
125   * For example, at 48kHz the permitted values are 120, 240, 480, or 960.
126   * Passing in a duration of less than 10ms (480 samples at 48kHz) will
127   * prevent the encoder from using the LPC or hybrid modes.
128   * @param [in] st <tt>OpusEncoder*</tt>: Encoder state
129   * @param [in] pcm <tt>float*</tt>: Input signal (interleaved if 2 channels). length is frame_size*channels*sizeof(float)
130   * @param [in] frame_size <tt>int</tt>: Number of samples per frame of input signal
131   * @param [out] data <tt>char*</tt>: Output payload (at least max_data_bytes long)
132   * @param [in] max_data_bytes <tt>int</tt>: Allocated memory for payload; don't use for controlling bitrate
133   * @returns length of the data payload (in bytes)
134   */
135 OPUS_EXPORT int opus_encode_float(
136     OpusEncoder *st,
137     const float *pcm,
138     int frame_size,
139     unsigned char *data,
140     int max_data_bytes
141 );
142
143 /** Frees an OpusEncoder allocated by opus_encoder_create.
144   * @param[in] st <tt>OpusEncoder*</tt>: State to be freed.
145   */
146 OPUS_EXPORT void opus_encoder_destroy(OpusEncoder *st);
147
148 /** Perform a CTL function on an Opus encoder.
149   * @see encoderctls
150   */
151 OPUS_EXPORT int opus_encoder_ctl(OpusEncoder *st, int request, ...);
152 /**@}*/
153
154 /** @defgroup opusdecoder Opus Decoder
155   * @{
156   */
157
158 /** Opus decoder state.
159   * This contains the complete state of an Opus decoder.
160   * It is position independent and can be freely copied.
161   * @see opus_decoder_create,opus_decoder_init
162   */
163 typedef struct OpusDecoder OpusDecoder;
164
165 /** Gets the size of an OpusDecoder structure.
166   * @param [in] channels <tt>int</tt>: Number of channels
167   * @returns size
168   */
169 OPUS_EXPORT int opus_decoder_get_size(int channels);
170
171 /** Allocates and initializes a decoder state.
172   * @param [in] Fs <tt>opus_int32</tt>: Sampling rate of input signal (Hz)
173   * @param [in] channels <tt>int</tt>: Number of channels (1/2) in input signal
174   * @param [out] error <tt>int*</tt>: Error code
175   */
176 OPUS_EXPORT OpusDecoder *opus_decoder_create(
177     opus_int32 Fs,
178     int channels,
179     int *error
180 );
181
182 /** Initializes a previously allocated decoder state.
183   * The state must be the size returned by opus_decoder_get_size.
184   * This is intended for applications which use their own allocator instead of malloc. @see opus_decoder_create,opus_decoder_get_size
185   * To reset a previously initialized state use the OPUS_RESET_STATE CTL.
186   * @param [in] st <tt>OpusDecoder*</tt>: Decoder state.
187   * @param [in] Fs <tt>opus_int32</tt>: Sampling rate of input signal (Hz)
188   * @param [in] channels <tt>int</tt>: Number of channels (1/2) in input signal
189   * @retval OPUS_OK Success.
190   */
191 OPUS_EXPORT int opus_decoder_init(
192     OpusDecoder *st,
193     opus_int32 Fs,
194     int channels
195 );
196
197 /** Decode an Opus frame
198   * @param [in] st <tt>OpusDecoder*</tt>: Decoder state
199   * @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to indicate packet loss
200   * @param [in] len <tt>int</tt>: Number of bytes in payload*
201   * @param [out] pcm <tt>opus_int16*</tt>: Output signal (interleaved if 2 channels). length
202   *  is frame_size*channels*sizeof(opus_int16)
203   * @param [in] frame_size Number of samples per channel of available space in *pcm,
204   *  if less than the maximum frame size (120ms) some frames can not be decoded
205   * @param [in] decode_fec <tt>int</tt>: Flag (0/1) to request that any in-band forward error correction data be
206   *  decoded. If no such data is available the frame is decoded as if it were lost.
207   * @returns Number of decoded samples
208   */
209 OPUS_EXPORT int opus_decode(
210     OpusDecoder *st,
211     const unsigned char *data,
212     int len,
213     opus_int16 *pcm,
214     int frame_size,
215     int decode_fec
216 );
217
218 /** Decode an opus frame with floating point output
219   * @param [in] st <tt>OpusDecoder*</tt>: Decoder state
220   * @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to indicate packet loss
221   * @param [in] len <tt>int</tt>: Number of bytes in payload
222   * @param [out] pcm <tt>float*</tt>: Output signal (interleaved if 2 channels). length
223   *  is frame_size*channels*sizeof(float)
224   * @param [in] frame_size Number of samples per channel of available space in *pcm,
225   *  if less than the maximum frame size (120ms) some frames can not be decoded
226   * @param [in] decode_fec <tt>int</tt>: Flag (0/1) to request that any in-band forward error correction data be
227   *  decoded. If no such data is available the frame is decoded as if it were lost.
228   * @returns Number of decoded samples
229   */
230 OPUS_EXPORT int opus_decode_float(
231     OpusDecoder *st,
232     const unsigned char *data,
233     int len,
234     float *pcm,
235     int frame_size,
236     int decode_fec
237 );
238
239 /** Perform a CTL function on an Opus decoder.
240   * @see decoderctls
241   */
242 OPUS_EXPORT int opus_decoder_ctl(OpusDecoder *st, int request, ...);
243
244 /** Frees an OpusDecoder allocated by opus_decoder_create.
245   * @param[in] st <tt>OpusDecoder*</tt>: State to be freed.
246   */
247 OPUS_EXPORT void opus_decoder_destroy(OpusDecoder *st);
248
249 /** Parse an opus packet into one or more frames.
250   * Opus_decode will perform this operation internally so most applications do
251   * not need to use this function.
252   * This function does not copy the frames, the returned pointers are pointers into
253   * the input packet.
254   * @param [in] data <tt>char*</tt>: Opus packet to be parsed
255   * @param [in] len <tt>int</tt>: size of data
256   * @param [out] out_toc <tt>char*</tt>: TOC pointer
257   * @param [out] frames <tt>char*[48]</tt> encapsulated frames
258   * @param [out] size <tt>short[48]</tt> sizes of the encapsulated frames
259   * @param [out] payload_offset <tt>int*</tt>: @todo bloop?
260   * @returns number of frames
261   */
262 OPUS_EXPORT int opus_packet_parse(
263    const unsigned char *data,
264    int len,
265    unsigned char *out_toc,
266    const unsigned char *frames[48],
267    short size[48],
268    int *payload_offset
269 );
270
271 /** Gets the bandwidth of an Opus packet.
272   * @param [in] data <tt>char*</tt>: Opus packet
273   * @retval OPUS_BANDWIDTH_NARROWBAND Narrowband (4kHz bandpass)
274   * @retval OPUS_BANDWIDTH_MEDIUMBAND Mediumband (6kHz bandpass)
275   * @retval OPUS_BANDWIDTH_WIDEBAND Wideband (8kHz bandpass)
276   * @retval OPUS_BANDWIDTH_SUPERWIDEBAND Superwideband (12kHz bandpass)
277   * @retval OPUS_BANDWIDTH_FULLBAND Fullband (20kHz bandpass)
278   * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type
279   */
280 OPUS_EXPORT int opus_packet_get_bandwidth(const unsigned char *data);
281
282 /** Gets the number of samples per frame from an Opus packet.
283   * @param [in] data <tt>char*</tt>: Opus packet
284   * @param [in] Fs <tt>opus_int32</tt>: Sampling rate in Hz
285   * @returns Number of samples per frame
286   * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type
287   */
288 OPUS_EXPORT int opus_packet_get_samples_per_frame(const unsigned char *data, opus_int32 Fs);
289
290 /** Gets the number of channels from an Opus packet.
291   * @param [in] data <tt>char*</tt>: Opus packet
292   * @returns Number of channels
293   * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type
294   */
295 OPUS_EXPORT int opus_packet_get_nb_channels(const unsigned char *data);
296
297 /** Gets the number of frame in an Opus packet.
298   * @param [in] packet <tt>char*</tt>: Opus packet
299   * @param [in] len <tt>int</tt>: Length of packet
300   * @returns Number of frames
301   * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type
302   */
303 OPUS_EXPORT int opus_packet_get_nb_frames(const unsigned char packet[], int len);
304
305 /** Gets the number of samples of an Opus packet.
306   * @param [in] dec <tt>OpusDecoder*</tt>: Decoder state
307   * @param [in] packet <tt>char*</tt>: Opus packet
308   * @param [in] len <tt>int</tt>: Length of packet
309   * @returns Number of samples
310   * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type
311   */
312 OPUS_EXPORT int opus_decoder_get_nb_samples(const OpusDecoder *dec, const unsigned char packet[], int len);
313 /**@}*/
314
315 /** @defgroup repacketizer Repacketizer
316   * @{
317   */
318
319 typedef struct OpusRepacketizer OpusRepacketizer;
320
321 OPUS_EXPORT int opus_repacketizer_get_size(void);
322
323 OPUS_EXPORT OpusRepacketizer *opus_repacketizer_init(OpusRepacketizer *rp);
324
325 OPUS_EXPORT OpusRepacketizer *opus_repacketizer_create(void);
326
327 OPUS_EXPORT void opus_repacketizer_destroy(OpusRepacketizer *rp);
328
329 OPUS_EXPORT int opus_repacketizer_cat(OpusRepacketizer *rp, const unsigned char *data, int len);
330
331 OPUS_EXPORT int opus_repacketizer_out_range(OpusRepacketizer *rp, int begin, int end, unsigned char *data, int maxlen);
332
333 OPUS_EXPORT int opus_repacketizer_get_nb_frames(OpusRepacketizer *rp);
334
335 OPUS_EXPORT int opus_repacketizer_out(OpusRepacketizer *rp, unsigned char *data, int maxlen);
336
337 /**@}*/
338
339 #ifdef __cplusplus
340 }
341 #endif
342
343 #endif /* OPUS_H */