Make repacketizer API use opus_int32 for lengths and add some additional error handling.
[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 /**
44  * @mainpage Opus
45  *
46  * The Opus codec is designed for interactive speech and audio transmission over the Internet.
47  * It is designed by the IETF Codec Working Group and incorporates technology from
48  * Skype's SILK codec and Xiph.Org's CELT codec.
49  *
50  * The Opus codec is designed to handle a wide range of interactive audio applications,
51  * including Voice over IP, videoconferencing, in-game chat, and even remote live music
52  * performances. It can scale from low bit-rate narrowband speech to very high quality
53  * stereo music. Its main features are:
54
55  * @li Sampling rates from 8 to 48 kHz
56  * @li Bit-rates from 6 kb/s 510 kb/s
57  * @li Support for both constant bit-rate (CBR) and variable bit-rate (VBR)
58  * @li Audio bandwidth from narrowband to full-band
59  * @li Support for speech and music
60  * @li Support for mono and stereo
61  * @li Frame sizes from 2.5 ms to 60 ms
62  * @li Good loss robustness and packet loss concealment (PLC)
63  * @li Floating point and fixed-point implementation
64  *
65  * Documentation sections:
66  * @li @ref opusencoder
67  * @li @ref opusdecoder
68  * @li @ref repacketizer
69  * @li @ref libinfo
70  */
71
72 /** @defgroup opusencoder Opus Encoder
73   * @{
74   *
75   * Since Opus is a stateful codec, the encoding process starts with creating an encoder
76   * state. This can be done with:
77   *
78   * @code
79   * int          error;
80   * OpusEncoder *enc;
81   * enc = opus_encoder_create(Fs, channels, application, &error);
82   * @endcode
83   *
84   * From this point, @c enc can be used for encoding an audio stream. An encoder state
85   * @b must @b not be used for more than one stream at the same time. Similarly, the encoder
86   * state @b must @b not be re-initialized for each frame.
87   *
88   * While opus_encoder_create() allocates memory for the state, it's also possible
89   * to initialize pre-allocated memory:
90   *
91   * @code
92   * int          size;
93   * int          error;
94   * OpusEncoder *enc;
95   * size = opus_encoder_get_size(channels);
96   * enc = malloc(size);
97   * error = opus_encoder_init(enc, Fs, channels, application);
98   * @endcode
99   *
100   * where opus_encoder_get_size() returns the required size for the encoder state. Note that
101   * future versions of this code may change the size, so no assuptions should be made about it.
102   *
103   * The encoder state is always continuous in memory and only a shallow copy is sufficient
104   * to copy it (e.g. memcpy())
105   *
106   * It is possible to change some of the encoder's settings using the opus_encoder_ctl()
107   * interface. All these settings already default to the recommended value, so they should
108   * only be changed when necessary. The most common settings one may want to change are:
109   *
110   * @code
111   * opus_encoder_ctl(enc, OPUS_SET_BITRATE(bitrate));
112   * opus_encoder_ctl(enc, OPUS_SET_COMPLEXITY(complexity));
113   * opus_encoder_ctl(enc, OPUS_SET_SIGNAL(signal_type));
114   * @endcode
115   *
116   * where
117   *
118   * @arg bitrate is in bits per second (b/s)
119   * @arg complexity is a value from 1 to 10, where 1 is the lowest complexity and 10 is the highest
120   * @arg signal_type is either OPUS_AUTO (default), OPUS_SIGNAL_VOICE, or OPUS_SIGNAL_MUSIC
121   *
122   * See @ref encoderctls and @ref genericctls for a complete list of parameters that can be set or queried. Most parameters can be set or changed at any time during a stream.
123   *
124   * To encode a frame, opus_encode() or opus_encode_float() must be called with exactly one frame (2.5, 5, 10, 20, 40 or 60 ms) of audio data:
125   * @code
126   * len = opus_encode(enc, audio_frame, frame_size, packet, max_packet);
127   * @endcode
128   *
129   * where
130   * <ul>
131   * <li>audio_frame is the audio data in opus_int16 (or float for opus_encode_float())</li>
132   * <li>frame_size is the duration of the frame in samples (per channel)</li>
133   * <li>packet is the byte array to which the compressed data is written</li>
134   * <li>max_packet is the maximum number of bytes that can be written in the packet (1276 bytes is recommended)</li>
135   * </ul>
136   *
137   * opus_encode() and opus_encode_frame() return the number of bytes actually written to the packet.
138   * The return value <b>can be negative</b>, which indicates that an error has occurred. If the return value
139   * is 1 byte, then the packet does not need to be transmitted (DTX).
140   *
141   * Once the encoder state if no longer needed, it can be destroyed with
142   *
143   * @code
144   * opus_encoder_destroy(enc);
145   * @endcode
146   *
147   * If the encoder was created with opus_encoder_init() rather than opus_encoder_create(),
148   * then no action is required aside from potentially freeing the memory that was manually
149   * allocated for it (calling free(enc) for the example above)
150   *
151   */
152
153 /** Opus encoder state.
154   * This contains the complete state of an Opus encoder.
155   * It is position independent and can be freely copied.
156   * @see opus_encoder_create,opus_encoder_init
157   */
158 typedef struct OpusEncoder OpusEncoder;
159
160 OPUS_EXPORT int opus_encoder_get_size(int channels);
161
162 /**
163  */
164
165 /** Allocates and initializes an encoder state.
166  * There are three coding modes:
167  *
168  * @ref OPUS_APPLICATION_VOIP gives best quality at a given bitrate for voice
169  *    signals. It enhances the  input signal by high-pass filtering and
170  *    emphasizing formants and harmonics. Optionally  it includes in-band
171  *    forward error correction to protect against packet loss. Use this
172  *    mode for typical VoIP applications. Because of the enhancement,
173  *    even at high bitrates the output may sound different from the input.
174  *
175  * @ref OPUS_APPLICATION_AUDIO gives best quality at a given bitrate for most
176  *    non-voice signals like music. Use this mode for music and mixed
177  *    (music/voice) content, broadcast, and applications requiring less
178  *    than 15 ms of coding delay.
179  *
180  * @ref OPUS_APPLICATION_RESTRICTED_LOWDELAY configures low-delay mode that
181  *    disables the speech-optimized mode in exchange for slightly reduced delay.
182  *
183  * This is useful when the caller knows that the speech-optimized modes will not be needed (use with caution).
184  * @param [in] Fs <tt>opus_int32</tt>: Sampling rate of input signal (Hz)
185  * @param [in] channels <tt>int</tt>: Number of channels (1/2) in input signal
186  * @param [in] application <tt>int</tt>: Coding mode (@ref OPUS_APPLICATION_VOIP/@ref OPUS_APPLICATION_AUDIO/@ref OPUS_APPLICATION_RESTRICTED_LOWDELAY)
187  * @param [out] error <tt>int*</tt>: @ref errorcodes
188  * @note Regardless of the sampling rate and number channels selected, the Opus encoder
189  * can switch to a lower audio audio bandwidth or number of channels if the bitrate
190  * selected is too low. This also means that it is safe to always use 48 kHz stereo input
191  * and let the encoder optimize the encoding.
192  */
193 OPUS_EXPORT OpusEncoder *opus_encoder_create(
194     opus_int32 Fs,
195     int channels,
196     int application,
197     int *error
198 );
199
200 /** Initializes a previously allocated encoder state
201   * The memory pointed to by st must be the size returned by opus_encoder_get_size.
202   * This is intended for applications which use their own allocator instead of malloc.
203   * @see opus_encoder_create(),opus_encoder_get_size()
204   * To reset a previously initialized state use the OPUS_RESET_STATE CTL.
205   * @param [in] st <tt>OpusEncoder*</tt>: Encoder state
206   * @param [in] Fs <tt>opus_int32</tt>: Sampling rate of input signal (Hz)
207   * @param [in] channels <tt>int</tt>: Number of channels (1/2) in input signal
208   * @param [in] application <tt>int</tt>: Coding mode (OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO/OPUS_APPLICATION_RESTRICTED_LOWDELAY)
209   * @retval OPUS_OK Success or @ref errorcodes
210   */
211 OPUS_EXPORT int opus_encoder_init(
212     OpusEncoder *st,
213     opus_int32 Fs,
214     int channels,
215     int application
216 );
217
218 /** Encodes an Opus frame.
219   * The passed frame_size must an opus frame size for the encoder's sampling rate.
220   * For example, at 48kHz the permitted values are 120, 240, 480, or 960.
221   * Passing in a duration of less than 10ms (480 samples at 48kHz) will
222   * prevent the encoder from using the LPC or hybrid modes.
223   * @param [in] st <tt>OpusEncoder*</tt>: Encoder state
224   * @param [in] pcm <tt>opus_int16*</tt>: Input signal (interleaved if 2 channels). length is frame_size*channels*sizeof(opus_int16)
225   * @param [in] frame_size <tt>int</tt>: Number of samples per frame of input signal
226   * @param [out] data <tt>char*</tt>: Output payload (at least max_data_bytes long)
227   * @param [in] max_data_bytes <tt>int</tt>: Allocated memory for payload; don't use for controlling bitrate
228   * @returns length of the data payload (in bytes) or @ref errorcodes
229   */
230 OPUS_EXPORT int opus_encode(
231     OpusEncoder *st,
232     const opus_int16 *pcm,
233     int frame_size,
234     unsigned char *data,
235     int max_data_bytes
236 );
237
238 /** Encodes an Opus frame from floating point input.
239   * The passed frame_size must an opus frame size for the encoder's sampling rate.
240   * For example, at 48kHz the permitted values are 120, 240, 480, or 960.
241   * Passing in a duration of less than 10ms (480 samples at 48kHz) will
242   * prevent the encoder from using the LPC or hybrid modes.
243   * @param [in] st <tt>OpusEncoder*</tt>: Encoder state
244   * @param [in] pcm <tt>float*</tt>: Input signal (interleaved if 2 channels). length is frame_size*channels*sizeof(float)
245   * @param [in] frame_size <tt>int</tt>: Number of samples per frame of input signal
246   * @param [out] data <tt>char*</tt>: Output payload (at least max_data_bytes long)
247   * @param [in] max_data_bytes <tt>int</tt>: Allocated memory for payload; don't use for controlling bitrate
248   * @returns length of the data payload (in bytes) or @ref errorcodes
249   */
250 OPUS_EXPORT int opus_encode_float(
251     OpusEncoder *st,
252     const float *pcm,
253     int frame_size,
254     unsigned char *data,
255     int max_data_bytes
256 );
257
258 /** Frees an OpusEncoder allocated by opus_encoder_create.
259   * @param[in] st <tt>OpusEncoder*</tt>: State to be freed.
260   */
261 OPUS_EXPORT void opus_encoder_destroy(OpusEncoder *st);
262
263 /** Perform a CTL function on an Opus encoder.
264   * @see encoderctls
265   */
266 OPUS_EXPORT int opus_encoder_ctl(OpusEncoder *st, int request, ...);
267 /**@}*/
268
269 /** @defgroup opusdecoder Opus Decoder
270   * @{
271   *
272   *
273   * The decoding process also starts with creating a decoder
274   * state. This can be done with:
275   * @code
276   * int          error;
277   * OpusDecoder *dec;
278   * dec = opus_decoder_create(Fs, channels, &error);
279   * @endcode
280   * where
281   * @li Fs is the sampling rate and must be 8000, 12000, 16000, 24000, or 48000
282   * @li channels is the number of channels (1 or 2)
283   * @li error will hold the error code in case or failure (or OPUS_OK on success)
284   * @li the return value is a newly created decoder state to be used for decoding
285   *
286   * While opus_decoder_create() allocates memory for the state, it's also possible
287   * to initialize pre-allocated memory:
288   * @code
289   * int          size;
290   * int          error;
291   * OpusDecoder *dec;
292   * size = opus_decoder_get_size(channels);
293   * dec = malloc(size);
294   * error = opus_decoder_init(dec, Fs, channels);
295   * @endcode
296   * where opus_decoder_get_size() returns the required size for the decoder state. Note that
297   * future versions of this code may change the size, so no assuptions should be made about it.
298   *
299   * The decoder state is always continuous in memory and only a shallow copy is sufficient
300   * to copy it (e.g. memcpy())
301   *
302   * To decode a frame, opus_decode() or opus_decode_float() must be called with a packet of compressed audio data:
303   * @code
304   * frame_size = opus_decode(enc, packet, len, decoded, max_size);
305   * @endcode
306   * where
307   *
308   * @li packet is the byte array containing the compressed data
309   * @li len is the exact number of bytes contained in the packet
310   * @li decoded is the decoded audio data in opus_int16 (or float for opus_decode_float())
311   * @li max_size is the max duration of the frame in samples (per channel) that can fit into the decoded_frame array
312   *
313   * opus_decode() and opus_decode_frame() return the number of samples ()per channel) decoded from the packet.
314   * If that value is negative, then an error has occured. This can occur if the packet is corrupted or if the audio
315   * buffer is too small to hold the decoded audio.
316
317 */
318
319 /** Opus decoder state.
320   * This contains the complete state of an Opus decoder.
321   * It is position independent and can be freely copied.
322   * @see opus_decoder_create,opus_decoder_init
323   */
324 typedef struct OpusDecoder OpusDecoder;
325
326 /** Gets the size of an OpusDecoder structure.
327   * @param [in] channels <tt>int</tt>: Number of channels
328   * @returns size
329   */
330 OPUS_EXPORT int opus_decoder_get_size(int channels);
331
332 /** Allocates and initializes a decoder state.
333   * @param [in] Fs <tt>opus_int32</tt>: Sampling rate of input signal (Hz)
334   * @param [in] channels <tt>int</tt>: Number of channels (1/2) in input signal
335   * @param [out] error <tt>int*</tt>: OPUS_OK Success or @ref errorcodes
336   */
337 OPUS_EXPORT OpusDecoder *opus_decoder_create(
338     opus_int32 Fs,
339     int channels,
340     int *error
341 );
342
343 /** Initializes a previously allocated decoder state.
344   * The state must be the size returned by opus_decoder_get_size.
345   * This is intended for applications which use their own allocator instead of malloc. @see opus_decoder_create,opus_decoder_get_size
346   * To reset a previously initialized state use the OPUS_RESET_STATE CTL.
347   * @param [in] st <tt>OpusDecoder*</tt>: Decoder state.
348   * @param [in] Fs <tt>opus_int32</tt>: Sampling rate of input signal (Hz)
349   * @param [in] channels <tt>int</tt>: Number of channels (1/2) in input signal
350   * @retval OPUS_OK Success or @ref errorcodes
351   */
352 OPUS_EXPORT int opus_decoder_init(
353     OpusDecoder *st,
354     opus_int32 Fs,
355     int channels
356 );
357
358 /** Decode an Opus frame
359   * @param [in] st <tt>OpusDecoder*</tt>: Decoder state
360   * @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to indicate packet loss
361   * @param [in] len <tt>int</tt>: Number of bytes in payload*
362   * @param [out] pcm <tt>opus_int16*</tt>: Output signal (interleaved if 2 channels). length
363   *  is frame_size*channels*sizeof(opus_int16)
364   * @param [in] frame_size Number of samples per channel of available space in *pcm,
365   *  if less than the maximum frame size (120ms) some frames can not be decoded
366   * @param [in] decode_fec <tt>int</tt>: Flag (0/1) to request that any in-band forward error correction data be
367   *  decoded. If no such data is available the frame is decoded as if it were lost.
368   * @returns Number of decoded samples or @ref errorcodes
369   */
370 OPUS_EXPORT int opus_decode(
371     OpusDecoder *st,
372     const unsigned char *data,
373     int len,
374     opus_int16 *pcm,
375     int frame_size,
376     int decode_fec
377 );
378
379 /** Decode an opus frame with floating point output
380   * @param [in] st <tt>OpusDecoder*</tt>: Decoder state
381   * @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to indicate packet loss
382   * @param [in] len <tt>int</tt>: Number of bytes in payload
383   * @param [out] pcm <tt>float*</tt>: Output signal (interleaved if 2 channels). length
384   *  is frame_size*channels*sizeof(float)
385   * @param [in] frame_size Number of samples per channel of available space in *pcm,
386   *  if less than the maximum frame size (120ms) some frames can not be decoded
387   * @param [in] decode_fec <tt>int</tt>: Flag (0/1) to request that any in-band forward error correction data be
388   *  decoded. If no such data is available the frame is decoded as if it were lost.
389   * @returns Number of decoded samples or @ref errorcodes
390   */
391 OPUS_EXPORT int opus_decode_float(
392     OpusDecoder *st,
393     const unsigned char *data,
394     int len,
395     float *pcm,
396     int frame_size,
397     int decode_fec
398 );
399
400 /** Perform a CTL function on an Opus decoder.
401   * @see decoderctls
402   */
403 OPUS_EXPORT int opus_decoder_ctl(OpusDecoder *st, int request, ...);
404
405 /** Frees an OpusDecoder allocated by opus_decoder_create.
406   * @param[in] st <tt>OpusDecoder*</tt>: State to be freed.
407   */
408 OPUS_EXPORT void opus_decoder_destroy(OpusDecoder *st);
409
410 /** Parse an opus packet into one or more frames.
411   * Opus_decode will perform this operation internally so most applications do
412   * not need to use this function.
413   * This function does not copy the frames, the returned pointers are pointers into
414   * the input packet.
415   * @param [in] data <tt>char*</tt>: Opus packet to be parsed
416   * @param [in] len <tt>int</tt>: size of data
417   * @param [out] out_toc <tt>char*</tt>: TOC pointer
418   * @param [out] frames <tt>char*[48]</tt> encapsulated frames
419   * @param [out] size <tt>short[48]</tt> sizes of the encapsulated frames
420   * @param [out] payload_offset <tt>int*</tt>: returns the position of the payload within the packet (in bytes)
421   * @returns number of frames
422   */
423 OPUS_EXPORT int opus_packet_parse(
424    const unsigned char *data,
425    int len,
426    unsigned char *out_toc,
427    const unsigned char *frames[48],
428    short size[48],
429    int *payload_offset
430 );
431
432 /** Gets the bandwidth of an Opus packet.
433   * @param [in] data <tt>char*</tt>: Opus packet
434   * @retval OPUS_BANDWIDTH_NARROWBAND Narrowband (4kHz bandpass)
435   * @retval OPUS_BANDWIDTH_MEDIUMBAND Mediumband (6kHz bandpass)
436   * @retval OPUS_BANDWIDTH_WIDEBAND Wideband (8kHz bandpass)
437   * @retval OPUS_BANDWIDTH_SUPERWIDEBAND Superwideband (12kHz bandpass)
438   * @retval OPUS_BANDWIDTH_FULLBAND Fullband (20kHz bandpass)
439   * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type
440   */
441 OPUS_EXPORT int opus_packet_get_bandwidth(const unsigned char *data);
442
443 /** Gets the number of samples per frame from an Opus packet.
444   * @param [in] data <tt>char*</tt>: Opus packet
445   * @param [in] Fs <tt>opus_int32</tt>: Sampling rate in Hz
446   * @returns Number of samples per frame
447   * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type
448   */
449 OPUS_EXPORT int opus_packet_get_samples_per_frame(const unsigned char *data, opus_int32 Fs);
450
451 /** Gets the number of channels from an Opus packet.
452   * @param [in] data <tt>char*</tt>: Opus packet
453   * @returns Number of channels
454   * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type
455   */
456 OPUS_EXPORT int opus_packet_get_nb_channels(const unsigned char *data);
457
458 /** Gets the number of frame in an Opus packet.
459   * @param [in] packet <tt>char*</tt>: Opus packet
460   * @param [in] len <tt>int</tt>: Length of packet
461   * @returns Number of frames
462   * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type
463   */
464 OPUS_EXPORT int opus_packet_get_nb_frames(const unsigned char packet[], int len);
465
466 /** Gets the number of samples of an Opus packet.
467   * @param [in] dec <tt>OpusDecoder*</tt>: Decoder state
468   * @param [in] packet <tt>char*</tt>: Opus packet
469   * @param [in] len <tt>int</tt>: Length of packet
470   * @returns Number of samples
471   * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type
472   */
473 OPUS_EXPORT int opus_decoder_get_nb_samples(const OpusDecoder *dec, const unsigned char packet[], int len);
474 /**@}*/
475
476 /** @defgroup repacketizer Repacketizer
477   * @{
478   *
479   * The repacketizer can be used to merge multiple Opus packets into a single packet
480   * or alternatively to split Opus packets that have previously been merged.
481   *
482   */
483
484 typedef struct OpusRepacketizer OpusRepacketizer;
485
486 OPUS_EXPORT int opus_repacketizer_get_size(void);
487
488 OPUS_EXPORT OpusRepacketizer *opus_repacketizer_init(OpusRepacketizer *rp);
489
490 OPUS_EXPORT OpusRepacketizer *opus_repacketizer_create(void);
491
492 OPUS_EXPORT void opus_repacketizer_destroy(OpusRepacketizer *rp);
493
494 OPUS_EXPORT int opus_repacketizer_cat(OpusRepacketizer *rp, const unsigned char *data, int len);
495
496 OPUS_EXPORT opus_int32 opus_repacketizer_out_range(OpusRepacketizer *rp, int begin, int end, unsigned char *data, int maxlen);
497
498 OPUS_EXPORT int opus_repacketizer_get_nb_frames(OpusRepacketizer *rp);
499
500 OPUS_EXPORT opus_int32 opus_repacketizer_out(OpusRepacketizer *rp, unsigned char *data, int maxlen);
501
502 /**@}*/
503
504 #ifdef __cplusplus
505 }
506 #endif
507
508 #endif /* OPUS_H */