media_engine.h (9881B)
1 /* 2 * Copyright (c) 2004 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 MEDIA_BASE_MEDIA_ENGINE_H_ 12 #define MEDIA_BASE_MEDIA_ENGINE_H_ 13 14 #include <cstdint> 15 #include <memory> 16 #include <optional> 17 #include <vector> 18 19 #include "api/array_view.h" 20 #include "api/audio/audio_device.h" 21 #include "api/audio_codecs/audio_codec_pair_id.h" 22 #include "api/audio_codecs/audio_decoder_factory.h" 23 #include "api/audio_codecs/audio_encoder_factory.h" 24 #include "api/audio_options.h" 25 #include "api/crypto/crypto_options.h" 26 #include "api/environment/environment.h" 27 #include "api/field_trials_view.h" 28 #include "api/rtc_error.h" 29 #include "api/rtp_parameters.h" 30 #include "api/scoped_refptr.h" 31 #include "api/video/video_bitrate_allocator_factory.h" 32 #include "call/audio_state.h" 33 #include "media/base/codec.h" 34 #include "media/base/media_channel.h" 35 #include "media/base/media_config.h" 36 #include "media/base/stream_params.h" 37 #include "rtc_base/system/file_wrapper.h" 38 39 namespace webrtc { 40 41 class AudioMixer; 42 class Call; 43 44 // Checks that the scalability_mode value of each encoding is supported by at 45 // least one video codec of the list. If the list is empty, no check is done. 46 RTCError CheckScalabilityModeValues(const RtpParameters& new_parameters, 47 ArrayView<Codec> send_codecs, 48 std::optional<Codec> send_codec); 49 50 // Checks the parameters have valid and supported values, and checks parameters 51 // with CheckScalabilityModeValues(). 52 RTCError CheckRtpParametersValues(const RtpParameters& new_parameters, 53 ArrayView<Codec> send_codecs, 54 std::optional<Codec> send_codec, 55 const FieldTrialsView& field_trials); 56 57 // Checks that the immutable values have not changed in new_parameters and 58 // checks all parameters with CheckRtpParametersValues(). 59 RTCError CheckRtpParametersInvalidModificationAndValues( 60 const RtpParameters& old_parameters, 61 const RtpParameters& new_parameters, 62 ArrayView<Codec> send_codecs, 63 std::optional<Codec> send_codec, 64 const FieldTrialsView& field_trials); 65 66 // Checks that the immutable values have not changed in new_parameters and 67 // checks parameters (except SVC) with CheckRtpParametersValues(). It should 68 // usually be paired with a call to CheckScalabilityModeValues(). 69 RTCError CheckRtpParametersInvalidModificationAndValues( 70 const RtpParameters& old_parameters, 71 const RtpParameters& new_parameters, 72 const FieldTrialsView& field_trials); 73 74 class RtpHeaderExtensionQueryInterface { 75 public: 76 virtual ~RtpHeaderExtensionQueryInterface() = default; 77 78 // Returns a vector of RtpHeaderExtensionCapability, whose direction is 79 // kStopped if the extension is stopped (not used) by default. 80 virtual std::vector<RtpHeaderExtensionCapability> GetRtpHeaderExtensions( 81 const webrtc::FieldTrialsView* field_trials) const = 0; 82 }; 83 84 class VoiceEngineInterface : public RtpHeaderExtensionQueryInterface { 85 public: 86 VoiceEngineInterface() = default; 87 virtual ~VoiceEngineInterface() = default; 88 89 VoiceEngineInterface(const VoiceEngineInterface&) = delete; 90 VoiceEngineInterface& operator=(const VoiceEngineInterface&) = delete; 91 92 // Initialization 93 // Starts the engine. 94 virtual void Init() = 0; 95 96 // TODO(solenberg): Remove once VoE API refactoring is done. 97 virtual scoped_refptr<AudioState> GetAudioState() const = 0; 98 99 virtual std::unique_ptr<VoiceMediaSendChannelInterface> CreateSendChannel( 100 const Environment& env, 101 Call* call, 102 const MediaConfig& config, 103 const AudioOptions& options, 104 const CryptoOptions& crypto_options, 105 AudioCodecPairId codec_pair_id) = 0; 106 107 virtual std::unique_ptr<VoiceMediaReceiveChannelInterface> 108 CreateReceiveChannel(const Environment& env, 109 Call* call, 110 const MediaConfig& config, 111 const AudioOptions& options, 112 const CryptoOptions& crypto_options, 113 AudioCodecPairId codec_pair_id) = 0; 114 115 // Legacy: Retrieve list of supported codecs. 116 // + protection codecs, and assigns PT numbers that may have to be 117 // reassigned. 118 // This function is being moved to CodecVendor 119 // TODO: https://issues.webrtc.org/360058654 - remove when all users updated. 120 [[deprecated]] inline const std::vector<Codec>& send_codecs() const { 121 return LegacySendCodecs(); 122 } 123 [[deprecated]] inline const std::vector<Codec>& recv_codecs() const { 124 return LegacyRecvCodecs(); 125 } 126 virtual const std::vector<Codec>& LegacySendCodecs() const = 0; 127 virtual const std::vector<Codec>& LegacyRecvCodecs() const = 0; 128 129 virtual AudioEncoderFactory* encoder_factory() const = 0; 130 virtual AudioDecoderFactory* decoder_factory() const = 0; 131 132 // Starts AEC dump using existing file, a maximum file size in bytes can be 133 // specified. Logging is stopped just before the size limit is exceeded. 134 // If max_size_bytes is set to a value <= 0, no limit will be used. 135 virtual bool StartAecDump(FileWrapper file, int64_t max_size_bytes) = 0; 136 137 // Stops recording AEC dump. 138 virtual void StopAecDump() = 0; 139 140 virtual std::optional<AudioDeviceModule::Stats> GetAudioDeviceStats() = 0; 141 }; 142 143 class VideoEngineInterface : public RtpHeaderExtensionQueryInterface { 144 public: 145 VideoEngineInterface() = default; 146 virtual ~VideoEngineInterface() = default; 147 148 VideoEngineInterface(const VideoEngineInterface&) = delete; 149 VideoEngineInterface& operator=(const VideoEngineInterface&) = delete; 150 151 virtual std::unique_ptr<VideoMediaSendChannelInterface> CreateSendChannel( 152 const Environment& env, 153 Call* call, 154 const MediaConfig& config, 155 const VideoOptions& options, 156 const CryptoOptions& crypto_options, 157 VideoBitrateAllocatorFactory* video_bitrate_allocator_factory) = 0; 158 159 virtual std::unique_ptr<VideoMediaReceiveChannelInterface> 160 CreateReceiveChannel(const Environment& env, 161 Call* call, 162 const MediaConfig& config, 163 const VideoOptions& options, 164 const CryptoOptions& crypto_options) = 0; 165 166 // Legacy: Retrieve list of supported codecs. 167 // + protection codecs, and assigns PT numbers that may have to be 168 // reassigned. 169 // This functionality is being moved to the CodecVendor class. 170 // TODO: https://issues.webrtc.org/360058654 - deprecate and remove. 171 [[deprecated]] inline std::vector<Codec> send_codecs() const { 172 return LegacySendCodecs(); 173 } 174 [[deprecated]] inline std::vector<Codec> recv_codecs() const { 175 return LegacyRecvCodecs(); 176 } 177 virtual std::vector<Codec> LegacySendCodecs() const = 0; 178 virtual std::vector<Codec> LegacyRecvCodecs() const = 0; 179 // As above, but if include_rtx is false, don't include RTX codecs. 180 [[deprecated]] inline std::vector<Codec> send_codecs(bool include_rtx) const { 181 return LegacySendCodecs(include_rtx); 182 } 183 virtual std::vector<Codec> LegacySendCodecs(bool include_rtx) const = 0; 184 virtual std::vector<Codec> LegacyRecvCodecs(bool include_rtx) const = 0; 185 [[deprecated]] inline std::vector<Codec> recv_codecs(bool include_rtx) const { 186 return LegacyRecvCodecs(include_rtx); 187 } 188 }; 189 190 // MediaEngineInterface is an abstraction of a media engine which can be 191 // subclassed to support different media componentry backends. 192 // It supports voice and video operations in the same class to facilitate 193 // proper synchronization between both media types. 194 class MediaEngineInterface { 195 public: 196 virtual ~MediaEngineInterface() {} 197 198 // Initialization. Needs to be called on the worker thread. 199 virtual bool Init() = 0; 200 201 virtual VoiceEngineInterface& voice() = 0; 202 virtual VideoEngineInterface& video() = 0; 203 virtual const VoiceEngineInterface& voice() const = 0; 204 virtual const VideoEngineInterface& video() const = 0; 205 }; 206 207 // CompositeMediaEngine constructs a MediaEngine from separate 208 // voice and video engine classes. 209 // Optionally owns a FieldTrialsView trials map. 210 class CompositeMediaEngine : public MediaEngineInterface { 211 public: 212 CompositeMediaEngine(std::unique_ptr<FieldTrialsView> trials, 213 std::unique_ptr<VoiceEngineInterface> audio_engine, 214 std::unique_ptr<VideoEngineInterface> video_engine); 215 CompositeMediaEngine(std::unique_ptr<VoiceEngineInterface> audio_engine, 216 std::unique_ptr<VideoEngineInterface> video_engine); 217 ~CompositeMediaEngine() override; 218 219 // Always succeeds. 220 bool Init() override; 221 222 VoiceEngineInterface& voice() override; 223 VideoEngineInterface& video() override; 224 const VoiceEngineInterface& voice() const override; 225 const VideoEngineInterface& video() const override; 226 227 private: 228 const std::unique_ptr<FieldTrialsView> trials_; 229 const std::unique_ptr<VoiceEngineInterface> voice_engine_; 230 const std::unique_ptr<VideoEngineInterface> video_engine_; 231 }; 232 233 RtpParameters CreateRtpParametersWithOneEncoding(); 234 RtpParameters CreateRtpParametersWithEncodings(StreamParams sp); 235 236 // Returns a vector of RTP extensions as visible from RtpSender/Receiver 237 // GetCapabilities(). The returned vector only shows what will definitely be 238 // offered by default, i.e. the list of extensions returned from 239 // GetRtpHeaderExtensions() that are not kStopped. 240 std::vector<RtpExtension> GetDefaultEnabledRtpHeaderExtensions( 241 const RtpHeaderExtensionQueryInterface& query_interface, 242 const webrtc::FieldTrialsView* field_trials); 243 244 } // namespace webrtc 245 246 247 #endif // MEDIA_BASE_MEDIA_ENGINE_H_