Jean-Marc Valin | 6696a14 | 2011-08-22 10:40:38 -0400 | [diff] [blame] | 1 | /* Copyright (c) 2010-2011 Xiph.Org Foundation, Skype Limited |
| 2 | Written by Jean-Marc Valin and Koen Vos */ |
Jean-Marc Valin | 24af303 | 2010-06-30 14:29:45 -0400 | [diff] [blame] | 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 | |
Jean-Marc Valin | 24af303 | 2010-06-30 14:29:45 -0400 | [diff] [blame] | 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 |
Jean-Marc Valin | cb05e7c | 2012-04-20 16:40:24 -0400 | [diff] [blame] | 18 | A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER |
| 19 | OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, |
Jean-Marc Valin | 24af303 | 2010-06-30 14:29:45 -0400 | [diff] [blame] | 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 | |
Ralph Giles | 1b95196 | 2011-09-07 10:40:25 -0700 | [diff] [blame] | 28 | /** |
| 29 | * @file opus.h |
| 30 | * @brief Opus reference implementation API |
| 31 | */ |
| 32 | |
Jean-Marc Valin | 05dd36a | 2010-10-18 12:50:49 -0400 | [diff] [blame] | 33 | #ifndef OPUS_H |
| 34 | #define OPUS_H |
Jean-Marc Valin | 24f36e0 | 2010-07-06 14:41:20 -0400 | [diff] [blame] | 35 | |
Jean-Marc Valin | d6a0216 | 2011-07-29 20:10:27 -0400 | [diff] [blame] | 36 | #include "opus_types.h" |
Jean-Marc Valin | f9e701a | 2011-08-31 17:47:48 -0400 | [diff] [blame] | 37 | #include "opus_defines.h" |
Jean-Marc Valin | d6a0216 | 2011-07-29 20:10:27 -0400 | [diff] [blame] | 38 | |
Jean-Marc Valin | 24f36e0 | 2010-07-06 14:41:20 -0400 | [diff] [blame] | 39 | #ifdef __cplusplus |
| 40 | extern "C" { |
| 41 | #endif |
| 42 | |
Jean-Marc Valin | c248e6d | 2011-09-22 17:59:22 -0400 | [diff] [blame] | 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 |
Gregory Maxwell | 595b334 | 2012-06-11 01:42:32 -0400 | [diff] [blame] | 56 | * @li Bit-rates from 6 kb/s to 510 kb/s |
Jean-Marc Valin | c248e6d | 2011-09-22 17:59:22 -0400 | [diff] [blame] | 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 |
Gregory Maxwell | 595b334 | 2012-06-11 01:42:32 -0400 | [diff] [blame] | 61 | * @li Support for multichannel (up to 255 channels) |
Jean-Marc Valin | c248e6d | 2011-09-22 17:59:22 -0400 | [diff] [blame] | 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: |
Gregory Maxwell | d445f02 | 2012-05-20 19:28:45 -0400 | [diff] [blame] | 67 | * @li @ref opus_encoder |
| 68 | * @li @ref opus_decoder |
| 69 | * @li @ref opus_repacketizer |
| 70 | * @li @ref opus_libinfo |
Gregory Maxwell | 1f65ce8 | 2012-06-10 21:15:02 -0400 | [diff] [blame] | 71 | * @li @ref opus_custom |
Jean-Marc Valin | c248e6d | 2011-09-22 17:59:22 -0400 | [diff] [blame] | 72 | */ |
| 73 | |
Gregory Maxwell | d445f02 | 2012-05-20 19:28:45 -0400 | [diff] [blame] | 74 | /** @defgroup opus_encoder Opus Encoder |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 75 | * @{ |
Jean-Marc Valin | c248e6d | 2011-09-22 17:59:22 -0400 | [diff] [blame] | 76 | * |
Gregory Maxwell | daa1459 | 2012-06-10 21:30:01 -0400 | [diff] [blame] | 77 | * @brief This page describes the process and functions used to encode Opus. |
| 78 | * |
Jean-Marc Valin | c248e6d | 2011-09-22 17:59:22 -0400 | [diff] [blame] | 79 | * Since Opus is a stateful codec, the encoding process starts with creating an encoder |
| 80 | * state. This can be done with: |
| 81 | * |
| 82 | * @code |
| 83 | * int error; |
| 84 | * OpusEncoder *enc; |
| 85 | * enc = opus_encoder_create(Fs, channels, application, &error); |
| 86 | * @endcode |
| 87 | * |
Jean-Marc Valin | 2557750 | 2011-09-22 22:13:46 -0400 | [diff] [blame] | 88 | * From this point, @c enc can be used for encoding an audio stream. An encoder state |
| 89 | * @b must @b not be used for more than one stream at the same time. Similarly, the encoder |
| 90 | * state @b must @b not be re-initialized for each frame. |
Jean-Marc Valin | c248e6d | 2011-09-22 17:59:22 -0400 | [diff] [blame] | 91 | * |
| 92 | * While opus_encoder_create() allocates memory for the state, it's also possible |
| 93 | * to initialize pre-allocated memory: |
| 94 | * |
| 95 | * @code |
| 96 | * int size; |
| 97 | * int error; |
| 98 | * OpusEncoder *enc; |
| 99 | * size = opus_encoder_get_size(channels); |
| 100 | * enc = malloc(size); |
| 101 | * error = opus_encoder_init(enc, Fs, channels, application); |
| 102 | * @endcode |
| 103 | * |
| 104 | * where opus_encoder_get_size() returns the required size for the encoder state. Note that |
| 105 | * future versions of this code may change the size, so no assuptions should be made about it. |
| 106 | * |
| 107 | * The encoder state is always continuous in memory and only a shallow copy is sufficient |
| 108 | * to copy it (e.g. memcpy()) |
| 109 | * |
| 110 | * It is possible to change some of the encoder's settings using the opus_encoder_ctl() |
| 111 | * interface. All these settings already default to the recommended value, so they should |
| 112 | * only be changed when necessary. The most common settings one may want to change are: |
| 113 | * |
| 114 | * @code |
| 115 | * opus_encoder_ctl(enc, OPUS_SET_BITRATE(bitrate)); |
| 116 | * opus_encoder_ctl(enc, OPUS_SET_COMPLEXITY(complexity)); |
| 117 | * opus_encoder_ctl(enc, OPUS_SET_SIGNAL(signal_type)); |
| 118 | * @endcode |
| 119 | * |
| 120 | * where |
Jean-Marc Valin | 2557750 | 2011-09-22 22:13:46 -0400 | [diff] [blame] | 121 | * |
| 122 | * @arg bitrate is in bits per second (b/s) |
| 123 | * @arg complexity is a value from 1 to 10, where 1 is the lowest complexity and 10 is the highest |
| 124 | * @arg signal_type is either OPUS_AUTO (default), OPUS_SIGNAL_VOICE, or OPUS_SIGNAL_MUSIC |
| 125 | * |
Gregory Maxwell | d445f02 | 2012-05-20 19:28:45 -0400 | [diff] [blame] | 126 | * 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. |
Jean-Marc Valin | c248e6d | 2011-09-22 17:59:22 -0400 | [diff] [blame] | 127 | * |
| 128 | * 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: |
| 129 | * @code |
| 130 | * len = opus_encode(enc, audio_frame, frame_size, packet, max_packet); |
| 131 | * @endcode |
| 132 | * |
| 133 | * where |
| 134 | * <ul> |
| 135 | * <li>audio_frame is the audio data in opus_int16 (or float for opus_encode_float())</li> |
| 136 | * <li>frame_size is the duration of the frame in samples (per channel)</li> |
| 137 | * <li>packet is the byte array to which the compressed data is written</li> |
Gregory Maxwell | e702817 | 2011-11-19 23:58:09 -0500 | [diff] [blame] | 138 | * <li>max_packet is the maximum number of bytes that can be written in the packet (4000 bytes is recommended)</li> |
Jean-Marc Valin | c248e6d | 2011-09-22 17:59:22 -0400 | [diff] [blame] | 139 | * </ul> |
| 140 | * |
| 141 | * opus_encode() and opus_encode_frame() return the number of bytes actually written to the packet. |
Jean-Marc Valin | 2557750 | 2011-09-22 22:13:46 -0400 | [diff] [blame] | 142 | * The return value <b>can be negative</b>, which indicates that an error has occurred. If the return value |
| 143 | * is 1 byte, then the packet does not need to be transmitted (DTX). |
Jean-Marc Valin | c248e6d | 2011-09-22 17:59:22 -0400 | [diff] [blame] | 144 | * |
| 145 | * Once the encoder state if no longer needed, it can be destroyed with |
| 146 | * |
| 147 | * @code |
| 148 | * opus_encoder_destroy(enc); |
| 149 | * @endcode |
| 150 | * |
| 151 | * If the encoder was created with opus_encoder_init() rather than opus_encoder_create(), |
| 152 | * then no action is required aside from potentially freeing the memory that was manually |
| 153 | * allocated for it (calling free(enc) for the example above) |
| 154 | * |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 155 | */ |
Jean-Marc Valin | f9bc460 | 2011-03-08 14:57:46 -0500 | [diff] [blame] | 156 | |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 157 | /** Opus encoder state. |
| 158 | * This contains the complete state of an Opus encoder. |
| 159 | * It is position independent and can be freely copied. |
| 160 | * @see opus_encoder_create,opus_encoder_init |
| 161 | */ |
Jean-Marc Valin | 05dd36a | 2010-10-18 12:50:49 -0400 | [diff] [blame] | 162 | typedef struct OpusEncoder OpusEncoder; |
Jean-Marc Valin | 24af303 | 2010-06-30 14:29:45 -0400 | [diff] [blame] | 163 | |
Timothy B. Terriberry | ddd551e | 2012-09-09 03:13:26 -0700 | [diff] [blame^] | 164 | /** Gets the size of an OpusEncoder structure. |
| 165 | * @param[in] channels <tt>int</tt>: Number of channels. |
| 166 | * This must be 1 or 2. |
| 167 | * @returns The size in bytes. |
| 168 | */ |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame] | 169 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_encoder_get_size(int channels); |
Jean-Marc Valin | d4e9340 | 2011-08-27 00:52:26 -0400 | [diff] [blame] | 170 | |
Ralph Giles | 1b95196 | 2011-09-07 10:40:25 -0700 | [diff] [blame] | 171 | /** |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 172 | */ |
| 173 | |
| 174 | /** Allocates and initializes an encoder state. |
| 175 | * There are three coding modes: |
Jean-Marc Valin | 2557750 | 2011-09-22 22:13:46 -0400 | [diff] [blame] | 176 | * |
| 177 | * @ref OPUS_APPLICATION_VOIP gives best quality at a given bitrate for voice |
Ralph Giles | 641eea8 | 2011-08-02 10:06:59 -0700 | [diff] [blame] | 178 | * signals. It enhances the input signal by high-pass filtering and |
| 179 | * emphasizing formants and harmonics. Optionally it includes in-band |
| 180 | * forward error correction to protect against packet loss. Use this |
| 181 | * mode for typical VoIP applications. Because of the enhancement, |
| 182 | * even at high bitrates the output may sound different from the input. |
Jean-Marc Valin | 2557750 | 2011-09-22 22:13:46 -0400 | [diff] [blame] | 183 | * |
| 184 | * @ref OPUS_APPLICATION_AUDIO gives best quality at a given bitrate for most |
Ralph Giles | 641eea8 | 2011-08-02 10:06:59 -0700 | [diff] [blame] | 185 | * non-voice signals like music. Use this mode for music and mixed |
| 186 | * (music/voice) content, broadcast, and applications requiring less |
| 187 | * than 15 ms of coding delay. |
Jean-Marc Valin | 2557750 | 2011-09-22 22:13:46 -0400 | [diff] [blame] | 188 | * |
| 189 | * @ref OPUS_APPLICATION_RESTRICTED_LOWDELAY configures low-delay mode that |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 190 | * disables the speech-optimized mode in exchange for slightly reduced delay. |
Gregory Maxwell | fdd0c52 | 2012-05-16 20:00:32 -0400 | [diff] [blame] | 191 | * This mode can only be set on an newly initialized or freshly reset encoder |
| 192 | * because it changes the codec delay. |
Jean-Marc Valin | 2557750 | 2011-09-22 22:13:46 -0400 | [diff] [blame] | 193 | * |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 194 | * This is useful when the caller knows that the speech-optimized modes will not be needed (use with caution). |
| 195 | * @param [in] Fs <tt>opus_int32</tt>: Sampling rate of input signal (Hz) |
| 196 | * @param [in] channels <tt>int</tt>: Number of channels (1/2) in input signal |
Jean-Marc Valin | 2557750 | 2011-09-22 22:13:46 -0400 | [diff] [blame] | 197 | * @param [in] application <tt>int</tt>: Coding mode (@ref OPUS_APPLICATION_VOIP/@ref OPUS_APPLICATION_AUDIO/@ref OPUS_APPLICATION_RESTRICTED_LOWDELAY) |
Gregory Maxwell | d445f02 | 2012-05-20 19:28:45 -0400 | [diff] [blame] | 198 | * @param [out] error <tt>int*</tt>: @ref opus_errorcodes |
Jean-Marc Valin | 2557750 | 2011-09-22 22:13:46 -0400 | [diff] [blame] | 199 | * @note Regardless of the sampling rate and number channels selected, the Opus encoder |
| 200 | * can switch to a lower audio audio bandwidth or number of channels if the bitrate |
| 201 | * selected is too low. This also means that it is safe to always use 48 kHz stereo input |
| 202 | * and let the encoder optimize the encoding. |
Koen Vos | 479e18b | 2011-05-25 23:09:52 -0400 | [diff] [blame] | 203 | */ |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame] | 204 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusEncoder *opus_encoder_create( |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 205 | opus_int32 Fs, |
| 206 | int channels, |
| 207 | int application, |
| 208 | int *error |
Koen Vos | 479e18b | 2011-05-25 23:09:52 -0400 | [diff] [blame] | 209 | ); |
| 210 | |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 211 | /** Initializes a previously allocated encoder state |
| 212 | * The memory pointed to by st must be the size returned by opus_encoder_get_size. |
Jean-Marc Valin | 2557750 | 2011-09-22 22:13:46 -0400 | [diff] [blame] | 213 | * This is intended for applications which use their own allocator instead of malloc. |
| 214 | * @see opus_encoder_create(),opus_encoder_get_size() |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 215 | * To reset a previously initialized state use the OPUS_RESET_STATE CTL. |
| 216 | * @param [in] st <tt>OpusEncoder*</tt>: Encoder state |
| 217 | * @param [in] Fs <tt>opus_int32</tt>: Sampling rate of input signal (Hz) |
| 218 | * @param [in] channels <tt>int</tt>: Number of channels (1/2) in input signal |
| 219 | * @param [in] application <tt>int</tt>: Coding mode (OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO/OPUS_APPLICATION_RESTRICTED_LOWDELAY) |
Gregory Maxwell | d445f02 | 2012-05-20 19:28:45 -0400 | [diff] [blame] | 220 | * @retval OPUS_OK Success or @ref opus_errorcodes |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 221 | */ |
Jean-Marc Valin | 9d8dc3a | 2011-08-29 09:40:57 -0400 | [diff] [blame] | 222 | OPUS_EXPORT int opus_encoder_init( |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 223 | OpusEncoder *st, |
| 224 | opus_int32 Fs, |
| 225 | int channels, |
| 226 | int application |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame] | 227 | ) OPUS_ARG_NONNULL(1); |
Jean-Marc Valin | 24af303 | 2010-06-30 14:29:45 -0400 | [diff] [blame] | 228 | |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 229 | /** Encodes an Opus frame. |
| 230 | * The passed frame_size must an opus frame size for the encoder's sampling rate. |
Gregory Maxwell | bf7c160 | 2012-08-06 09:24:03 -0400 | [diff] [blame] | 231 | * For example, at 48kHz the permitted values are 120, 240, 480, 960, 1920, and 2880. |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 232 | * Passing in a duration of less than 10ms (480 samples at 48kHz) will |
| 233 | * prevent the encoder from using the LPC or hybrid modes. |
| 234 | * @param [in] st <tt>OpusEncoder*</tt>: Encoder state |
| 235 | * @param [in] pcm <tt>opus_int16*</tt>: Input signal (interleaved if 2 channels). length is frame_size*channels*sizeof(opus_int16) |
| 236 | * @param [in] frame_size <tt>int</tt>: Number of samples per frame of input signal |
| 237 | * @param [out] data <tt>char*</tt>: Output payload (at least max_data_bytes long) |
Gregory Maxwell | e702817 | 2011-11-19 23:58:09 -0500 | [diff] [blame] | 238 | * @param [in] max_data_bytes <tt>opus_int32</tt>: Allocated memory for payload; don't use for controlling bitrate |
Gregory Maxwell | d445f02 | 2012-05-20 19:28:45 -0400 | [diff] [blame] | 239 | * @returns length of the data payload (in bytes) or @ref opus_errorcodes |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 240 | */ |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame] | 241 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_encode( |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 242 | OpusEncoder *st, |
| 243 | const opus_int16 *pcm, |
| 244 | int frame_size, |
| 245 | unsigned char *data, |
Gregory Maxwell | e702817 | 2011-11-19 23:58:09 -0500 | [diff] [blame] | 246 | opus_int32 max_data_bytes |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame] | 247 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4); |
Jean-Marc Valin | 24af303 | 2010-06-30 14:29:45 -0400 | [diff] [blame] | 248 | |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 249 | /** Encodes an Opus frame from floating point input. |
| 250 | * The passed frame_size must an opus frame size for the encoder's sampling rate. |
Gregory Maxwell | bf7c160 | 2012-08-06 09:24:03 -0400 | [diff] [blame] | 251 | * For example, at 48kHz the permitted values are 120, 240, 480, 960, 1920, and 2880. |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 252 | * Passing in a duration of less than 10ms (480 samples at 48kHz) will |
| 253 | * prevent the encoder from using the LPC or hybrid modes. |
| 254 | * @param [in] st <tt>OpusEncoder*</tt>: Encoder state |
Gregory Maxwell | 1f65ce8 | 2012-06-10 21:15:02 -0400 | [diff] [blame] | 255 | * @param [in] pcm <tt>float*</tt>: Input in float format (interleaved if 2 channels), with a normal range of +/-1.0. |
| 256 | * Samples with a range beyond +/-1.0 are supported but will |
| 257 | * be clipped by decoders using the integer API and should |
| 258 | * only be used if it is known that the far end supports |
| 259 | * extended dynamic range. |
| 260 | * length is frame_size*channels*sizeof(float) |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 261 | * @param [in] frame_size <tt>int</tt>: Number of samples per frame of input signal |
| 262 | * @param [out] data <tt>char*</tt>: Output payload (at least max_data_bytes long) |
Gregory Maxwell | e702817 | 2011-11-19 23:58:09 -0500 | [diff] [blame] | 263 | * @param [in] max_data_bytes <tt>opus_int32</tt>: Allocated memory for payload; don't use for controlling bitrate |
Gregory Maxwell | d445f02 | 2012-05-20 19:28:45 -0400 | [diff] [blame] | 264 | * @returns length of the data payload (in bytes) or @ref opus_errorcodes |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 265 | */ |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame] | 266 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_encode_float( |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 267 | OpusEncoder *st, |
| 268 | const float *pcm, |
| 269 | int frame_size, |
| 270 | unsigned char *data, |
Gregory Maxwell | e702817 | 2011-11-19 23:58:09 -0500 | [diff] [blame] | 271 | opus_int32 max_data_bytes |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame] | 272 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4); |
Gregory Maxwell | 06677d7 | 2011-08-19 12:17:22 -0400 | [diff] [blame] | 273 | |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 274 | /** Frees an OpusEncoder allocated by opus_encoder_create. |
| 275 | * @param[in] st <tt>OpusEncoder*</tt>: State to be freed. |
| 276 | */ |
Jean-Marc Valin | 280c060 | 2011-05-05 20:47:42 -0400 | [diff] [blame] | 277 | OPUS_EXPORT void opus_encoder_destroy(OpusEncoder *st); |
Jean-Marc Valin | 04584ea | 2010-06-30 15:03:35 -0400 | [diff] [blame] | 278 | |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 279 | /** Perform a CTL function on an Opus encoder. |
Ralph Giles | 10ebc02 | 2011-11-25 23:25:38 -0500 | [diff] [blame] | 280 | * |
| 281 | * Generally the request and subsequent arguments are generated |
| 282 | * by a convenience macro. |
Gregory Maxwell | d445f02 | 2012-05-20 19:28:45 -0400 | [diff] [blame] | 283 | * @see opus_encoderctls |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 284 | */ |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame] | 285 | OPUS_EXPORT int opus_encoder_ctl(OpusEncoder *st, int request, ...) OPUS_ARG_NONNULL(1); |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 286 | /**@}*/ |
Jean-Marc Valin | 04584ea | 2010-06-30 15:03:35 -0400 | [diff] [blame] | 287 | |
Gregory Maxwell | d445f02 | 2012-05-20 19:28:45 -0400 | [diff] [blame] | 288 | /** @defgroup opus_decoder Opus Decoder |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 289 | * @{ |
Jean-Marc Valin | c248e6d | 2011-09-22 17:59:22 -0400 | [diff] [blame] | 290 | * |
Gregory Maxwell | daa1459 | 2012-06-10 21:30:01 -0400 | [diff] [blame] | 291 | * @brief This page describes the process and functions used to decode Opus. |
Jean-Marc Valin | c248e6d | 2011-09-22 17:59:22 -0400 | [diff] [blame] | 292 | * |
| 293 | * The decoding process also starts with creating a decoder |
| 294 | * state. This can be done with: |
| 295 | * @code |
| 296 | * int error; |
| 297 | * OpusDecoder *dec; |
| 298 | * dec = opus_decoder_create(Fs, channels, &error); |
| 299 | * @endcode |
| 300 | * where |
| 301 | * @li Fs is the sampling rate and must be 8000, 12000, 16000, 24000, or 48000 |
| 302 | * @li channels is the number of channels (1 or 2) |
| 303 | * @li error will hold the error code in case or failure (or OPUS_OK on success) |
| 304 | * @li the return value is a newly created decoder state to be used for decoding |
| 305 | * |
| 306 | * While opus_decoder_create() allocates memory for the state, it's also possible |
| 307 | * to initialize pre-allocated memory: |
| 308 | * @code |
| 309 | * int size; |
| 310 | * int error; |
| 311 | * OpusDecoder *dec; |
| 312 | * size = opus_decoder_get_size(channels); |
| 313 | * dec = malloc(size); |
| 314 | * error = opus_decoder_init(dec, Fs, channels); |
| 315 | * @endcode |
| 316 | * where opus_decoder_get_size() returns the required size for the decoder state. Note that |
| 317 | * future versions of this code may change the size, so no assuptions should be made about it. |
| 318 | * |
| 319 | * The decoder state is always continuous in memory and only a shallow copy is sufficient |
| 320 | * to copy it (e.g. memcpy()) |
| 321 | * |
| 322 | * To decode a frame, opus_decode() or opus_decode_float() must be called with a packet of compressed audio data: |
| 323 | * @code |
Ralph Giles | 1e0ba0f | 2011-12-02 13:22:22 -0800 | [diff] [blame] | 324 | * frame_size = opus_decode(dec, packet, len, decoded, max_size, 0); |
Jean-Marc Valin | c248e6d | 2011-09-22 17:59:22 -0400 | [diff] [blame] | 325 | * @endcode |
| 326 | * where |
| 327 | * |
| 328 | * @li packet is the byte array containing the compressed data |
| 329 | * @li len is the exact number of bytes contained in the packet |
| 330 | * @li decoded is the decoded audio data in opus_int16 (or float for opus_decode_float()) |
| 331 | * @li max_size is the max duration of the frame in samples (per channel) that can fit into the decoded_frame array |
| 332 | * |
Ralph Giles | 1e0ba0f | 2011-12-02 13:22:22 -0800 | [diff] [blame] | 333 | * opus_decode() and opus_decode_float() return the number of samples (per channel) decoded from the packet. |
Jean-Marc Valin | c248e6d | 2011-09-22 17:59:22 -0400 | [diff] [blame] | 334 | * If that value is negative, then an error has occured. This can occur if the packet is corrupted or if the audio |
| 335 | * buffer is too small to hold the decoded audio. |
Gregory Maxwell | b0c120b | 2012-07-21 16:35:19 -0400 | [diff] [blame] | 336 | * |
| 337 | * Opus is a stateful codec with overlapping blocks and as a result Opus |
| 338 | * packets are not coded independently of each other. Packets must be |
| 339 | * passed into the decoder serially and in the correct order for a correct |
| 340 | * decode. Lost packets can be replaced with loss concealment by calling |
| 341 | * the decoder with a null pointer and zero length for the missing packet. |
| 342 | * |
| 343 | * A single codec state may only be accessed from a single thread at |
| 344 | * a time and any required locking must be performed by the caller. Separate |
| 345 | * streams must be decoded with separate decoder states and can be decoded |
| 346 | * in parallel unless the library was compiled with NONTHREADSAFE_PSEUDOSTACK |
| 347 | * defined. |
| 348 | * |
| 349 | */ |
Jean-Marc Valin | d4e9340 | 2011-08-27 00:52:26 -0400 | [diff] [blame] | 350 | |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 351 | /** Opus decoder state. |
| 352 | * This contains the complete state of an Opus decoder. |
| 353 | * It is position independent and can be freely copied. |
| 354 | * @see opus_decoder_create,opus_decoder_init |
| 355 | */ |
| 356 | typedef struct OpusDecoder OpusDecoder; |
Jean-Marc Valin | d4e9340 | 2011-08-27 00:52:26 -0400 | [diff] [blame] | 357 | |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 358 | /** Gets the size of an OpusDecoder structure. |
Timothy B. Terriberry | ddd551e | 2012-09-09 03:13:26 -0700 | [diff] [blame^] | 359 | * @param [in] channels <tt>int</tt>: Number of channels. |
| 360 | * This must be 1 or 2. |
| 361 | * @returns The size in bytes. |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 362 | */ |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame] | 363 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decoder_get_size(int channels); |
Jean-Marc Valin | d4e9340 | 2011-08-27 00:52:26 -0400 | [diff] [blame] | 364 | |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 365 | /** Allocates and initializes a decoder state. |
Ralph Giles | f402852 | 2012-03-22 13:29:04 -0700 | [diff] [blame] | 366 | * @param [in] Fs <tt>opus_int32</tt>: Sample rate to decode at (Hz) |
| 367 | * @param [in] channels <tt>int</tt>: Number of channels (1/2) to decode |
Gregory Maxwell | d445f02 | 2012-05-20 19:28:45 -0400 | [diff] [blame] | 368 | * @param [out] error <tt>int*</tt>: OPUS_OK Success or @ref opus_errorcodes |
Ralph Giles | f402852 | 2012-03-22 13:29:04 -0700 | [diff] [blame] | 369 | * |
| 370 | * Internally Opus stores data at 48000 Hz, so that should be the default |
| 371 | * value for Fs. However, the decoder can efficiently decode to buffers |
| 372 | * at 8, 12, 16, and 24 kHz so if for some reason the caller cannot use |
| 373 | * data at the full sample rate, or knows the compressed data doesn't |
| 374 | * use the full frequency range, it can request decoding at a reduced |
| 375 | * rate. Likewise, the decoder is capable of filling in either mono or |
| 376 | * interleaved stereo pcm buffers, at the caller's request. |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 377 | */ |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame] | 378 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusDecoder *opus_decoder_create( |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 379 | opus_int32 Fs, |
| 380 | int channels, |
| 381 | int *error |
Koen Vos | 479e18b | 2011-05-25 23:09:52 -0400 | [diff] [blame] | 382 | ); |
Jean-Marc Valin | 280c060 | 2011-05-05 20:47:42 -0400 | [diff] [blame] | 383 | |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 384 | /** Initializes a previously allocated decoder state. |
| 385 | * The state must be the size returned by opus_decoder_get_size. |
| 386 | * This is intended for applications which use their own allocator instead of malloc. @see opus_decoder_create,opus_decoder_get_size |
| 387 | * To reset a previously initialized state use the OPUS_RESET_STATE CTL. |
| 388 | * @param [in] st <tt>OpusDecoder*</tt>: Decoder state. |
Ralph Giles | f402852 | 2012-03-22 13:29:04 -0700 | [diff] [blame] | 389 | * @param [in] Fs <tt>opus_int32</tt>: Sampling rate to decode to (Hz) |
| 390 | * @param [in] channels <tt>int</tt>: Number of channels (1/2) to decode |
Gregory Maxwell | d445f02 | 2012-05-20 19:28:45 -0400 | [diff] [blame] | 391 | * @retval OPUS_OK Success or @ref opus_errorcodes |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 392 | */ |
| 393 | OPUS_EXPORT int opus_decoder_init( |
| 394 | OpusDecoder *st, |
| 395 | opus_int32 Fs, |
| 396 | int channels |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame] | 397 | ) OPUS_ARG_NONNULL(1); |
Jean-Marc Valin | 24f36e0 | 2010-07-06 14:41:20 -0400 | [diff] [blame] | 398 | |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 399 | /** Decode an Opus frame |
| 400 | * @param [in] st <tt>OpusDecoder*</tt>: Decoder state |
| 401 | * @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to indicate packet loss |
Gregory Maxwell | e702817 | 2011-11-19 23:58:09 -0500 | [diff] [blame] | 402 | * @param [in] len <tt>opus_int32</tt>: Number of bytes in payload* |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 403 | * @param [out] pcm <tt>opus_int16*</tt>: Output signal (interleaved if 2 channels). length |
| 404 | * is frame_size*channels*sizeof(opus_int16) |
| 405 | * @param [in] frame_size Number of samples per channel of available space in *pcm, |
| 406 | * if less than the maximum frame size (120ms) some frames can not be decoded |
| 407 | * @param [in] decode_fec <tt>int</tt>: Flag (0/1) to request that any in-band forward error correction data be |
| 408 | * decoded. If no such data is available the frame is decoded as if it were lost. |
Gregory Maxwell | d445f02 | 2012-05-20 19:28:45 -0400 | [diff] [blame] | 409 | * @returns Number of decoded samples or @ref opus_errorcodes |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 410 | */ |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame] | 411 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decode( |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 412 | OpusDecoder *st, |
| 413 | const unsigned char *data, |
Gregory Maxwell | e702817 | 2011-11-19 23:58:09 -0500 | [diff] [blame] | 414 | opus_int32 len, |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 415 | opus_int16 *pcm, |
| 416 | int frame_size, |
| 417 | int decode_fec |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame] | 418 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4); |
Jean-Marc Valin | 04584ea | 2010-06-30 15:03:35 -0400 | [diff] [blame] | 419 | |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 420 | /** Decode an opus frame with floating point output |
| 421 | * @param [in] st <tt>OpusDecoder*</tt>: Decoder state |
| 422 | * @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to indicate packet loss |
Gregory Maxwell | e702817 | 2011-11-19 23:58:09 -0500 | [diff] [blame] | 423 | * @param [in] len <tt>opus_int32</tt>: Number of bytes in payload |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 424 | * @param [out] pcm <tt>float*</tt>: Output signal (interleaved if 2 channels). length |
| 425 | * is frame_size*channels*sizeof(float) |
| 426 | * @param [in] frame_size Number of samples per channel of available space in *pcm, |
| 427 | * if less than the maximum frame size (120ms) some frames can not be decoded |
| 428 | * @param [in] decode_fec <tt>int</tt>: Flag (0/1) to request that any in-band forward error correction data be |
| 429 | * decoded. If no such data is available the frame is decoded as if it were lost. |
Gregory Maxwell | d445f02 | 2012-05-20 19:28:45 -0400 | [diff] [blame] | 430 | * @returns Number of decoded samples or @ref opus_errorcodes |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 431 | */ |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame] | 432 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decode_float( |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 433 | OpusDecoder *st, |
| 434 | const unsigned char *data, |
Gregory Maxwell | e702817 | 2011-11-19 23:58:09 -0500 | [diff] [blame] | 435 | opus_int32 len, |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 436 | float *pcm, |
| 437 | int frame_size, |
| 438 | int decode_fec |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame] | 439 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4); |
Gregory Maxwell | 06677d7 | 2011-08-19 12:17:22 -0400 | [diff] [blame] | 440 | |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 441 | /** Perform a CTL function on an Opus decoder. |
Ralph Giles | 10ebc02 | 2011-11-25 23:25:38 -0500 | [diff] [blame] | 442 | * |
| 443 | * Generally the request and subsequent arguments are generated |
| 444 | * by a convenience macro. |
Gregory Maxwell | d445f02 | 2012-05-20 19:28:45 -0400 | [diff] [blame] | 445 | * @see opus_genericctls |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 446 | */ |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame] | 447 | OPUS_EXPORT int opus_decoder_ctl(OpusDecoder *st, int request, ...) OPUS_ARG_NONNULL(1); |
Jean-Marc Valin | 24f36e0 | 2010-07-06 14:41:20 -0400 | [diff] [blame] | 448 | |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 449 | /** Frees an OpusDecoder allocated by opus_decoder_create. |
| 450 | * @param[in] st <tt>OpusDecoder*</tt>: State to be freed. |
| 451 | */ |
Jean-Marc Valin | 280c060 | 2011-05-05 20:47:42 -0400 | [diff] [blame] | 452 | OPUS_EXPORT void opus_decoder_destroy(OpusDecoder *st); |
Jean-Marc Valin | 04584ea | 2010-06-30 15:03:35 -0400 | [diff] [blame] | 453 | |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 454 | /** Parse an opus packet into one or more frames. |
| 455 | * Opus_decode will perform this operation internally so most applications do |
| 456 | * not need to use this function. |
| 457 | * This function does not copy the frames, the returned pointers are pointers into |
| 458 | * the input packet. |
| 459 | * @param [in] data <tt>char*</tt>: Opus packet to be parsed |
Gregory Maxwell | e702817 | 2011-11-19 23:58:09 -0500 | [diff] [blame] | 460 | * @param [in] len <tt>opus_int32</tt>: size of data |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 461 | * @param [out] out_toc <tt>char*</tt>: TOC pointer |
| 462 | * @param [out] frames <tt>char*[48]</tt> encapsulated frames |
| 463 | * @param [out] size <tt>short[48]</tt> sizes of the encapsulated frames |
Jean-Marc Valin | 77519bf | 2011-09-10 01:11:50 -0400 | [diff] [blame] | 464 | * @param [out] payload_offset <tt>int*</tt>: returns the position of the payload within the packet (in bytes) |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 465 | * @returns number of frames |
| 466 | */ |
| 467 | OPUS_EXPORT int opus_packet_parse( |
| 468 | const unsigned char *data, |
Gregory Maxwell | e702817 | 2011-11-19 23:58:09 -0500 | [diff] [blame] | 469 | opus_int32 len, |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 470 | unsigned char *out_toc, |
| 471 | const unsigned char *frames[48], |
| 472 | short size[48], |
| 473 | int *payload_offset |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame] | 474 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4); |
Jean-Marc Valin | 4154dad | 2011-08-08 11:57:13 -0400 | [diff] [blame] | 475 | |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 476 | /** Gets the bandwidth of an Opus packet. |
| 477 | * @param [in] data <tt>char*</tt>: Opus packet |
| 478 | * @retval OPUS_BANDWIDTH_NARROWBAND Narrowband (4kHz bandpass) |
| 479 | * @retval OPUS_BANDWIDTH_MEDIUMBAND Mediumband (6kHz bandpass) |
| 480 | * @retval OPUS_BANDWIDTH_WIDEBAND Wideband (8kHz bandpass) |
| 481 | * @retval OPUS_BANDWIDTH_SUPERWIDEBAND Superwideband (12kHz bandpass) |
| 482 | * @retval OPUS_BANDWIDTH_FULLBAND Fullband (20kHz bandpass) |
| 483 | * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type |
| 484 | */ |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame] | 485 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_bandwidth(const unsigned char *data) OPUS_ARG_NONNULL(1); |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 486 | |
| 487 | /** Gets the number of samples per frame from an Opus packet. |
Timothy B. Terriberry | ddd551e | 2012-09-09 03:13:26 -0700 | [diff] [blame^] | 488 | * @param [in] data <tt>char*</tt>: Opus packet. |
| 489 | * This must contain at least one byte of |
| 490 | * data. |
| 491 | * @param [in] Fs <tt>opus_int32</tt>: Sampling rate in Hz. |
| 492 | * This must be a multiple of 400, or |
| 493 | * inaccurate results will be returned. |
| 494 | * @returns Number of samples per frame. |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 495 | */ |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame] | 496 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_samples_per_frame(const unsigned char *data, opus_int32 Fs) OPUS_ARG_NONNULL(1); |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 497 | |
| 498 | /** Gets the number of channels from an Opus packet. |
| 499 | * @param [in] data <tt>char*</tt>: Opus packet |
| 500 | * @returns Number of channels |
| 501 | * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type |
| 502 | */ |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame] | 503 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_nb_channels(const unsigned char *data) OPUS_ARG_NONNULL(1); |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 504 | |
Ralph Giles | 10ebc02 | 2011-11-25 23:25:38 -0500 | [diff] [blame] | 505 | /** Gets the number of frames in an Opus packet. |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 506 | * @param [in] packet <tt>char*</tt>: Opus packet |
Gregory Maxwell | e702817 | 2011-11-19 23:58:09 -0500 | [diff] [blame] | 507 | * @param [in] len <tt>opus_int32</tt>: Length of packet |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 508 | * @returns Number of frames |
| 509 | * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type |
| 510 | */ |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame] | 511 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_nb_frames(const unsigned char packet[], opus_int32 len) OPUS_ARG_NONNULL(1); |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 512 | |
| 513 | /** Gets the number of samples of an Opus packet. |
| 514 | * @param [in] dec <tt>OpusDecoder*</tt>: Decoder state |
| 515 | * @param [in] packet <tt>char*</tt>: Opus packet |
Gregory Maxwell | e702817 | 2011-11-19 23:58:09 -0500 | [diff] [blame] | 516 | * @param [in] len <tt>opus_int32</tt>: Length of packet |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 517 | * @returns Number of samples |
| 518 | * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type |
| 519 | */ |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame] | 520 | 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); |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 521 | /**@}*/ |
Jean-Marc Valin | 0fe4078 | 2011-03-13 12:41:08 -0400 | [diff] [blame] | 522 | |
Gregory Maxwell | d445f02 | 2012-05-20 19:28:45 -0400 | [diff] [blame] | 523 | /** @defgroup opus_repacketizer Repacketizer |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 524 | * @{ |
Jean-Marc Valin | c248e6d | 2011-09-22 17:59:22 -0400 | [diff] [blame] | 525 | * |
Timothy B. Terriberry | ddd551e | 2012-09-09 03:13:26 -0700 | [diff] [blame^] | 526 | * The repacketizer can be used to merge multiple Opus packets into a single |
| 527 | * packet or alternatively to split Opus packets that have previously been |
| 528 | * merged. The repacketizer currently only operates on elementary Opus |
| 529 | * streams. It will not manipualte multistream packets successfully, except in |
| 530 | * the degenerate case where they consist of data from a single stream. |
Jean-Marc Valin | c248e6d | 2011-09-22 17:59:22 -0400 | [diff] [blame] | 531 | * |
Timothy B. Terriberry | ddd551e | 2012-09-09 03:13:26 -0700 | [diff] [blame^] | 532 | * The repacketizing process starts with creating a repacketizer state, either |
| 533 | * by calling opus_repacketizer_create() or by allocating the memory yourself, |
| 534 | * e.g., |
| 535 | * @code |
| 536 | * OpusRepacketizer *rp; |
| 537 | * rp = (OpusRepacketizer*)malloc(opus_repacketizer_get_size()); |
| 538 | * if (rp != NULL) |
| 539 | * opus_repacketizer_init(rp); |
| 540 | * @endcode |
| 541 | * |
| 542 | * Then the application should submit packets with opus_repacketizer_cat(), |
| 543 | * extract new packets with opus_repacketizer_out() or |
| 544 | * opus_repacketizer_out_range(), and then reset the state for the next set of |
| 545 | * input packets via opus_repacketizer_init(). |
| 546 | * |
| 547 | * For example, to split a sequence of packets into individual frames: |
| 548 | * @code |
| 549 | * unsigned char *data; |
| 550 | * int len; |
| 551 | * while (get_next_packet(&data, &len)) |
| 552 | * { |
| 553 | * unsigned char out[1276]; |
| 554 | * opus_int32 out_len; |
| 555 | * int nb_frames; |
| 556 | * int err; |
| 557 | * int i; |
| 558 | * err = opus_repacketizer_cat(rp, data, len); |
| 559 | * if (err != OPUS_OK) |
| 560 | * { |
| 561 | * release_packet(data); |
| 562 | * return err; |
| 563 | * } |
| 564 | * nb_frames = opus_repacketizer_get_nb_frames(rp); |
| 565 | * for (i = 0; i < nb_frames; i++) |
| 566 | * { |
| 567 | * out_len = opus_repacketizer_out_range(rp, i, i+1, out, sizeof(out)); |
| 568 | * if (out_len < 0) |
| 569 | * { |
| 570 | * release_packet(data); |
| 571 | * return (int)out_len; |
| 572 | * } |
| 573 | * output_next_packet(out, out_len); |
| 574 | * } |
| 575 | * opus_repacketizer_init(rp); |
| 576 | * release_packet(data); |
| 577 | * } |
| 578 | * @endcode |
| 579 | * |
| 580 | * Alternatively, to combine a sequence of frames into packets that each |
| 581 | * contain up to <code>TARGET_DURATION_MS</code> milliseconds of data: |
| 582 | * @code |
| 583 | * // The maximum number of packets with duration TARGET_DURATION_MS occurs |
| 584 | * // when the frame size is 2.5 ms, for a total of (TARGET_DURATION_MS*5/2) |
| 585 | * // packets. |
| 586 | * unsigned char *data[(TARGET_DURATION_MS*5/2)+1]; |
| 587 | * opus_int32 len[(TARGET_DURATION_MS*5/2)+1]; |
| 588 | * int nb_packets; |
| 589 | * unsigned char out[1277*(TARGET_DURATION_MS*5/2)]; |
| 590 | * opus_int32 out_len; |
| 591 | * int prev_toc; |
| 592 | * nb_packets = 0; |
| 593 | * while (get_next_packet(data+nb_packets, len+nb_packets)) |
| 594 | * { |
| 595 | * int nb_frames; |
| 596 | * int err; |
| 597 | * nb_frames = opus_packet_get_nb_frames(data[nb_packets], len[nb_packets]); |
| 598 | * if (nb_frames < 1) |
| 599 | * { |
| 600 | * release_packets(data, nb_packets+1); |
| 601 | * return nb_frames; |
| 602 | * } |
| 603 | * nb_frames += opus_repacketizer_get_nb_frames(rp); |
| 604 | * // If adding the next packet would exceed our target, or it has an |
| 605 | * // incompatible TOC sequence, output the packets we already have before |
| 606 | * // submitting it. |
| 607 | * // N.B., The nb_packets > 0 check ensures we've submitted at least one |
| 608 | * // packet since the last call to opus_repacketizer_init(). Otherwise a |
| 609 | * // single packet longer than TARGET_DURATION_MS would cause us to try to |
| 610 | * // output an (invalid) empty packet. It also ensures that prev_toc has |
| 611 | * // been set to a valid value. Additionally, len[nb_packets] > 0 is |
| 612 | * // guaranteed by the call to opus_packet_get_nb_frames() above, so the |
| 613 | * // reference to data[nb_packets][0] should be valid. |
| 614 | * if (nb_packets > 0 && ( |
| 615 | * ((prev_toc & 0xFC) != (data[nb_packets][0] & 0xFC)) || |
| 616 | * opus_packet_get_samples_per_frame(data[nb_packets], 2000)*nb_frames > |
| 617 | * TARGET_DURATION_MS*2)) |
| 618 | * { |
| 619 | * out_len = opus_repacketizer_out(rp, out, sizeof(out)); |
| 620 | * if (out_len < 0) |
| 621 | * { |
| 622 | * release_packets(data, nb_packets+1); |
| 623 | * return (int)out_len; |
| 624 | * } |
| 625 | * output_next_packet(out, out_len); |
| 626 | * opus_repacketizer_init(rp); |
| 627 | * release_packets(data, nb_packets); |
| 628 | * data[0] = data[nb_packets]; |
| 629 | * len[0] = len[nb_packets]; |
| 630 | * nb_packets = 0; |
| 631 | * } |
| 632 | * err = opus_repacketizer_cat(rp, data[nb_packets], len[nb_packets]); |
| 633 | * if (err != OPUS_OK) |
| 634 | * { |
| 635 | * release_packets(data, nb_packets+1); |
| 636 | * return err; |
| 637 | * } |
| 638 | * prev_toc = data[nb_packets][0]; |
| 639 | * nb_packets++; |
| 640 | * } |
| 641 | * // Output the final, partial packet. |
| 642 | * if (nb_packets > 0) |
| 643 | * { |
| 644 | * out_len = opus_repacketizer_out(rp, out, sizeof(out)); |
| 645 | * release_packets(data, nb_packets); |
| 646 | * if (out_len < 0) |
| 647 | * return (int)out_len; |
| 648 | * output_next_packet(out, out_len); |
| 649 | * } |
| 650 | * @endcode |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 651 | */ |
Jean-Marc Valin | d9636c5 | 2011-07-31 22:29:05 -0400 | [diff] [blame] | 652 | |
Jean-Marc Valin | 369553f | 2011-08-10 08:54:49 -0400 | [diff] [blame] | 653 | typedef struct OpusRepacketizer OpusRepacketizer; |
| 654 | |
Timothy B. Terriberry | ddd551e | 2012-09-09 03:13:26 -0700 | [diff] [blame^] | 655 | /** Gets the size of an <code>OpusRepacketizer</code> structure. |
| 656 | * @returns The size in bytes. |
| 657 | */ |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame] | 658 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_repacketizer_get_size(void); |
Jean-Marc Valin | 369553f | 2011-08-10 08:54:49 -0400 | [diff] [blame] | 659 | |
Timothy B. Terriberry | ddd551e | 2012-09-09 03:13:26 -0700 | [diff] [blame^] | 660 | /** (Re)initializes a previously allocated repacketizer state. |
| 661 | * The state must be the size returned by opus_repacketizer_get_size(). |
| 662 | * This can be used for applications which use their own allocator instead of |
| 663 | * malloc(). |
| 664 | * It must also be called to reset the queue of packets waiting to be |
| 665 | * repacketized, which is necessary if the maximum packet duration of 120 ms |
| 666 | * is reached or if you wish to submit packets with a different Opus |
| 667 | * configuration (coding mode, audio bandwidth, frame size, or channel count). |
| 668 | * Failure to do so will prevent a new packet from being added with |
| 669 | * opus_repacketizer_cat(). |
| 670 | * @see opus_repacketizer_create |
| 671 | * @see opus_repacketizer_get_size |
| 672 | * @see opus_repacketizer_cat |
| 673 | * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state to |
| 674 | * (re)initialize. |
| 675 | * @returns A pointer to the same repacketizer state that was passed in. |
| 676 | */ |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame] | 677 | OPUS_EXPORT OpusRepacketizer *opus_repacketizer_init(OpusRepacketizer *rp) OPUS_ARG_NONNULL(1); |
Jean-Marc Valin | 369553f | 2011-08-10 08:54:49 -0400 | [diff] [blame] | 678 | |
Timothy B. Terriberry | ddd551e | 2012-09-09 03:13:26 -0700 | [diff] [blame^] | 679 | /** Allocates and initializes a repacketizer state. |
| 680 | */ |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame] | 681 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusRepacketizer *opus_repacketizer_create(void); |
Jean-Marc Valin | 369553f | 2011-08-10 08:54:49 -0400 | [diff] [blame] | 682 | |
Timothy B. Terriberry | ddd551e | 2012-09-09 03:13:26 -0700 | [diff] [blame^] | 683 | /** Frees an <code>OpusRepacketizer</code> allocated by |
| 684 | * opus_repacketizer_create(). |
| 685 | * @param[in] rp <tt>OpusRepacketizer*</tt>: State to be freed. |
| 686 | */ |
Jean-Marc Valin | c2d86f0 | 2011-08-10 14:17:55 -0400 | [diff] [blame] | 687 | OPUS_EXPORT void opus_repacketizer_destroy(OpusRepacketizer *rp); |
| 688 | |
Timothy B. Terriberry | ddd551e | 2012-09-09 03:13:26 -0700 | [diff] [blame^] | 689 | /** Add a packet to the current repacketizer state. |
| 690 | * This packet must match the configuration of any packets already submitted |
| 691 | * for repacketization since the last call to opus_repacketizer_init(). |
| 692 | * This means that it must have the same coding mode, audio bandwidth, frame |
| 693 | * size, and channel count. |
| 694 | * This can be checked in advance by examining the top 6 bits of the first |
| 695 | * byte of the packet, and ensuring they match the top 6 bits of the first |
| 696 | * byte of any previously submitted packet. |
| 697 | * The total duration of audio in the repacketizer state also must not exceed |
| 698 | * 120 ms, the maximum duration of a single packet, after adding this packet. |
| 699 | * |
| 700 | * The contents of the current repacketizer state can be extracted into new |
| 701 | * packets using opus_repacketizer_out() or opus_repacketizer_out_range(). |
| 702 | * |
| 703 | * In order to add a packet with a different configuration or to add more |
| 704 | * audio beyond 120 ms, you must clear the repacketizer state by calling |
| 705 | * opus_repacketizer_init(). |
| 706 | * If a packet is too large to add to the current repacketizer state, no part |
| 707 | * of it is added, even if it contains multiple frames, some of which might |
| 708 | * fit. |
| 709 | * If you wish to be able to add parts of such packets, you should first use |
| 710 | * another repacketizer to split the packet into pieces and add them |
| 711 | * individually. |
| 712 | * @see opus_repacketizer_out_range |
| 713 | * @see opus_repacketizer_out |
| 714 | * @see opus_repacketizer_init |
| 715 | * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state to which to |
| 716 | * add the packet. |
| 717 | * @param[in] data <tt>const unsigned char*</tt>: The packet data. |
| 718 | * The application must ensure |
| 719 | * this pointer remains valid |
| 720 | * until the next call to |
| 721 | * opus_repacketizer_init() or |
| 722 | * opus_repacketizer_destroy(). |
| 723 | * @param len <tt>opus_int32</tt>: The number of bytes in the packet data. |
| 724 | * @returns An error code indicating whether or not the operation succeeded. |
| 725 | * @retval #OPUS_OK The packet's contents have been added to the repacketizer |
| 726 | * state. |
| 727 | * @retval #OPUS_INVALID_PACKET The packet did not have a valid TOC sequence, |
| 728 | * the packet's TOC sequence was not compatible |
| 729 | * with previously submitted packets (because |
| 730 | * the coding mode, audio bandwidth, frame size, |
| 731 | * or channel count did not match), or adding |
| 732 | * this packet would increase the total amount of |
| 733 | * audio stored in the repacketizer state to more |
| 734 | * than 120 ms. |
| 735 | */ |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame] | 736 | OPUS_EXPORT int opus_repacketizer_cat(OpusRepacketizer *rp, const unsigned char *data, opus_int32 len) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2); |
Jean-Marc Valin | 369553f | 2011-08-10 08:54:49 -0400 | [diff] [blame] | 737 | |
Timothy B. Terriberry | ddd551e | 2012-09-09 03:13:26 -0700 | [diff] [blame^] | 738 | |
| 739 | /** Construct a new packet from data previously submitted to the repacketizer |
| 740 | * state via opus_repacketizer_cat(). |
| 741 | * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state from which to |
| 742 | * construct the new packet. |
| 743 | * @param begin <tt>int</tt>: The index of the first frame in the current |
| 744 | * repacketizer state to include in the output. |
| 745 | * @param end <tt>int</tt>: One past the index of the last frame in the |
| 746 | * current repacketizer state to include in the |
| 747 | * output. |
| 748 | * @param[out] data <tt>const unsigned char*</tt>: The buffer in which to |
| 749 | * store the output packet. |
| 750 | * @param maxlen <tt>opus_int32</tt>: The maximum number of bytes to store in |
| 751 | * the output buffer. In order to guarantee |
| 752 | * success, this should be at least |
| 753 | * <code>1276</code> for a single frame, |
| 754 | * or for multiple frames, |
| 755 | * <code>1277*(end-begin)</code>. |
| 756 | * However, <code>1*(end-begin)</code> plus |
| 757 | * the size of all packet data submitted to |
| 758 | * the repacketizer since the last call to |
| 759 | * opus_repacketizer_init() or |
| 760 | * opus_repacketizer_create() is also |
| 761 | * sufficient, and possibly much smaller. |
| 762 | * @returns The total size of the output packet on success, or an error code |
| 763 | * on failure. |
| 764 | * @retval #OPUS_BAD_ARG <code>[begin,end)</code> was an invalid range of |
| 765 | * frames (begin < 0, begin >= end, or end > |
| 766 | * opus_repacketizer_get_nb_frames()). |
| 767 | * @retval #OPUS_BUFFER_TOO_SMALL \a maxlen was insufficient to contain the |
| 768 | * complete output packet. |
| 769 | */ |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame] | 770 | 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); |
Jean-Marc Valin | 369553f | 2011-08-10 08:54:49 -0400 | [diff] [blame] | 771 | |
Timothy B. Terriberry | ddd551e | 2012-09-09 03:13:26 -0700 | [diff] [blame^] | 772 | /** Return the total number of frames contained in packet data submitted to |
| 773 | * the repacketizer state so far via opus_repacketizer_cat() since the last |
| 774 | * call to opus_repacketizer_init() or opus_repacketizer_create(). |
| 775 | * This defines the valid range of packets that can be extracted with |
| 776 | * opus_repacketizer_out_range() or opus_repacketizer_out(). |
| 777 | * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state containing the |
| 778 | * frames. |
| 779 | * @returns The total number of frames contained in the packet data submitted |
| 780 | * to the repacketizer state. |
| 781 | */ |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame] | 782 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_repacketizer_get_nb_frames(OpusRepacketizer *rp) OPUS_ARG_NONNULL(1); |
Jean-Marc Valin | c2d86f0 | 2011-08-10 14:17:55 -0400 | [diff] [blame] | 783 | |
Timothy B. Terriberry | ddd551e | 2012-09-09 03:13:26 -0700 | [diff] [blame^] | 784 | /** Construct a new packet from data previously submitted to the repacketizer |
| 785 | * state via opus_repacketizer_cat(). |
| 786 | * This is a convenience routine that returns all the data submitted so far |
| 787 | * in a single packet. |
| 788 | * It is equivalent to calling |
| 789 | * @code |
| 790 | * opus_repacketizer_out_range(rp, 0, opus_repacketizer_get_nb_frames(rp), |
| 791 | * data, maxlen) |
| 792 | * @endcode |
| 793 | * @param rp <tt>OpusRepacketizer*</tt>: The repacketizer state from which to |
| 794 | * construct the new packet. |
| 795 | * @param[out] data <tt>const unsigned char*</tt>: The buffer in which to |
| 796 | * store the output packet. |
| 797 | * @param maxlen <tt>opus_int32</tt>: The maximum number of bytes to store in |
| 798 | * the output buffer. In order to guarantee |
| 799 | * success, this should be at least |
| 800 | * <code>1277*opus_repacketizer_get_nb_frames(rp)</code>. |
| 801 | * However, |
| 802 | * <code>1*opus_repacketizer_get_nb_frames(rp)</code> |
| 803 | * plus the size of all packet data |
| 804 | * submitted to the repacketizer since the |
| 805 | * last call to opus_repacketizer_init() or |
| 806 | * opus_repacketizer_create() is also |
| 807 | * sufficient, and possibly much smaller. |
| 808 | * @returns The total size of the output packet on success, or an error code |
| 809 | * on failure. |
| 810 | * @retval #OPUS_BUFFER_TOO_SMALL \a maxlen was insufficient to contain the |
| 811 | * complete output packet. |
| 812 | */ |
Gregory Maxwell | c64f4a4 | 2012-06-01 02:21:53 -0400 | [diff] [blame] | 813 | OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_repacketizer_out(OpusRepacketizer *rp, unsigned char *data, opus_int32 maxlen) OPUS_ARG_NONNULL(1); |
Jean-Marc Valin | e8dbcb8 | 2011-08-10 09:47:30 -0400 | [diff] [blame] | 814 | |
Gregory Maxwell | 3bcf367 | 2011-09-09 17:11:43 -0400 | [diff] [blame] | 815 | /**@}*/ |
| 816 | |
Jean-Marc Valin | 24f36e0 | 2010-07-06 14:41:20 -0400 | [diff] [blame] | 817 | #ifdef __cplusplus |
| 818 | } |
| 819 | #endif |
| 820 | |
Jean-Marc Valin | 05dd36a | 2010-10-18 12:50:49 -0400 | [diff] [blame] | 821 | #endif /* OPUS_H */ |