Line data Source code
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_INCLUDE_AUDIO_CODING_MODULE_H_
12 : #define WEBRTC_MODULES_AUDIO_CODING_INCLUDE_AUDIO_CODING_MODULE_H_
13 :
14 : #include <memory>
15 : #include <string>
16 : #include <vector>
17 :
18 : #include "webrtc/base/deprecation.h"
19 : #include "webrtc/base/function_view.h"
20 : #include "webrtc/base/optional.h"
21 : #include "webrtc/common_types.h"
22 : #include "webrtc/modules/audio_coding/codecs/audio_decoder_factory.h"
23 : #include "webrtc/modules/audio_coding/include/audio_coding_module_typedefs.h"
24 : #include "webrtc/modules/audio_coding/neteq/include/neteq.h"
25 : #include "webrtc/modules/include/module.h"
26 : #include "webrtc/system_wrappers/include/clock.h"
27 : #include "webrtc/typedefs.h"
28 :
29 : namespace webrtc {
30 :
31 : // forward declarations
32 : struct CodecInst;
33 : struct WebRtcRTPHeader;
34 : class AudioDecoder;
35 : class AudioEncoder;
36 : class AudioFrame;
37 : class RTPFragmentationHeader;
38 :
39 : #define WEBRTC_10MS_PCM_AUDIO 960 // 16 bits super wideband 48 kHz
40 :
41 : // Callback class used for sending data ready to be packetized
42 0 : class AudioPacketizationCallback {
43 : public:
44 0 : virtual ~AudioPacketizationCallback() {}
45 :
46 : virtual int32_t SendData(FrameType frame_type,
47 : uint8_t payload_type,
48 : uint32_t timestamp,
49 : const uint8_t* payload_data,
50 : size_t payload_len_bytes,
51 : const RTPFragmentationHeader* fragmentation) = 0;
52 : };
53 :
54 : // Callback class used for reporting VAD decision
55 0 : class ACMVADCallback {
56 : public:
57 0 : virtual ~ACMVADCallback() {}
58 :
59 : virtual int32_t InFrameType(FrameType frame_type) = 0;
60 : };
61 :
62 : class AudioCodingModule {
63 : protected:
64 0 : AudioCodingModule() {}
65 :
66 : public:
67 0 : struct Config {
68 : Config();
69 : Config(const Config&);
70 : ~Config();
71 :
72 : int id;
73 : NetEq::Config neteq_config;
74 : Clock* clock;
75 : rtc::scoped_refptr<AudioDecoderFactory> decoder_factory;
76 : };
77 :
78 : ///////////////////////////////////////////////////////////////////////////
79 : // Creation and destruction of a ACM.
80 : //
81 : // The second method is used for testing where a simulated clock can be
82 : // injected into ACM. ACM will take the ownership of the object clock and
83 : // delete it when destroyed.
84 : //
85 : static AudioCodingModule* Create(int id);
86 : static AudioCodingModule* Create(int id, Clock* clock);
87 : static AudioCodingModule* Create(const Config& config);
88 0 : virtual ~AudioCodingModule() = default;
89 :
90 : ///////////////////////////////////////////////////////////////////////////
91 : // Utility functions
92 : //
93 :
94 : ///////////////////////////////////////////////////////////////////////////
95 : // uint8_t NumberOfCodecs()
96 : // Returns number of supported codecs.
97 : //
98 : // Return value:
99 : // number of supported codecs.
100 : ///
101 : static int NumberOfCodecs();
102 :
103 : ///////////////////////////////////////////////////////////////////////////
104 : // int32_t Codec()
105 : // Get supported codec with list number.
106 : //
107 : // Input:
108 : // -list_id : list number.
109 : //
110 : // Output:
111 : // -codec : a structure where the parameters of the codec,
112 : // given by list number is written to.
113 : //
114 : // Return value:
115 : // -1 if the list number (list_id) is invalid.
116 : // 0 if succeeded.
117 : //
118 : static int Codec(int list_id, CodecInst* codec);
119 :
120 : ///////////////////////////////////////////////////////////////////////////
121 : // int32_t Codec()
122 : // Get supported codec with the given codec name, sampling frequency, and
123 : // a given number of channels.
124 : //
125 : // Input:
126 : // -payload_name : name of the codec.
127 : // -sampling_freq_hz : sampling frequency of the codec. Note! for RED
128 : // a sampling frequency of -1 is a valid input.
129 : // -channels : number of channels ( 1 - mono, 2 - stereo).
130 : //
131 : // Output:
132 : // -codec : a structure where the function returns the
133 : // default parameters of the codec.
134 : //
135 : // Return value:
136 : // -1 if no codec matches the given parameters.
137 : // 0 if succeeded.
138 : //
139 : static int Codec(const char* payload_name, CodecInst* codec,
140 : int sampling_freq_hz, size_t channels);
141 :
142 : ///////////////////////////////////////////////////////////////////////////
143 : // int32_t Codec()
144 : //
145 : // Returns the list number of the given codec name, sampling frequency, and
146 : // a given number of channels.
147 : //
148 : // Input:
149 : // -payload_name : name of the codec.
150 : // -sampling_freq_hz : sampling frequency of the codec. Note! for RED
151 : // a sampling frequency of -1 is a valid input.
152 : // -channels : number of channels ( 1 - mono, 2 - stereo).
153 : //
154 : // Return value:
155 : // if the codec is found, the index of the codec in the list,
156 : // -1 if the codec is not found.
157 : //
158 : static int Codec(const char* payload_name, int sampling_freq_hz,
159 : size_t channels);
160 :
161 : ///////////////////////////////////////////////////////////////////////////
162 : // bool IsCodecValid()
163 : // Checks the validity of the parameters of the given codec.
164 : //
165 : // Input:
166 : // -codec : the structure which keeps the parameters of the
167 : // codec.
168 : //
169 : // Return value:
170 : // true if the parameters are valid,
171 : // false if any parameter is not valid.
172 : //
173 : static bool IsCodecValid(const CodecInst& codec);
174 :
175 : ///////////////////////////////////////////////////////////////////////////
176 : // Sender
177 : //
178 :
179 : ///////////////////////////////////////////////////////////////////////////
180 : // int32_t RegisterSendCodec()
181 : // Registers a codec, specified by |send_codec|, as sending codec.
182 : // This API can be called multiple of times to register Codec. The last codec
183 : // registered overwrites the previous ones.
184 : // The API can also be used to change payload type for CNG and RED, which are
185 : // registered by default to default payload types.
186 : // Note that registering CNG and RED won't overwrite speech codecs.
187 : // This API can be called to set/change the send payload-type, frame-size
188 : // or encoding rate (if applicable for the codec).
189 : //
190 : // Note: If a stereo codec is registered as send codec, VAD/DTX will
191 : // automatically be turned off, since it is not supported for stereo sending.
192 : //
193 : // Note: If a secondary encoder is already registered, and the new send-codec
194 : // has a sampling rate that does not match the secondary encoder, the
195 : // secondary encoder will be unregistered.
196 : //
197 : // Input:
198 : // -send_codec : Parameters of the codec to be registered, c.f.
199 : // common_types.h for the definition of
200 : // CodecInst.
201 : //
202 : // Return value:
203 : // -1 if failed to initialize,
204 : // 0 if succeeded.
205 : //
206 : virtual int32_t RegisterSendCodec(const CodecInst& send_codec) = 0;
207 :
208 : // Registers |external_speech_encoder| as encoder. The new encoder will
209 : // replace any previously registered speech encoder (internal or external).
210 : virtual void RegisterExternalSendCodec(
211 : AudioEncoder* external_speech_encoder) = 0;
212 :
213 : // |modifier| is called exactly once with one argument: a pointer to the
214 : // unique_ptr that holds the current encoder (which is null if there is no
215 : // current encoder). For the duration of the call, |modifier| has exclusive
216 : // access to the unique_ptr; it may call the encoder, steal the encoder and
217 : // replace it with another encoder or with nullptr, etc.
218 : virtual void ModifyEncoder(
219 : rtc::FunctionView<void(std::unique_ptr<AudioEncoder>*)> modifier) = 0;
220 :
221 : // |modifier| is called exactly once with one argument: a const pointer to the
222 : // current encoder (which is null if there is no current encoder).
223 : virtual void QueryEncoder(
224 : rtc::FunctionView<void(AudioEncoder const*)> query) = 0;
225 :
226 : // Utility method for simply replacing the existing encoder with a new one.
227 0 : void SetEncoder(std::unique_ptr<AudioEncoder> new_encoder) {
228 0 : ModifyEncoder([&](std::unique_ptr<AudioEncoder>* encoder) {
229 0 : *encoder = std::move(new_encoder);
230 0 : });
231 0 : }
232 :
233 : ///////////////////////////////////////////////////////////////////////////
234 : // int32_t SendCodec()
235 : // Get parameters for the codec currently registered as send codec.
236 : //
237 : // Return value:
238 : // The send codec, or nothing if we don't have one
239 : //
240 : virtual rtc::Optional<CodecInst> SendCodec() const = 0;
241 :
242 : ///////////////////////////////////////////////////////////////////////////
243 : // int32_t SendFrequency()
244 : // Get the sampling frequency of the current encoder in Hertz.
245 : //
246 : // Return value:
247 : // positive; sampling frequency [Hz] of the current encoder.
248 : // -1 if an error has happened.
249 : //
250 : virtual int32_t SendFrequency() const = 0;
251 :
252 : ///////////////////////////////////////////////////////////////////////////
253 : // Sets the bitrate to the specified value in bits/sec. If the value is not
254 : // supported by the codec, it will choose another appropriate value.
255 : //
256 : // This is only used in test code that rely on old ACM APIs.
257 : // TODO(minyue): Remove it when possible.
258 : virtual void SetBitRate(int bitrate_bps) = 0;
259 :
260 : // int32_t RegisterTransportCallback()
261 : // Register a transport callback which will be called to deliver
262 : // the encoded buffers whenever Process() is called and a
263 : // bit-stream is ready.
264 : //
265 : // Input:
266 : // -transport : pointer to the callback class
267 : // transport->SendData() is called whenever
268 : // Process() is called and bit-stream is ready
269 : // to deliver.
270 : //
271 : // Return value:
272 : // -1 if the transport callback could not be registered
273 : // 0 if registration is successful.
274 : //
275 : virtual int32_t RegisterTransportCallback(
276 : AudioPacketizationCallback* transport) = 0;
277 :
278 : ///////////////////////////////////////////////////////////////////////////
279 : // int32_t Add10MsData()
280 : // Add 10MS of raw (PCM) audio data and encode it. If the sampling
281 : // frequency of the audio does not match the sampling frequency of the
282 : // current encoder ACM will resample the audio. If an encoded packet was
283 : // produced, it will be delivered via the callback object registered using
284 : // RegisterTransportCallback, and the return value from this function will
285 : // be the number of bytes encoded.
286 : //
287 : // Input:
288 : // -audio_frame : the input audio frame, containing raw audio
289 : // sampling frequency etc.,
290 : // c.f. module_common_types.h for definition of
291 : // AudioFrame.
292 : //
293 : // Return value:
294 : // >= 0 number of bytes encoded.
295 : // -1 some error occurred.
296 : //
297 : virtual int32_t Add10MsData(const AudioFrame& audio_frame) = 0;
298 :
299 : ///////////////////////////////////////////////////////////////////////////
300 : // (RED) Redundant Coding
301 : //
302 :
303 : ///////////////////////////////////////////////////////////////////////////
304 : // int32_t SetREDStatus()
305 : // configure RED status i.e. on/off.
306 : //
307 : // RFC 2198 describes a solution which has a single payload type which
308 : // signifies a packet with redundancy. That packet then becomes a container,
309 : // encapsulating multiple payloads into a single RTP packet.
310 : // Such a scheme is flexible, since any amount of redundancy may be
311 : // encapsulated within a single packet. There is, however, a small overhead
312 : // since each encapsulated payload must be preceded by a header indicating
313 : // the type of data enclosed.
314 : //
315 : // Input:
316 : // -enable_red : if true RED is enabled, otherwise RED is
317 : // disabled.
318 : //
319 : // Return value:
320 : // -1 if failed to set RED status,
321 : // 0 if succeeded.
322 : //
323 : virtual int32_t SetREDStatus(bool enable_red) = 0;
324 :
325 : ///////////////////////////////////////////////////////////////////////////
326 : // bool REDStatus()
327 : // Get RED status
328 : //
329 : // Return value:
330 : // true if RED is enabled,
331 : // false if RED is disabled.
332 : //
333 : virtual bool REDStatus() const = 0;
334 :
335 : ///////////////////////////////////////////////////////////////////////////
336 : // (FEC) Forward Error Correction (codec internal)
337 : //
338 :
339 : ///////////////////////////////////////////////////////////////////////////
340 : // int32_t SetCodecFEC()
341 : // Configures codec internal FEC status i.e. on/off. No effects on codecs that
342 : // do not provide internal FEC.
343 : //
344 : // Input:
345 : // -enable_fec : if true FEC will be enabled otherwise the FEC is
346 : // disabled.
347 : //
348 : // Return value:
349 : // -1 if failed, or the codec does not support FEC
350 : // 0 if succeeded.
351 : //
352 : virtual int SetCodecFEC(bool enable_codec_fec) = 0;
353 :
354 : ///////////////////////////////////////////////////////////////////////////
355 : // bool CodecFEC()
356 : // Gets status of codec internal FEC.
357 : //
358 : // Return value:
359 : // true if FEC is enabled,
360 : // false if FEC is disabled.
361 : //
362 : virtual bool CodecFEC() const = 0;
363 :
364 : ///////////////////////////////////////////////////////////////////////////
365 : // int SetPacketLossRate()
366 : // Sets expected packet loss rate for encoding. Some encoders provide packet
367 : // loss gnostic encoding to make stream less sensitive to packet losses,
368 : // through e.g., FEC. No effects on codecs that do not provide such encoding.
369 : //
370 : // Input:
371 : // -packet_loss_rate : expected packet loss rate (0 -- 100 inclusive).
372 : //
373 : // Return value
374 : // -1 if failed to set packet loss rate,
375 : // 0 if succeeded.
376 : //
377 : // This is only used in test code that rely on old ACM APIs.
378 : // TODO(minyue): Remove it when possible.
379 : virtual int SetPacketLossRate(int packet_loss_rate) = 0;
380 :
381 : ///////////////////////////////////////////////////////////////////////////
382 : // (VAD) Voice Activity Detection
383 : //
384 :
385 : ///////////////////////////////////////////////////////////////////////////
386 : // int32_t SetVAD()
387 : // If DTX is enabled & the codec does not have internal DTX/VAD
388 : // WebRtc VAD will be automatically enabled and |enable_vad| is ignored.
389 : //
390 : // If DTX is disabled but VAD is enabled no DTX packets are send,
391 : // regardless of whether the codec has internal DTX/VAD or not. In this
392 : // case, WebRtc VAD is running to label frames as active/in-active.
393 : //
394 : // NOTE! VAD/DTX is not supported when sending stereo.
395 : //
396 : // Inputs:
397 : // -enable_dtx : if true DTX is enabled,
398 : // otherwise DTX is disabled.
399 : // -enable_vad : if true VAD is enabled,
400 : // otherwise VAD is disabled.
401 : // -vad_mode : determines the aggressiveness of VAD. A more
402 : // aggressive mode results in more frames labeled
403 : // as in-active, c.f. definition of
404 : // ACMVADMode in audio_coding_module_typedefs.h
405 : // for valid values.
406 : //
407 : // Return value:
408 : // -1 if failed to set up VAD/DTX,
409 : // 0 if succeeded.
410 : //
411 : virtual int32_t SetVAD(const bool enable_dtx = true,
412 : const bool enable_vad = false,
413 : const ACMVADMode vad_mode = VADNormal) = 0;
414 :
415 : ///////////////////////////////////////////////////////////////////////////
416 : // int32_t VAD()
417 : // Get VAD status.
418 : //
419 : // Outputs:
420 : // -dtx_enabled : is set to true if DTX is enabled, otherwise
421 : // is set to false.
422 : // -vad_enabled : is set to true if VAD is enabled, otherwise
423 : // is set to false.
424 : // -vad_mode : is set to the current aggressiveness of VAD.
425 : //
426 : // Return value:
427 : // -1 if fails to retrieve the setting of DTX/VAD,
428 : // 0 if succeeded.
429 : //
430 : virtual int32_t VAD(bool* dtx_enabled, bool* vad_enabled,
431 : ACMVADMode* vad_mode) const = 0;
432 :
433 : ///////////////////////////////////////////////////////////////////////////
434 : // int32_t RegisterVADCallback()
435 : // Call this method to register a callback function which is called
436 : // any time that ACM encounters an empty frame. That is a frame which is
437 : // recognized inactive. Depending on the codec WebRtc VAD or internal codec
438 : // VAD is employed to identify a frame as active/inactive.
439 : //
440 : // Input:
441 : // -vad_callback : pointer to a callback function.
442 : //
443 : // Return value:
444 : // -1 if failed to register the callback function.
445 : // 0 if the callback function is registered successfully.
446 : //
447 : virtual int32_t RegisterVADCallback(ACMVADCallback* vad_callback) = 0;
448 :
449 : ///////////////////////////////////////////////////////////////////////////
450 : // Receiver
451 : //
452 :
453 : ///////////////////////////////////////////////////////////////////////////
454 : // int32_t InitializeReceiver()
455 : // Any decoder-related state of ACM will be initialized to the
456 : // same state when ACM is created. This will not interrupt or
457 : // effect encoding functionality of ACM. ACM would lose all the
458 : // decoding-related settings by calling this function.
459 : // For instance, all registered codecs are deleted and have to be
460 : // registered again.
461 : //
462 : // Return value:
463 : // -1 if failed to initialize,
464 : // 0 if succeeded.
465 : //
466 : virtual int32_t InitializeReceiver() = 0;
467 :
468 : ///////////////////////////////////////////////////////////////////////////
469 : // int32_t ReceiveFrequency()
470 : // Get sampling frequency of the last received payload.
471 : //
472 : // Return value:
473 : // non-negative the sampling frequency in Hertz.
474 : // -1 if an error has occurred.
475 : //
476 : virtual int32_t ReceiveFrequency() const = 0;
477 :
478 : ///////////////////////////////////////////////////////////////////////////
479 : // int32_t PlayoutFrequency()
480 : // Get sampling frequency of audio played out.
481 : //
482 : // Return value:
483 : // the sampling frequency in Hertz.
484 : //
485 : virtual int32_t PlayoutFrequency() const = 0;
486 :
487 : // Registers a decoder for the given payload type. Returns true iff
488 : // successful.
489 : virtual bool RegisterReceiveCodec(int rtp_payload_type,
490 : const SdpAudioFormat& audio_format) = 0;
491 :
492 : ///////////////////////////////////////////////////////////////////////////
493 : // int32_t RegisterReceiveCodec()
494 : // Register possible decoders, can be called multiple times for
495 : // codecs, CNG-NB, CNG-WB, CNG-SWB, AVT and RED.
496 : //
497 : // Input:
498 : // -receive_codec : parameters of the codec to be registered, c.f.
499 : // common_types.h for the definition of
500 : // CodecInst.
501 : //
502 : // Return value:
503 : // -1 if failed to register the codec
504 : // 0 if the codec registered successfully.
505 : //
506 : virtual int RegisterReceiveCodec(const CodecInst& receive_codec) = 0;
507 :
508 : // Register a decoder; call repeatedly to register multiple decoders. |df| is
509 : // a decoder factory that returns an iSAC decoder; it will be called once if
510 : // the decoder being registered is iSAC.
511 : virtual int RegisterReceiveCodec(
512 : const CodecInst& receive_codec,
513 : rtc::FunctionView<std::unique_ptr<AudioDecoder>()> isac_factory) = 0;
514 :
515 : // Registers an external decoder. The name is only used to provide information
516 : // back to the caller about the decoder. Hence, the name is arbitrary, and may
517 : // be empty.
518 : virtual int RegisterExternalReceiveCodec(int rtp_payload_type,
519 : AudioDecoder* external_decoder,
520 : int sample_rate_hz,
521 : int num_channels,
522 : const std::string& name) = 0;
523 :
524 : ///////////////////////////////////////////////////////////////////////////
525 : // int32_t UnregisterReceiveCodec()
526 : // Unregister the codec currently registered with a specific payload type
527 : // from the list of possible receive codecs.
528 : //
529 : // Input:
530 : // -payload_type : The number representing the payload type to
531 : // unregister.
532 : //
533 : // Output:
534 : // -1 if fails to unregister.
535 : // 0 if the given codec is successfully unregistered.
536 : //
537 : virtual int UnregisterReceiveCodec(
538 : uint8_t payload_type) = 0;
539 :
540 : ///////////////////////////////////////////////////////////////////////////
541 : // int32_t ReceiveCodec()
542 : // Get the codec associated with last received payload.
543 : //
544 : // Output:
545 : // -curr_receive_codec : parameters of the codec associated with the last
546 : // received payload, c.f. common_types.h for
547 : // the definition of CodecInst.
548 : //
549 : // Return value:
550 : // -1 if failed to retrieve the codec,
551 : // 0 if the codec is successfully retrieved.
552 : //
553 : virtual int32_t ReceiveCodec(CodecInst* curr_receive_codec) const = 0;
554 :
555 : ///////////////////////////////////////////////////////////////////////////
556 : // rtc::Optional<SdpAudioFormat> ReceiveFormat()
557 : // Get the format associated with last received payload.
558 : //
559 : // Return value:
560 : // An SdpAudioFormat describing the format associated with the last
561 : // received payload.
562 : // An empty Optional if no payload has yet been received.
563 : //
564 : virtual rtc::Optional<SdpAudioFormat> ReceiveFormat() const = 0;
565 :
566 : ///////////////////////////////////////////////////////////////////////////
567 : // int32_t IncomingPacket()
568 : // Call this function to insert a parsed RTP packet into ACM.
569 : //
570 : // Inputs:
571 : // -incoming_payload : received payload.
572 : // -payload_len_bytes : the length of payload in bytes.
573 : // -rtp_info : the relevant information retrieved from RTP
574 : // header.
575 : //
576 : // Return value:
577 : // -1 if failed to push in the payload
578 : // 0 if payload is successfully pushed in.
579 : //
580 : virtual int32_t IncomingPacket(const uint8_t* incoming_payload,
581 : const size_t payload_len_bytes,
582 : const WebRtcRTPHeader& rtp_info) = 0;
583 :
584 : ///////////////////////////////////////////////////////////////////////////
585 : // int32_t IncomingPayload()
586 : // Call this API to push incoming payloads when there is no rtp-info.
587 : // The rtp-info will be created in ACM. One usage for this API is when
588 : // pre-encoded files are pushed in ACM
589 : //
590 : // Inputs:
591 : // -incoming_payload : received payload.
592 : // -payload_len_byte : the length, in bytes, of the received payload.
593 : // -payload_type : the payload-type. This specifies which codec has
594 : // to be used to decode the payload.
595 : // -timestamp : send timestamp of the payload. ACM starts with
596 : // a random value and increment it by the
597 : // packet-size, which is given when the codec in
598 : // question is registered by RegisterReceiveCodec().
599 : // Therefore, it is essential to have the timestamp
600 : // if the frame-size differ from the registered
601 : // value or if the incoming payload contains DTX
602 : // packets.
603 : //
604 : // Return value:
605 : // -1 if failed to push in the payload
606 : // 0 if payload is successfully pushed in.
607 : //
608 : virtual int32_t IncomingPayload(const uint8_t* incoming_payload,
609 : const size_t payload_len_byte,
610 : const uint8_t payload_type,
611 : const uint32_t timestamp = 0) = 0;
612 :
613 : ///////////////////////////////////////////////////////////////////////////
614 : // int SetMinimumPlayoutDelay()
615 : // Set a minimum for the playout delay, used for lip-sync. NetEq maintains
616 : // such a delay unless channel condition yields to a higher delay.
617 : //
618 : // Input:
619 : // -time_ms : minimum delay in milliseconds.
620 : //
621 : // Return value:
622 : // -1 if failed to set the delay,
623 : // 0 if the minimum delay is set.
624 : //
625 : virtual int SetMinimumPlayoutDelay(int time_ms) = 0;
626 :
627 : ///////////////////////////////////////////////////////////////////////////
628 : // int SetMaximumPlayoutDelay()
629 : // Set a maximum for the playout delay
630 : //
631 : // Input:
632 : // -time_ms : maximum delay in milliseconds.
633 : //
634 : // Return value:
635 : // -1 if failed to set the delay,
636 : // 0 if the maximum delay is set.
637 : //
638 : virtual int SetMaximumPlayoutDelay(int time_ms) = 0;
639 :
640 : //
641 : // The shortest latency, in milliseconds, required by jitter buffer. This
642 : // is computed based on inter-arrival times and playout mode of NetEq. The
643 : // actual delay is the maximum of least-required-delay and the minimum-delay
644 : // specified by SetMinumumPlayoutDelay() API.
645 : //
646 : virtual int LeastRequiredDelayMs() const = 0;
647 :
648 : // int32_t PlayoutTimestamp()
649 : // The send timestamp of an RTP packet is associated with the decoded
650 : // audio of the packet in question. This function returns the timestamp of
651 : // the latest audio obtained by calling PlayoutData10ms().
652 : //
653 : // Input:
654 : // -timestamp : a reference to a uint32_t to receive the
655 : // timestamp.
656 : // Return value:
657 : // 0 if the output is a correct timestamp.
658 : // -1 if failed to output the correct timestamp.
659 : //
660 : RTC_DEPRECATED virtual int32_t PlayoutTimestamp(uint32_t* timestamp) = 0;
661 :
662 : ///////////////////////////////////////////////////////////////////////////
663 : // int32_t PlayoutTimestamp()
664 : // The send timestamp of an RTP packet is associated with the decoded
665 : // audio of the packet in question. This function returns the timestamp of
666 : // the latest audio obtained by calling PlayoutData10ms(), or empty if no
667 : // valid timestamp is available.
668 : //
669 : virtual rtc::Optional<uint32_t> PlayoutTimestamp() = 0;
670 :
671 : ///////////////////////////////////////////////////////////////////////////
672 : // int FilteredCurrentDelayMs()
673 : // Returns the current total delay from NetEq (packet buffer and sync buffer)
674 : // in ms, with smoothing applied to even out short-time fluctuations due to
675 : // jitter. The packet buffer part of the delay is not updated during DTX/CNG
676 : // periods.
677 : //
678 : virtual int FilteredCurrentDelayMs() const = 0;
679 :
680 : ///////////////////////////////////////////////////////////////////////////
681 : // int32_t PlayoutData10Ms(
682 : // Get 10 milliseconds of raw audio data for playout, at the given sampling
683 : // frequency. ACM will perform a resampling if required.
684 : //
685 : // Input:
686 : // -desired_freq_hz : the desired sampling frequency, in Hertz, of the
687 : // output audio. If set to -1, the function returns
688 : // the audio at the current sampling frequency.
689 : //
690 : // Output:
691 : // -audio_frame : output audio frame which contains raw audio data
692 : // and other relevant parameters, c.f.
693 : // module_common_types.h for the definition of
694 : // AudioFrame.
695 : // -muted : if true, the sample data in audio_frame is not
696 : // populated, and must be interpreted as all zero.
697 : //
698 : // Return value:
699 : // -1 if the function fails,
700 : // 0 if the function succeeds.
701 : //
702 : virtual int32_t PlayoutData10Ms(int32_t desired_freq_hz,
703 : AudioFrame* audio_frame,
704 : bool* muted) = 0;
705 :
706 : /////////////////////////////////////////////////////////////////////////////
707 : // Same as above, but without the muted parameter. This methods should not be
708 : // used if enable_fast_accelerate was set to true in NetEq::Config.
709 : // TODO(henrik.lundin) Remove this method when downstream dependencies are
710 : // ready.
711 : virtual int32_t PlayoutData10Ms(int32_t desired_freq_hz,
712 : AudioFrame* audio_frame) = 0;
713 :
714 : ///////////////////////////////////////////////////////////////////////////
715 : // Codec specific
716 : //
717 :
718 : ///////////////////////////////////////////////////////////////////////////
719 : // int SetOpusApplication()
720 : // Sets the intended application if current send codec is Opus. Opus uses this
721 : // to optimize the encoding for applications like VOIP and music. Currently,
722 : // two modes are supported: kVoip and kAudio.
723 : //
724 : // Input:
725 : // - application : intended application.
726 : //
727 : // Return value:
728 : // -1 if current send codec is not Opus or error occurred in setting the
729 : // Opus application mode.
730 : // 0 if the Opus application mode is successfully set.
731 : //
732 : virtual int SetOpusApplication(OpusApplicationMode application) = 0;
733 :
734 : ///////////////////////////////////////////////////////////////////////////
735 : // int SetOpusMaxPlaybackRate()
736 : // If current send codec is Opus, informs it about maximum playback rate the
737 : // receiver will render. Opus can use this information to optimize the bit
738 : // rate and increase the computation efficiency.
739 : //
740 : // Input:
741 : // -frequency_hz : maximum playback rate in Hz.
742 : //
743 : // Return value:
744 : // -1 if current send codec is not Opus or
745 : // error occurred in setting the maximum playback rate,
746 : // 0 if maximum bandwidth is set successfully.
747 : //
748 : virtual int SetOpusMaxPlaybackRate(int frequency_hz) = 0;
749 :
750 : ///////////////////////////////////////////////////////////////////////////
751 : // EnableOpusDtx()
752 : // Enable the DTX, if current send codec is Opus.
753 : //
754 : // Return value:
755 : // -1 if current send codec is not Opus or error occurred in enabling the
756 : // Opus DTX.
757 : // 0 if Opus DTX is enabled successfully.
758 : //
759 : virtual int EnableOpusDtx() = 0;
760 :
761 : ///////////////////////////////////////////////////////////////////////////
762 : // int DisableOpusDtx()
763 : // If current send codec is Opus, disables its internal DTX.
764 : //
765 : // Return value:
766 : // -1 if current send codec is not Opus or error occurred in disabling DTX.
767 : // 0 if Opus DTX is disabled successfully.
768 : //
769 : virtual int DisableOpusDtx() = 0;
770 :
771 : ///////////////////////////////////////////////////////////////////////////
772 : // statistics
773 : //
774 :
775 : ///////////////////////////////////////////////////////////////////////////
776 : // int32_t GetNetworkStatistics()
777 : // Get network statistics. Note that the internal statistics of NetEq are
778 : // reset by this call.
779 : //
780 : // Input:
781 : // -network_statistics : a structure that contains network statistics.
782 : //
783 : // Return value:
784 : // -1 if failed to set the network statistics,
785 : // 0 if statistics are set successfully.
786 : //
787 : virtual int32_t GetNetworkStatistics(
788 : NetworkStatistics* network_statistics) = 0;
789 :
790 : //
791 : // Enable NACK and set the maximum size of the NACK list. If NACK is already
792 : // enable then the maximum NACK list size is modified accordingly.
793 : //
794 : // If the sequence number of last received packet is N, the sequence numbers
795 : // of NACK list are in the range of [N - |max_nack_list_size|, N).
796 : //
797 : // |max_nack_list_size| should be positive (none zero) and less than or
798 : // equal to |Nack::kNackListSizeLimit|. Otherwise, No change is applied and -1
799 : // is returned. 0 is returned at success.
800 : //
801 : virtual int EnableNack(size_t max_nack_list_size) = 0;
802 :
803 : // Disable NACK.
804 : virtual void DisableNack() = 0;
805 :
806 : //
807 : // Get a list of packets to be retransmitted. |round_trip_time_ms| is an
808 : // estimate of the round-trip-time (in milliseconds). Missing packets which
809 : // will be playout in a shorter time than the round-trip-time (with respect
810 : // to the time this API is called) will not be included in the list.
811 : //
812 : // Negative |round_trip_time_ms| results is an error message and empty list
813 : // is returned.
814 : //
815 : virtual std::vector<uint16_t> GetNackList(
816 : int64_t round_trip_time_ms) const = 0;
817 :
818 : virtual void GetDecodingCallStatistics(
819 : AudioDecodingCallStats* call_stats) const = 0;
820 : };
821 :
822 : } // namespace webrtc
823 :
824 : #endif // WEBRTC_MODULES_AUDIO_CODING_INCLUDE_AUDIO_CODING_MODULE_H_
|
