henrike@webrtc.org | 28e2075 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 1 | /* |
kjellander | b24317b | 2016-02-10 07:54:43 -0800 | [diff] [blame] | 2 | * Copyright 2012 The WebRTC project authors. All Rights Reserved. |
henrike@webrtc.org | 28e2075 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 3 | * |
kjellander | b24317b | 2016-02-10 07:54:43 -0800 | [diff] [blame] | 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. |
henrike@webrtc.org | 28e2075 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 9 | */ |
| 10 | |
| 11 | // This file contains interfaces for MediaStream, MediaTrack and MediaSource. |
| 12 | // These interfaces are used for implementing MediaStream and MediaTrack as |
| 13 | // defined in http://dev.w3.org/2011/webrtc/editor/webrtc.html#stream-api. These |
| 14 | // interfaces must be used only with PeerConnection. PeerConnectionManager |
| 15 | // interface provides the factory methods to create MediaStream and MediaTracks. |
| 16 | |
Henrik Kjellander | 15583c1 | 2016-02-10 10:53:12 +0100 | [diff] [blame] | 17 | #ifndef WEBRTC_API_MEDIASTREAMINTERFACE_H_ |
| 18 | #define WEBRTC_API_MEDIASTREAMINTERFACE_H_ |
henrike@webrtc.org | 28e2075 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 19 | |
pbos | 9baddf2 | 2017-01-02 06:44:41 -0800 | [diff] [blame] | 20 | #include <stddef.h> |
| 21 | |
henrike@webrtc.org | 28e2075 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 22 | #include <string> |
| 23 | #include <vector> |
| 24 | |
nisse | af91689 | 2017-01-10 07:44:26 -0800 | [diff] [blame^] | 25 | #include "webrtc/api/video/video_frame.h" |
| 26 | // TODO(nisse): Transition hack, Chrome expects that including this |
| 27 | // file declares I420Buffer. Delete after users of I420Buffer are |
| 28 | // fixed to include the new header. |
| 29 | #include "webrtc/api/video/i420_buffer.h" |
buildbot@webrtc.org | d4e598d | 2014-07-29 17:36:52 +0000 | [diff] [blame] | 30 | #include "webrtc/base/refcount.h" |
| 31 | #include "webrtc/base/scoped_ref_ptr.h" |
Per | c0d31e9 | 2016-03-31 17:23:39 +0200 | [diff] [blame] | 32 | #include "webrtc/base/optional.h" |
perkj | a3ede6c | 2016-03-08 01:27:48 +0100 | [diff] [blame] | 33 | #include "webrtc/media/base/mediachannel.h" |
nisse | e73afba | 2016-01-28 04:47:08 -0800 | [diff] [blame] | 34 | #include "webrtc/media/base/videosinkinterface.h" |
nisse | db25d2e | 2016-02-26 01:24:58 -0800 | [diff] [blame] | 35 | #include "webrtc/media/base/videosourceinterface.h" |
henrike@webrtc.org | 28e2075 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 36 | |
henrike@webrtc.org | 28e2075 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 37 | namespace webrtc { |
| 38 | |
| 39 | // Generic observer interface. |
| 40 | class ObserverInterface { |
| 41 | public: |
| 42 | virtual void OnChanged() = 0; |
| 43 | |
| 44 | protected: |
| 45 | virtual ~ObserverInterface() {} |
| 46 | }; |
| 47 | |
| 48 | class NotifierInterface { |
| 49 | public: |
| 50 | virtual void RegisterObserver(ObserverInterface* observer) = 0; |
| 51 | virtual void UnregisterObserver(ObserverInterface* observer) = 0; |
| 52 | |
| 53 | virtual ~NotifierInterface() {} |
| 54 | }; |
| 55 | |
| 56 | // Base class for sources. A MediaStreamTrack have an underlying source that |
| 57 | // provide media. A source can be shared with multiple tracks. |
buildbot@webrtc.org | d4e598d | 2014-07-29 17:36:52 +0000 | [diff] [blame] | 58 | class MediaSourceInterface : public rtc::RefCountInterface, |
henrike@webrtc.org | 28e2075 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 59 | public NotifierInterface { |
| 60 | public: |
| 61 | enum SourceState { |
| 62 | kInitializing, |
| 63 | kLive, |
| 64 | kEnded, |
| 65 | kMuted |
| 66 | }; |
| 67 | |
| 68 | virtual SourceState state() const = 0; |
| 69 | |
tommi | 6eca7e3 | 2015-12-15 04:27:11 -0800 | [diff] [blame] | 70 | virtual bool remote() const = 0; |
| 71 | |
henrike@webrtc.org | 28e2075 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 72 | protected: |
| 73 | virtual ~MediaSourceInterface() {} |
| 74 | }; |
| 75 | |
| 76 | // Information about a track. |
buildbot@webrtc.org | d4e598d | 2014-07-29 17:36:52 +0000 | [diff] [blame] | 77 | class MediaStreamTrackInterface : public rtc::RefCountInterface, |
henrike@webrtc.org | 28e2075 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 78 | public NotifierInterface { |
| 79 | public: |
| 80 | enum TrackState { |
perkj | c8f952d | 2016-03-23 00:33:56 -0700 | [diff] [blame] | 81 | kLive, |
| 82 | kEnded, |
henrike@webrtc.org | 28e2075 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 83 | }; |
| 84 | |
deadbeef | fac0655 | 2015-11-25 11:26:01 -0800 | [diff] [blame] | 85 | static const char kAudioKind[]; |
| 86 | static const char kVideoKind[]; |
| 87 | |
nisse | fcc640f | 2016-04-01 01:10:42 -0700 | [diff] [blame] | 88 | // The kind() method must return kAudioKind only if the object is a |
| 89 | // subclass of AudioTrackInterface, and kVideoKind only if the |
| 90 | // object is a subclass of VideoTrackInterface. It is typically used |
| 91 | // to protect a static_cast<> to the corresponding subclass. |
henrike@webrtc.org | 28e2075 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 92 | virtual std::string kind() const = 0; |
| 93 | virtual std::string id() const = 0; |
| 94 | virtual bool enabled() const = 0; |
| 95 | virtual TrackState state() const = 0; |
| 96 | virtual bool set_enabled(bool enable) = 0; |
fischman@webrtc.org | 32001ef | 2013-08-12 23:26:21 +0000 | [diff] [blame] | 97 | |
| 98 | protected: |
| 99 | virtual ~MediaStreamTrackInterface() {} |
henrike@webrtc.org | 28e2075 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 100 | }; |
| 101 | |
perkj | a3ede6c | 2016-03-08 01:27:48 +0100 | [diff] [blame] | 102 | // VideoTrackSourceInterface is a reference counted source used for VideoTracks. |
| 103 | // The same source can be used in multiple VideoTracks. |
| 104 | class VideoTrackSourceInterface |
| 105 | : public MediaSourceInterface, |
nisse | acd935b | 2016-11-11 03:55:13 -0800 | [diff] [blame] | 106 | public rtc::VideoSourceInterface<VideoFrame> { |
perkj | a3ede6c | 2016-03-08 01:27:48 +0100 | [diff] [blame] | 107 | public: |
nisse | fcc640f | 2016-04-01 01:10:42 -0700 | [diff] [blame] | 108 | struct Stats { |
| 109 | // Original size of captured frame, before video adaptation. |
| 110 | int input_width; |
| 111 | int input_height; |
| 112 | }; |
perkj | a3ede6c | 2016-03-08 01:27:48 +0100 | [diff] [blame] | 113 | |
perkj | 0d3eef2 | 2016-03-09 02:39:17 +0100 | [diff] [blame] | 114 | // Indicates that parameters suitable for screencasts should be automatically |
| 115 | // applied to RtpSenders. |
| 116 | // TODO(perkj): Remove these once all known applications have moved to |
| 117 | // explicitly setting suitable parameters for screencasts and dont' need this |
| 118 | // implicit behavior. |
| 119 | virtual bool is_screencast() const = 0; |
| 120 | |
Per | c0d31e9 | 2016-03-31 17:23:39 +0200 | [diff] [blame] | 121 | // Indicates that the encoder should denoise video before encoding it. |
| 122 | // If it is not set, the default configuration is used which is different |
| 123 | // depending on video codec. |
perkj | 0d3eef2 | 2016-03-09 02:39:17 +0100 | [diff] [blame] | 124 | // TODO(perkj): Remove this once denoising is done by the source, and not by |
| 125 | // the encoder. |
Per | c0d31e9 | 2016-03-31 17:23:39 +0200 | [diff] [blame] | 126 | virtual rtc::Optional<bool> needs_denoising() const = 0; |
perkj | a3ede6c | 2016-03-08 01:27:48 +0100 | [diff] [blame] | 127 | |
nisse | fcc640f | 2016-04-01 01:10:42 -0700 | [diff] [blame] | 128 | // Returns false if no stats are available, e.g, for a remote |
| 129 | // source, or a source which has not seen its first frame yet. |
| 130 | // Should avoid blocking. |
| 131 | virtual bool GetStats(Stats* stats) = 0; |
| 132 | |
perkj | a3ede6c | 2016-03-08 01:27:48 +0100 | [diff] [blame] | 133 | protected: |
| 134 | virtual ~VideoTrackSourceInterface() {} |
| 135 | }; |
henrike@webrtc.org | 28e2075 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 136 | |
nisse | db25d2e | 2016-02-26 01:24:58 -0800 | [diff] [blame] | 137 | class VideoTrackInterface |
| 138 | : public MediaStreamTrackInterface, |
nisse | acd935b | 2016-11-11 03:55:13 -0800 | [diff] [blame] | 139 | public rtc::VideoSourceInterface<VideoFrame> { |
henrike@webrtc.org | 28e2075 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 140 | public: |
pbos | 5214a0a | 2016-12-16 15:39:11 -0800 | [diff] [blame] | 141 | // Video track content hint, used to override the source is_screencast |
| 142 | // property. |
| 143 | // See https://crbug.com/653531 and https://github.com/WICG/mst-content-hint. |
| 144 | enum class ContentHint { kNone, kFluid, kDetailed }; |
| 145 | |
nisse | db25d2e | 2016-02-26 01:24:58 -0800 | [diff] [blame] | 146 | // Register a video sink for this track. |
nisse | acd935b | 2016-11-11 03:55:13 -0800 | [diff] [blame] | 147 | void AddOrUpdateSink(rtc::VideoSinkInterface<VideoFrame>* sink, |
pbos | 5214a0a | 2016-12-16 15:39:11 -0800 | [diff] [blame] | 148 | const rtc::VideoSinkWants& wants) override {} |
| 149 | void RemoveSink(rtc::VideoSinkInterface<VideoFrame>* sink) override {} |
henrike@webrtc.org | 28e2075 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 150 | |
perkj | a3ede6c | 2016-03-08 01:27:48 +0100 | [diff] [blame] | 151 | virtual VideoTrackSourceInterface* GetSource() const = 0; |
henrike@webrtc.org | 28e2075 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 152 | |
pbos | 5214a0a | 2016-12-16 15:39:11 -0800 | [diff] [blame] | 153 | virtual ContentHint content_hint() const { return ContentHint::kNone; } |
| 154 | virtual void set_content_hint(ContentHint hint) {} |
| 155 | |
henrike@webrtc.org | 28e2075 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 156 | protected: |
| 157 | virtual ~VideoTrackInterface() {} |
| 158 | }; |
| 159 | |
tommi | 6eca7e3 | 2015-12-15 04:27:11 -0800 | [diff] [blame] | 160 | // Interface for receiving audio data from a AudioTrack. |
| 161 | class AudioTrackSinkInterface { |
| 162 | public: |
| 163 | virtual void OnData(const void* audio_data, |
| 164 | int bits_per_sample, |
| 165 | int sample_rate, |
Peter Kasting | 6955870 | 2016-01-12 16:26:35 -0800 | [diff] [blame] | 166 | size_t number_of_channels, |
tommi | 6eca7e3 | 2015-12-15 04:27:11 -0800 | [diff] [blame] | 167 | size_t number_of_frames) = 0; |
| 168 | |
| 169 | protected: |
| 170 | virtual ~AudioTrackSinkInterface() {} |
| 171 | }; |
| 172 | |
henrike@webrtc.org | 28e2075 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 173 | // AudioSourceInterface is a reference counted source used for AudioTracks. |
| 174 | // The same source can be used in multiple AudioTracks. |
henrike@webrtc.org | 28e2075 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 175 | class AudioSourceInterface : public MediaSourceInterface { |
wu@webrtc.org | b9a088b | 2014-02-13 23:18:49 +0000 | [diff] [blame] | 176 | public: |
| 177 | class AudioObserver { |
| 178 | public: |
| 179 | virtual void OnSetVolume(double volume) = 0; |
| 180 | |
| 181 | protected: |
| 182 | virtual ~AudioObserver() {} |
| 183 | }; |
| 184 | |
| 185 | // TODO(xians): Makes all the interface pure virtual after Chrome has their |
| 186 | // implementations. |
| 187 | // Sets the volume to the source. |volume| is in the range of [0, 10]. |
Tommi | f888bb5 | 2015-12-12 01:37:01 +0100 | [diff] [blame] | 188 | // TODO(tommi): This method should be on the track and ideally volume should |
| 189 | // be applied in the track in a way that does not affect clones of the track. |
wu@webrtc.org | b9a088b | 2014-02-13 23:18:49 +0000 | [diff] [blame] | 190 | virtual void SetVolume(double volume) {} |
| 191 | |
| 192 | // Registers/unregisters observer to the audio source. |
| 193 | virtual void RegisterAudioObserver(AudioObserver* observer) {} |
| 194 | virtual void UnregisterAudioObserver(AudioObserver* observer) {} |
henrike@webrtc.org | 28e2075 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 195 | |
tommi | 6eca7e3 | 2015-12-15 04:27:11 -0800 | [diff] [blame] | 196 | // TODO(tommi): Make pure virtual. |
| 197 | virtual void AddSink(AudioTrackSinkInterface* sink) {} |
| 198 | virtual void RemoveSink(AudioTrackSinkInterface* sink) {} |
mallinath@webrtc.org | 67ee6b9 | 2014-02-03 16:57:16 +0000 | [diff] [blame] | 199 | }; |
| 200 | |
henrike@webrtc.org | 40b3b68 | 2014-03-03 18:30:11 +0000 | [diff] [blame] | 201 | // Interface of the audio processor used by the audio track to collect |
| 202 | // statistics. |
buildbot@webrtc.org | d4e598d | 2014-07-29 17:36:52 +0000 | [diff] [blame] | 203 | class AudioProcessorInterface : public rtc::RefCountInterface { |
henrike@webrtc.org | 40b3b68 | 2014-03-03 18:30:11 +0000 | [diff] [blame] | 204 | public: |
| 205 | struct AudioProcessorStats { |
| 206 | AudioProcessorStats() : typing_noise_detected(false), |
| 207 | echo_return_loss(0), |
| 208 | echo_return_loss_enhancement(0), |
| 209 | echo_delay_median_ms(0), |
Minyue | 2a8a78c | 2016-04-07 16:48:15 +0200 | [diff] [blame] | 210 | echo_delay_std_ms(0), |
ivoc | 8c63a82 | 2016-10-21 04:10:03 -0700 | [diff] [blame] | 211 | aec_quality_min(0.0), |
| 212 | residual_echo_likelihood(0.0f), |
Minyue | 2a8a78c | 2016-04-07 16:48:15 +0200 | [diff] [blame] | 213 | aec_divergent_filter_fraction(0.0) {} |
henrike@webrtc.org | 40b3b68 | 2014-03-03 18:30:11 +0000 | [diff] [blame] | 214 | ~AudioProcessorStats() {} |
| 215 | |
| 216 | bool typing_noise_detected; |
| 217 | int echo_return_loss; |
| 218 | int echo_return_loss_enhancement; |
| 219 | int echo_delay_median_ms; |
henrike@webrtc.org | 40b3b68 | 2014-03-03 18:30:11 +0000 | [diff] [blame] | 220 | int echo_delay_std_ms; |
ivoc | 8c63a82 | 2016-10-21 04:10:03 -0700 | [diff] [blame] | 221 | float aec_quality_min; |
| 222 | float residual_echo_likelihood; |
Minyue | 2a8a78c | 2016-04-07 16:48:15 +0200 | [diff] [blame] | 223 | float aec_divergent_filter_fraction; |
henrike@webrtc.org | 40b3b68 | 2014-03-03 18:30:11 +0000 | [diff] [blame] | 224 | }; |
| 225 | |
| 226 | // Get audio processor statistics. |
| 227 | virtual void GetStats(AudioProcessorStats* stats) = 0; |
| 228 | |
| 229 | protected: |
| 230 | virtual ~AudioProcessorInterface() {} |
| 231 | }; |
| 232 | |
henrike@webrtc.org | 28e2075 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 233 | class AudioTrackInterface : public MediaStreamTrackInterface { |
| 234 | public: |
| 235 | // TODO(xians): Figure out if the following interface should be const or not. |
| 236 | virtual AudioSourceInterface* GetSource() const = 0; |
| 237 | |
henrike@webrtc.org | 40b3b68 | 2014-03-03 18:30:11 +0000 | [diff] [blame] | 238 | // Add/Remove a sink that will receive the audio data from the track. |
| 239 | virtual void AddSink(AudioTrackSinkInterface* sink) = 0; |
| 240 | virtual void RemoveSink(AudioTrackSinkInterface* sink) = 0; |
mallinath@webrtc.org | 67ee6b9 | 2014-02-03 16:57:16 +0000 | [diff] [blame] | 241 | |
henrike@webrtc.org | 40b3b68 | 2014-03-03 18:30:11 +0000 | [diff] [blame] | 242 | // Get the signal level from the audio track. |
| 243 | // Return true on success, otherwise false. |
| 244 | // TODO(xians): Change the interface to int GetSignalLevel() and pure virtual |
| 245 | // after Chrome has the correct implementation of the interface. |
| 246 | virtual bool GetSignalLevel(int* level) { return false; } |
| 247 | |
| 248 | // Get the audio processor used by the audio track. Return NULL if the track |
| 249 | // does not have any processor. |
| 250 | // TODO(xians): Make the interface pure virtual. |
buildbot@webrtc.org | d4e598d | 2014-07-29 17:36:52 +0000 | [diff] [blame] | 251 | virtual rtc::scoped_refptr<AudioProcessorInterface> |
henrike@webrtc.org | b90991d | 2014-03-04 19:54:57 +0000 | [diff] [blame] | 252 | GetAudioProcessor() { return NULL; } |
henrike@webrtc.org | 40b3b68 | 2014-03-03 18:30:11 +0000 | [diff] [blame] | 253 | |
henrike@webrtc.org | 28e2075 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 254 | protected: |
| 255 | virtual ~AudioTrackInterface() {} |
| 256 | }; |
| 257 | |
buildbot@webrtc.org | d4e598d | 2014-07-29 17:36:52 +0000 | [diff] [blame] | 258 | typedef std::vector<rtc::scoped_refptr<AudioTrackInterface> > |
henrike@webrtc.org | 28e2075 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 259 | AudioTrackVector; |
buildbot@webrtc.org | d4e598d | 2014-07-29 17:36:52 +0000 | [diff] [blame] | 260 | typedef std::vector<rtc::scoped_refptr<VideoTrackInterface> > |
henrike@webrtc.org | 28e2075 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 261 | VideoTrackVector; |
| 262 | |
buildbot@webrtc.org | d4e598d | 2014-07-29 17:36:52 +0000 | [diff] [blame] | 263 | class MediaStreamInterface : public rtc::RefCountInterface, |
henrike@webrtc.org | 28e2075 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 264 | public NotifierInterface { |
| 265 | public: |
| 266 | virtual std::string label() const = 0; |
| 267 | |
| 268 | virtual AudioTrackVector GetAudioTracks() = 0; |
| 269 | virtual VideoTrackVector GetVideoTracks() = 0; |
buildbot@webrtc.org | d4e598d | 2014-07-29 17:36:52 +0000 | [diff] [blame] | 270 | virtual rtc::scoped_refptr<AudioTrackInterface> |
henrike@webrtc.org | 28e2075 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 271 | FindAudioTrack(const std::string& track_id) = 0; |
buildbot@webrtc.org | d4e598d | 2014-07-29 17:36:52 +0000 | [diff] [blame] | 272 | virtual rtc::scoped_refptr<VideoTrackInterface> |
henrike@webrtc.org | 28e2075 | 2013-07-10 00:45:36 +0000 | [diff] [blame] | 273 | FindVideoTrack(const std::string& track_id) = 0; |
| 274 | |
| 275 | virtual bool AddTrack(AudioTrackInterface* track) = 0; |
| 276 | virtual bool AddTrack(VideoTrackInterface* track) = 0; |
| 277 | virtual bool RemoveTrack(AudioTrackInterface* track) = 0; |
| 278 | virtual bool RemoveTrack(VideoTrackInterface* track) = 0; |
| 279 | |
| 280 | protected: |
| 281 | virtual ~MediaStreamInterface() {} |
| 282 | }; |
| 283 | |
| 284 | } // namespace webrtc |
| 285 | |
Henrik Kjellander | 15583c1 | 2016-02-10 10:53:12 +0100 | [diff] [blame] | 286 | #endif // WEBRTC_API_MEDIASTREAMINTERFACE_H_ |