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