diff options
Diffstat (limited to 'lib/rbcodec/codecs/libopus/opus.h')
-rw-r--r-- | lib/rbcodec/codecs/libopus/opus.h | 882 |
1 files changed, 882 insertions, 0 deletions
diff --git a/lib/rbcodec/codecs/libopus/opus.h b/lib/rbcodec/codecs/libopus/opus.h new file mode 100644 index 0000000000..c242fec0e7 --- /dev/null +++ b/lib/rbcodec/codecs/libopus/opus.h | |||
@@ -0,0 +1,882 @@ | |||
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 | * @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 assuptions 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)</li> | ||
140 | * </ul> | ||
141 | * | ||
142 | * opus_encode() and opus_encode_frame() return the number of bytes actually written to the packet. | ||
143 | * The return value <b>can be negative</b>, which indicates that an error has occurred. If the return value | ||
144 | * is 1 byte, then the packet does not need to be transmitted (DTX). | ||
145 | * | ||
146 | * Once the encoder state if no longer needed, it can be destroyed with | ||
147 | * | ||
148 | * @code | ||
149 | * opus_encoder_destroy(enc); | ||
150 | * @endcode | ||
151 | * | ||
152 | * If the encoder was created with opus_encoder_init() rather than opus_encoder_create(), | ||
153 | * then no action is required aside from potentially freeing the memory that was manually | ||
154 | * allocated for it (calling free(enc) for the example above) | ||
155 | * | ||
156 | */ | ||
157 | |||
158 | /** Opus encoder state. | ||
159 | * This contains the complete state of an Opus encoder. | ||
160 | * It is position independent and can be freely copied. | ||
161 | * @see opus_encoder_create,opus_encoder_init | ||
162 | */ | ||
163 | typedef struct OpusEncoder OpusEncoder; | ||
164 | |||
165 | /** Gets the size of an <code>OpusEncoder</code> structure. | ||
166 | * @param[in] channels <tt>int</tt>: Number of channels. | ||
167 | * This must be 1 or 2. | ||
168 | * @returns The size in bytes. | ||
169 | */ | ||
170 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_encoder_get_size(int channels); | ||
171 | |||
172 | /** | ||
173 | */ | ||
174 | |||
175 | /** Allocates and initializes an encoder state. | ||
176 | * There are three coding modes: | ||
177 | * | ||
178 | * @ref OPUS_APPLICATION_VOIP gives best quality at a given bitrate for voice | ||
179 | * signals. It enhances the input signal by high-pass filtering and | ||
180 | * emphasizing formants and harmonics. Optionally it includes in-band | ||
181 | * forward error correction to protect against packet loss. Use this | ||
182 | * mode for typical VoIP applications. Because of the enhancement, | ||
183 | * even at high bitrates the output may sound different from the input. | ||
184 | * | ||
185 | * @ref OPUS_APPLICATION_AUDIO gives best quality at a given bitrate for most | ||
186 | * non-voice signals like music. Use this mode for music and mixed | ||
187 | * (music/voice) content, broadcast, and applications requiring less | ||
188 | * than 15 ms of coding delay. | ||
189 | * | ||
190 | * @ref OPUS_APPLICATION_RESTRICTED_LOWDELAY configures low-delay mode that | ||
191 | * disables the speech-optimized mode in exchange for slightly reduced delay. | ||
192 | * This mode can only be set on an newly initialized or freshly reset encoder | ||
193 | * because it changes the codec delay. | ||
194 | * | ||
195 | * This is useful when the caller knows that the speech-optimized modes will not be needed (use with caution). | ||
196 | * @param [in] Fs <tt>opus_int32</tt>: Sampling rate of input signal (Hz) | ||
197 | * This must be one of 8000, 12000, 16000, | ||
198 | * 24000, or 48000. | ||
199 | * @param [in] channels <tt>int</tt>: Number of channels (1 or 2) in input signal | ||
200 | * @param [in] application <tt>int</tt>: Coding mode (@ref OPUS_APPLICATION_VOIP/@ref OPUS_APPLICATION_AUDIO/@ref OPUS_APPLICATION_RESTRICTED_LOWDELAY) | ||
201 | * @param [out] error <tt>int*</tt>: @ref opus_errorcodes | ||
202 | * @note Regardless of the sampling rate and number channels selected, the Opus encoder | ||
203 | * can switch to a lower audio bandwidth or number of channels if the bitrate | ||
204 | * selected is too low. This also means that it is safe to always use 48 kHz stereo input | ||
205 | * and let the encoder optimize the encoding. | ||
206 | */ | ||
207 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusEncoder *opus_encoder_create( | ||
208 | opus_int32 Fs, | ||
209 | int channels, | ||
210 | int application, | ||
211 | int *error | ||
212 | ); | ||
213 | |||
214 | /** Initializes a previously allocated encoder state | ||
215 | * The memory pointed to by st must be at least the size returned by opus_encoder_get_size(). | ||
216 | * This is intended for applications which use their own allocator instead of malloc. | ||
217 | * @see opus_encoder_create(),opus_encoder_get_size() | ||
218 | * To reset a previously initialized state, use the #OPUS_RESET_STATE CTL. | ||
219 | * @param [in] st <tt>OpusEncoder*</tt>: Encoder state | ||
220 | * @param [in] Fs <tt>opus_int32</tt>: Sampling rate of input signal (Hz) | ||
221 | * This must be one of 8000, 12000, 16000, | ||
222 | * 24000, or 48000. | ||
223 | * @param [in] channels <tt>int</tt>: Number of channels (1 or 2) in input signal | ||
224 | * @param [in] application <tt>int</tt>: Coding mode (OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO/OPUS_APPLICATION_RESTRICTED_LOWDELAY) | ||
225 | * @retval #OPUS_OK Success or @ref opus_errorcodes | ||
226 | */ | ||
227 | OPUS_EXPORT int opus_encoder_init( | ||
228 | OpusEncoder *st, | ||
229 | opus_int32 Fs, | ||
230 | int channels, | ||
231 | int application | ||
232 | ) OPUS_ARG_NONNULL(1); | ||
233 | |||
234 | /** Encodes an Opus frame. | ||
235 | * @param [in] st <tt>OpusEncoder*</tt>: Encoder state | ||
236 | * @param [in] pcm <tt>opus_int16*</tt>: Input signal (interleaved if 2 channels). length is frame_size*channels*sizeof(opus_int16) | ||
237 | * @param [in] frame_size <tt>int</tt>: Number of samples per channel in the | ||
238 | * input signal. | ||
239 | * This must be an Opus frame size for | ||
240 | * the encoder's sampling rate. | ||
241 | * For example, at 48 kHz the permitted | ||
242 | * values are 120, 240, 480, 960, 1920, | ||
243 | * and 2880. | ||
244 | * Passing in a duration of less than | ||
245 | * 10 ms (480 samples at 48 kHz) will | ||
246 | * prevent the encoder from using the LPC | ||
247 | * or hybrid modes. | ||
248 | * @param [out] data <tt>unsigned char*</tt>: Output payload. | ||
249 | * This must contain storage for at | ||
250 | * least \a max_data_bytes. | ||
251 | * @param [in] max_data_bytes <tt>opus_int32</tt>: Size of the allocated | ||
252 | * memory for the output | ||
253 | * payload. This may be | ||
254 | * used to impose an upper limit on | ||
255 | * the variable bitrate, but should | ||
256 | * not be used as the only bitrate | ||
257 | * control. | ||
258 | * @returns The length of the encoded packet (in bytes) on success or a | ||
259 | * negative error code (see @ref opus_errorcodes) on failure. | ||
260 | */ | ||
261 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_encode( | ||
262 | OpusEncoder *st, | ||
263 | const opus_int16 *pcm, | ||
264 | int frame_size, | ||
265 | unsigned char *data, | ||
266 | opus_int32 max_data_bytes | ||
267 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4); | ||
268 | |||
269 | /** Encodes an Opus frame from floating point input. | ||
270 | * @param [in] st <tt>OpusEncoder*</tt>: Encoder state | ||
271 | * @param [in] pcm <tt>float*</tt>: Input in float format (interleaved if 2 channels), with a normal range of +/-1.0. | ||
272 | * Samples with a range beyond +/-1.0 are supported but will | ||
273 | * be clipped by decoders using the integer API and should | ||
274 | * only be used if it is known that the far end supports | ||
275 | * extended dynamic range. | ||
276 | * length is frame_size*channels*sizeof(float) | ||
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 variable bitrate, but should | ||
296 | * not be used as the only bitrate | ||
297 | * control. | ||
298 | * @returns The length of the encoded packet (in bytes) on success or a | ||
299 | * negative error code (see @ref opus_errorcodes) on failure. | ||
300 | */ | ||
301 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_encode_float( | ||
302 | OpusEncoder *st, | ||
303 | const float *pcm, | ||
304 | int frame_size, | ||
305 | unsigned char *data, | ||
306 | opus_int32 max_data_bytes | ||
307 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4); | ||
308 | |||
309 | /** Frees an <code>OpusEncoder</code> allocated by opus_encoder_create(). | ||
310 | * @param[in] st <tt>OpusEncoder*</tt>: State to be freed. | ||
311 | */ | ||
312 | OPUS_EXPORT void opus_encoder_destroy(OpusEncoder *st); | ||
313 | |||
314 | /** Perform a CTL function on an Opus encoder. | ||
315 | * | ||
316 | * Generally the request and subsequent arguments are generated | ||
317 | * by a convenience macro. | ||
318 | * @param st <tt>OpusEncoder*</tt>: Encoder state. | ||
319 | * @param request This and all remaining parameters should be replaced by one | ||
320 | * of the convenience macros in @ref opus_genericctls or | ||
321 | * @ref opus_encoderctls. | ||
322 | * @see opus_genericctls | ||
323 | * @see opus_encoderctls | ||
324 | */ | ||
325 | OPUS_EXPORT int opus_encoder_ctl(OpusEncoder *st, int request, ...) OPUS_ARG_NONNULL(1); | ||
326 | /**@}*/ | ||
327 | |||
328 | /** @defgroup opus_decoder Opus Decoder | ||
329 | * @{ | ||
330 | * | ||
331 | * @brief This page describes the process and functions used to decode Opus. | ||
332 | * | ||
333 | * The decoding process also starts with creating a decoder | ||
334 | * state. This can be done with: | ||
335 | * @code | ||
336 | * int error; | ||
337 | * OpusDecoder *dec; | ||
338 | * dec = opus_decoder_create(Fs, channels, &error); | ||
339 | * @endcode | ||
340 | * where | ||
341 | * @li Fs is the sampling rate and must be 8000, 12000, 16000, 24000, or 48000 | ||
342 | * @li channels is the number of channels (1 or 2) | ||
343 | * @li error will hold the error code in case or failure (or #OPUS_OK on success) | ||
344 | * @li the return value is a newly created decoder state to be used for decoding | ||
345 | * | ||
346 | * While opus_decoder_create() allocates memory for the state, it's also possible | ||
347 | * to initialize pre-allocated memory: | ||
348 | * @code | ||
349 | * int size; | ||
350 | * int error; | ||
351 | * OpusDecoder *dec; | ||
352 | * size = opus_decoder_get_size(channels); | ||
353 | * dec = malloc(size); | ||
354 | * error = opus_decoder_init(dec, Fs, channels); | ||
355 | * @endcode | ||
356 | * where opus_decoder_get_size() returns the required size for the decoder state. Note that | ||
357 | * future versions of this code may change the size, so no assuptions should be made about it. | ||
358 | * | ||
359 | * The decoder state is always continuous in memory and only a shallow copy is sufficient | ||
360 | * to copy it (e.g. memcpy()) | ||
361 | * | ||
362 | * To decode a frame, opus_decode() or opus_decode_float() must be called with a packet of compressed audio data: | ||
363 | * @code | ||
364 | * frame_size = opus_decode(dec, packet, len, decoded, max_size, 0); | ||
365 | * @endcode | ||
366 | * where | ||
367 | * | ||
368 | * @li packet is the byte array containing the compressed data | ||
369 | * @li len is the exact number of bytes contained in the packet | ||
370 | * @li decoded is the decoded audio data in opus_int16 (or float for opus_decode_float()) | ||
371 | * @li max_size is the max duration of the frame in samples (per channel) that can fit into the decoded_frame array | ||
372 | * | ||
373 | * opus_decode() and opus_decode_float() return the number of samples (per channel) decoded from the packet. | ||
374 | * If that value is negative, then an error has occured. This can occur if the packet is corrupted or if the audio | ||
375 | * buffer is too small to hold the decoded audio. | ||
376 | * | ||
377 | * Opus is a stateful codec with overlapping blocks and as a result Opus | ||
378 | * packets are not coded independently of each other. Packets must be | ||
379 | * passed into the decoder serially and in the correct order for a correct | ||
380 | * decode. Lost packets can be replaced with loss concealment by calling | ||
381 | * the decoder with a null pointer and zero length for the missing packet. | ||
382 | * | ||
383 | * A single codec state may only be accessed from a single thread at | ||
384 | * a time and any required locking must be performed by the caller. Separate | ||
385 | * streams must be decoded with separate decoder states and can be decoded | ||
386 | * in parallel unless the library was compiled with NONTHREADSAFE_PSEUDOSTACK | ||
387 | * defined. | ||
388 | * | ||
389 | */ | ||
390 | |||
391 | /** Opus decoder state. | ||
392 | * This contains the complete state of an Opus decoder. | ||
393 | * It is position independent and can be freely copied. | ||
394 | * @see opus_decoder_create,opus_decoder_init | ||
395 | */ | ||
396 | typedef struct OpusDecoder OpusDecoder; | ||
397 | |||
398 | /** Gets the size of an <code>OpusDecoder</code> structure. | ||
399 | * @param [in] channels <tt>int</tt>: Number of channels. | ||
400 | * This must be 1 or 2. | ||
401 | * @returns The size in bytes. | ||
402 | */ | ||
403 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decoder_get_size(int channels); | ||
404 | |||
405 | /** Allocates and initializes a decoder state. | ||
406 | * @param [in] Fs <tt>opus_int32</tt>: Sample rate to decode at (Hz). | ||
407 | * This must be one of 8000, 12000, 16000, | ||
408 | * 24000, or 48000. | ||
409 | * @param [in] channels <tt>int</tt>: Number of channels (1 or 2) to decode | ||
410 | * @param [out] error <tt>int*</tt>: #OPUS_OK Success or @ref opus_errorcodes | ||
411 | * | ||
412 | * Internally Opus stores data at 48000 Hz, so that should be the default | ||
413 | * value for Fs. However, the decoder can efficiently decode to buffers | ||
414 | * at 8, 12, 16, and 24 kHz so if for some reason the caller cannot use | ||
415 | * data at the full sample rate, or knows the compressed data doesn't | ||
416 | * use the full frequency range, it can request decoding at a reduced | ||
417 | * rate. Likewise, the decoder is capable of filling in either mono or | ||
418 | * interleaved stereo pcm buffers, at the caller's request. | ||
419 | */ | ||
420 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusDecoder *opus_decoder_create( | ||
421 | opus_int32 Fs, | ||
422 | int channels, | ||
423 | int *error | ||
424 | ); | ||
425 | |||
426 | /** Initializes a previously allocated decoder state. | ||
427 | * The state must be at least the size returned by opus_decoder_get_size(). | ||
428 | * This is intended for applications which use their own allocator instead of malloc. @see opus_decoder_create,opus_decoder_get_size | ||
429 | * To reset a previously initialized state, use the #OPUS_RESET_STATE CTL. | ||
430 | * @param [in] st <tt>OpusDecoder*</tt>: Decoder state. | ||
431 | * @param [in] Fs <tt>opus_int32</tt>: Sampling rate to decode to (Hz). | ||
432 | * This must be one of 8000, 12000, 16000, | ||
433 | * 24000, or 48000. | ||
434 | * @param [in] channels <tt>int</tt>: Number of channels (1 or 2) to decode | ||
435 | * @retval #OPUS_OK Success or @ref opus_errorcodes | ||
436 | */ | ||
437 | OPUS_EXPORT int opus_decoder_init( | ||
438 | OpusDecoder *st, | ||
439 | opus_int32 Fs, | ||
440 | int channels | ||
441 | ) OPUS_ARG_NONNULL(1); | ||
442 | |||
443 | /** Decode an Opus packet. | ||
444 | * @param [in] st <tt>OpusDecoder*</tt>: Decoder state | ||
445 | * @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to indicate packet loss | ||
446 | * @param [in] len <tt>opus_int32</tt>: Number of bytes in payload* | ||
447 | * @param [out] pcm <tt>opus_int16*</tt>: Output signal (interleaved if 2 channels). length | ||
448 | * is frame_size*channels*sizeof(opus_int16) | ||
449 | * @param [in] frame_size Number of samples per channel of available space in \a pcm. | ||
450 | * If this is less than the maximum frame size (120 ms), this function will | ||
451 | * not be capable of decoding some packets. | ||
452 | * @param [in] decode_fec <tt>int</tt>: Flag (0 or 1) to request that any in-band forward error correction data be | ||
453 | * decoded. If no such data is available, the frame is decoded as if it were lost. | ||
454 | * @returns Number of decoded samples or @ref opus_errorcodes | ||
455 | */ | ||
456 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decode( | ||
457 | OpusDecoder *st, | ||
458 | const unsigned char *data, | ||
459 | opus_int32 len, | ||
460 | opus_int16 *pcm, | ||
461 | int frame_size, | ||
462 | int decode_fec | ||
463 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4); | ||
464 | |||
465 | /** Decode an Opus packet with floating point output. | ||
466 | * @param [in] st <tt>OpusDecoder*</tt>: Decoder state | ||
467 | * @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to indicate packet loss | ||
468 | * @param [in] len <tt>opus_int32</tt>: Number of bytes in payload | ||
469 | * @param [out] pcm <tt>float*</tt>: Output signal (interleaved if 2 channels). length | ||
470 | * is frame_size*channels*sizeof(float) | ||
471 | * @param [in] frame_size Number of samples per channel of available space in *pcm, | ||
472 | * if less than the maximum frame size (120ms) some frames can not be decoded | ||
473 | * @param [in] decode_fec <tt>int</tt>: Flag (0 or 1) to request that any in-band forward error correction data be | ||
474 | * decoded. If no such data is available the frame is decoded as if it were lost. | ||
475 | * @returns Number of decoded samples or @ref opus_errorcodes | ||
476 | */ | ||
477 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decode_float( | ||
478 | OpusDecoder *st, | ||
479 | const unsigned char *data, | ||
480 | opus_int32 len, | ||
481 | float *pcm, | ||
482 | int frame_size, | ||
483 | int decode_fec | ||
484 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4); | ||
485 | |||
486 | /** Perform a CTL function on an Opus decoder. | ||
487 | * | ||
488 | * Generally the request and subsequent arguments are generated | ||
489 | * by a convenience macro. | ||
490 | * @param st <tt>OpusDecoder*</tt>: Decoder state. | ||
491 | * @param request This and all remaining parameters should be replaced by one | ||
492 | * of the convenience macros in @ref opus_genericctls or | ||
493 | * @ref opus_decoderctls. | ||
494 | * @see opus_genericctls | ||
495 | * @see opus_decoderctls | ||
496 | */ | ||
497 | OPUS_EXPORT int opus_decoder_ctl(OpusDecoder *st, int request, ...) OPUS_ARG_NONNULL(1); | ||
498 | |||
499 | /** Frees an <code>OpusDecoder</code> allocated by opus_decoder_create(). | ||
500 | * @param[in] st <tt>OpusDecoder*</tt>: State to be freed. | ||
501 | */ | ||
502 | OPUS_EXPORT void opus_decoder_destroy(OpusDecoder *st); | ||
503 | |||
504 | /** Parse an opus packet into one or more frames. | ||
505 | * Opus_decode will perform this operation internally so most applications do | ||
506 | * not need to use this function. | ||
507 | * This function does not copy the frames, the returned pointers are pointers into | ||
508 | * the input packet. | ||
509 | * @param [in] data <tt>char*</tt>: Opus packet to be parsed | ||
510 | * @param [in] len <tt>opus_int32</tt>: size of data | ||
511 | * @param [out] out_toc <tt>char*</tt>: TOC pointer | ||
512 | * @param [out] frames <tt>char*[48]</tt> encapsulated frames | ||
513 | * @param [out] size <tt>short[48]</tt> sizes of the encapsulated frames | ||
514 | * @param [out] payload_offset <tt>int*</tt>: returns the position of the payload within the packet (in bytes) | ||
515 | * @returns number of frames | ||
516 | */ | ||
517 | OPUS_EXPORT int opus_packet_parse( | ||
518 | const unsigned char *data, | ||
519 | opus_int32 len, | ||
520 | unsigned char *out_toc, | ||
521 | const unsigned char *frames[48], | ||
522 | short size[48], | ||
523 | int *payload_offset | ||
524 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4); | ||
525 | |||
526 | /** Gets the bandwidth of an Opus packet. | ||
527 | * @param [in] data <tt>char*</tt>: Opus packet | ||
528 | * @retval OPUS_BANDWIDTH_NARROWBAND Narrowband (4kHz bandpass) | ||
529 | * @retval OPUS_BANDWIDTH_MEDIUMBAND Mediumband (6kHz bandpass) | ||
530 | * @retval OPUS_BANDWIDTH_WIDEBAND Wideband (8kHz bandpass) | ||
531 | * @retval OPUS_BANDWIDTH_SUPERWIDEBAND Superwideband (12kHz bandpass) | ||
532 | * @retval OPUS_BANDWIDTH_FULLBAND Fullband (20kHz bandpass) | ||
533 | * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type | ||
534 | */ | ||
535 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_bandwidth(const unsigned char *data) OPUS_ARG_NONNULL(1); | ||
536 | |||
537 | /** Gets the number of samples per frame from an Opus packet. | ||
538 | * @param [in] data <tt>char*</tt>: Opus packet. | ||
539 | * This must contain at least one byte of | ||
540 | * data. | ||
541 | * @param [in] Fs <tt>opus_int32</tt>: Sampling rate in Hz. | ||
542 | * This must be a multiple of 400, or | ||
543 | * inaccurate results will be returned. | ||
544 | * @returns Number of samples per frame. | ||
545 | */ | ||
546 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_samples_per_frame(const unsigned char *data, opus_int32 Fs) OPUS_ARG_NONNULL(1); | ||
547 | |||
548 | /** Gets the number of channels from an Opus packet. | ||
549 | * @param [in] data <tt>char*</tt>: Opus packet | ||
550 | * @returns Number of channels | ||
551 | * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type | ||
552 | */ | ||
553 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_nb_channels(const unsigned char *data) OPUS_ARG_NONNULL(1); | ||
554 | |||
555 | /** Gets the number of frames in an Opus packet. | ||
556 | * @param [in] packet <tt>char*</tt>: Opus packet | ||
557 | * @param [in] len <tt>opus_int32</tt>: Length of packet | ||
558 | * @returns Number of frames | ||
559 | * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type | ||
560 | */ | ||
561 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_nb_frames(const unsigned char packet[], opus_int32 len) OPUS_ARG_NONNULL(1); | ||
562 | |||
563 | /** Gets the number of samples of an Opus packet. | ||
564 | * @param [in] dec <tt>OpusDecoder*</tt>: Decoder state | ||
565 | * @param [in] packet <tt>char*</tt>: Opus packet | ||
566 | * @param [in] len <tt>opus_int32</tt>: Length of packet | ||
567 | * @returns Number of samples | ||
568 | * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type | ||
569 | */ | ||
570 | 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); | ||
571 | /**@}*/ | ||
572 | |||
573 | /** @defgroup opus_repacketizer Repacketizer | ||
574 | * @{ | ||
575 | * | ||
576 | * The repacketizer can be used to merge multiple Opus packets into a single | ||
577 | * packet or alternatively to split Opus packets that have previously been | ||
578 | * merged. Splitting valid Opus packets is always guaranteed to succeed, | ||
579 | * whereas merging valid packets only succeeds if all frames have the same | ||
580 | * mode, bandwidth, and frame size, and when the total duration of the merged | ||
581 | * packet is no more than 120 ms. | ||
582 | * The repacketizer currently only operates on elementary Opus | ||
583 | * streams. It will not manipualte multistream packets successfully, except in | ||
584 | * the degenerate case where they consist of data from a single stream. | ||
585 | * | ||
586 | * The repacketizing process starts with creating a repacketizer state, either | ||
587 | * by calling opus_repacketizer_create() or by allocating the memory yourself, | ||
588 | * e.g., | ||
589 | * @code | ||
590 | * OpusRepacketizer *rp; | ||
591 | * rp = (OpusRepacketizer*)malloc(opus_repacketizer_get_size()); | ||
592 | * if (rp != NULL) | ||
593 | * opus_repacketizer_init(rp); | ||
594 | * @endcode | ||
595 | * | ||
596 | * Then the application should submit packets with opus_repacketizer_cat(), | ||
597 | * extract new packets with opus_repacketizer_out() or | ||
598 | * opus_repacketizer_out_range(), and then reset the state for the next set of | ||
599 | * input packets via opus_repacketizer_init(). | ||
600 | * | ||
601 | * For example, to split a sequence of packets into individual frames: | ||
602 | * @code | ||
603 | * unsigned char *data; | ||
604 | * int len; | ||
605 | * while (get_next_packet(&data, &len)) | ||
606 | * { | ||
607 | * unsigned char out[1276]; | ||
608 | * opus_int32 out_len; | ||
609 | * int nb_frames; | ||
610 | * int err; | ||
611 | * int i; | ||
612 | * err = opus_repacketizer_cat(rp, data, len); | ||
613 | * if (err != OPUS_OK) | ||
614 | * { | ||
615 | * release_packet(data); | ||
616 | * return err; | ||
617 | * } | ||
618 | * nb_frames = opus_repacketizer_get_nb_frames(rp); | ||
619 | * for (i = 0; i < nb_frames; i++) | ||
620 | * { | ||
621 | * out_len = opus_repacketizer_out_range(rp, i, i+1, out, sizeof(out)); | ||
622 | * if (out_len < 0) | ||
623 | * { | ||
624 | * release_packet(data); | ||
625 | * return (int)out_len; | ||
626 | * } | ||
627 | * output_next_packet(out, out_len); | ||
628 | * } | ||
629 | * opus_repacketizer_init(rp); | ||
630 | * release_packet(data); | ||
631 | * } | ||
632 | * @endcode | ||
633 | * | ||
634 | * Alternatively, to combine a sequence of frames into packets that each | ||
635 | * contain up to <code>TARGET_DURATION_MS</code> milliseconds of data: | ||
636 | * @code | ||
637 | * // The maximum number of packets with duration TARGET_DURATION_MS occurs | ||
638 | * // when the frame size is 2.5 ms, for a total of (TARGET_DURATION_MS*2/5) | ||
639 | * // packets. | ||
640 | * unsigned char *data[(TARGET_DURATION_MS*2/5)+1]; | ||
641 | * opus_int32 len[(TARGET_DURATION_MS*2/5)+1]; | ||
642 | * int nb_packets; | ||
643 | * unsigned char out[1277*(TARGET_DURATION_MS*2/2)]; | ||
644 | * opus_int32 out_len; | ||
645 | * int prev_toc; | ||
646 | * nb_packets = 0; | ||
647 | * while (get_next_packet(data+nb_packets, len+nb_packets)) | ||
648 | * { | ||
649 | * int nb_frames; | ||
650 | * int err; | ||
651 | * nb_frames = opus_packet_get_nb_frames(data[nb_packets], len[nb_packets]); | ||
652 | * if (nb_frames < 1) | ||
653 | * { | ||
654 | * release_packets(data, nb_packets+1); | ||
655 | * return nb_frames; | ||
656 | * } | ||
657 | * nb_frames += opus_repacketizer_get_nb_frames(rp); | ||
658 | * // If adding the next packet would exceed our target, or it has an | ||
659 | * // incompatible TOC sequence, output the packets we already have before | ||
660 | * // submitting it. | ||
661 | * // N.B., The nb_packets > 0 check ensures we've submitted at least one | ||
662 | * // packet since the last call to opus_repacketizer_init(). Otherwise a | ||
663 | * // single packet longer than TARGET_DURATION_MS would cause us to try to | ||
664 | * // output an (invalid) empty packet. It also ensures that prev_toc has | ||
665 | * // been set to a valid value. Additionally, len[nb_packets] > 0 is | ||
666 | * // guaranteed by the call to opus_packet_get_nb_frames() above, so the | ||
667 | * // reference to data[nb_packets][0] should be valid. | ||
668 | * if (nb_packets > 0 && ( | ||
669 | * ((prev_toc & 0xFC) != (data[nb_packets][0] & 0xFC)) || | ||
670 | * opus_packet_get_samples_per_frame(data[nb_packets], 48000)*nb_frames > | ||
671 | * TARGET_DURATION_MS*48)) | ||
672 | * { | ||
673 | * out_len = opus_repacketizer_out(rp, out, sizeof(out)); | ||
674 | * if (out_len < 0) | ||
675 | * { | ||
676 | * release_packets(data, nb_packets+1); | ||
677 | * return (int)out_len; | ||
678 | * } | ||
679 | * output_next_packet(out, out_len); | ||
680 | * opus_repacketizer_init(rp); | ||
681 | * release_packets(data, nb_packets); | ||
682 | * data[0] = data[nb_packets]; | ||
683 | * len[0] = len[nb_packets]; | ||
684 | * nb_packets = 0; | ||
685 | * } | ||
686 | * err = opus_repacketizer_cat(rp, data[nb_packets], len[nb_packets]); | ||
687 | * if (err != OPUS_OK) | ||
688 | * { | ||
689 | * release_packets(data, nb_packets+1); | ||
690 | * return err; | ||
691 | * } | ||
692 | * prev_toc = data[nb_packets][0]; | ||
693 | * nb_packets++; | ||
694 | * } | ||
695 | * // Output the final, partial packet. | ||
696 | * if (nb_packets > 0) | ||
697 | * { | ||
698 | * out_len = opus_repacketizer_out(rp, out, sizeof(out)); | ||
699 | * release_packets(data, nb_packets); | ||
700 | * if (out_len < 0) | ||
701 | * return (int)out_len; | ||
702 | * output_next_packet(out, out_len); | ||
703 | * } | ||
704 | * @endcode | ||
705 | * | ||
706 | * An alternate way of merging packets is to simply call opus_repacketizer_cat() | ||
707 | * unconditionally until it fails. At that point, the merged packet can be | ||
708 | * obtained with opus_repacketizer_out() and the input packet for which | ||
709 | * opus_repacketizer_cat() needs to be re-added to a newly reinitialized | ||
710 | * repacketizer state. | ||
711 | */ | ||
712 | |||
713 | typedef struct OpusRepacketizer OpusRepacketizer; | ||
714 | |||
715 | /** Gets the size of an <code>OpusRepacketizer</code> structure. | ||
716 | * @returns The size in bytes. | ||
717 | */ | ||
718 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_repacketizer_get_size(void); | ||
719 | |||
720 | /** (Re)initializes a previously allocated repacketizer state. | ||
721 | * The state must be at least the size returned by opus_repacketizer_get_size(). | ||
722 | * This can be used for applications which use their own allocator instead of | ||
723 | * malloc(). | ||
724 | * It must also be called to reset the queue of packets waiting to be | ||
725 | * repacketized, which is necessary if the maximum packet duration of 120 ms | ||
726 | * is reached or if you wish to submit packets with a different Opus | ||
727 | * configuration (coding mode, audio bandwidth, frame size, or channel count). | ||
728 | * Failure to do so will prevent a new packet from being added with | ||
729 | * opus_repacketizer_cat(). | ||
730 | * @see opus_repacketizer_create | ||
731 | * @see opus_repacketizer_get_size | ||
732 | * @see opus_repacketizer_cat | ||
733 | * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state to | ||
734 | * (re)initialize. | ||
735 | * @returns A pointer to the same repacketizer state that was passed in. | ||
736 | */ | ||
737 | OPUS_EXPORT OpusRepacketizer *opus_repacketizer_init(OpusRepacketizer *rp) OPUS_ARG_NONNULL(1); | ||
738 | |||
739 | /** Allocates memory and initializes the new repacketizer with | ||
740 | * opus_repacketizer_init(). | ||
741 | */ | ||
742 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusRepacketizer *opus_repacketizer_create(void); | ||
743 | |||
744 | /** Frees an <code>OpusRepacketizer</code> allocated by | ||
745 | * opus_repacketizer_create(). | ||
746 | * @param[in] rp <tt>OpusRepacketizer*</tt>: State to be freed. | ||
747 | */ | ||
748 | OPUS_EXPORT void opus_repacketizer_destroy(OpusRepacketizer *rp); | ||
749 | |||
750 | /** Add a packet to the current repacketizer state. | ||
751 | * This packet must match the configuration of any packets already submitted | ||
752 | * for repacketization since the last call to opus_repacketizer_init(). | ||
753 | * This means that it must have the same coding mode, audio bandwidth, frame | ||
754 | * size, and channel count. | ||
755 | * This can be checked in advance by examining the top 6 bits of the first | ||
756 | * byte of the packet, and ensuring they match the top 6 bits of the first | ||
757 | * byte of any previously submitted packet. | ||
758 | * The total duration of audio in the repacketizer state also must not exceed | ||
759 | * 120 ms, the maximum duration of a single packet, after adding this packet. | ||
760 | * | ||
761 | * The contents of the current repacketizer state can be extracted into new | ||
762 | * packets using opus_repacketizer_out() or opus_repacketizer_out_range(). | ||
763 | * | ||
764 | * In order to add a packet with a different configuration or to add more | ||
765 | * audio beyond 120 ms, you must clear the repacketizer state by calling | ||
766 | * opus_repacketizer_init(). | ||
767 | * If a packet is too large to add to the current repacketizer state, no part | ||
768 | * of it is added, even if it contains multiple frames, some of which might | ||
769 | * fit. | ||
770 | * If you wish to be able to add parts of such packets, you should first use | ||
771 | * another repacketizer to split the packet into pieces and add them | ||
772 | * individually. | ||
773 | * @see opus_repacketizer_out_range | ||
774 | * @see opus_repacketizer_out | ||
775 | * @see opus_repacketizer_init | ||
776 | * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state to which to | ||
777 | * add the packet. | ||
778 | * @param[in] data <tt>const unsigned char*</tt>: The packet data. | ||
779 | * The application must ensure | ||
780 | * this pointer remains valid | ||
781 | * until the next call to | ||
782 | * opus_repacketizer_init() or | ||
783 | * opus_repacketizer_destroy(). | ||
784 | * @param len <tt>opus_int32</tt>: The number of bytes in the packet data. | ||
785 | * @returns An error code indicating whether or not the operation succeeded. | ||
786 | * @retval #OPUS_OK The packet's contents have been added to the repacketizer | ||
787 | * state. | ||
788 | * @retval #OPUS_INVALID_PACKET The packet did not have a valid TOC sequence, | ||
789 | * the packet's TOC sequence was not compatible | ||
790 | * with previously submitted packets (because | ||
791 | * the coding mode, audio bandwidth, frame size, | ||
792 | * or channel count did not match), or adding | ||
793 | * this packet would increase the total amount of | ||
794 | * audio stored in the repacketizer state to more | ||
795 | * than 120 ms. | ||
796 | */ | ||
797 | OPUS_EXPORT int opus_repacketizer_cat(OpusRepacketizer *rp, const unsigned char *data, opus_int32 len) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2); | ||
798 | |||
799 | |||
800 | /** Construct a new packet from data previously submitted to the repacketizer | ||
801 | * state via opus_repacketizer_cat(). | ||
802 | * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state from which to | ||
803 | * construct the new packet. | ||
804 | * @param begin <tt>int</tt>: The index of the first frame in the current | ||
805 | * repacketizer state to include in the output. | ||
806 | * @param end <tt>int</tt>: One past the index of the last frame in the | ||
807 | * current repacketizer state to include in the | ||
808 | * output. | ||
809 | * @param[out] data <tt>const unsigned char*</tt>: The buffer in which to | ||
810 | * store the output packet. | ||
811 | * @param maxlen <tt>opus_int32</tt>: The maximum number of bytes to store in | ||
812 | * the output buffer. In order to guarantee | ||
813 | * success, this should be at least | ||
814 | * <code>1276</code> for a single frame, | ||
815 | * or for multiple frames, | ||
816 | * <code>1277*(end-begin)</code>. | ||
817 | * However, <code>1*(end-begin)</code> plus | ||
818 | * the size of all packet data submitted to | ||
819 | * the repacketizer since the last call to | ||
820 | * opus_repacketizer_init() or | ||
821 | * opus_repacketizer_create() is also | ||
822 | * sufficient, and possibly much smaller. | ||
823 | * @returns The total size of the output packet on success, or an error code | ||
824 | * on failure. | ||
825 | * @retval #OPUS_BAD_ARG <code>[begin,end)</code> was an invalid range of | ||
826 | * frames (begin < 0, begin >= end, or end > | ||
827 | * opus_repacketizer_get_nb_frames()). | ||
828 | * @retval #OPUS_BUFFER_TOO_SMALL \a maxlen was insufficient to contain the | ||
829 | * complete output packet. | ||
830 | */ | ||
831 | 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); | ||
832 | |||
833 | /** Return the total number of frames contained in packet data submitted to | ||
834 | * the repacketizer state so far via opus_repacketizer_cat() since the last | ||
835 | * call to opus_repacketizer_init() or opus_repacketizer_create(). | ||
836 | * This defines the valid range of packets that can be extracted with | ||
837 | * opus_repacketizer_out_range() or opus_repacketizer_out(). | ||
838 | * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state containing the | ||
839 | * frames. | ||
840 | * @returns The total number of frames contained in the packet data submitted | ||
841 | * to the repacketizer state. | ||
842 | */ | ||
843 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_repacketizer_get_nb_frames(OpusRepacketizer *rp) OPUS_ARG_NONNULL(1); | ||
844 | |||
845 | /** Construct a new packet from data previously submitted to the repacketizer | ||
846 | * state via opus_repacketizer_cat(). | ||
847 | * This is a convenience routine that returns all the data submitted so far | ||
848 | * in a single packet. | ||
849 | * It is equivalent to calling | ||
850 | * @code | ||
851 | * opus_repacketizer_out_range(rp, 0, opus_repacketizer_get_nb_frames(rp), | ||
852 | * data, maxlen) | ||
853 | * @endcode | ||
854 | * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state from which to | ||
855 | * construct the new packet. | ||
856 | * @param[out] data <tt>const unsigned char*</tt>: The buffer in which to | ||
857 | * store the output packet. | ||
858 | * @param maxlen <tt>opus_int32</tt>: The maximum number of bytes to store in | ||
859 | * the output buffer. In order to guarantee | ||
860 | * success, this should be at least | ||
861 | * <code>1277*opus_repacketizer_get_nb_frames(rp)</code>. | ||
862 | * However, | ||
863 | * <code>1*opus_repacketizer_get_nb_frames(rp)</code> | ||
864 | * plus the size of all packet data | ||
865 | * submitted to the repacketizer since the | ||
866 | * last call to 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_BUFFER_TOO_SMALL \a maxlen was insufficient to contain the | ||
872 | * complete output packet. | ||
873 | */ | ||
874 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_repacketizer_out(OpusRepacketizer *rp, unsigned char *data, opus_int32 maxlen) OPUS_ARG_NONNULL(1); | ||
875 | |||
876 | /**@}*/ | ||
877 | |||
878 | #ifdef __cplusplus | ||
879 | } | ||
880 | #endif | ||
881 | |||
882 | #endif /* OPUS_H */ | ||