1 /*
2  *  Copyright (c) 2016 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 API_AUDIO_CODECS_AUDIO_FORMAT_H_
12 #define API_AUDIO_CODECS_AUDIO_FORMAT_H_
13 
14 #include <stddef.h>
15 
16 #include <map>
17 #include <string>
18 
19 #include "absl/strings/string_view.h"
20 #include "rtc_base/checks.h"
21 #include "rtc_base/system/rtc_export.h"
22 
23 namespace webrtc {
24 
25 // SDP specification for a single audio codec.
26 struct RTC_EXPORT SdpAudioFormat {
27   using Parameters = std::map<std::string, std::string>;
28 
29   SdpAudioFormat(const SdpAudioFormat&);
30   SdpAudioFormat(SdpAudioFormat&&);
31   SdpAudioFormat(absl::string_view name, int clockrate_hz, size_t num_channels);
32   SdpAudioFormat(absl::string_view name,
33                  int clockrate_hz,
34                  size_t num_channels,
35                  const Parameters& param);
36   SdpAudioFormat(absl::string_view name,
37                  int clockrate_hz,
38                  size_t num_channels,
39                  Parameters&& param);
40   ~SdpAudioFormat();
41 
42   // Returns true if this format is compatible with |o|. In SDP terminology:
43   // would it represent the same codec between an offer and an answer? As
44   // opposed to operator==, this method disregards codec parameters.
45   bool Matches(const SdpAudioFormat& o) const;
46 
47   SdpAudioFormat& operator=(const SdpAudioFormat&);
48   SdpAudioFormat& operator=(SdpAudioFormat&&);
49 
50   friend bool operator==(const SdpAudioFormat& a, const SdpAudioFormat& b);
51   friend bool operator!=(const SdpAudioFormat& a, const SdpAudioFormat& b) {
52     return !(a == b);
53   }
54 
55   std::string name;
56   int clockrate_hz;
57   size_t num_channels;
58   Parameters parameters;
59 };
60 
61 // Information about how an audio format is treated by the codec implementation.
62 // Contains basic information, such as sample rate and number of channels, which
63 // isn't uniformly presented by SDP. Also contains flags indicating support for
64 // integrating with other parts of WebRTC, like external VAD and comfort noise
65 // level calculation.
66 //
67 // To avoid API breakage, and make the code clearer, AudioCodecInfo should not
68 // be directly initializable with any flags indicating optional support. If it
69 // were, these initializers would break any time a new flag was added. It's also
70 // more difficult to understand:
71 //   AudioCodecInfo info{16000, 1, 32000, true, false, false, true, true};
72 // than
73 //   AudioCodecInfo info(16000, 1, 32000);
74 //   info.allow_comfort_noise = true;
75 //   info.future_flag_b = true;
76 //   info.future_flag_c = true;
77 struct AudioCodecInfo {
78   AudioCodecInfo(int sample_rate_hz, size_t num_channels, int bitrate_bps);
79   AudioCodecInfo(int sample_rate_hz,
80                  size_t num_channels,
81                  int default_bitrate_bps,
82                  int min_bitrate_bps,
83                  int max_bitrate_bps);
84   AudioCodecInfo(const AudioCodecInfo& b) = default;
85   ~AudioCodecInfo() = default;
86 
87   bool operator==(const AudioCodecInfo& b) const {
88     return sample_rate_hz == b.sample_rate_hz &&
89            num_channels == b.num_channels &&
90            default_bitrate_bps == b.default_bitrate_bps &&
91            min_bitrate_bps == b.min_bitrate_bps &&
92            max_bitrate_bps == b.max_bitrate_bps &&
93            allow_comfort_noise == b.allow_comfort_noise &&
94            supports_network_adaption == b.supports_network_adaption;
95   }
96 
97   bool operator!=(const AudioCodecInfo& b) const { return !(*this == b); }
98 
HasFixedBitrateAudioCodecInfo99   bool HasFixedBitrate() const {
100     RTC_DCHECK_GE(min_bitrate_bps, 0);
101     RTC_DCHECK_LE(min_bitrate_bps, default_bitrate_bps);
102     RTC_DCHECK_GE(max_bitrate_bps, default_bitrate_bps);
103     return min_bitrate_bps == max_bitrate_bps;
104   }
105 
106   int sample_rate_hz;
107   size_t num_channels;
108   int default_bitrate_bps;
109   int min_bitrate_bps;
110   int max_bitrate_bps;
111 
112   bool allow_comfort_noise = true;  // This codec can be used with an external
113                                     // comfort noise generator.
114   bool supports_network_adaption = false;  // This codec can adapt to varying
115                                            // network conditions.
116 };
117 
118 // AudioCodecSpec ties an audio format to specific information about the codec
119 // and its implementation.
120 struct AudioCodecSpec {
121   bool operator==(const AudioCodecSpec& b) const {
122     return format == b.format && info == b.info;
123   }
124 
125   bool operator!=(const AudioCodecSpec& b) const { return !(*this == b); }
126 
127   SdpAudioFormat format;
128   AudioCodecInfo info;
129 };
130 
131 }  // namespace webrtc
132 
133 #endif  // API_AUDIO_CODECS_AUDIO_FORMAT_H_
134