src/third_party/webrtc/modules/audio_coding/codecs/opus/interface/opus_interface.h

   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_SetMaxBandwidth(...)
  77  *
  78  * Configures the maximum bandwidth for encoding. This can be taken as a hint
  79  * about the maximum output bandwidth that the receiver is capable to render,
  80  * due to hardware limitations. Sending signals with higher audio bandwidth
  81  * results in higher than necessary network usage and encoding complexity.
  82  *
  83  * Input:
  84  *      - inst               : Encoder context
  85  *      - bandwidth          : Maximum encoding bandwidth in Hz.
  86  *                             This parameter can take any value, but values
  87  *                             other than Opus typical bandwidths: 4000, 6000,
  88  *                             8000, 12000, and 20000 will be rounded up (values
  89  *                             greater than 20000 will be rounded down) to
  90  *                             these values.
  91  * Return value              :  0 - Success
  92  *                             -1 - Error
  93  */
  94 int16_t WebRtcOpus_SetMaxBandwidth(OpusEncInst* inst, int32_t bandwidth);
  95
  96 /* TODO(minyue): Check whether an API to check the FEC and the packet loss rate
  97  * is needed. It might not be very useful since there are not many use cases and
  98  * the caller can always maintain the states. */
  99
 100 /****************************************************************************
 101  * WebRtcOpus_EnableFec()
 102  *
 103  * This function enables FEC for encoding.
 104  *
 105  * Input:
 106  *      - inst               : Encoder context
 107  *
 108  * Return value              :  0 - Success
 109  *                             -1 - Error
 110  */
 111 int16_t WebRtcOpus_EnableFec(OpusEncInst* inst);
 112
 113 /****************************************************************************
 114  * WebRtcOpus_DisableFec()
 115  *
 116  * This function disables FEC for encoding.
 117  *
 118  * Input:
 119  *      - inst               : Encoder context
 120  *
 121  * Return value              :  0 - Success
 122  *                             -1 - Error
 123  */
 124 int16_t WebRtcOpus_DisableFec(OpusEncInst* inst);
 125
 126 /*
 127  * WebRtcOpus_SetComplexity(...)
 128  *
 129  * This function adjusts the computational complexity. The effect is the same as
 130  * calling the complexity setting of Opus as an Opus encoder related CTL.
 131  *
 132  * Input:
 133  *      - inst               : Encoder context
 134  *      - complexity         : New target complexity (0-10, inclusive)
 135  *
 136  * Return value              :  0 - Success
 137  *                             -1 - Error
 138  */
 139 int16_t WebRtcOpus_SetComplexity(OpusEncInst* inst, int32_t complexity);
 140
 141 int16_t WebRtcOpus_DecoderCreate(OpusDecInst** inst, int channels);
 142 int16_t WebRtcOpus_DecoderFree(OpusDecInst* inst);
 143
 144 /****************************************************************************
 145  * WebRtcOpus_DecoderChannels(...)
 146  *
 147  * This function returns the number of channels created for Opus decoder.
 148  */
 149 int WebRtcOpus_DecoderChannels(OpusDecInst* inst);
 150
 151 /****************************************************************************
 152  * WebRtcOpus_DecoderInit(...)
 153  *
 154  * This function resets state of the decoder.
 155  *
 156  * Input:
 157  *      - inst               : Decoder context
 158  *
 159  * Return value              :  0 - Success
 160  *                             -1 - Error
 161  */
 162 int16_t WebRtcOpus_DecoderInitNew(OpusDecInst* inst);
 163 int16_t WebRtcOpus_DecoderInit(OpusDecInst* inst);
 164 int16_t WebRtcOpus_DecoderInitSlave(OpusDecInst* inst);
 165
 166 /****************************************************************************
 167  * WebRtcOpus_Decode(...)
 168  *
 169  * This function decodes an Opus packet into one or more audio frames at the
 170  * ACM interface's sampling rate (32 kHz).
 171  *
 172  * Input:
 173  *      - inst               : Decoder context
 174  *      - encoded            : Encoded data
 175  *      - encoded_bytes      : Bytes in encoded vector
 176  *
 177  * Output:
 178  *      - decoded            : The decoded vector
 179  *      - audio_type         : 1 normal, 2 CNG (for Opus it should
 180  *                             always return 1 since we're not using Opus's
 181  *                             built-in DTX/CNG scheme)
 182  *
 183  * Return value              : >0 - Samples per channel in decoded vector
 184  *                             -1 - Error
 185  */
 186 int16_t WebRtcOpus_DecodeNew(OpusDecInst* inst, const uint8_t* encoded,
 187                              int16_t encoded_bytes, int16_t* decoded,
 188                              int16_t* audio_type);
 189 int16_t WebRtcOpus_Decode(OpusDecInst* inst, const int16_t* encoded,
 190                           int16_t encoded_bytes, int16_t* decoded,
 191                           int16_t* audio_type);
 192 int16_t WebRtcOpus_DecodeSlave(OpusDecInst* inst, const int16_t* encoded,
 193                                int16_t encoded_bytes, int16_t* decoded,
 194                                int16_t* audio_type);
 195
 196 /****************************************************************************
 197  * WebRtcOpus_DecodePlc(...)
 198  * TODO(tlegrand): Remove master and slave functions when NetEq4 is in place.
 199  * WebRtcOpus_DecodePlcMaster(...)
 200  * WebRtcOpus_DecodePlcSlave(...)
 201  *
 202  * This function processes PLC for opus frame(s).
 203  * Input:
 204  *        - inst                  : Decoder context
 205  *        - number_of_lost_frames : Number of PLC frames to produce
 206  *
 207  * Output:
 208  *        - decoded               : The decoded vector
 209  *
 210  * Return value                   : >0 - number of samples in decoded PLC vector
 211  *                                  -1 - Error
 212  */
 213 int16_t WebRtcOpus_DecodePlc(OpusDecInst* inst, int16_t* decoded,
 214                              int16_t number_of_lost_frames);
 215 int16_t WebRtcOpus_DecodePlcMaster(OpusDecInst* inst, int16_t* decoded,
 216                                    int16_t number_of_lost_frames);
 217 int16_t WebRtcOpus_DecodePlcSlave(OpusDecInst* inst, int16_t* decoded,
 218                                   int16_t number_of_lost_frames);
 219
 220 /****************************************************************************
 221  * WebRtcOpus_DecodeFec(...)
 222  *
 223  * This function decodes the FEC data from an Opus packet into one or more audio
 224  * frames at the ACM interface's sampling rate (32 kHz).
 225  *
 226  * Input:
 227  *      - inst               : Decoder context
 228  *      - encoded            : Encoded data
 229  *      - encoded_bytes      : Bytes in encoded vector
 230  *
 231  * Output:
 232  *      - decoded            : The decoded vector (previous frame)
 233  *
 234  * Return value              : >0 - Samples per channel in decoded vector
 235  *                              0 - No FEC data in the packet
 236  *                             -1 - Error
 237  */
 238 int16_t WebRtcOpus_DecodeFec(OpusDecInst* inst, const uint8_t* encoded,
 239                              int16_t encoded_bytes, int16_t* decoded,
 240                              int16_t* audio_type);
 241
 242 /****************************************************************************
 243  * WebRtcOpus_DurationEst(...)
 244  *
 245  * This function calculates the duration of an opus packet.
 246  * Input:
 247  *        - inst                 : Decoder context
 248  *        - payload              : Encoded data pointer
 249  *        - payload_length_bytes : Bytes of encoded data
 250  *
 251  * Return value                  : The duration of the packet, in samples.
 252  */
 253 int WebRtcOpus_DurationEst(OpusDecInst* inst,
 254                            const uint8_t* payload,
 255                            int payload_length_bytes);
 256
 257 /* TODO(minyue): Check whether it is needed to add a decoder context to the
 258  * arguments, like WebRtcOpus_DurationEst(...). In fact, the packet itself tells
 259  * the duration. The decoder context in WebRtcOpus_DurationEst(...) is not used.
 260  * So it may be advisable to remove it from WebRtcOpus_DurationEst(...). */
 261
 262 /****************************************************************************
 263  * WebRtcOpus_FecDurationEst(...)
 264  *
 265  * This function calculates the duration of the FEC data within an opus packet.
 266  * Input:
 267  *        - payload              : Encoded data pointer
 268  *        - payload_length_bytes : Bytes of encoded data
 269  *
 270  * Return value                  : >0 - The duration of the FEC data in the
 271  *                                 packet in samples.
 272  *                                  0 - No FEC data in the packet.
 273  */
 274 int WebRtcOpus_FecDurationEst(const uint8_t* payload,
 275                               int payload_length_bytes);
 276
 277 /****************************************************************************
 278  * WebRtcOpus_PacketHasFec(...)
 279  *
 280  * This function detects if an opus packet has FEC.
 281  * Input:
 282  *        - payload              : Encoded data pointer
 283  *        - payload_length_bytes : Bytes of encoded data
 284  *
 285  * Return value                  : 0 - the packet does NOT contain FEC.
 286  *                                 1 - the packet contains FEC.
 287  */
 288 int WebRtcOpus_PacketHasFec(const uint8_t* payload,
 289                             int payload_length_bytes);
 290
 291 #ifdef __cplusplus
 292 }  // extern "C"
 293 #endif
 294
 295 #endif  // WEBRTC_MODULES_AUDIO_CODING_CODECS_OPUS_INTERFACE_OPUS_INTERFACE_H_