blob: d05b76e75d2e6dca9afdd526c481d80f840a963d [file] [log] [blame]
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +00001/*
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
Henrik Kjellander74640892015-10-29 11:31:02 +010011#ifndef WEBRTC_MODULES_AUDIO_CODING_NETEQ_INCLUDE_NETEQ_H_
12#define WEBRTC_MODULES_AUDIO_CODING_NETEQ_INCLUDE_NETEQ_H_
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +000013
pbos@webrtc.org12dc1a32013-08-05 16:22:53 +000014#include <string.h> // Provide access to size_t.
15
Henrik Lundin905495c2015-05-25 16:58:41 +020016#include <string>
henrik.lundin114c1b32017-04-26 07:47:32 -070017#include <vector>
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +000018
sprang@webrtc.orgfe5d36b2013-10-28 09:21:07 +000019#include "webrtc/common_types.h"
kwiberg@webrtc.orge04a93b2014-12-09 10:12:53 +000020#include "webrtc/modules/audio_coding/neteq/audio_decoder_impl.h"
Edward Lemurc20978e2017-07-06 19:44:34 +020021#include "webrtc/rtc_base/constructormagic.h"
22#include "webrtc/rtc_base/optional.h"
23#include "webrtc/rtc_base/scoped_ref_ptr.h"
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +000024#include "webrtc/typedefs.h"
25
26namespace webrtc {
27
28// Forward declarations.
henrik.lundin6d8e0112016-03-04 10:34:21 -080029class AudioFrame;
ossue3525782016-05-25 07:37:43 -070030class AudioDecoderFactory;
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +000031
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +000032struct NetEqNetworkStatistics {
33 uint16_t current_buffer_size_ms; // Current jitter buffer size in ms.
34 uint16_t preferred_buffer_size_ms; // Target buffer size in ms.
35 uint16_t jitter_peaks_found; // 1 if adding extra delay due to peaky
36 // jitter; 0 otherwise.
37 uint16_t packet_loss_rate; // Loss rate (network + late) in Q14.
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +000038 uint16_t expand_rate; // Fraction (of original stream) of synthesized
minyue@webrtc.org7d721ee2015-02-18 10:01:53 +000039 // audio inserted through expansion (in Q14).
40 uint16_t speech_expand_rate; // Fraction (of original stream) of synthesized
41 // speech inserted through expansion (in Q14).
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +000042 uint16_t preemptive_rate; // Fraction of data inserted through pre-emptive
43 // expansion (in Q14).
44 uint16_t accelerate_rate; // Fraction of data removed through acceleration
45 // (in Q14).
minyue-webrtc0c3ca752017-08-23 15:59:38 +020046 uint16_t secondary_decoded_rate; // Fraction of data coming from FEC/RED
minyue@webrtc.org2c1bcf22015-02-17 10:17:09 +000047 // decoding (in Q14).
minyue-webrtc0c3ca752017-08-23 15:59:38 +020048 uint16_t secondary_discarded_rate; // Fraction of discarded FEC/RED data (in
49 // Q14).
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +000050 int32_t clockdrift_ppm; // Average clock-drift in parts-per-million
51 // (positive or negative).
Peter Kastingdce40cf2015-08-24 14:52:23 -070052 size_t added_zero_samples; // Number of zero samples added in "off" mode.
Henrik Lundin1bb8cf82015-08-25 13:08:04 +020053 // Statistics for packet waiting times, i.e., the time between a packet
54 // arrives until it is decoded.
55 int mean_waiting_time_ms;
56 int median_waiting_time_ms;
57 int min_waiting_time_ms;
58 int max_waiting_time_ms;
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +000059};
60
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +000061enum NetEqPlayoutMode {
62 kPlayoutOn,
63 kPlayoutOff,
64 kPlayoutFax,
65 kPlayoutStreaming
66};
67
68// This is the interface class for NetEq.
69class NetEq {
70 public:
henrik.lundin@webrtc.orgea257842014-08-07 12:27:37 +000071 enum BackgroundNoiseMode {
72 kBgnOn, // Default behavior with eternal noise.
73 kBgnFade, // Noise fades to zero after some time.
74 kBgnOff // Background noise is always zero.
75 };
76
henrik.lundin@webrtc.org35ead382014-04-14 18:49:17 +000077 struct Config {
78 Config()
79 : sample_rate_hz(16000),
henrik.lundin9bc26672015-11-02 03:25:57 -080080 enable_post_decode_vad(false),
henrik.lundin@webrtc.org116ed1d2014-04-28 08:20:04 +000081 max_packets_in_buffer(50),
82 // |max_delay_ms| has the same effect as calling SetMaximumDelay().
henrik.lundin@webrtc.orgea257842014-08-07 12:27:37 +000083 max_delay_ms(2000),
henrik.lundin@webrtc.org7cbc4f92014-10-07 06:37:39 +000084 background_noise_mode(kBgnOff),
Henrik Lundincf808d22015-05-27 14:33:29 +020085 playout_mode(kPlayoutOn),
86 enable_fast_accelerate(false) {}
henrik.lundin@webrtc.org35ead382014-04-14 18:49:17 +000087
Henrik Lundin905495c2015-05-25 16:58:41 +020088 std::string ToString() const;
89
Henrik Lundin83b5c052015-05-08 10:33:57 +020090 int sample_rate_hz; // Initial value. Will change with input data.
henrik.lundin9bc26672015-11-02 03:25:57 -080091 bool enable_post_decode_vad;
Peter Kastingdce40cf2015-08-24 14:52:23 -070092 size_t max_packets_in_buffer;
henrik.lundin@webrtc.org116ed1d2014-04-28 08:20:04 +000093 int max_delay_ms;
henrik.lundin@webrtc.orgea257842014-08-07 12:27:37 +000094 BackgroundNoiseMode background_noise_mode;
henrik.lundin@webrtc.org7cbc4f92014-10-07 06:37:39 +000095 NetEqPlayoutMode playout_mode;
Henrik Lundincf808d22015-05-27 14:33:29 +020096 bool enable_fast_accelerate;
henrik.lundin7a926812016-05-12 13:51:28 -070097 bool enable_muted_state = false;
henrik.lundin@webrtc.org35ead382014-04-14 18:49:17 +000098 };
99
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +0000100 enum ReturnCodes {
101 kOK = 0,
102 kFail = -1,
103 kNotImplemented = -2
104 };
105
henrik.lundin@webrtc.org35ead382014-04-14 18:49:17 +0000106 // Creates a new NetEq object, with parameters set in |config|. The |config|
107 // object will only have to be valid for the duration of the call to this
108 // method.
ossue3525782016-05-25 07:37:43 -0700109 static NetEq* Create(
110 const NetEq::Config& config,
111 const rtc::scoped_refptr<AudioDecoderFactory>& decoder_factory);
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +0000112
113 virtual ~NetEq() {}
114
115 // Inserts a new packet into NetEq. The |receive_timestamp| is an indication
116 // of the time when the packet was received, and should be measured with
117 // the same tick rate as the RTP timestamp of the current payload.
118 // Returns 0 on success, -1 on failure.
Henrik Lundin70c09bd2017-04-24 15:56:56 +0200119 virtual int InsertPacket(const RTPHeader& rtp_header,
kwibergee2bac22015-11-11 10:34:00 -0800120 rtc::ArrayView<const uint8_t> payload,
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +0000121 uint32_t receive_timestamp) = 0;
122
henrik.lundinb8c55b12017-05-10 07:38:01 -0700123 // Lets NetEq know that a packet arrived with an empty payload. This typically
124 // happens when empty packets are used for probing the network channel, and
125 // these packets use RTP sequence numbers from the same series as the actual
126 // audio packets.
127 virtual void InsertEmptyPacket(const RTPHeader& rtp_header) = 0;
128
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +0000129 // Instructs NetEq to deliver 10 ms of audio data. The data is written to
henrik.lundin7dc68892016-04-06 01:03:02 -0700130 // |audio_frame|. All data in |audio_frame| is wiped; |data_|, |speech_type_|,
131 // |num_channels_|, |sample_rate_hz_|, |samples_per_channel_|, and
henrik.lundin55480f52016-03-08 02:37:57 -0800132 // |vad_activity_| are updated upon success. If an error is returned, some
henrik.lundin5fac3f02016-08-24 11:18:49 -0700133 // fields may not have been updated, or may contain inconsistent values.
henrik.lundin7a926812016-05-12 13:51:28 -0700134 // If muted state is enabled (through Config::enable_muted_state), |muted|
135 // may be set to true after a prolonged expand period. When this happens, the
136 // |data_| in |audio_frame| is not written, but should be interpreted as being
137 // all zeros.
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +0000138 // Returns kOK on success, or kFail in case of an error.
henrik.lundin7a926812016-05-12 13:51:28 -0700139 virtual int GetAudio(AudioFrame* audio_frame, bool* muted) = 0;
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +0000140
kwiberg1c07c702017-03-27 07:15:49 -0700141 // Replaces the current set of decoders with the given one.
142 virtual void SetCodecs(const std::map<int, SdpAudioFormat>& codecs) = 0;
143
henrik.lundin4cf61dd2015-12-09 06:20:58 -0800144 // Associates |rtp_payload_type| with |codec| and |codec_name|, and stores the
145 // information in the codec database. Returns 0 on success, -1 on failure.
146 // The name is only used to provide information back to the caller about the
147 // decoders. Hence, the name is arbitrary, and may be empty.
kwibergee1879c2015-10-29 06:20:28 -0700148 virtual int RegisterPayloadType(NetEqDecoder codec,
henrik.lundin4cf61dd2015-12-09 06:20:58 -0800149 const std::string& codec_name,
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +0000150 uint8_t rtp_payload_type) = 0;
151
152 // Provides an externally created decoder object |decoder| to insert in the
153 // decoder database. The decoder implements a decoder of type |codec| and
kwiberg342f7402016-06-16 03:18:00 -0700154 // associates it with |rtp_payload_type| and |codec_name|. Returns kOK on
155 // success, kFail on failure. The name is only used to provide information
156 // back to the caller about the decoders. Hence, the name is arbitrary, and
157 // may be empty.
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +0000158 virtual int RegisterExternalDecoder(AudioDecoder* decoder,
kwibergee1879c2015-10-29 06:20:28 -0700159 NetEqDecoder codec,
henrik.lundin4cf61dd2015-12-09 06:20:58 -0800160 const std::string& codec_name,
kwiberg342f7402016-06-16 03:18:00 -0700161 uint8_t rtp_payload_type) = 0;
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +0000162
kwiberg5adaf732016-10-04 09:33:27 -0700163 // Associates |rtp_payload_type| with the given codec, which NetEq will
164 // instantiate when it needs it. Returns true iff successful.
165 virtual bool RegisterPayloadType(int rtp_payload_type,
166 const SdpAudioFormat& audio_format) = 0;
167
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +0000168 // Removes |rtp_payload_type| from the codec database. Returns 0 on success,
Henrik Lundinc417d9e2017-06-14 12:29:03 +0200169 // -1 on failure. Removing a payload type that is not registered is ok and
170 // will not result in an error.
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +0000171 virtual int RemovePayloadType(uint8_t rtp_payload_type) = 0;
172
kwiberg6b19b562016-09-20 04:02:25 -0700173 // Removes all payload types from the codec database.
174 virtual void RemoveAllPayloadTypes() = 0;
175
turaj@webrtc.orgf1efc572013-08-16 23:44:24 +0000176 // Sets a minimum delay in millisecond for packet buffer. The minimum is
177 // maintained unless a higher latency is dictated by channel condition.
178 // Returns true if the minimum is successfully applied, otherwise false is
179 // returned.
180 virtual bool SetMinimumDelay(int delay_ms) = 0;
181
182 // Sets a maximum delay in milliseconds for packet buffer. The latency will
183 // not exceed the given value, even required delay (given the channel
henrik.lundin@webrtc.org116ed1d2014-04-28 08:20:04 +0000184 // conditions) is higher. Calling this method has the same effect as setting
185 // the |max_delay_ms| value in the NetEq::Config struct.
turaj@webrtc.orgf1efc572013-08-16 23:44:24 +0000186 virtual bool SetMaximumDelay(int delay_ms) = 0;
187
188 // The smallest latency required. This is computed bases on inter-arrival
189 // time and internal NetEq logic. Note that in computing this latency none of
190 // the user defined limits (applied by calling setMinimumDelay() and/or
191 // SetMaximumDelay()) are applied.
192 virtual int LeastRequiredDelayMs() const = 0;
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +0000193
194 // Not implemented.
195 virtual int SetTargetDelay() = 0;
196
henrik.lundin114c1b32017-04-26 07:47:32 -0700197 // Returns the current target delay in ms. This includes any extra delay
198 // requested through SetMinimumDelay.
199 virtual int TargetDelayMs() = 0;
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +0000200
henrik.lundin9c3efd02015-08-27 13:12:22 -0700201 // Returns the current total delay (packet buffer and sync buffer) in ms.
202 virtual int CurrentDelayMs() const = 0;
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +0000203
henrik.lundinb3f1c5d2016-08-22 15:39:53 -0700204 // Returns the current total delay (packet buffer and sync buffer) in ms,
205 // with smoothing applied to even out short-time fluctuations due to jitter.
206 // The packet buffer part of the delay is not updated during DTX/CNG periods.
207 virtual int FilteredCurrentDelayMs() const = 0;
208
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +0000209 // Sets the playout mode to |mode|.
henrik.lundin@webrtc.org7cbc4f92014-10-07 06:37:39 +0000210 // Deprecated. Set the mode in the Config struct passed to the constructor.
211 // TODO(henrik.lundin) Delete.
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +0000212 virtual void SetPlayoutMode(NetEqPlayoutMode mode) = 0;
213
214 // Returns the current playout mode.
henrik.lundin@webrtc.org7cbc4f92014-10-07 06:37:39 +0000215 // Deprecated.
216 // TODO(henrik.lundin) Delete.
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +0000217 virtual NetEqPlayoutMode PlayoutMode() const = 0;
218
219 // Writes the current network statistics to |stats|. The statistics are reset
220 // after the call.
221 virtual int NetworkStatistics(NetEqNetworkStatistics* stats) = 0;
222
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +0000223 // Writes the current RTCP statistics to |stats|. The statistics are reset
224 // and a new report period is started with the call.
225 virtual void GetRtcpStatistics(RtcpStatistics* stats) = 0;
226
227 // Same as RtcpStatistics(), but does not reset anything.
228 virtual void GetRtcpStatisticsNoReset(RtcpStatistics* stats) = 0;
229
230 // Enables post-decode VAD. When enabled, GetAudio() will return
231 // kOutputVADPassive when the signal contains no speech.
232 virtual void EnableVad() = 0;
233
234 // Disables post-decode VAD.
235 virtual void DisableVad() = 0;
236
henrik.lundin9a410dd2016-04-06 01:39:22 -0700237 // Returns the RTP timestamp for the last sample delivered by GetAudio().
238 // The return value will be empty if no valid timestamp is available.
henrik.lundin15c51e32016-04-06 08:38:56 -0700239 virtual rtc::Optional<uint32_t> GetPlayoutTimestamp() const = 0;
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +0000240
henrik.lundind89814b2015-11-23 06:49:25 -0800241 // Returns the sample rate in Hz of the audio produced in the last GetAudio
242 // call. If GetAudio has not been called yet, the configured sample rate
243 // (Config::sample_rate_hz) is returned.
244 virtual int last_output_sample_rate_hz() const = 0;
245
kwiberg6f0f6162016-09-20 03:07:46 -0700246 // Returns info about the decoder for the given payload type, or an empty
247 // value if we have no decoder for that payload type.
248 virtual rtc::Optional<CodecInst> GetDecoder(int payload_type) const = 0;
249
ossuf1b08da2016-09-23 02:19:43 -0700250 // Returns the decoder format for the given payload type. Returns empty if no
251 // such payload type was registered.
252 virtual rtc::Optional<SdpAudioFormat> GetDecoderFormat(
253 int payload_type) const = 0;
kwibergc4ccd4d2016-09-21 10:55:15 -0700254
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +0000255 // Not implemented.
256 virtual int SetTargetNumberOfChannels() = 0;
257
258 // Not implemented.
259 virtual int SetTargetSampleRate() = 0;
260
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +0000261 // Flushes both the packet buffer and the sync buffer.
262 virtual void FlushBuffers() = 0;
263
turaj@webrtc.org7df97062013-08-02 18:07:13 +0000264 // Current usage of packet-buffer and it's limits.
265 virtual void PacketBufferStatistics(int* current_num_packets,
henrik.lundin@webrtc.org116ed1d2014-04-28 08:20:04 +0000266 int* max_num_packets) const = 0;
turaj@webrtc.org7df97062013-08-02 18:07:13 +0000267
henrik.lundin48ed9302015-10-29 05:36:24 -0700268 // Enables NACK and sets the maximum size of the NACK list, which should be
269 // positive and no larger than Nack::kNackListSizeLimit. If NACK is already
270 // enabled then the maximum NACK list size is modified accordingly.
271 virtual void EnableNack(size_t max_nack_list_size) = 0;
272
273 virtual void DisableNack() = 0;
274
275 // Returns a list of RTP sequence numbers corresponding to packets to be
276 // retransmitted, given an estimate of the round-trip time in milliseconds.
277 virtual std::vector<uint16_t> GetNackList(
278 int64_t round_trip_time_ms) const = 0;
minyue@webrtc.orgd7301772013-08-29 00:58:14 +0000279
henrik.lundin114c1b32017-04-26 07:47:32 -0700280 // Returns a vector containing the timestamps of the packets that were decoded
281 // in the last GetAudio call. If no packets were decoded in the last call, the
282 // vector is empty.
283 // Mainly intended for testing.
284 virtual std::vector<uint32_t> LastDecodedTimestamps() const = 0;
285
286 // Returns the length of the audio yet to play in the sync buffer.
287 // Mainly intended for testing.
288 virtual int SyncBufferSizeMs() const = 0;
289
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +0000290 protected:
291 NetEq() {}
292
293 private:
henrikg3c089d72015-09-16 05:37:44 -0700294 RTC_DISALLOW_COPY_AND_ASSIGN(NetEq);
henrik.lundin@webrtc.orgd94659d2013-01-29 12:09:21 +0000295};
296
297} // namespace webrtc
Henrik Kjellander74640892015-10-29 11:31:02 +0100298#endif // WEBRTC_MODULES_AUDIO_CODING_NETEQ_INCLUDE_NETEQ_H_