Line data Source code
1 : /*
2 : * Copyright (c) 2014 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_AUDIO_ENCODER_H_
12 : #define WEBRTC_MODULES_AUDIO_CODING_CODECS_AUDIO_ENCODER_H_
13 :
14 : #include <algorithm>
15 : #include <vector>
16 :
17 : #include "webrtc/base/array_view.h"
18 : #include "webrtc/base/buffer.h"
19 : #include "webrtc/base/deprecation.h"
20 : #include "webrtc/base/optional.h"
21 : #include "webrtc/typedefs.h"
22 :
23 : namespace webrtc {
24 :
25 : class Clock;
26 : class RtcEventLog;
27 :
28 : // This is the interface class for encoders in AudioCoding module. Each codec
29 : // type must have an implementation of this class.
30 0 : class AudioEncoder {
31 : public:
32 : // Used for UMA logging of codec usage. The same codecs, with the
33 : // same values, must be listed in
34 : // src/tools/metrics/histograms/histograms.xml in chromium to log
35 : // correct values.
36 : enum class CodecType {
37 : kOther = 0, // Codec not specified, and/or not listed in this enum
38 : kOpus = 1,
39 : kIsac = 2,
40 : kPcmA = 3,
41 : kPcmU = 4,
42 : kG722 = 5,
43 : kIlbc = 6,
44 :
45 : // Number of histogram bins in the UMA logging of codec types. The
46 : // total number of different codecs that are logged cannot exceed this
47 : // number.
48 : kMaxLoggedAudioCodecTypes
49 : };
50 :
51 0 : struct EncodedInfoLeaf {
52 : size_t encoded_bytes = 0;
53 : uint32_t encoded_timestamp = 0;
54 : int payload_type = 0;
55 : bool send_even_if_empty = false;
56 : bool speech = true;
57 : CodecType encoder_type = CodecType::kOther;
58 : };
59 :
60 : // This is the main struct for auxiliary encoding information. Each encoded
61 : // packet should be accompanied by one EncodedInfo struct, containing the
62 : // total number of |encoded_bytes|, the |encoded_timestamp| and the
63 : // |payload_type|. If the packet contains redundant encodings, the |redundant|
64 : // vector will be populated with EncodedInfoLeaf structs. Each struct in the
65 : // vector represents one encoding; the order of structs in the vector is the
66 : // same as the order in which the actual payloads are written to the byte
67 : // stream. When EncoderInfoLeaf structs are present in the vector, the main
68 : // struct's |encoded_bytes| will be the sum of all the |encoded_bytes| in the
69 : // vector.
70 0 : struct EncodedInfo : public EncodedInfoLeaf {
71 : EncodedInfo();
72 : EncodedInfo(const EncodedInfo&);
73 : EncodedInfo(EncodedInfo&&);
74 : ~EncodedInfo();
75 : EncodedInfo& operator=(const EncodedInfo&);
76 : EncodedInfo& operator=(EncodedInfo&&);
77 :
78 : std::vector<EncodedInfoLeaf> redundant;
79 : };
80 :
81 0 : virtual ~AudioEncoder() = default;
82 :
83 : // Returns the input sample rate in Hz and the number of input channels.
84 : // These are constants set at instantiation time.
85 : virtual int SampleRateHz() const = 0;
86 : virtual size_t NumChannels() const = 0;
87 :
88 : // Returns the rate at which the RTP timestamps are updated. The default
89 : // implementation returns SampleRateHz().
90 : virtual int RtpTimestampRateHz() const;
91 :
92 : // Returns the number of 10 ms frames the encoder will put in the next
93 : // packet. This value may only change when Encode() outputs a packet; i.e.,
94 : // the encoder may vary the number of 10 ms frames from packet to packet, but
95 : // it must decide the length of the next packet no later than when outputting
96 : // the preceding packet.
97 : virtual size_t Num10MsFramesInNextPacket() const = 0;
98 :
99 : // Returns the maximum value that can be returned by
100 : // Num10MsFramesInNextPacket().
101 : virtual size_t Max10MsFramesInAPacket() const = 0;
102 :
103 : // Returns the current target bitrate in bits/s. The value -1 means that the
104 : // codec adapts the target automatically, and a current target cannot be
105 : // provided.
106 : virtual int GetTargetBitrate() const = 0;
107 :
108 : // Accepts one 10 ms block of input audio (i.e., SampleRateHz() / 100 *
109 : // NumChannels() samples). Multi-channel audio must be sample-interleaved.
110 : // The encoder appends zero or more bytes of output to |encoded| and returns
111 : // additional encoding information. Encode() checks some preconditions, calls
112 : // EncodeImpl() which does the actual work, and then checks some
113 : // postconditions.
114 : EncodedInfo Encode(uint32_t rtp_timestamp,
115 : rtc::ArrayView<const int16_t> audio,
116 : rtc::Buffer* encoded);
117 :
118 : // Resets the encoder to its starting state, discarding any input that has
119 : // been fed to the encoder but not yet emitted in a packet.
120 : virtual void Reset() = 0;
121 :
122 : // Enables or disables codec-internal FEC (forward error correction). Returns
123 : // true if the codec was able to comply. The default implementation returns
124 : // true when asked to disable FEC and false when asked to enable it (meaning
125 : // that FEC isn't supported).
126 : virtual bool SetFec(bool enable);
127 :
128 : // Enables or disables codec-internal VAD/DTX. Returns true if the codec was
129 : // able to comply. The default implementation returns true when asked to
130 : // disable DTX and false when asked to enable it (meaning that DTX isn't
131 : // supported).
132 : virtual bool SetDtx(bool enable);
133 :
134 : // Returns the status of codec-internal DTX. The default implementation always
135 : // returns false.
136 : virtual bool GetDtx() const;
137 :
138 : // Sets the application mode. Returns true if the codec was able to comply.
139 : // The default implementation just returns false.
140 : enum class Application { kSpeech, kAudio };
141 : virtual bool SetApplication(Application application);
142 :
143 : // Tells the encoder about the highest sample rate the decoder is expected to
144 : // use when decoding the bitstream. The encoder would typically use this
145 : // information to adjust the quality of the encoding. The default
146 : // implementation does nothing.
147 : virtual void SetMaxPlaybackRate(int frequency_hz);
148 :
149 : // This is to be deprecated. Please use |OnReceivedTargetAudioBitrate|
150 : // instead.
151 : // Tells the encoder what average bitrate we'd like it to produce. The
152 : // encoder is free to adjust or disregard the given bitrate (the default
153 : // implementation does the latter).
154 : RTC_DEPRECATED virtual void SetTargetBitrate(int target_bps);
155 :
156 : // Causes this encoder to let go of any other encoders it contains, and
157 : // returns a pointer to an array where they are stored (which is required to
158 : // live as long as this encoder). Unless the returned array is empty, you may
159 : // not call any methods on this encoder afterwards, except for the
160 : // destructor. The default implementation just returns an empty array.
161 : // NOTE: This method is subject to change. Do not call or override it.
162 : virtual rtc::ArrayView<std::unique_ptr<AudioEncoder>>
163 : ReclaimContainedEncoders();
164 :
165 : // Enables audio network adaptor. Returns true if successful.
166 : virtual bool EnableAudioNetworkAdaptor(const std::string& config_string,
167 : RtcEventLog* event_log,
168 : const Clock* clock);
169 :
170 : // Disables audio network adaptor.
171 : virtual void DisableAudioNetworkAdaptor();
172 :
173 : // Provides uplink packet loss fraction to this encoder to allow it to adapt.
174 : // |uplink_packet_loss_fraction| is in the range [0.0, 1.0].
175 : virtual void OnReceivedUplinkPacketLossFraction(
176 : float uplink_packet_loss_fraction);
177 :
178 : // Provides target audio bitrate to this encoder to allow it to adapt.
179 : virtual void OnReceivedTargetAudioBitrate(int target_bps);
180 :
181 : // Provides target audio bitrate and corresponding probing interval of
182 : // the bandwidth estimator to this encoder to allow it to adapt.
183 : virtual void OnReceivedUplinkBandwidth(
184 : int target_audio_bitrate_bps,
185 : rtc::Optional<int64_t> probing_interval_ms);
186 :
187 : // Provides RTT to this encoder to allow it to adapt.
188 : virtual void OnReceivedRtt(int rtt_ms);
189 :
190 : // Provides overhead to this encoder to adapt. The overhead is the number of
191 : // bytes that will be added to each packet the encoder generates.
192 : virtual void OnReceivedOverhead(size_t overhead_bytes_per_packet);
193 :
194 : // To allow encoder to adapt its frame length, it must be provided the frame
195 : // length range that receivers can accept.
196 : virtual void SetReceiverFrameLengthRange(int min_frame_length_ms,
197 : int max_frame_length_ms);
198 :
199 : protected:
200 : // Subclasses implement this to perform the actual encoding. Called by
201 : // Encode().
202 : virtual EncodedInfo EncodeImpl(uint32_t rtp_timestamp,
203 : rtc::ArrayView<const int16_t> audio,
204 : rtc::Buffer* encoded) = 0;
205 : };
206 : } // namespace webrtc
207 : #endif // WEBRTC_MODULES_AUDIO_CODING_CODECS_AUDIO_ENCODER_H_
|
