1 /* 2 * Copyright (c) 2012 The WebRTC project authors. All Rights Reserved. 3 * 4 * Use of this source code is governed by a BSD-style license 5 * that can be found in the LICENSE file in the root of the source 6 * tree. An additional intellectual property rights grant can be found 7 * in the file PATENTS. All contributing project authors may 8 * be found in the AUTHORS file in the root of the source tree. 9 */ 10 11 #ifndef WEBRTC_MODULES_AUDIO_CODING_CODECS_OPUS_INTERFACE_OPUS_INTERFACE_H_ 12 #define WEBRTC_MODULES_AUDIO_CODING_CODECS_OPUS_INTERFACE_OPUS_INTERFACE_H_ 13 14 #include "webrtc/typedefs.h" 15 16 #ifdef __cplusplus 17 extern "C" { 18 #endif 19 20 // Opaque wrapper types for the codec state. 21 typedef struct WebRtcOpusEncInst OpusEncInst; 22 typedef struct WebRtcOpusDecInst OpusDecInst; 23 24 int16_t WebRtcOpus_EncoderCreate(OpusEncInst** inst, int32_t channels); 25 int16_t WebRtcOpus_EncoderFree(OpusEncInst* inst); 26 27 /**************************************************************************** 28 * WebRtcOpus_Encode(...) 29 * 30 * This function encodes audio as a series of Opus frames and inserts 31 * it into a packet. Input buffer can be any length. 32 * 33 * Input: 34 * - inst : Encoder context 35 * - audio_in : Input speech data buffer 36 * - samples : Samples per channel in audio_in 37 * - length_encoded_buffer : Output buffer size 38 * 39 * Output: 40 * - encoded : Output compressed data buffer 41 * 42 * Return value : >0 - Length (in bytes) of coded data 43 * -1 - Error 44 */ 45 int16_t WebRtcOpus_Encode(OpusEncInst* inst, int16_t* audio_in, int16_t samples, 46 int16_t length_encoded_buffer, uint8_t* encoded); 47 48 /**************************************************************************** 49 * WebRtcOpus_SetBitRate(...) 50 * 51 * This function adjusts the target bitrate of the encoder. 52 * 53 * Input: 54 * - inst : Encoder context 55 * - rate : New target bitrate 56 * 57 * Return value : 0 - Success 58 * -1 - Error 59 */ 60 int16_t WebRtcOpus_SetBitRate(OpusEncInst* inst, int32_t rate); 61 62 /**************************************************************************** 63 * WebRtcOpus_SetPacketLossRate(...) 64 * 65 * This function configures the encoder's expected packet loss percentage. 66 * 67 * Input: 68 * - inst : Encoder context 69 * - loss_rate : loss percentage in the range 0-100, inclusive. 70 * Return value : 0 - Success 71 * -1 - Error 72 */ 73 int16_t WebRtcOpus_SetPacketLossRate(OpusEncInst* inst, int32_t loss_rate); 74 75 /**************************************************************************** 76 * WebRtcOpus_SetMaxPlaybackRate(...) 77 * 78 * Configures the maximum playback rate for encoding. Due to hardware 79 * limitations, the receiver may render audio up to a playback rate. Opus 80 * encoder can use this information to optimize for network usage and encoding 81 * complexity. This will affect the audio bandwidth in the coded audio. However, 82 * the input/output sample rate is not affected. 83 * 84 * Input: 85 * - inst : Encoder context 86 * - frequency_hz : Maximum playback rate in Hz. 87 * This parameter can take any value. The relation 88 * between the value and the Opus internal mode is 89 * as following: 90 * frequency_hz <= 8000 narrow band 91 * 8000 < frequency_hz <= 12000 medium band 92 * 12000 < frequency_hz <= 16000 wide band 93 * 16000 < frequency_hz <= 24000 super wide band 94 * frequency_hz > 24000 full band 95 * Return value : 0 - Success 96 * -1 - Error 97 */ 98 int16_t WebRtcOpus_SetMaxPlaybackRate(OpusEncInst* inst, int32_t frequency_hz); 99 100 /* TODO(minyue): Check whether an API to check the FEC and the packet loss rate 101 * is needed. It might not be very useful since there are not many use cases and 102 * the caller can always maintain the states. */ 103 104 /**************************************************************************** 105 * WebRtcOpus_EnableFec() 106 * 107 * This function enables FEC for encoding. 108 * 109 * Input: 110 * - inst : Encoder context 111 * 112 * Return value : 0 - Success 113 * -1 - Error 114 */ 115 int16_t WebRtcOpus_EnableFec(OpusEncInst* inst); 116 117 /**************************************************************************** 118 * WebRtcOpus_DisableFec() 119 * 120 * This function disables FEC for encoding. 121 * 122 * Input: 123 * - inst : Encoder context 124 * 125 * Return value : 0 - Success 126 * -1 - Error 127 */ 128 int16_t WebRtcOpus_DisableFec(OpusEncInst* inst); 129 130 /* 131 * WebRtcOpus_SetComplexity(...) 132 * 133 * This function adjusts the computational complexity. The effect is the same as 134 * calling the complexity setting of Opus as an Opus encoder related CTL. 135 * 136 * Input: 137 * - inst : Encoder context 138 * - complexity : New target complexity (0-10, inclusive) 139 * 140 * Return value : 0 - Success 141 * -1 - Error 142 */ 143 int16_t WebRtcOpus_SetComplexity(OpusEncInst* inst, int32_t complexity); 144 145 int16_t WebRtcOpus_DecoderCreate(OpusDecInst** inst, int channels); 146 int16_t WebRtcOpus_DecoderFree(OpusDecInst* inst); 147 148 /**************************************************************************** 149 * WebRtcOpus_DecoderChannels(...) 150 * 151 * This function returns the number of channels created for Opus decoder. 152 */ 153 int WebRtcOpus_DecoderChannels(OpusDecInst* inst); 154 155 /**************************************************************************** 156 * WebRtcOpus_DecoderInit(...) 157 * 158 * This function resets state of the decoder. 159 * 160 * Input: 161 * - inst : Decoder context 162 * 163 * Return value : 0 - Success 164 * -1 - Error 165 */ 166 int16_t WebRtcOpus_DecoderInitNew(OpusDecInst* inst); 167 int16_t WebRtcOpus_DecoderInit(OpusDecInst* inst); 168 int16_t WebRtcOpus_DecoderInitSlave(OpusDecInst* inst); 169 170 /**************************************************************************** 171 * WebRtcOpus_Decode(...) 172 * 173 * This function decodes an Opus packet into one or more audio frames at the 174 * ACM interface's sampling rate (32 kHz). 175 * 176 * Input: 177 * - inst : Decoder context 178 * - encoded : Encoded data 179 * - encoded_bytes : Bytes in encoded vector 180 * 181 * Output: 182 * - decoded : The decoded vector 183 * - audio_type : 1 normal, 2 CNG (for Opus it should 184 * always return 1 since we're not using Opus's 185 * built-in DTX/CNG scheme) 186 * 187 * Return value : >0 - Samples per channel in decoded vector 188 * -1 - Error 189 */ 190 int16_t WebRtcOpus_DecodeNew(OpusDecInst* inst, const uint8_t* encoded, 191 int16_t encoded_bytes, int16_t* decoded, 192 int16_t* audio_type); 193 int16_t WebRtcOpus_Decode(OpusDecInst* inst, const int16_t* encoded, 194 int16_t encoded_bytes, int16_t* decoded, 195 int16_t* audio_type); 196 int16_t WebRtcOpus_DecodeSlave(OpusDecInst* inst, const int16_t* encoded, 197 int16_t encoded_bytes, int16_t* decoded, 198 int16_t* audio_type); 199 200 /**************************************************************************** 201 * WebRtcOpus_DecodePlc(...) 202 * TODO(tlegrand): Remove master and slave functions when NetEq4 is in place. 203 * WebRtcOpus_DecodePlcMaster(...) 204 * WebRtcOpus_DecodePlcSlave(...) 205 * 206 * This function processes PLC for opus frame(s). 207 * Input: 208 * - inst : Decoder context 209 * - number_of_lost_frames : Number of PLC frames to produce 210 * 211 * Output: 212 * - decoded : The decoded vector 213 * 214 * Return value : >0 - number of samples in decoded PLC vector 215 * -1 - Error 216 */ 217 int16_t WebRtcOpus_DecodePlc(OpusDecInst* inst, int16_t* decoded, 218 int16_t number_of_lost_frames); 219 int16_t WebRtcOpus_DecodePlcMaster(OpusDecInst* inst, int16_t* decoded, 220 int16_t number_of_lost_frames); 221 int16_t WebRtcOpus_DecodePlcSlave(OpusDecInst* inst, int16_t* decoded, 222 int16_t number_of_lost_frames); 223 224 /**************************************************************************** 225 * WebRtcOpus_DecodeFec(...) 226 * 227 * This function decodes the FEC data from an Opus packet into one or more audio 228 * frames at the ACM interface's sampling rate (32 kHz). 229 * 230 * Input: 231 * - inst : Decoder context 232 * - encoded : Encoded data 233 * - encoded_bytes : Bytes in encoded vector 234 * 235 * Output: 236 * - decoded : The decoded vector (previous frame) 237 * 238 * Return value : >0 - Samples per channel in decoded vector 239 * 0 - No FEC data in the packet 240 * -1 - Error 241 */ 242 int16_t WebRtcOpus_DecodeFec(OpusDecInst* inst, const uint8_t* encoded, 243 int16_t encoded_bytes, int16_t* decoded, 244 int16_t* audio_type); 245 246 /**************************************************************************** 247 * WebRtcOpus_DurationEst(...) 248 * 249 * This function calculates the duration of an opus packet. 250 * Input: 251 * - inst : Decoder context 252 * - payload : Encoded data pointer 253 * - payload_length_bytes : Bytes of encoded data 254 * 255 * Return value : The duration of the packet, in samples. 256 */ 257 int WebRtcOpus_DurationEst(OpusDecInst* inst, 258 const uint8_t* payload, 259 int payload_length_bytes); 260 261 /* TODO(minyue): Check whether it is needed to add a decoder context to the 262 * arguments, like WebRtcOpus_DurationEst(...). In fact, the packet itself tells 263 * the duration. The decoder context in WebRtcOpus_DurationEst(...) is not used. 264 * So it may be advisable to remove it from WebRtcOpus_DurationEst(...). */ 265 266 /**************************************************************************** 267 * WebRtcOpus_FecDurationEst(...) 268 * 269 * This function calculates the duration of the FEC data within an opus packet. 270 * Input: 271 * - payload : Encoded data pointer 272 * - payload_length_bytes : Bytes of encoded data 273 * 274 * Return value : >0 - The duration of the FEC data in the 275 * packet in samples. 276 * 0 - No FEC data in the packet. 277 */ 278 int WebRtcOpus_FecDurationEst(const uint8_t* payload, 279 int payload_length_bytes); 280 281 /**************************************************************************** 282 * WebRtcOpus_PacketHasFec(...) 283 * 284 * This function detects if an opus packet has FEC. 285 * Input: 286 * - payload : Encoded data pointer 287 * - payload_length_bytes : Bytes of encoded data 288 * 289 * Return value : 0 - the packet does NOT contain FEC. 290 * 1 - the packet contains FEC. 291 */ 292 int WebRtcOpus_PacketHasFec(const uint8_t* payload, 293 int payload_length_bytes); 294 295 #ifdef __cplusplus 296 } // extern "C" 297 #endif 298 299 #endif // WEBRTC_MODULES_AUDIO_CODING_CODECS_OPUS_INTERFACE_OPUS_INTERFACE_H_ 300
