blob: e029f710037cd1a9f5cae8cfa5818b9fc3a74913
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 |
40 | extern "C" { |
41 | #endif |
42 | |
43 | /** |
44 | * @defgroup opus Opus |
45 | * @ingroup MOD_AUDIO |
46 | * @brief Opus reference implementation API |
47 | * |
48 | * The Opus codec is designed for interactive speech and audio transmission over the Internet. |
49 | * It is designed by the IETF Codec Working Group and incorporates technology from |
50 | * Skype's SILK codec and Xiph.Org's CELT codec. |
51 | * |
52 | * The Opus codec is designed to handle a wide range of interactive audio applications, |
53 | * including Voice over IP, videoconferencing, in-game chat, and even remote live music |
54 | * performances. It can scale from low bit-rate narrowband speech to very high quality |
55 | * stereo music. Its main features are: |
56 | |
57 | * @li Sampling rates from 8 to 48 kHz |
58 | * @li Bit-rates from 6 kb/s to 510 kb/s |
59 | * @li Support for both constant bit-rate (CBR) and variable bit-rate (VBR) |
60 | * @li Audio bandwidth from narrowband to full-band |
61 | * @li Support for speech and music |
62 | * @li Support for mono and stereo |
63 | * @li Support for multichannel (up to 255 channels) |
64 | * @li Frame sizes from 2.5 ms to 60 ms |
65 | * @li Good loss robustness and packet loss concealment (PLC) |
66 | * @li Floating point and fixed-point implementation |
67 | * |
68 | * Documentation sections: |
69 | * @li @ref opus_encoder |
70 | * @li @ref opus_decoder |
71 | * @li @ref opus_repacketizer |
72 | * @li @ref opus_multistream |
73 | * @li @ref opus_libinfo |
74 | * @li @ref opus_custom |
75 | */ |
76 | |
77 | /** @defgroup opus_encoder Opus Encoder |
78 | * @ingroup opus |
79 | * @{ |
80 | * |
81 | * @brief This page describes the process and functions used to encode Opus. |
82 | * |
83 | * Since Opus is a stateful codec, the encoding process starts with creating an encoder |
84 | * state. This can be done with: |
85 | * |
86 | * @code |
87 | * int error; |
88 | * OpusEncoder *enc; |
89 | * enc = opus_encoder_create(Fs, channels, application, &error); |
90 | * @endcode |
91 | * |
92 | * From this point, @c enc can be used for encoding an audio stream. An encoder state |
93 | * @b must @b not be used for more than one stream at the same time. Similarly, the encoder |
94 | * state @b must @b not be re-initialized for each frame. |
95 | * |
96 | * While opus_encoder_create() allocates memory for the state, it's also possible |
97 | * to initialize pre-allocated memory: |
98 | * |
99 | * @code |
100 | * int size; |
101 | * int error; |
102 | * OpusEncoder *enc; |
103 | * size = opus_encoder_get_size(channels); |
104 | * enc = malloc(size); |
105 | * error = opus_encoder_init(enc, Fs, channels, application); |
106 | * @endcode |
107 | * |
108 | * where opus_encoder_get_size() returns the required size for the encoder state. Note that |
109 | * future versions of this code may change the size, so no assuptions should be made about it. |
110 | * |
111 | * The encoder state is always continuous in memory and only a shallow copy is sufficient |
112 | * to copy it (e.g. memcpy()) |
113 | * |
114 | * It is possible to change some of the encoder's settings using the opus_encoder_ctl() |
115 | * interface. All these settings already default to the recommended value, so they should |
116 | * only be changed when necessary. The most common settings one may want to change are: |
117 | * |
118 | * @code |
119 | * opus_encoder_ctl(enc, OPUS_SET_BITRATE(bitrate)); |
120 | * opus_encoder_ctl(enc, OPUS_SET_COMPLEXITY(complexity)); |
121 | * opus_encoder_ctl(enc, OPUS_SET_SIGNAL(signal_type)); |
122 | * @endcode |
123 | * |
124 | * where |
125 | * |
126 | * @arg bitrate is in bits per second (b/s) |
127 | * @arg complexity is a value from 1 to 10, where 1 is the lowest complexity and 10 is the highest |
128 | * @arg signal_type is either OPUS_AUTO (default), OPUS_SIGNAL_VOICE, or OPUS_SIGNAL_MUSIC |
129 | * |
130 | * 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. |
131 | * |
132 | * 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: |
133 | * @code |
134 | * len = opus_encode(enc, audio_frame, frame_size, packet, max_packet); |
135 | * @endcode |
136 | * |
137 | * where |
138 | * <ul> |
139 | * <li>audio_frame is the audio data in opus_int16 (or float for opus_encode_float())</li> |
140 | * <li>frame_size is the duration of the frame in samples (per channel)</li> |
141 | * <li>packet is the byte array to which the compressed data is written</li> |
142 | * <li>max_packet is the maximum number of bytes that can be written in the packet (4000 bytes is recommended). |
143 | * Do not use max_packet to control VBR target bitrate, instead use the #OPUS_SET_BITRATE CTL.</li> |
144 | * </ul> |
145 | * |
146 | * opus_encode() and opus_encode_float() return the number of bytes actually written to the packet. |
147 | * The return value <b>can be negative</b>, which indicates that an error has occurred. If the return value |
148 | * is 2 bytes or less, then the packet does not need to be transmitted (DTX). |
149 | * |
150 | * Once the encoder state if no longer needed, it can be destroyed with |
151 | * |
152 | * @code |
153 | * opus_encoder_destroy(enc); |
154 | * @endcode |
155 | * |
156 | * If the encoder was created with opus_encoder_init() rather than opus_encoder_create(), |
157 | * then no action is required aside from potentially freeing the memory that was manually |
158 | * allocated for it (calling free(enc) for the example above) |
159 | * |
160 | */ |
161 | |
162 | /** Opus encoder state. |
163 | * This contains the complete state of an Opus encoder. |
164 | * It is position independent and can be freely copied. |
165 | * @see opus_encoder_create,opus_encoder_init |
166 | */ |
167 | typedef struct OpusEncoder OpusEncoder; |
168 | |
169 | /** Gets the size of an <code>OpusEncoder</code> structure. |
170 | * @param[in] channels <tt>int</tt>: Number of channels. |
171 | * This must be 1 or 2. |
172 | * @returns The size in bytes. |
173 | */ |
174 | OPUS_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 (@ref OPUS_APPLICATION_VOIP/@ref OPUS_APPLICATION_AUDIO/@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 | */ |
211 | OPUS_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 (OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO/OPUS_APPLICATION_RESTRICTED_LOWDELAY) |
229 | * @retval #OPUS_OK Success or @ref opus_errorcodes |
230 | */ |
231 | OPUS_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 | */ |
266 | OPUS_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 from floating point input. |
275 | * @param [in] st <tt>OpusEncoder*</tt>: Encoder state |
276 | * @param [in] pcm <tt>float*</tt>: Input in float format (interleaved if 2 channels), with a normal range of +/-1.0. |
277 | * Samples with a range beyond +/-1.0 are supported but will |
278 | * be clipped by decoders using the integer API and should |
279 | * only be used if it is known that the far end supports |
280 | * extended dynamic range. |
281 | * length is frame_size*channels*sizeof(float) |
282 | * @param [in] frame_size <tt>int</tt>: Number of samples per channel in the |
283 | * input signal. |
284 | * This must be an Opus frame size for |
285 | * the encoder's sampling rate. |
286 | * For example, at 48 kHz the permitted |
287 | * values are 120, 240, 480, 960, 1920, |
288 | * and 2880. |
289 | * Passing in a duration of less than |
290 | * 10 ms (480 samples at 48 kHz) will |
291 | * prevent the encoder from using the LPC |
292 | * or hybrid modes. |
293 | * @param [out] data <tt>unsigned char*</tt>: Output payload. |
294 | * This must contain storage for at |
295 | * least \a max_data_bytes. |
296 | * @param [in] max_data_bytes <tt>opus_int32</tt>: Size of the allocated |
297 | * memory for the output |
298 | * payload. This may be |
299 | * used to impose an upper limit on |
300 | * the instant bitrate, but should |
301 | * not be used as the only bitrate |
302 | * control. Use #OPUS_SET_BITRATE to |
303 | * control the bitrate. |
304 | * @returns The length of the encoded packet (in bytes) on success or a |
305 | * negative error code (see @ref opus_errorcodes) on failure. |
306 | */ |
307 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_encode_float( |
308 | OpusEncoder *st, |
309 | const float *pcm, |
310 | int frame_size, |
311 | unsigned char *data, |
312 | opus_int32 max_data_bytes |
313 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4); |
314 | |
315 | /** Frees an <code>OpusEncoder</code> allocated by opus_encoder_create(). |
316 | * @param[in] st <tt>OpusEncoder*</tt>: State to be freed. |
317 | */ |
318 | OPUS_EXPORT void opus_encoder_destroy(OpusEncoder *st); |
319 | |
320 | /** Perform a CTL function on an Opus encoder. |
321 | * |
322 | * Generally the request and subsequent arguments are generated |
323 | * by a convenience macro. |
324 | * @param st <tt>OpusEncoder*</tt>: Encoder state. |
325 | * @param request This and all remaining parameters should be replaced by one |
326 | * of the convenience macros in @ref opus_genericctls or |
327 | * @ref opus_encoderctls. |
328 | * @see opus_genericctls |
329 | * @see opus_encoderctls |
330 | */ |
331 | OPUS_EXPORT int opus_encoder_ctl(OpusEncoder *st, int request, ...) OPUS_ARG_NONNULL(1); |
332 | /**@}*/ |
333 | |
334 | /** @defgroup opus_decoder Opus Decoder |
335 | * @ingroup opus |
336 | * @{ |
337 | * |
338 | * @brief This page describes the process and functions used to decode Opus. |
339 | * |
340 | * The decoding process also starts with creating a decoder |
341 | * state. This can be done with: |
342 | * @code |
343 | * int error; |
344 | * OpusDecoder *dec; |
345 | * dec = opus_decoder_create(Fs, channels, &error); |
346 | * @endcode |
347 | * where |
348 | * @li Fs is the sampling rate and must be 8000, 12000, 16000, 24000, or 48000 |
349 | * @li channels is the number of channels (1 or 2) |
350 | * @li error will hold the error code in case of failure (or #OPUS_OK on success) |
351 | * @li the return value is a newly created decoder state to be used for decoding |
352 | * |
353 | * While opus_decoder_create() allocates memory for the state, it's also possible |
354 | * to initialize pre-allocated memory: |
355 | * @code |
356 | * int size; |
357 | * int error; |
358 | * OpusDecoder *dec; |
359 | * size = opus_decoder_get_size(channels); |
360 | * dec = malloc(size); |
361 | * error = opus_decoder_init(dec, Fs, channels); |
362 | * @endcode |
363 | * where opus_decoder_get_size() returns the required size for the decoder state. Note that |
364 | * future versions of this code may change the size, so no assuptions should be made about it. |
365 | * |
366 | * The decoder state is always continuous in memory and only a shallow copy is sufficient |
367 | * to copy it (e.g. memcpy()) |
368 | * |
369 | * To decode a frame, opus_decode() or opus_decode_float() must be called with a packet of compressed audio data: |
370 | * @code |
371 | * frame_size = opus_decode(dec, packet, len, decoded, max_size, 0); |
372 | * @endcode |
373 | * where |
374 | * |
375 | * @li packet is the byte array containing the compressed data |
376 | * @li len is the exact number of bytes contained in the packet |
377 | * @li decoded is the decoded audio data in opus_int16 (or float for opus_decode_float()) |
378 | * @li max_size is the max duration of the frame in samples (per channel) that can fit into the decoded_frame array |
379 | * |
380 | * opus_decode() and opus_decode_float() return the number of samples (per channel) decoded from the packet. |
381 | * If that value is negative, then an error has occurred. This can occur if the packet is corrupted or if the audio |
382 | * buffer is too small to hold the decoded audio. |
383 | * |
384 | * Opus is a stateful codec with overlapping blocks and as a result Opus |
385 | * packets are not coded independently of each other. Packets must be |
386 | * passed into the decoder serially and in the correct order for a correct |
387 | * decode. Lost packets can be replaced with loss concealment by calling |
388 | * the decoder with a null pointer and zero length for the missing packet. |
389 | * |
390 | * A single codec state may only be accessed from a single thread at |
391 | * a time and any required locking must be performed by the caller. Separate |
392 | * streams must be decoded with separate decoder states and can be decoded |
393 | * in parallel unless the library was compiled with NONTHREADSAFE_PSEUDOSTACK |
394 | * defined. |
395 | * |
396 | */ |
397 | |
398 | /** Opus decoder state. |
399 | * This contains the complete state of an Opus decoder. |
400 | * It is position independent and can be freely copied. |
401 | * @see opus_decoder_create,opus_decoder_init |
402 | */ |
403 | typedef struct OpusDecoder OpusDecoder; |
404 | |
405 | /** Gets the size of an <code>OpusDecoder</code> structure. |
406 | * @param [in] channels <tt>int</tt>: Number of channels. |
407 | * This must be 1 or 2. |
408 | * @returns The size in bytes. |
409 | */ |
410 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decoder_get_size(int channels); |
411 | |
412 | /** Allocates and initializes a decoder state. |
413 | * @param [in] Fs <tt>opus_int32</tt>: Sample rate to decode at (Hz). |
414 | * This must be one of 8000, 12000, 16000, |
415 | * 24000, or 48000. |
416 | * @param [in] channels <tt>int</tt>: Number of channels (1 or 2) to decode |
417 | * @param [out] error <tt>int*</tt>: #OPUS_OK Success or @ref opus_errorcodes |
418 | * |
419 | * Internally Opus stores data at 48000 Hz, so that should be the default |
420 | * value for Fs. However, the decoder can efficiently decode to buffers |
421 | * at 8, 12, 16, and 24 kHz so if for some reason the caller cannot use |
422 | * data at the full sample rate, or knows the compressed data doesn't |
423 | * use the full frequency range, it can request decoding at a reduced |
424 | * rate. Likewise, the decoder is capable of filling in either mono or |
425 | * interleaved stereo pcm buffers, at the caller's request. |
426 | */ |
427 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusDecoder *opus_decoder_create( |
428 | opus_int32 Fs, |
429 | int channels, |
430 | int *error |
431 | ); |
432 | |
433 | /** Initializes a previously allocated decoder state. |
434 | * The state must be at least the size returned by opus_decoder_get_size(). |
435 | * This is intended for applications which use their own allocator instead of malloc. @see opus_decoder_create,opus_decoder_get_size |
436 | * To reset a previously initialized state, use the #OPUS_RESET_STATE CTL. |
437 | * @param [in] st <tt>OpusDecoder*</tt>: Decoder state. |
438 | * @param [in] Fs <tt>opus_int32</tt>: Sampling rate to decode to (Hz). |
439 | * This must be one of 8000, 12000, 16000, |
440 | * 24000, or 48000. |
441 | * @param [in] channels <tt>int</tt>: Number of channels (1 or 2) to decode |
442 | * @retval #OPUS_OK Success or @ref opus_errorcodes |
443 | */ |
444 | OPUS_EXPORT int opus_decoder_init( |
445 | OpusDecoder *st, |
446 | opus_int32 Fs, |
447 | int channels |
448 | ) OPUS_ARG_NONNULL(1); |
449 | |
450 | /** Decode an Opus packet. |
451 | * @param [in] st <tt>OpusDecoder*</tt>: Decoder state |
452 | * @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to indicate packet loss |
453 | * @param [in] len <tt>opus_int32</tt>: Number of bytes in payload* |
454 | * @param [out] pcm <tt>opus_int16*</tt>: Output signal (interleaved if 2 channels). length |
455 | * is frame_size*channels*sizeof(opus_int16) |
456 | * @param [in] frame_size Number of samples per channel of available space in \a pcm. |
457 | * If this is less than the maximum packet duration (120ms; 5760 for 48kHz), this function will |
458 | * not be capable of decoding some packets. In the case of PLC (data==NULL) or FEC (decode_fec=1), |
459 | * then frame_size needs to be exactly the duration of audio that is missing, otherwise the |
460 | * decoder will not be in the optimal state to decode the next incoming packet. For the PLC and |
461 | * FEC cases, frame_size <b>must</b> be a multiple of 2.5 ms. |
462 | * @param [in] decode_fec <tt>int</tt>: Flag (0 or 1) to request that any in-band forward error correction data be |
463 | * decoded. If no such data is available, the frame is decoded as if it were lost. |
464 | * @returns Number of decoded samples or @ref opus_errorcodes |
465 | */ |
466 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decode( |
467 | OpusDecoder *st, |
468 | const unsigned char *data, |
469 | opus_int32 len, |
470 | opus_int16 *pcm, |
471 | int frame_size, |
472 | int decode_fec |
473 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4); |
474 | |
475 | /** Decode an Opus packet with floating point output. |
476 | * @param [in] st <tt>OpusDecoder*</tt>: Decoder state |
477 | * @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to indicate packet loss |
478 | * @param [in] len <tt>opus_int32</tt>: Number of bytes in payload |
479 | * @param [out] pcm <tt>float*</tt>: Output signal (interleaved if 2 channels). length |
480 | * is frame_size*channels*sizeof(float) |
481 | * @param [in] frame_size Number of samples per channel of available space in \a pcm. |
482 | * If this is less than the maximum packet duration (120ms; 5760 for 48kHz), this function will |
483 | * not be capable of decoding some packets. In the case of PLC (data==NULL) or FEC (decode_fec=1), |
484 | * then frame_size needs to be exactly the duration of audio that is missing, otherwise the |
485 | * decoder will not be in the optimal state to decode the next incoming packet. For the PLC and |
486 | * FEC cases, frame_size <b>must</b> be a multiple of 2.5 ms. |
487 | * @param [in] decode_fec <tt>int</tt>: Flag (0 or 1) to request that any in-band forward error correction data be |
488 | * decoded. If no such data is available the frame is decoded as if it were lost. |
489 | * @returns Number of decoded samples or @ref opus_errorcodes |
490 | */ |
491 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decode_float( |
492 | OpusDecoder *st, |
493 | const unsigned char *data, |
494 | opus_int32 len, |
495 | float *pcm, |
496 | int frame_size, |
497 | int decode_fec |
498 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4); |
499 | |
500 | /** Perform a CTL function on an Opus decoder. |
501 | * |
502 | * Generally the request and subsequent arguments are generated |
503 | * by a convenience macro. |
504 | * @param st <tt>OpusDecoder*</tt>: Decoder state. |
505 | * @param request This and all remaining parameters should be replaced by one |
506 | * of the convenience macros in @ref opus_genericctls or |
507 | * @ref opus_decoderctls. |
508 | * @see opus_genericctls |
509 | * @see opus_decoderctls |
510 | */ |
511 | OPUS_EXPORT int opus_decoder_ctl(OpusDecoder *st, int request, ...) OPUS_ARG_NONNULL(1); |
512 | |
513 | /** Frees an <code>OpusDecoder</code> allocated by opus_decoder_create(). |
514 | * @param[in] st <tt>OpusDecoder*</tt>: State to be freed. |
515 | */ |
516 | OPUS_EXPORT void opus_decoder_destroy(OpusDecoder *st); |
517 | |
518 | /** Parse an opus packet into one or more frames. |
519 | * Opus_decode will perform this operation internally so most applications do |
520 | * not need to use this function. |
521 | * This function does not copy the frames, the returned pointers are pointers into |
522 | * the input packet. |
523 | * @param [in] data <tt>char*</tt>: Opus packet to be parsed |
524 | * @param [in] len <tt>opus_int32</tt>: size of data |
525 | * @param [out] out_toc <tt>char*</tt>: TOC pointer |
526 | * @param [out] frames <tt>char*[48]</tt> encapsulated frames |
527 | * @param [out] size <tt>opus_int16[48]</tt> sizes of the encapsulated frames |
528 | * @param [out] payload_offset <tt>int*</tt>: returns the position of the payload within the packet (in bytes) |
529 | * @returns number of frames |
530 | */ |
531 | OPUS_EXPORT int opus_packet_parse( |
532 | const unsigned char *data, |
533 | opus_int32 len, |
534 | unsigned char *out_toc, |
535 | const unsigned char *frames[48], |
536 | opus_int16 size[48], |
537 | int *payload_offset |
538 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4); |
539 | |
540 | /** Gets the bandwidth of an Opus packet. |
541 | * @param [in] data <tt>char*</tt>: Opus packet |
542 | * @retval OPUS_BANDWIDTH_NARROWBAND Narrowband (4kHz bandpass) |
543 | * @retval OPUS_BANDWIDTH_MEDIUMBAND Mediumband (6kHz bandpass) |
544 | * @retval OPUS_BANDWIDTH_WIDEBAND Wideband (8kHz bandpass) |
545 | * @retval OPUS_BANDWIDTH_SUPERWIDEBAND Superwideband (12kHz bandpass) |
546 | * @retval OPUS_BANDWIDTH_FULLBAND Fullband (20kHz bandpass) |
547 | * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type |
548 | */ |
549 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_bandwidth(const unsigned char *data) OPUS_ARG_NONNULL(1); |
550 | |
551 | /** Gets the number of samples per frame from an Opus packet. |
552 | * @param [in] data <tt>char*</tt>: Opus packet. |
553 | * This must contain at least one byte of |
554 | * data. |
555 | * @param [in] Fs <tt>opus_int32</tt>: Sampling rate in Hz. |
556 | * This must be a multiple of 400, or |
557 | * inaccurate results will be returned. |
558 | * @returns Number of samples per frame. |
559 | */ |
560 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_samples_per_frame(const unsigned char *data, opus_int32 Fs) OPUS_ARG_NONNULL(1); |
561 | |
562 | /** Gets the number of channels from an Opus packet. |
563 | * @param [in] data <tt>char*</tt>: Opus packet |
564 | * @returns Number of channels |
565 | * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type |
566 | */ |
567 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_nb_channels(const unsigned char *data) OPUS_ARG_NONNULL(1); |
568 | |
569 | /** Gets the number of frames in an Opus packet. |
570 | * @param [in] packet <tt>char*</tt>: Opus packet |
571 | * @param [in] len <tt>opus_int32</tt>: Length of packet |
572 | * @returns Number of frames |
573 | * @retval OPUS_BAD_ARG Insufficient data was passed to the function |
574 | * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type |
575 | */ |
576 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_nb_frames(const unsigned char packet[], opus_int32 len) OPUS_ARG_NONNULL(1); |
577 | |
578 | /** Gets the number of samples of an Opus packet. |
579 | * @param [in] packet <tt>char*</tt>: Opus packet |
580 | * @param [in] len <tt>opus_int32</tt>: Length of packet |
581 | * @param [in] Fs <tt>opus_int32</tt>: Sampling rate in Hz. |
582 | * This must be a multiple of 400, or |
583 | * inaccurate results will be returned. |
584 | * @returns Number of samples |
585 | * @retval OPUS_BAD_ARG Insufficient data was passed to the function |
586 | * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type |
587 | */ |
588 | OPUS_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); |
589 | |
590 | /** Gets the number of samples of an Opus packet. |
591 | * @param [in] dec <tt>OpusDecoder*</tt>: Decoder state |
592 | * @param [in] packet <tt>char*</tt>: Opus packet |
593 | * @param [in] len <tt>opus_int32</tt>: Length of packet |
594 | * @returns Number of samples |
595 | * @retval OPUS_BAD_ARG Insufficient data was passed to the function |
596 | * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type |
597 | */ |
598 | OPUS_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); |
599 | |
600 | /** Applies soft-clipping to bring a float signal within the [-1,1] range. If |
601 | * the signal is already in that range, nothing is done. If there are values |
602 | * outside of [-1,1], then the signal is clipped as smoothly as possible to |
603 | * both fit in the range and avoid creating excessive distortion in the |
604 | * process. |
605 | * @param [in,out] pcm <tt>float*</tt>: Input PCM and modified PCM |
606 | * @param [in] frame_size <tt>int</tt> Number of samples per channel to process |
607 | * @param [in] channels <tt>int</tt>: Number of channels |
608 | * @param [in,out] softclip_mem <tt>float*</tt>: State memory for the soft clipping process (one float per channel, initialized to zero) |
609 | */ |
610 | OPUS_EXPORT void opus_pcm_soft_clip(float *pcm, int frame_size, int channels, float *softclip_mem); |
611 | |
612 | |
613 | /**@}*/ |
614 | |
615 | /** @defgroup opus_repacketizer Repacketizer |
616 | * @ingroup opus |
617 | * @{ |
618 | * |
619 | * The repacketizer can be used to merge multiple Opus packets into a single |
620 | * packet or alternatively to split Opus packets that have previously been |
621 | * merged. Splitting valid Opus packets is always guaranteed to succeed, |
622 | * whereas merging valid packets only succeeds if all frames have the same |
623 | * mode, bandwidth, and frame size, and when the total duration of the merged |
624 | * packet is no more than 120 ms. The 120 ms limit comes from the |
625 | * specification and limits decoder memory requirements at a point where |
626 | * framing overhead becomes negligible. |
627 | * |
628 | * The repacketizer currently only operates on elementary Opus |
629 | * streams. It will not manipualte multistream packets successfully, except in |
630 | * the degenerate case where they consist of data from a single stream. |
631 | * |
632 | * The repacketizing process starts with creating a repacketizer state, either |
633 | * by calling opus_repacketizer_create() or by allocating the memory yourself, |
634 | * e.g., |
635 | * @code |
636 | * OpusRepacketizer *rp; |
637 | * rp = (OpusRepacketizer*)malloc(opus_repacketizer_get_size()); |
638 | * if (rp != NULL) |
639 | * opus_repacketizer_init(rp); |
640 | * @endcode |
641 | * |
642 | * Then the application should submit packets with opus_repacketizer_cat(), |
643 | * extract new packets with opus_repacketizer_out() or |
644 | * opus_repacketizer_out_range(), and then reset the state for the next set of |
645 | * input packets via opus_repacketizer_init(). |
646 | * |
647 | * For example, to split a sequence of packets into individual frames: |
648 | * @code |
649 | * unsigned char *data; |
650 | * int len; |
651 | * while (get_next_packet(&data, &len)) |
652 | * { |
653 | * unsigned char out[1276]; |
654 | * opus_int32 out_len; |
655 | * int nb_frames; |
656 | * int err; |
657 | * int i; |
658 | * err = opus_repacketizer_cat(rp, data, len); |
659 | * if (err != OPUS_OK) |
660 | * { |
661 | * release_packet(data); |
662 | * return err; |
663 | * } |
664 | * nb_frames = opus_repacketizer_get_nb_frames(rp); |
665 | * for (i = 0; i < nb_frames; i++) |
666 | * { |
667 | * out_len = opus_repacketizer_out_range(rp, i, i+1, out, sizeof(out)); |
668 | * if (out_len < 0) |
669 | * { |
670 | * release_packet(data); |
671 | * return (int)out_len; |
672 | * } |
673 | * output_next_packet(out, out_len); |
674 | * } |
675 | * opus_repacketizer_init(rp); |
676 | * release_packet(data); |
677 | * } |
678 | * @endcode |
679 | * |
680 | * Alternatively, to combine a sequence of frames into packets that each |
681 | * contain up to <code>TARGET_DURATION_MS</code> milliseconds of data: |
682 | * @code |
683 | * // The maximum number of packets with duration TARGET_DURATION_MS occurs |
684 | * // when the frame size is 2.5 ms, for a total of (TARGET_DURATION_MS*2/5) |
685 | * // packets. |
686 | * unsigned char *data[(TARGET_DURATION_MS*2/5)+1]; |
687 | * opus_int32 len[(TARGET_DURATION_MS*2/5)+1]; |
688 | * int nb_packets; |
689 | * unsigned char out[1277*(TARGET_DURATION_MS*2/2)]; |
690 | * opus_int32 out_len; |
691 | * int prev_toc; |
692 | * nb_packets = 0; |
693 | * while (get_next_packet(data+nb_packets, len+nb_packets)) |
694 | * { |
695 | * int nb_frames; |
696 | * int err; |
697 | * nb_frames = opus_packet_get_nb_frames(data[nb_packets], len[nb_packets]); |
698 | * if (nb_frames < 1) |
699 | * { |
700 | * release_packets(data, nb_packets+1); |
701 | * return nb_frames; |
702 | * } |
703 | * nb_frames += opus_repacketizer_get_nb_frames(rp); |
704 | * // If adding the next packet would exceed our target, or it has an |
705 | * // incompatible TOC sequence, output the packets we already have before |
706 | * // submitting it. |
707 | * // N.B., The nb_packets > 0 check ensures we've submitted at least one |
708 | * // packet since the last call to opus_repacketizer_init(). Otherwise a |
709 | * // single packet longer than TARGET_DURATION_MS would cause us to try to |
710 | * // output an (invalid) empty packet. It also ensures that prev_toc has |
711 | * // been set to a valid value. Additionally, len[nb_packets] > 0 is |
712 | * // guaranteed by the call to opus_packet_get_nb_frames() above, so the |
713 | * // reference to data[nb_packets][0] should be valid. |
714 | * if (nb_packets > 0 && ( |
715 | * ((prev_toc & 0xFC) != (data[nb_packets][0] & 0xFC)) || |
716 | * opus_packet_get_samples_per_frame(data[nb_packets], 48000)*nb_frames > |
717 | * TARGET_DURATION_MS*48)) |
718 | * { |
719 | * out_len = opus_repacketizer_out(rp, out, sizeof(out)); |
720 | * if (out_len < 0) |
721 | * { |
722 | * release_packets(data, nb_packets+1); |
723 | * return (int)out_len; |
724 | * } |
725 | * output_next_packet(out, out_len); |
726 | * opus_repacketizer_init(rp); |
727 | * release_packets(data, nb_packets); |
728 | * data[0] = data[nb_packets]; |
729 | * len[0] = len[nb_packets]; |
730 | * nb_packets = 0; |
731 | * } |
732 | * err = opus_repacketizer_cat(rp, data[nb_packets], len[nb_packets]); |
733 | * if (err != OPUS_OK) |
734 | * { |
735 | * release_packets(data, nb_packets+1); |
736 | * return err; |
737 | * } |
738 | * prev_toc = data[nb_packets][0]; |
739 | * nb_packets++; |
740 | * } |
741 | * // Output the final, partial packet. |
742 | * if (nb_packets > 0) |
743 | * { |
744 | * out_len = opus_repacketizer_out(rp, out, sizeof(out)); |
745 | * release_packets(data, nb_packets); |
746 | * if (out_len < 0) |
747 | * return (int)out_len; |
748 | * output_next_packet(out, out_len); |
749 | * } |
750 | * @endcode |
751 | * |
752 | * An alternate way of merging packets is to simply call opus_repacketizer_cat() |
753 | * unconditionally until it fails. At that point, the merged packet can be |
754 | * obtained with opus_repacketizer_out() and the input packet for which |
755 | * opus_repacketizer_cat() needs to be re-added to a newly reinitialized |
756 | * repacketizer state. |
757 | */ |
758 | |
759 | typedef struct OpusRepacketizer OpusRepacketizer; |
760 | |
761 | /** Gets the size of an <code>OpusRepacketizer</code> structure. |
762 | * @returns The size in bytes. |
763 | */ |
764 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_repacketizer_get_size(void); |
765 | |
766 | /** (Re)initializes a previously allocated repacketizer state. |
767 | * The state must be at least the size returned by opus_repacketizer_get_size(). |
768 | * This can be used for applications which use their own allocator instead of |
769 | * malloc(). |
770 | * It must also be called to reset the queue of packets waiting to be |
771 | * repacketized, which is necessary if the maximum packet duration of 120 ms |
772 | * is reached or if you wish to submit packets with a different Opus |
773 | * configuration (coding mode, audio bandwidth, frame size, or channel count). |
774 | * Failure to do so will prevent a new packet from being added with |
775 | * opus_repacketizer_cat(). |
776 | * @see opus_repacketizer_create |
777 | * @see opus_repacketizer_get_size |
778 | * @see opus_repacketizer_cat |
779 | * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state to |
780 | * (re)initialize. |
781 | * @returns A pointer to the same repacketizer state that was passed in. |
782 | */ |
783 | OPUS_EXPORT OpusRepacketizer *opus_repacketizer_init(OpusRepacketizer *rp) OPUS_ARG_NONNULL(1); |
784 | |
785 | /** Allocates memory and initializes the new repacketizer with |
786 | * opus_repacketizer_init(). |
787 | */ |
788 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusRepacketizer *opus_repacketizer_create(void); |
789 | |
790 | /** Frees an <code>OpusRepacketizer</code> allocated by |
791 | * opus_repacketizer_create(). |
792 | * @param[in] rp <tt>OpusRepacketizer*</tt>: State to be freed. |
793 | */ |
794 | OPUS_EXPORT void opus_repacketizer_destroy(OpusRepacketizer *rp); |
795 | |
796 | /** Add a packet to the current repacketizer state. |
797 | * This packet must match the configuration of any packets already submitted |
798 | * for repacketization since the last call to opus_repacketizer_init(). |
799 | * This means that it must have the same coding mode, audio bandwidth, frame |
800 | * size, and channel count. |
801 | * This can be checked in advance by examining the top 6 bits of the first |
802 | * byte of the packet, and ensuring they match the top 6 bits of the first |
803 | * byte of any previously submitted packet. |
804 | * The total duration of audio in the repacketizer state also must not exceed |
805 | * 120 ms, the maximum duration of a single packet, after adding this packet. |
806 | * |
807 | * The contents of the current repacketizer state can be extracted into new |
808 | * packets using opus_repacketizer_out() or opus_repacketizer_out_range(). |
809 | * |
810 | * In order to add a packet with a different configuration or to add more |
811 | * audio beyond 120 ms, you must clear the repacketizer state by calling |
812 | * opus_repacketizer_init(). |
813 | * If a packet is too large to add to the current repacketizer state, no part |
814 | * of it is added, even if it contains multiple frames, some of which might |
815 | * fit. |
816 | * If you wish to be able to add parts of such packets, you should first use |
817 | * another repacketizer to split the packet into pieces and add them |
818 | * individually. |
819 | * @see opus_repacketizer_out_range |
820 | * @see opus_repacketizer_out |
821 | * @see opus_repacketizer_init |
822 | * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state to which to |
823 | * add the packet. |
824 | * @param[in] data <tt>const unsigned char*</tt>: The packet data. |
825 | * The application must ensure |
826 | * this pointer remains valid |
827 | * until the next call to |
828 | * opus_repacketizer_init() or |
829 | * opus_repacketizer_destroy(). |
830 | * @param len <tt>opus_int32</tt>: The number of bytes in the packet data. |
831 | * @returns An error code indicating whether or not the operation succeeded. |
832 | * @retval #OPUS_OK The packet's contents have been added to the repacketizer |
833 | * state. |
834 | * @retval #OPUS_INVALID_PACKET The packet did not have a valid TOC sequence, |
835 | * the packet's TOC sequence was not compatible |
836 | * with previously submitted packets (because |
837 | * the coding mode, audio bandwidth, frame size, |
838 | * or channel count did not match), or adding |
839 | * this packet would increase the total amount of |
840 | * audio stored in the repacketizer state to more |
841 | * than 120 ms. |
842 | */ |
843 | OPUS_EXPORT int opus_repacketizer_cat(OpusRepacketizer *rp, const unsigned char *data, opus_int32 len) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2); |
844 | |
845 | |
846 | /** Construct a new packet from data previously submitted to the repacketizer |
847 | * state via opus_repacketizer_cat(). |
848 | * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state from which to |
849 | * construct the new packet. |
850 | * @param begin <tt>int</tt>: The index of the first frame in the current |
851 | * repacketizer state to include in the output. |
852 | * @param end <tt>int</tt>: One past the index of the last frame in the |
853 | * current repacketizer state to include in the |
854 | * output. |
855 | * @param[out] data <tt>const unsigned char*</tt>: The buffer in which to |
856 | * store the output packet. |
857 | * @param maxlen <tt>opus_int32</tt>: The maximum number of bytes to store in |
858 | * the output buffer. In order to guarantee |
859 | * success, this should be at least |
860 | * <code>1276</code> for a single frame, |
861 | * or for multiple frames, |
862 | * <code>1277*(end-begin)</code>. |
863 | * However, <code>1*(end-begin)</code> plus |
864 | * the size of all packet data submitted to |
865 | * the repacketizer since the last call to |
866 | * opus_repacketizer_init() or |
867 | * opus_repacketizer_create() is also |
868 | * sufficient, and possibly much smaller. |
869 | * @returns The total size of the output packet on success, or an error code |
870 | * on failure. |
871 | * @retval #OPUS_BAD_ARG <code>[begin,end)</code> was an invalid range of |
872 | * frames (begin < 0, begin >= end, or end > |
873 | * opus_repacketizer_get_nb_frames()). |
874 | * @retval #OPUS_BUFFER_TOO_SMALL \a maxlen was insufficient to contain the |
875 | * complete output packet. |
876 | */ |
877 | OPUS_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); |
878 | |
879 | /** Return the total number of frames contained in packet data submitted to |
880 | * the repacketizer state so far via opus_repacketizer_cat() since the last |
881 | * call to opus_repacketizer_init() or opus_repacketizer_create(). |
882 | * This defines the valid range of packets that can be extracted with |
883 | * opus_repacketizer_out_range() or opus_repacketizer_out(). |
884 | * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state containing the |
885 | * frames. |
886 | * @returns The total number of frames contained in the packet data submitted |
887 | * to the repacketizer state. |
888 | */ |
889 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_repacketizer_get_nb_frames(OpusRepacketizer *rp) OPUS_ARG_NONNULL(1); |
890 | |
891 | /** Construct a new packet from data previously submitted to the repacketizer |
892 | * state via opus_repacketizer_cat(). |
893 | * This is a convenience routine that returns all the data submitted so far |
894 | * in a single packet. |
895 | * It is equivalent to calling |
896 | * @code |
897 | * opus_repacketizer_out_range(rp, 0, opus_repacketizer_get_nb_frames(rp), |
898 | * data, maxlen) |
899 | * @endcode |
900 | * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state from which to |
901 | * construct the new packet. |
902 | * @param[out] data <tt>const unsigned char*</tt>: The buffer in which to |
903 | * store the output packet. |
904 | * @param maxlen <tt>opus_int32</tt>: The maximum number of bytes to store in |
905 | * the output buffer. In order to guarantee |
906 | * success, this should be at least |
907 | * <code>1277*opus_repacketizer_get_nb_frames(rp)</code>. |
908 | * However, |
909 | * <code>1*opus_repacketizer_get_nb_frames(rp)</code> |
910 | * plus the size of all packet data |
911 | * submitted to the repacketizer since the |
912 | * last call to opus_repacketizer_init() or |
913 | * opus_repacketizer_create() is also |
914 | * sufficient, and possibly much smaller. |
915 | * @returns The total size of the output packet on success, or an error code |
916 | * on failure. |
917 | * @retval #OPUS_BUFFER_TOO_SMALL \a maxlen was insufficient to contain the |
918 | * complete output packet. |
919 | */ |
920 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_repacketizer_out(OpusRepacketizer *rp, unsigned char *data, opus_int32 maxlen) OPUS_ARG_NONNULL(1); |
921 | |
922 | /** Pads a given Opus packet to a larger size (possibly changing the TOC sequence). |
923 | * @param[in,out] data <tt>const unsigned char*</tt>: The buffer containing the |
924 | * packet to pad. |
925 | * @param len <tt>opus_int32</tt>: The size of the packet. |
926 | * This must be at least 1. |
927 | * @param new_len <tt>opus_int32</tt>: The desired size of the packet after padding. |
928 | * This must be at least as large as len. |
929 | * @returns an error code |
930 | * @retval #OPUS_OK \a on success. |
931 | * @retval #OPUS_BAD_ARG \a len was less than 1 or new_len was less than len. |
932 | * @retval #OPUS_INVALID_PACKET \a data did not contain a valid Opus packet. |
933 | */ |
934 | OPUS_EXPORT int opus_packet_pad(unsigned char *data, opus_int32 len, opus_int32 new_len); |
935 | |
936 | /** Remove all padding from a given Opus packet and rewrite the TOC sequence to |
937 | * minimize space usage. |
938 | * @param[in,out] data <tt>const unsigned char*</tt>: The buffer containing the |
939 | * packet to strip. |
940 | * @param len <tt>opus_int32</tt>: The size of the packet. |
941 | * This must be at least 1. |
942 | * @returns The new size of the output packet on success, or an error code |
943 | * on failure. |
944 | * @retval #OPUS_BAD_ARG \a len was less than 1. |
945 | * @retval #OPUS_INVALID_PACKET \a data did not contain a valid Opus packet. |
946 | */ |
947 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_packet_unpad(unsigned char *data, opus_int32 len); |
948 | |
949 | /** Pads a given Opus multi-stream packet to a larger size (possibly changing the TOC sequence). |
950 | * @param[in,out] data <tt>const unsigned char*</tt>: The buffer containing the |
951 | * packet to pad. |
952 | * @param len <tt>opus_int32</tt>: The size of the packet. |
953 | * This must be at least 1. |
954 | * @param new_len <tt>opus_int32</tt>: The desired size of the packet after padding. |
955 | * This must be at least 1. |
956 | * @param nb_streams <tt>opus_int32</tt>: The number of streams (not channels) in the packet. |
957 | * This must be at least as large as len. |
958 | * @returns an error code |
959 | * @retval #OPUS_OK \a on success. |
960 | * @retval #OPUS_BAD_ARG \a len was less than 1. |
961 | * @retval #OPUS_INVALID_PACKET \a data did not contain a valid Opus packet. |
962 | */ |
963 | OPUS_EXPORT int opus_multistream_packet_pad(unsigned char *data, opus_int32 len, opus_int32 new_len, int nb_streams); |
964 | |
965 | /** Remove all padding from a given Opus multi-stream packet and rewrite the TOC sequence to |
966 | * minimize space usage. |
967 | * @param[in,out] data <tt>const unsigned char*</tt>: The buffer containing the |
968 | * packet to strip. |
969 | * @param len <tt>opus_int32</tt>: The size of the packet. |
970 | * This must be at least 1. |
971 | * @param nb_streams <tt>opus_int32</tt>: The number of streams (not channels) in the packet. |
972 | * This must be at least 1. |
973 | * @returns The new size of the output packet on success, or an error code |
974 | * on failure. |
975 | * @retval #OPUS_BAD_ARG \a len was less than 1 or new_len was less than len. |
976 | * @retval #OPUS_INVALID_PACKET \a data did not contain a valid Opus packet. |
977 | */ |
978 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_multistream_packet_unpad(unsigned char *data, opus_int32 len, int nb_streams); |
979 | |
980 | /**@}*/ |
981 | |
982 | #ifdef __cplusplus |
983 | } |
984 | #endif |
985 | |
986 | #endif /* OPUS_H */ |
987 |