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 COPYRIGHT OWNER
19 OR 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
40extern "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 to 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 Support for multichannel (up to 255 channels)
62 * @li Frame sizes from 2.5 ms to 60 ms
63 * @li Good loss robustness and packet loss concealment (PLC)
64 * @li Floating point and fixed-point implementation
65 *
66 * Documentation sections:
67 * @li @ref opus_encoder
68 * @li @ref opus_decoder
69 * @li @ref opus_repacketizer
70 * @li @ref opus_multistream
71 * @li @ref opus_libinfo
72 * @li @ref opus_custom
73 */
74
75/** @defgroup opus_encoder Opus Encoder
76 * @{
77 *
78 * @brief This page describes the process and functions used to encode Opus.
79 *
80 * Since Opus is a stateful codec, the encoding process starts with creating an encoder
81 * state. This can be done with:
82 *
83 * @code
84 * int error;
85 * OpusEncoder *enc;
86 * enc = opus_encoder_create(Fs, channels, application, &error);
87 * @endcode
88 *
89 * From this point, @c enc can be used for encoding an audio stream. An encoder state
90 * @b must @b not be used for more than one stream at the same time. Similarly, the encoder
91 * state @b must @b not be re-initialized for each frame.
92 *
93 * While opus_encoder_create() allocates memory for the state, it's also possible
94 * to initialize pre-allocated memory:
95 *
96 * @code
97 * int size;
98 * int error;
99 * OpusEncoder *enc;
100 * size = opus_encoder_get_size(channels);
101 * enc = malloc(size);
102 * error = opus_encoder_init(enc, Fs, channels, application);
103 * @endcode
104 *
105 * where opus_encoder_get_size() returns the required size for the encoder state. Note that
106 * future versions of this code may change the size, so no assumptions should be made about it.
107 *
108 * The encoder state is always continuous in memory and only a shallow copy is sufficient
109 * to copy it (e.g. memcpy())
110 *
111 * It is possible to change some of the encoder's settings using the opus_encoder_ctl()
112 * interface. All these settings already default to the recommended value, so they should
113 * only be changed when necessary. The most common settings one may want to change are:
114 *
115 * @code
116 * opus_encoder_ctl(enc, OPUS_SET_BITRATE(bitrate));
117 * opus_encoder_ctl(enc, OPUS_SET_COMPLEXITY(complexity));
118 * opus_encoder_ctl(enc, OPUS_SET_SIGNAL(signal_type));
119 * @endcode
120 *
121 * where
122 *
123 * @arg bitrate is in bits per second (b/s)
124 * @arg complexity is a value from 1 to 10, where 1 is the lowest complexity and 10 is the highest
125 * @arg signal_type is either OPUS_AUTO (default), OPUS_SIGNAL_VOICE, or OPUS_SIGNAL_MUSIC
126 *
127 * See @ref opus_encoderctls and @ref opus_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.
128 *
129 * 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:
130 * @code
131 * len = opus_encode(enc, audio_frame, frame_size, packet, max_packet);
132 * @endcode
133 *
134 * where
135 * <ul>
136 * <li>audio_frame is the audio data in opus_int16 (or float for opus_encode_float())</li>
137 * <li>frame_size is the duration of the frame in samples (per channel)</li>
138 * <li>packet is the byte array to which the compressed data is written</li>
139 * <li>max_packet is the maximum number of bytes that can be written in the packet (4000 bytes is recommended).
140 * Do not use max_packet to control VBR target bitrate, instead use the #OPUS_SET_BITRATE CTL.</li>
141 * </ul>
142 *
143 * opus_encode() and opus_encode_float() return the number of bytes actually written to the packet.
144 * The return value <b>can be negative</b>, which indicates that an error has occurred. If the return value
145 * is 2 bytes or less, then the packet does not need to be transmitted (DTX).
146 *
147 * Once the encoder state if no longer needed, it can be destroyed with
148 *
149 * @code
150 * opus_encoder_destroy(enc);
151 * @endcode
152 *
153 * If the encoder was created with opus_encoder_init() rather than opus_encoder_create(),
154 * then no action is required aside from potentially freeing the memory that was manually
155 * allocated for it (calling free(enc) for the example above)
156 *
157 */
158
159/** Opus encoder state.
160 * This contains the complete state of an Opus encoder.
161 * It is position independent and can be freely copied.
162 * @see opus_encoder_create,opus_encoder_init
163 */
164typedef struct OpusEncoder OpusEncoder;
165
166/** Gets the size of an <code>OpusEncoder</code> structure.
167 * @param[in] channels <tt>int</tt>: Number of channels.
168 * This must be 1 or 2.
169 * @returns The size in bytes.
170 * @note Since this function does not take the application as input, it will overestimate
171 * the size required for OPUS_APPLICATION_RESTRICTED_SILK and OPUS_APPLICATION_RESTRICTED_CELT.
172 * That is generally not a problem, except when trying to know the size to use for a copy.
173 */
174OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_encoder_get_size(int channels);
175
176/**
177 */
178
179/** Allocates and initializes an encoder state.
180 * There are three coding modes:
181 *
182 * @ref OPUS_APPLICATION_VOIP gives best quality at a given bitrate for voice
183 * signals. It enhances the input signal by high-pass filtering and
184 * emphasizing formants and harmonics. Optionally it includes in-band
185 * forward error correction to protect against packet loss. Use this
186 * mode for typical VoIP applications. Because of the enhancement,
187 * even at high bitrates the output may sound different from the input.
188 *
189 * @ref OPUS_APPLICATION_AUDIO gives best quality at a given bitrate for most
190 * non-voice signals like music. Use this mode for music and mixed
191 * (music/voice) content, broadcast, and applications requiring less
192 * than 15 ms of coding delay.
193 *
194 * @ref OPUS_APPLICATION_RESTRICTED_LOWDELAY configures low-delay mode that
195 * disables the speech-optimized mode in exchange for slightly reduced delay.
196 * This mode can only be set on an newly initialized or freshly reset encoder
197 * because it changes the codec delay.
198 *
199 * This is useful when the caller knows that the speech-optimized modes will not be needed (use with caution).
200 * @param [in] Fs <tt>opus_int32</tt>: Sampling rate of input signal (Hz)
201 * This must be one of 8000, 12000, 16000,
202 * 24000, or 48000.
203 * @param [in] channels <tt>int</tt>: Number of channels (1 or 2) in input signal
204 * @param [in] application <tt>int</tt>: Coding mode (one of @ref OPUS_APPLICATION_VOIP, @ref OPUS_APPLICATION_AUDIO, or @ref OPUS_APPLICATION_RESTRICTED_LOWDELAY)
205 * @param [out] error <tt>int*</tt>: @ref opus_errorcodes
206 * @note Regardless of the sampling rate and number channels selected, the Opus encoder
207 * can switch to a lower audio bandwidth or number of channels if the bitrate
208 * selected is too low. This also means that it is safe to always use 48 kHz stereo input
209 * and let the encoder optimize the encoding.
210 */
211OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusEncoder *opus_encoder_create(
212 opus_int32 Fs,
213 int channels,
214 int application,
215 int *error
216);
217
218/** Initializes a previously allocated encoder state
219 * The memory pointed to by st must be at least the size returned by opus_encoder_get_size().
220 * This is intended for applications which use their own allocator instead of malloc.
221 * @see opus_encoder_create(),opus_encoder_get_size()
222 * To reset a previously initialized state, use the #OPUS_RESET_STATE CTL.
223 * @param [in] st <tt>OpusEncoder*</tt>: Encoder state
224 * @param [in] Fs <tt>opus_int32</tt>: Sampling rate of input signal (Hz)
225 * This must be one of 8000, 12000, 16000,
226 * 24000, or 48000.
227 * @param [in] channels <tt>int</tt>: Number of channels (1 or 2) in input signal
228 * @param [in] application <tt>int</tt>: Coding mode (one of OPUS_APPLICATION_VOIP, OPUS_APPLICATION_AUDIO, or OPUS_APPLICATION_RESTRICTED_LOWDELAY)
229 * @retval #OPUS_OK Success or @ref opus_errorcodes
230 */
231OPUS_EXPORT int opus_encoder_init(
232 OpusEncoder *st,
233 opus_int32 Fs,
234 int channels,
235 int application
236) OPUS_ARG_NONNULL(1);
237
238/** Encodes an Opus frame.
239 * @param [in] st <tt>OpusEncoder*</tt>: Encoder state
240 * @param [in] pcm <tt>opus_int16*</tt>: Input signal (interleaved if 2 channels). length is frame_size*channels*sizeof(opus_int16)
241 * @param [in] frame_size <tt>int</tt>: Number of samples per channel in the
242 * input signal.
243 * This must be an Opus frame size for
244 * the encoder's sampling rate.
245 * For example, at 48 kHz the permitted
246 * values are 120, 240, 480, 960, 1920,
247 * and 2880.
248 * Passing in a duration of less than
249 * 10 ms (480 samples at 48 kHz) will
250 * prevent the encoder from using the LPC
251 * or hybrid modes.
252 * @param [out] data <tt>unsigned char*</tt>: Output payload.
253 * This must contain storage for at
254 * least \a max_data_bytes.
255 * @param [in] max_data_bytes <tt>opus_int32</tt>: Size of the allocated
256 * memory for the output
257 * payload. This may be
258 * used to impose an upper limit on
259 * the instant bitrate, but should
260 * not be used as the only bitrate
261 * control. Use #OPUS_SET_BITRATE to
262 * control the bitrate.
263 * @returns The length of the encoded packet (in bytes) on success or a
264 * negative error code (see @ref opus_errorcodes) on failure.
265 */
266OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_encode(
267 OpusEncoder *st,
268 const opus_int16 *pcm,
269 int frame_size,
270 unsigned char *data,
271 opus_int32 max_data_bytes
272) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4);
273
274/** Encodes an Opus frame.
275 * @param [in] st <tt>OpusEncoder*</tt>: Encoder state
276 * @param [in] pcm <tt>opus_int32*</tt>: Input signal (interleaved if 2 channels) representing (or slightly exceeding) 24-bit values. length is frame_size*channels*sizeof(opus_int32)
277 * @param [in] frame_size <tt>int</tt>: Number of samples per channel in the
278 * input signal.
279 * This must be an Opus frame size for
280 * the encoder's sampling rate.
281 * For example, at 48 kHz the permitted
282 * values are 120, 240, 480, 960, 1920,
283 * and 2880.
284 * Passing in a duration of less than
285 * 10 ms (480 samples at 48 kHz) will
286 * prevent the encoder from using the LPC
287 * or hybrid modes.
288 * @param [out] data <tt>unsigned char*</tt>: Output payload.
289 * This must contain storage for at
290 * least \a max_data_bytes.
291 * @param [in] max_data_bytes <tt>opus_int32</tt>: Size of the allocated
292 * memory for the output
293 * payload. This may be
294 * used to impose an upper limit on
295 * the instant bitrate, but should
296 * not be used as the only bitrate
297 * control. Use #OPUS_SET_BITRATE to
298 * control the bitrate.
299 * @returns The length of the encoded packet (in bytes) on success or a
300 * negative error code (see @ref opus_errorcodes) on failure.
301 */
302OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_encode24(
303 OpusEncoder *st,
304 const opus_int32 *pcm,
305 int frame_size,
306 unsigned char *data,
307 opus_int32 max_data_bytes
308) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4);
309
310/** Encodes an Opus frame from floating point input.
311 * @param [in] st <tt>OpusEncoder*</tt>: Encoder state
312 * @param [in] pcm <tt>float*</tt>: Input in float format (interleaved if 2 channels), with a normal range of +/-1.0.
313 * Samples with a range beyond +/-1.0 are supported but will
314 * be clipped by decoders using the integer API and should
315 * only be used if it is known that the far end supports
316 * extended dynamic range.
317 * length is frame_size*channels*sizeof(float)
318 * @param [in] frame_size <tt>int</tt>: Number of samples per channel in the
319 * input signal.
320 * This must be an Opus frame size for
321 * the encoder's sampling rate.
322 * For example, at 48 kHz the permitted
323 * values are 120, 240, 480, 960, 1920,
324 * and 2880.
325 * Passing in a duration of less than
326 * 10 ms (480 samples at 48 kHz) will
327 * prevent the encoder from using the LPC
328 * or hybrid modes.
329 * @param [out] data <tt>unsigned char*</tt>: Output payload.
330 * This must contain storage for at
331 * least \a max_data_bytes.
332 * @param [in] max_data_bytes <tt>opus_int32</tt>: Size of the allocated
333 * memory for the output
334 * payload. This may be
335 * used to impose an upper limit on
336 * the instant bitrate, but should
337 * not be used as the only bitrate
338 * control. Use #OPUS_SET_BITRATE to
339 * control the bitrate.
340 * @returns The length of the encoded packet (in bytes) on success or a
341 * negative error code (see @ref opus_errorcodes) on failure.
342 */
343OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_encode_float(
344 OpusEncoder *st,
345 const float *pcm,
346 int frame_size,
347 unsigned char *data,
348 opus_int32 max_data_bytes
349) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4);
350
351/** Frees an <code>OpusEncoder</code> allocated by opus_encoder_create().
352 * @param[in] st <tt>OpusEncoder*</tt>: State to be freed.
353 */
354OPUS_EXPORT void opus_encoder_destroy(OpusEncoder *st);
355
356/** Perform a CTL function on an Opus encoder.
357 *
358 * Generally the request and subsequent arguments are generated
359 * by a convenience macro.
360 * @param st <tt>OpusEncoder*</tt>: Encoder state.
361 * @param request This and all remaining parameters should be replaced by one
362 * of the convenience macros in @ref opus_genericctls or
363 * @ref opus_encoderctls.
364 * @see opus_genericctls
365 * @see opus_encoderctls
366 */
367OPUS_EXPORT int opus_encoder_ctl(OpusEncoder *st, int request, ...) OPUS_ARG_NONNULL(1);
368/**@}*/
369
370/** @defgroup opus_decoder Opus Decoder
371 * @{
372 *
373 * @brief This page describes the process and functions used to decode Opus.
374 *
375 * The decoding process also starts with creating a decoder
376 * state. This can be done with:
377 * @code
378 * int error;
379 * OpusDecoder *dec;
380 * dec = opus_decoder_create(Fs, channels, &error);
381 * @endcode
382 * where
383 * @li Fs is the sampling rate and must be 8000, 12000, 16000, 24000, or 48000
384 * @li channels is the number of channels (1 or 2)
385 * @li error will hold the error code in case of failure (or #OPUS_OK on success)
386 * @li the return value is a newly created decoder state to be used for decoding
387 *
388 * While opus_decoder_create() allocates memory for the state, it's also possible
389 * to initialize pre-allocated memory:
390 * @code
391 * int size;
392 * int error;
393 * OpusDecoder *dec;
394 * size = opus_decoder_get_size(channels);
395 * dec = malloc(size);
396 * error = opus_decoder_init(dec, Fs, channels);
397 * @endcode
398 * where opus_decoder_get_size() returns the required size for the decoder state. Note that
399 * future versions of this code may change the size, so no assumptions should be made about it.
400 *
401 * The decoder state is always continuous in memory and only a shallow copy is sufficient
402 * to copy it (e.g. memcpy())
403 *
404 * To decode a frame, opus_decode() or opus_decode_float() must be called with a packet of compressed audio data:
405 * @code
406 * frame_size = opus_decode(dec, packet, len, decoded, max_size, 0);
407 * @endcode
408 * where
409 *
410 * @li packet is the byte array containing the compressed data
411 * @li len is the exact number of bytes contained in the packet
412 * @li decoded is the decoded audio data in opus_int16 (or float for opus_decode_float())
413 * @li max_size is the max duration of the frame in samples (per channel) that can fit into the decoded_frame array
414 *
415 * opus_decode() and opus_decode_float() return the number of samples (per channel) decoded from the packet.
416 * If that value is negative, then an error has occurred. This can occur if the packet is corrupted or if the audio
417 * buffer is too small to hold the decoded audio.
418 *
419 * Opus is a stateful codec with overlapping blocks and as a result Opus
420 * packets are not coded independently of each other. Packets must be
421 * passed into the decoder serially and in the correct order for a correct
422 * decode. Lost packets can be replaced with loss concealment by calling
423 * the decoder with a null pointer and zero length for the missing packet.
424 *
425 * A single codec state may only be accessed from a single thread at
426 * a time and any required locking must be performed by the caller. Separate
427 * streams must be decoded with separate decoder states and can be decoded
428 * in parallel unless the library was compiled with NONTHREADSAFE_PSEUDOSTACK
429 * defined.
430 *
431 */
432
433/** Opus decoder state.
434 * This contains the complete state of an Opus decoder.
435 * It is position independent and can be freely copied.
436 * @see opus_decoder_create,opus_decoder_init
437 */
438typedef struct OpusDecoder OpusDecoder;
439
440/** Opus DRED decoder.
441 * This contains the complete state of an Opus DRED decoder.
442 * It is position independent and can be freely copied.
443 * @see opus_dred_decoder_create,opus_dred_decoder_init
444 */
445typedef struct OpusDREDDecoder OpusDREDDecoder;
446
447
448/** Opus DRED state.
449 * This contains the complete state of an Opus DRED packet.
450 * It is position independent and can be freely copied.
451 * @see opus_dred_create,opus_dred_init
452 */
453typedef struct OpusDRED OpusDRED;
454
455/** Gets the size of an <code>OpusDecoder</code> structure.
456 * @param [in] channels <tt>int</tt>: Number of channels.
457 * This must be 1 or 2.
458 * @returns The size in bytes.
459 */
460OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decoder_get_size(int channels);
461
462/** Allocates and initializes a decoder state.
463 * @param [in] Fs <tt>opus_int32</tt>: Sample rate to decode at (Hz).
464 * This must be one of 8000, 12000, 16000,
465 * 24000, or 48000.
466 * @param [in] channels <tt>int</tt>: Number of channels (1 or 2) to decode
467 * @param [out] error <tt>int*</tt>: #OPUS_OK Success or @ref opus_errorcodes
468 *
469 * Internally Opus stores data at 48000 Hz, so that should be the default
470 * value for Fs. However, the decoder can efficiently decode to buffers
471 * at 8, 12, 16, and 24 kHz so if for some reason the caller cannot use
472 * data at the full sample rate, or knows the compressed data doesn't
473 * use the full frequency range, it can request decoding at a reduced
474 * rate. Likewise, the decoder is capable of filling in either mono or
475 * interleaved stereo pcm buffers, at the caller's request.
476 */
477OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusDecoder *opus_decoder_create(
478 opus_int32 Fs,
479 int channels,
480 int *error
481);
482
483/** Initializes a previously allocated decoder state.
484 * The state must be at least the size returned by opus_decoder_get_size().
485 * This is intended for applications which use their own allocator instead of malloc. @see opus_decoder_create,opus_decoder_get_size
486 * To reset a previously initialized state, use the #OPUS_RESET_STATE CTL.
487 * @param [in] st <tt>OpusDecoder*</tt>: Decoder state.
488 * @param [in] Fs <tt>opus_int32</tt>: Sampling rate to decode to (Hz).
489 * This must be one of 8000, 12000, 16000,
490 * 24000, or 48000.
491 * @param [in] channels <tt>int</tt>: Number of channels (1 or 2) to decode
492 * @retval #OPUS_OK Success or @ref opus_errorcodes
493 */
494OPUS_EXPORT int opus_decoder_init(
495 OpusDecoder *st,
496 opus_int32 Fs,
497 int channels
498) OPUS_ARG_NONNULL(1);
499
500/** Decode an Opus packet.
501 * @param [in] st <tt>OpusDecoder*</tt>: Decoder state
502 * @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to indicate packet loss
503 * @param [in] len <tt>opus_int32</tt>: Number of bytes in payload*
504 * @param [out] pcm <tt>opus_int16*</tt>: Output signal (interleaved if 2 channels). length
505 * is frame_size*channels*sizeof(opus_int16)
506 * @param [in] frame_size Number of samples per channel of available space in \a pcm.
507 * If this is less than the maximum packet duration (120ms; 5760 for 48kHz), this function will
508 * not be capable of decoding some packets. In the case of PLC (data==NULL) or FEC (decode_fec=1),
509 * then frame_size needs to be exactly the duration of audio that is missing, otherwise the
510 * decoder will not be in the optimal state to decode the next incoming packet. For the PLC and
511 * FEC cases, frame_size <b>must</b> be a multiple of 2.5 ms.
512 * @param [in] decode_fec <tt>int</tt>: Flag (0 or 1) to request that any in-band forward error correction data be
513 * decoded. If no such data is available, the frame is decoded as if it were lost.
514 * @returns Number of decoded samples per channel or @ref opus_errorcodes
515 */
516OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decode(
517 OpusDecoder *st,
518 const unsigned char *data,
519 opus_int32 len,
520 opus_int16 *pcm,
521 int frame_size,
522 int decode_fec
523) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
524
525/** Decode an Opus packet.
526 * @param [in] st <tt>OpusDecoder*</tt>: Decoder state
527 * @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to indicate packet loss
528 * @param [in] len <tt>opus_int32</tt>: Number of bytes in payload*
529 * @param [out] pcm <tt>opus_int32*</tt>: Output signal (interleaved if 2 channels) representing (or slightly exceeding) 24-bit values. length
530 * is frame_size*channels*sizeof(opus_int32)
531 * @param [in] frame_size Number of samples per channel of available space in \a pcm.
532 * If this is less than the maximum packet duration (120ms; 5760 for 48kHz), this function will
533 * not be capable of decoding some packets. In the case of PLC (data==NULL) or FEC (decode_fec=1),
534 * then frame_size needs to be exactly the duration of audio that is missing, otherwise the
535 * decoder will not be in the optimal state to decode the next incoming packet. For the PLC and
536 * FEC cases, frame_size <b>must</b> be a multiple of 2.5 ms.
537 * @param [in] decode_fec <tt>int</tt>: Flag (0 or 1) to request that any in-band forward error correction data be
538 * decoded. If no such data is available, the frame is decoded as if it were lost.
539 * @returns Number of decoded samples or @ref opus_errorcodes
540 */
541OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decode24(
542 OpusDecoder *st,
543 const unsigned char *data,
544 opus_int32 len,
545 opus_int32 *pcm,
546 int frame_size,
547 int decode_fec
548) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
549
550/** Decode an Opus packet with floating point output.
551 * @param [in] st <tt>OpusDecoder*</tt>: Decoder state
552 * @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to indicate packet loss
553 * @param [in] len <tt>opus_int32</tt>: Number of bytes in payload
554 * @param [out] pcm <tt>float*</tt>: Output signal (interleaved if 2 channels). length
555 * is frame_size*channels*sizeof(float)
556 * @param [in] frame_size Number of samples per channel of available space in \a pcm.
557 * If this is less than the maximum packet duration (120ms; 5760 for 48kHz), this function will
558 * not be capable of decoding some packets. In the case of PLC (data==NULL) or FEC (decode_fec=1),
559 * then frame_size needs to be exactly the duration of audio that is missing, otherwise the
560 * decoder will not be in the optimal state to decode the next incoming packet. For the PLC and
561 * FEC cases, frame_size <b>must</b> be a multiple of 2.5 ms.
562 * @param [in] decode_fec <tt>int</tt>: Flag (0 or 1) to request that any in-band forward error correction data be
563 * decoded. If no such data is available the frame is decoded as if it were lost.
564 * @returns Number of decoded samples per channel or @ref opus_errorcodes
565 */
566OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decode_float(
567 OpusDecoder *st,
568 const unsigned char *data,
569 opus_int32 len,
570 float *pcm,
571 int frame_size,
572 int decode_fec
573) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
574
575/** Perform a CTL function on an Opus decoder.
576 *
577 * Generally the request and subsequent arguments are generated
578 * by a convenience macro.
579 * @param st <tt>OpusDecoder*</tt>: Decoder state.
580 * @param request This and all remaining parameters should be replaced by one
581 * of the convenience macros in @ref opus_genericctls or
582 * @ref opus_decoderctls.
583 * @see opus_genericctls
584 * @see opus_decoderctls
585 */
586OPUS_EXPORT int opus_decoder_ctl(OpusDecoder *st, int request, ...) OPUS_ARG_NONNULL(1);
587
588/** Frees an <code>OpusDecoder</code> allocated by opus_decoder_create().
589 * @param[in] st <tt>OpusDecoder*</tt>: State to be freed.
590 */
591OPUS_EXPORT void opus_decoder_destroy(OpusDecoder *st);
592
593/** Gets the size of an <code>OpusDREDDecoder</code> structure.
594 * @returns The size in bytes.
595 */
596OPUS_EXPORT int opus_dred_decoder_get_size(void);
597
598/** Allocates and initializes an OpusDREDDecoder state.
599 * @param [out] error <tt>int*</tt>: #OPUS_OK Success or @ref opus_errorcodes
600 */
601OPUS_EXPORT OpusDREDDecoder *opus_dred_decoder_create(int *error);
602
603/** Initializes an <code>OpusDREDDecoder</code> state.
604 * @param[in] dec <tt>OpusDREDDecoder*</tt>: State to be initialized.
605 */
606OPUS_EXPORT int opus_dred_decoder_init(OpusDREDDecoder *dec);
607
608/** Frees an <code>OpusDREDDecoder</code> allocated by opus_dred_decoder_create().
609 * @param[in] dec <tt>OpusDREDDecoder*</tt>: State to be freed.
610 */
611OPUS_EXPORT void opus_dred_decoder_destroy(OpusDREDDecoder *dec);
612
613/** Perform a CTL function on an Opus DRED decoder.
614 *
615 * Generally the request and subsequent arguments are generated
616 * by a convenience macro.
617 * @param dred_dec <tt>OpusDREDDecoder*</tt>: DRED Decoder state.
618 * @param request This and all remaining parameters should be replaced by one
619 * of the convenience macros in @ref opus_genericctls or
620 * @ref opus_decoderctls.
621 * @see opus_genericctls
622 * @see opus_decoderctls
623 */
624OPUS_EXPORT int opus_dred_decoder_ctl(OpusDREDDecoder *dred_dec, int request, ...);
625
626/** Gets the size of an <code>OpusDRED</code> structure.
627 * @returns The size in bytes.
628 */
629OPUS_EXPORT int opus_dred_get_size(void);
630
631/** Allocates and initializes a DRED state.
632 * @param [out] error <tt>int*</tt>: #OPUS_OK Success or @ref opus_errorcodes
633 */
634OPUS_EXPORT OpusDRED *opus_dred_alloc(int *error);
635
636/** Frees an <code>OpusDRED</code> allocated by opus_dred_create().
637 * @param[in] dec <tt>OpusDRED*</tt>: State to be freed.
638 */
639OPUS_EXPORT void opus_dred_free(OpusDRED *dec);
640
641/** Decode an Opus DRED packet.
642 * @param [in] dred_dec <tt>OpusDRED*</tt>: DRED Decoder state
643 * @param [in] dred <tt>OpusDRED*</tt>: DRED state
644 * @param [in] data <tt>char*</tt>: Input payload
645 * @param [in] len <tt>opus_int32</tt>: Number of bytes in payload
646 * @param [in] max_dred_samples <tt>opus_int32</tt>: Maximum number of DRED samples that may be needed (if available in the packet).
647 * @param [in] sampling_rate <tt>opus_int32</tt>: Sampling rate used for max_dred_samples argument. Needs not match the actual sampling rate of the decoder.
648 * @param [out] dred_end <tt>opus_int32*</tt>: Number of non-encoded (silence) samples between the DRED timestamp and the last DRED sample.
649 * @param [in] defer_processing <tt>int</tt>: Flag (0 or 1). If set to one, the CPU-intensive part of the DRED decoding is deferred until opus_dred_process() is called.
650 * @returns Offset (positive) of the first decoded DRED samples, zero if no DRED is present, or @ref opus_errorcodes
651 */
652OPUS_EXPORT int opus_dred_parse(OpusDREDDecoder *dred_dec, OpusDRED *dred, const unsigned char *data, opus_int32 len, opus_int32 max_dred_samples, opus_int32 sampling_rate, int *dred_end, int defer_processing) OPUS_ARG_NONNULL(1);
653
654/** Finish decoding an Opus DRED packet. The function only needs to be called if opus_dred_parse() was called with defer_processing=1.
655 * The source and destination will often be the same DRED state.
656 * @param [in] dred_dec <tt>OpusDRED*</tt>: DRED Decoder state
657 * @param [in] src <tt>OpusDRED*</tt>: Source DRED state to start the processing from.
658 * @param [out] dst <tt>OpusDRED*</tt>: Destination DRED state to store the updated state after processing.
659 * @returns @ref opus_errorcodes
660 */
661OPUS_EXPORT int opus_dred_process(OpusDREDDecoder *dred_dec, const OpusDRED *src, OpusDRED *dst);
662
663/** Decode audio from an Opus DRED packet with 16-bit output.
664 * @param [in] st <tt>OpusDecoder*</tt>: Decoder state
665 * @param [in] dred <tt>OpusDRED*</tt>: DRED state
666 * @param [in] dred_offset <tt>opus_int32</tt>: position of the redundancy to decode (in samples before the beginning of the real audio data in the packet).
667 * @param [out] pcm <tt>opus_int16*</tt>: Output signal (interleaved if 2 channels). length
668 * is frame_size*channels*sizeof(opus_int16)
669 * @param [in] frame_size Number of samples per channel to decode in \a pcm.
670 * frame_size <b>must</b> be a multiple of 2.5 ms.
671 * @returns Number of decoded samples or @ref opus_errorcodes
672 */
673OPUS_EXPORT int opus_decoder_dred_decode(OpusDecoder *st, const OpusDRED *dred, opus_int32 dred_offset, opus_int16 *pcm, opus_int32 frame_size);
674
675/** Decode audio from an Opus DRED packet with 24-bit output.
676 * @param [in] st <tt>OpusDecoder*</tt>: Decoder state
677 * @param [in] dred <tt>OpusDRED*</tt>: DRED state
678 * @param [in] dred_offset <tt>opus_int32</tt>: position of the redundancy to decode (in samples before the beginning of the real audio data in the packet).
679 * @param [out] pcm <tt>opus_int32*</tt>: Output signal (interleaved if 2 channels). length
680 * is frame_size*channels*sizeof(opus_int16)
681 * @param [in] frame_size Number of samples per channel to decode in \a pcm.
682 * frame_size <b>must</b> be a multiple of 2.5 ms.
683 * @returns Number of decoded samples or @ref opus_errorcodes
684 */
685OPUS_EXPORT int opus_decoder_dred_decode24(OpusDecoder *st, const OpusDRED *dred, opus_int32 dred_offset, opus_int32 *pcm, opus_int32 frame_size);
686
687/** Decode audio from an Opus DRED packet with floating point output.
688 * @param [in] st <tt>OpusDecoder*</tt>: Decoder state
689 * @param [in] dred <tt>OpusDRED*</tt>: DRED state
690 * @param [in] dred_offset <tt>opus_int32</tt>: position of the redundancy to decode (in samples before the beginning of the real audio data in the packet).
691 * @param [out] pcm <tt>float*</tt>: Output signal (interleaved if 2 channels). length
692 * is frame_size*channels*sizeof(float)
693 * @param [in] frame_size Number of samples per channel to decode in \a pcm.
694 * frame_size <b>must</b> be a multiple of 2.5 ms.
695 * @returns Number of decoded samples or @ref opus_errorcodes
696 */
697OPUS_EXPORT int opus_decoder_dred_decode_float(OpusDecoder *st, const OpusDRED *dred, opus_int32 dred_offset, float *pcm, opus_int32 frame_size);
698
699
700/** Parse an opus packet into one or more frames.
701 * Opus_decode will perform this operation internally so most applications do
702 * not need to use this function.
703 * This function does not copy the frames, the returned pointers are pointers into
704 * the input packet.
705 * @param [in] data <tt>char*</tt>: Opus packet to be parsed
706 * @param [in] len <tt>opus_int32</tt>: size of data
707 * @param [out] out_toc <tt>char*</tt>: TOC pointer
708 * @param [out] frames <tt>char*[48]</tt> encapsulated frames
709 * @param [out] size <tt>opus_int16[48]</tt> sizes of the encapsulated frames
710 * @param [out] payload_offset <tt>int*</tt>: returns the position of the payload within the packet (in bytes)
711 * @returns number of frames
712 */
713OPUS_EXPORT int opus_packet_parse(
714 const unsigned char *data,
715 opus_int32 len,
716 unsigned char *out_toc,
717 const unsigned char *frames[48],
718 opus_int16 size[48],
719 int *payload_offset
720) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(5);
721
722/** Gets the bandwidth of an Opus packet.
723 * @param [in] data <tt>char*</tt>: Opus packet
724 * @retval OPUS_BANDWIDTH_NARROWBAND Narrowband (4kHz bandpass)
725 * @retval OPUS_BANDWIDTH_MEDIUMBAND Mediumband (6kHz bandpass)
726 * @retval OPUS_BANDWIDTH_WIDEBAND Wideband (8kHz bandpass)
727 * @retval OPUS_BANDWIDTH_SUPERWIDEBAND Superwideband (12kHz bandpass)
728 * @retval OPUS_BANDWIDTH_FULLBAND Fullband (20kHz bandpass)
729 * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type
730 */
731OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_bandwidth(const unsigned char *data) OPUS_ARG_NONNULL(1);
732
733/** Gets the number of samples per frame from an Opus packet.
734 * @param [in] data <tt>char*</tt>: Opus packet.
735 * This must contain at least one byte of
736 * data.
737 * @param [in] Fs <tt>opus_int32</tt>: Sampling rate in Hz.
738 * This must be a multiple of 400, or
739 * inaccurate results will be returned.
740 * @returns Number of samples per frame.
741 */
742OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_samples_per_frame(const unsigned char *data, opus_int32 Fs) OPUS_ARG_NONNULL(1);
743
744/** Gets the number of channels from an Opus packet.
745 * @param [in] data <tt>char*</tt>: Opus packet
746 * @returns Number of channels
747 * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type
748 */
749OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_nb_channels(const unsigned char *data) OPUS_ARG_NONNULL(1);
750
751/** Gets the number of frames in an Opus packet.
752 * @param [in] packet <tt>char*</tt>: Opus packet
753 * @param [in] len <tt>opus_int32</tt>: Length of packet
754 * @returns Number of frames
755 * @retval OPUS_BAD_ARG Insufficient data was passed to the function
756 * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type
757 */
758OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_nb_frames(const unsigned char packet[], opus_int32 len) OPUS_ARG_NONNULL(1);
759
760/** Gets the number of samples of an Opus packet.
761 * @param [in] packet <tt>char*</tt>: Opus packet
762 * @param [in] len <tt>opus_int32</tt>: Length of packet
763 * @param [in] Fs <tt>opus_int32</tt>: Sampling rate in Hz.
764 * This must be a multiple of 400, or
765 * inaccurate results will be returned.
766 * @returns Number of samples
767 * @retval OPUS_BAD_ARG Insufficient data was passed to the function
768 * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type
769 */
770OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_nb_samples(const unsigned char packet[], opus_int32 len, opus_int32 Fs) OPUS_ARG_NONNULL(1);
771
772/** Checks whether an Opus packet has LBRR.
773 * @param [in] packet <tt>char*</tt>: Opus packet
774 * @param [in] len <tt>opus_int32</tt>: Length of packet
775 * @returns 1 is LBRR is present, 0 otherwise
776 * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type
777 */
778OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_has_lbrr(const unsigned char packet[], opus_int32 len);
779
780/** Gets the number of samples of an Opus packet.
781 * @param [in] dec <tt>OpusDecoder*</tt>: Decoder state
782 * @param [in] packet <tt>char*</tt>: Opus packet
783 * @param [in] len <tt>opus_int32</tt>: Length of packet
784 * @returns Number of samples
785 * @retval OPUS_BAD_ARG Insufficient data was passed to the function
786 * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type
787 */
788OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decoder_get_nb_samples(const OpusDecoder *dec, const unsigned char packet[], opus_int32 len) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2);
789
790/** Applies soft-clipping to bring a float signal within the [-1,1] range. If
791 * the signal is already in that range, nothing is done. If there are values
792 * outside of [-1,1], then the signal is clipped as smoothly as possible to
793 * both fit in the range and avoid creating excessive distortion in the
794 * process.
795 * @param [in,out] pcm <tt>float*</tt>: Input PCM and modified PCM
796 * @param [in] frame_size <tt>int</tt> Number of samples per channel to process
797 * @param [in] channels <tt>int</tt>: Number of channels
798 * @param [in,out] softclip_mem <tt>float*</tt>: State memory for the soft clipping process (one float per channel, initialized to zero)
799 */
800OPUS_EXPORT void opus_pcm_soft_clip(float *pcm, int frame_size, int channels, float *softclip_mem);
801
802
803/**@}*/
804
805/** @defgroup opus_repacketizer Repacketizer
806 * @{
807 *
808 * The repacketizer can be used to merge multiple Opus packets into a single
809 * packet or alternatively to split Opus packets that have previously been
810 * merged. Splitting valid Opus packets is always guaranteed to succeed,
811 * whereas merging valid packets only succeeds if all frames have the same
812 * mode, bandwidth, and frame size, and when the total duration of the merged
813 * packet is no more than 120 ms. The 120 ms limit comes from the
814 * specification and limits decoder memory requirements at a point where
815 * framing overhead becomes negligible.
816 *
817 * The repacketizer currently only operates on elementary Opus
818 * streams. It will not manipulate multistream packets successfully, except in
819 * the degenerate case where they consist of data from a single stream.
820 *
821 * The repacketizing process starts with creating a repacketizer state, either
822 * by calling opus_repacketizer_create() or by allocating the memory yourself,
823 * e.g.,
824 * @code
825 * OpusRepacketizer *rp;
826 * rp = (OpusRepacketizer*)malloc(opus_repacketizer_get_size());
827 * if (rp != NULL)
828 * opus_repacketizer_init(rp);
829 * @endcode
830 *
831 * Then the application should submit packets with opus_repacketizer_cat(),
832 * extract new packets with opus_repacketizer_out() or
833 * opus_repacketizer_out_range(), and then reset the state for the next set of
834 * input packets via opus_repacketizer_init().
835 *
836 * For example, to split a sequence of packets into individual frames:
837 * @code
838 * unsigned char *data;
839 * int len;
840 * while (get_next_packet(&data, &len))
841 * {
842 * unsigned char out[1276];
843 * opus_int32 out_len;
844 * int nb_frames;
845 * int err;
846 * int i;
847 * err = opus_repacketizer_cat(rp, data, len);
848 * if (err != OPUS_OK)
849 * {
850 * release_packet(data);
851 * return err;
852 * }
853 * nb_frames = opus_repacketizer_get_nb_frames(rp);
854 * for (i = 0; i < nb_frames; i++)
855 * {
856 * out_len = opus_repacketizer_out_range(rp, i, i+1, out, sizeof(out));
857 * if (out_len < 0)
858 * {
859 * release_packet(data);
860 * return (int)out_len;
861 * }
862 * output_next_packet(out, out_len);
863 * }
864 * opus_repacketizer_init(rp);
865 * release_packet(data);
866 * }
867 * @endcode
868 *
869 * Alternatively, to combine a sequence of frames into packets that each
870 * contain up to <code>TARGET_DURATION_MS</code> milliseconds of data:
871 * @code
872 * // The maximum number of packets with duration TARGET_DURATION_MS occurs
873 * // when the frame size is 2.5 ms, for a total of (TARGET_DURATION_MS*2/5)
874 * // packets.
875 * unsigned char *data[(TARGET_DURATION_MS*2/5)+1];
876 * opus_int32 len[(TARGET_DURATION_MS*2/5)+1];
877 * int nb_packets;
878 * unsigned char out[1277*(TARGET_DURATION_MS*2/2)];
879 * opus_int32 out_len;
880 * int prev_toc;
881 * nb_packets = 0;
882 * while (get_next_packet(data+nb_packets, len+nb_packets))
883 * {
884 * int nb_frames;
885 * int err;
886 * nb_frames = opus_packet_get_nb_frames(data[nb_packets], len[nb_packets]);
887 * if (nb_frames < 1)
888 * {
889 * release_packets(data, nb_packets+1);
890 * return nb_frames;
891 * }
892 * nb_frames += opus_repacketizer_get_nb_frames(rp);
893 * // If adding the next packet would exceed our target, or it has an
894 * // incompatible TOC sequence, output the packets we already have before
895 * // submitting it.
896 * // N.B., The nb_packets > 0 check ensures we've submitted at least one
897 * // packet since the last call to opus_repacketizer_init(). Otherwise a
898 * // single packet longer than TARGET_DURATION_MS would cause us to try to
899 * // output an (invalid) empty packet. It also ensures that prev_toc has
900 * // been set to a valid value. Additionally, len[nb_packets] > 0 is
901 * // guaranteed by the call to opus_packet_get_nb_frames() above, so the
902 * // reference to data[nb_packets][0] should be valid.
903 * if (nb_packets > 0 && (
904 * ((prev_toc & 0xFC) != (data[nb_packets][0] & 0xFC)) ||
905 * opus_packet_get_samples_per_frame(data[nb_packets], 48000)*nb_frames >
906 * TARGET_DURATION_MS*48))
907 * {
908 * out_len = opus_repacketizer_out(rp, out, sizeof(out));
909 * if (out_len < 0)
910 * {
911 * release_packets(data, nb_packets+1);
912 * return (int)out_len;
913 * }
914 * output_next_packet(out, out_len);
915 * opus_repacketizer_init(rp);
916 * release_packets(data, nb_packets);
917 * data[0] = data[nb_packets];
918 * len[0] = len[nb_packets];
919 * nb_packets = 0;
920 * }
921 * err = opus_repacketizer_cat(rp, data[nb_packets], len[nb_packets]);
922 * if (err != OPUS_OK)
923 * {
924 * release_packets(data, nb_packets+1);
925 * return err;
926 * }
927 * prev_toc = data[nb_packets][0];
928 * nb_packets++;
929 * }
930 * // Output the final, partial packet.
931 * if (nb_packets > 0)
932 * {
933 * out_len = opus_repacketizer_out(rp, out, sizeof(out));
934 * release_packets(data, nb_packets);
935 * if (out_len < 0)
936 * return (int)out_len;
937 * output_next_packet(out, out_len);
938 * }
939 * @endcode
940 *
941 * An alternate way of merging packets is to simply call opus_repacketizer_cat()
942 * unconditionally until it fails. At that point, the merged packet can be
943 * obtained with opus_repacketizer_out() and the input packet for which
944 * opus_repacketizer_cat() needs to be re-added to a newly reinitialized
945 * repacketizer state.
946 */
947
948typedef struct OpusRepacketizer OpusRepacketizer;
949
950/** Gets the size of an <code>OpusRepacketizer</code> structure.
951 * @returns The size in bytes.
952 */
953OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_repacketizer_get_size(void);
954
955/** (Re)initializes a previously allocated repacketizer state.
956 * The state must be at least the size returned by opus_repacketizer_get_size().
957 * This can be used for applications which use their own allocator instead of
958 * malloc().
959 * It must also be called to reset the queue of packets waiting to be
960 * repacketized, which is necessary if the maximum packet duration of 120 ms
961 * is reached or if you wish to submit packets with a different Opus
962 * configuration (coding mode, audio bandwidth, frame size, or channel count).
963 * Failure to do so will prevent a new packet from being added with
964 * opus_repacketizer_cat().
965 * @see opus_repacketizer_create
966 * @see opus_repacketizer_get_size
967 * @see opus_repacketizer_cat
968 * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state to
969 * (re)initialize.
970 * @returns A pointer to the same repacketizer state that was passed in.
971 */
972OPUS_EXPORT OpusRepacketizer *opus_repacketizer_init(OpusRepacketizer *rp) OPUS_ARG_NONNULL(1);
973
974/** Allocates memory and initializes the new repacketizer with
975 * opus_repacketizer_init().
976 */
977OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusRepacketizer *opus_repacketizer_create(void);
978
979/** Frees an <code>OpusRepacketizer</code> allocated by
980 * opus_repacketizer_create().
981 * @param[in] rp <tt>OpusRepacketizer*</tt>: State to be freed.
982 */
983OPUS_EXPORT void opus_repacketizer_destroy(OpusRepacketizer *rp);
984
985/** Add a packet to the current repacketizer state.
986 * This packet must match the configuration of any packets already submitted
987 * for repacketization since the last call to opus_repacketizer_init().
988 * This means that it must have the same coding mode, audio bandwidth, frame
989 * size, and channel count.
990 * This can be checked in advance by examining the top 6 bits of the first
991 * byte of the packet, and ensuring they match the top 6 bits of the first
992 * byte of any previously submitted packet.
993 * The total duration of audio in the repacketizer state also must not exceed
994 * 120 ms, the maximum duration of a single packet, after adding this packet.
995 *
996 * The contents of the current repacketizer state can be extracted into new
997 * packets using opus_repacketizer_out() or opus_repacketizer_out_range().
998 *
999 * In order to add a packet with a different configuration or to add more
1000 * audio beyond 120 ms, you must clear the repacketizer state by calling
1001 * opus_repacketizer_init().
1002 * If a packet is too large to add to the current repacketizer state, no part
1003 * of it is added, even if it contains multiple frames, some of which might
1004 * fit.
1005 * If you wish to be able to add parts of such packets, you should first use
1006 * another repacketizer to split the packet into pieces and add them
1007 * individually.
1008 * @see opus_repacketizer_out_range
1009 * @see opus_repacketizer_out
1010 * @see opus_repacketizer_init
1011 * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state to which to
1012 * add the packet.
1013 * @param[in] data <tt>const unsigned char*</tt>: The packet data.
1014 * The application must ensure
1015 * this pointer remains valid
1016 * until the next call to
1017 * opus_repacketizer_init() or
1018 * opus_repacketizer_destroy().
1019 * @param len <tt>opus_int32</tt>: The number of bytes in the packet data.
1020 * @returns An error code indicating whether or not the operation succeeded.
1021 * @retval #OPUS_OK The packet's contents have been added to the repacketizer
1022 * state.
1023 * @retval #OPUS_INVALID_PACKET The packet did not have a valid TOC sequence,
1024 * the packet's TOC sequence was not compatible
1025 * with previously submitted packets (because
1026 * the coding mode, audio bandwidth, frame size,
1027 * or channel count did not match), or adding
1028 * this packet would increase the total amount of
1029 * audio stored in the repacketizer state to more
1030 * than 120 ms.
1031 */
1032OPUS_EXPORT int opus_repacketizer_cat(OpusRepacketizer *rp, const unsigned char *data, opus_int32 len) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2);
1033
1034
1035/** Construct a new packet from data previously submitted to the repacketizer
1036 * state via opus_repacketizer_cat().
1037 * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state from which to
1038 * construct the new packet.
1039 * @param begin <tt>int</tt>: The index of the first frame in the current
1040 * repacketizer state to include in the output.
1041 * @param end <tt>int</tt>: One past the index of the last frame in the
1042 * current repacketizer state to include in the
1043 * output.
1044 * @param[out] data <tt>const unsigned char*</tt>: The buffer in which to
1045 * store the output packet.
1046 * @param maxlen <tt>opus_int32</tt>: The maximum number of bytes to store in
1047 * the output buffer. In order to guarantee
1048 * success, this should be at least
1049 * <code>1276</code> for a single frame,
1050 * or for multiple frames,
1051 * <code>1277*(end-begin)</code>.
1052 * However, <code>1*(end-begin)</code> plus
1053 * the size of all packet data submitted to
1054 * the repacketizer since the last call to
1055 * opus_repacketizer_init() or
1056 * opus_repacketizer_create() is also
1057 * sufficient, and possibly much smaller.
1058 * @returns The total size of the output packet on success, or an error code
1059 * on failure.
1060 * @retval #OPUS_BAD_ARG <code>[begin,end)</code> was an invalid range of
1061 * frames (begin < 0, begin >= end, or end >
1062 * opus_repacketizer_get_nb_frames()).
1063 * @retval #OPUS_BUFFER_TOO_SMALL \a maxlen was insufficient to contain the
1064 * complete output packet.
1065 */
1066OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_repacketizer_out_range(OpusRepacketizer *rp, int begin, int end, unsigned char *data, opus_int32 maxlen) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
1067
1068/** Return the total number of frames contained in packet data submitted to
1069 * the repacketizer state so far via opus_repacketizer_cat() since the last
1070 * call to opus_repacketizer_init() or opus_repacketizer_create().
1071 * This defines the valid range of packets that can be extracted with
1072 * opus_repacketizer_out_range() or opus_repacketizer_out().
1073 * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state containing the
1074 * frames.
1075 * @returns The total number of frames contained in the packet data submitted
1076 * to the repacketizer state.
1077 */
1078OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_repacketizer_get_nb_frames(OpusRepacketizer *rp) OPUS_ARG_NONNULL(1);
1079
1080/** Construct a new packet from data previously submitted to the repacketizer
1081 * state via opus_repacketizer_cat().
1082 * This is a convenience routine that returns all the data submitted so far
1083 * in a single packet.
1084 * It is equivalent to calling
1085 * @code
1086 * opus_repacketizer_out_range(rp, 0, opus_repacketizer_get_nb_frames(rp),
1087 * data, maxlen)
1088 * @endcode
1089 * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state from which to
1090 * construct the new packet.
1091 * @param[out] data <tt>const unsigned char*</tt>: The buffer in which to
1092 * store the output packet.
1093 * @param maxlen <tt>opus_int32</tt>: The maximum number of bytes to store in
1094 * the output buffer. In order to guarantee
1095 * success, this should be at least
1096 * <code>1277*opus_repacketizer_get_nb_frames(rp)</code>.
1097 * However,
1098 * <code>1*opus_repacketizer_get_nb_frames(rp)</code>
1099 * plus the size of all packet data
1100 * submitted to the repacketizer since the
1101 * last call to opus_repacketizer_init() or
1102 * opus_repacketizer_create() is also
1103 * sufficient, and possibly much smaller.
1104 * @returns The total size of the output packet on success, or an error code
1105 * on failure.
1106 * @retval #OPUS_BUFFER_TOO_SMALL \a maxlen was insufficient to contain the
1107 * complete output packet.
1108 */
1109OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_repacketizer_out(OpusRepacketizer *rp, unsigned char *data, opus_int32 maxlen) OPUS_ARG_NONNULL(1);
1110
1111/** Pads a given Opus packet to a larger size (possibly changing the TOC sequence).
1112 * @param[in,out] data <tt>const unsigned char*</tt>: The buffer containing the
1113 * packet to pad.
1114 * @param len <tt>opus_int32</tt>: The size of the packet.
1115 * This must be at least 1.
1116 * @param new_len <tt>opus_int32</tt>: The desired size of the packet after padding.
1117 * This must be at least as large as len.
1118 * @returns an error code
1119 * @retval #OPUS_OK \a on success.
1120 * @retval #OPUS_BAD_ARG \a len was less than 1 or new_len was less than len.
1121 * @retval #OPUS_INVALID_PACKET \a data did not contain a valid Opus packet.
1122 */
1123OPUS_EXPORT int opus_packet_pad(unsigned char *data, opus_int32 len, opus_int32 new_len);
1124
1125/** Remove all padding from a given Opus packet and rewrite the TOC sequence to
1126 * minimize space usage.
1127 * @param[in,out] data <tt>const unsigned char*</tt>: The buffer containing the
1128 * packet to strip.
1129 * @param len <tt>opus_int32</tt>: The size of the packet.
1130 * This must be at least 1.
1131 * @returns The new size of the output packet on success, or an error code
1132 * on failure.
1133 * @retval #OPUS_BAD_ARG \a len was less than 1.
1134 * @retval #OPUS_INVALID_PACKET \a data did not contain a valid Opus packet.
1135 */
1136OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_packet_unpad(unsigned char *data, opus_int32 len);
1137
1138/** Pads a given Opus multi-stream packet to a larger size (possibly changing the TOC sequence).
1139 * @param[in,out] data <tt>const unsigned char*</tt>: The buffer containing the
1140 * packet to pad.
1141 * @param len <tt>opus_int32</tt>: The size of the packet.
1142 * This must be at least 1.
1143 * @param new_len <tt>opus_int32</tt>: The desired size of the packet after padding.
1144 * This must be at least 1.
1145 * @param nb_streams <tt>opus_int32</tt>: The number of streams (not channels) in the packet.
1146 * This must be at least as large as len.
1147 * @returns an error code
1148 * @retval #OPUS_OK \a on success.
1149 * @retval #OPUS_BAD_ARG \a len was less than 1.
1150 * @retval #OPUS_INVALID_PACKET \a data did not contain a valid Opus packet.
1151 */
1152OPUS_EXPORT int opus_multistream_packet_pad(unsigned char *data, opus_int32 len, opus_int32 new_len, int nb_streams);
1153
1154/** Remove all padding from a given Opus multi-stream packet and rewrite the TOC sequence to
1155 * minimize space usage.
1156 * @param[in,out] data <tt>const unsigned char*</tt>: The buffer containing the
1157 * packet to strip.
1158 * @param len <tt>opus_int32</tt>: The size of the packet.
1159 * This must be at least 1.
1160 * @param nb_streams <tt>opus_int32</tt>: The number of streams (not channels) in the packet.
1161 * This must be at least 1.
1162 * @returns The new size of the output packet on success, or an error code
1163 * on failure.
1164 * @retval #OPUS_BAD_ARG \a len was less than 1 or new_len was less than len.
1165 * @retval #OPUS_INVALID_PACKET \a data did not contain a valid Opus packet.
1166 */
1167OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_multistream_packet_unpad(unsigned char *data, opus_int32 len, int nb_streams);
1168
1169/**@}*/
1170
1171#ifdef __cplusplus
1172}
1173#endif
1174
1175#endif /* OPUS_H */
1176