blob: 69a50c97a3311b0e3259be0ea638e932e33e47dc [file] [log] [blame]
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001/*
kjellanderb24317b2016-02-10 07:54:43 -08002 * Copyright 2012 The WebRTC project authors. All Rights Reserved.
henrike@webrtc.org28e20752013-07-10 00:45:36 +00003 *
kjellanderb24317b2016-02-10 07:54:43 -08004 * 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.org28e20752013-07-10 00:45:36 +00009 */
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 Kjellander15583c12016-02-10 10:53:12 +010017#ifndef WEBRTC_API_MEDIASTREAMINTERFACE_H_
18#define WEBRTC_API_MEDIASTREAMINTERFACE_H_
henrike@webrtc.org28e20752013-07-10 00:45:36 +000019
20#include <string>
21#include <vector>
22
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +000023#include "webrtc/base/basictypes.h"
24#include "webrtc/base/refcount.h"
25#include "webrtc/base/scoped_ref_ptr.h"
perkja3ede6c2016-03-08 01:27:48 +010026#include "webrtc/media/base/mediachannel.h"
nissee73afba2016-01-28 04:47:08 -080027#include "webrtc/media/base/videosinkinterface.h"
nissedb25d2e2016-02-26 01:24:58 -080028#include "webrtc/media/base/videosourceinterface.h"
henrike@webrtc.org28e20752013-07-10 00:45:36 +000029
30namespace cricket {
31
32class AudioRenderer;
33class VideoCapturer;
34class VideoRenderer;
35class VideoFrame;
36
37} // namespace cricket
38
39namespace webrtc {
40
41// Generic observer interface.
42class ObserverInterface {
43 public:
44 virtual void OnChanged() = 0;
45
46 protected:
47 virtual ~ObserverInterface() {}
48};
49
50class NotifierInterface {
51 public:
52 virtual void RegisterObserver(ObserverInterface* observer) = 0;
53 virtual void UnregisterObserver(ObserverInterface* observer) = 0;
54
55 virtual ~NotifierInterface() {}
56};
57
58// Base class for sources. A MediaStreamTrack have an underlying source that
59// provide media. A source can be shared with multiple tracks.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +000060class MediaSourceInterface : public rtc::RefCountInterface,
henrike@webrtc.org28e20752013-07-10 00:45:36 +000061 public NotifierInterface {
62 public:
63 enum SourceState {
64 kInitializing,
65 kLive,
66 kEnded,
67 kMuted
68 };
69
70 virtual SourceState state() const = 0;
71
tommi6eca7e32015-12-15 04:27:11 -080072 virtual bool remote() const = 0;
73
henrike@webrtc.org28e20752013-07-10 00:45:36 +000074 protected:
75 virtual ~MediaSourceInterface() {}
76};
77
78// Information about a track.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +000079class MediaStreamTrackInterface : public rtc::RefCountInterface,
henrike@webrtc.org28e20752013-07-10 00:45:36 +000080 public NotifierInterface {
81 public:
82 enum TrackState {
83 kInitializing, // Track is beeing negotiated.
84 kLive = 1, // Track alive
85 kEnded = 2, // Track have ended
86 kFailed = 3, // Track negotiation failed.
87 };
88
deadbeeffac06552015-11-25 11:26:01 -080089 static const char kAudioKind[];
90 static const char kVideoKind[];
91
henrike@webrtc.org28e20752013-07-10 00:45:36 +000092 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;
97 // These methods should be called by implementation only.
98 virtual bool set_state(TrackState new_state) = 0;
fischman@webrtc.org32001ef2013-08-12 23:26:21 +000099
100 protected:
101 virtual ~MediaStreamTrackInterface() {}
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000102};
103
104// Interface for rendering VideoFrames from a VideoTrack
nissee73afba2016-01-28 04:47:08 -0800105class VideoRendererInterface
106 : public rtc::VideoSinkInterface<cricket::VideoFrame> {
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000107 public:
guoweis@webrtc.org00c509a2015-03-12 21:37:26 +0000108 // |frame| may have pending rotation. For clients which can't apply rotation,
109 // |frame|->GetCopyWithRotationApplied() will return a frame that has the
110 // rotation applied.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000111 virtual void RenderFrame(const cricket::VideoFrame* frame) = 0;
nissee73afba2016-01-28 04:47:08 -0800112 // Intended to replace RenderFrame.
113 void OnFrame(const cricket::VideoFrame& frame) override {
114 RenderFrame(&frame);
115 }
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000116
117 protected:
118 // The destructor is protected to prevent deletion via the interface.
119 // This is so that we allow reference counted classes, where the destructor
120 // should never be public, to implement the interface.
121 virtual ~VideoRendererInterface() {}
122};
123
perkja3ede6c2016-03-08 01:27:48 +0100124// VideoTrackSourceInterface is a reference counted source used for VideoTracks.
125// The same source can be used in multiple VideoTracks.
126class VideoTrackSourceInterface
127 : public MediaSourceInterface,
128 public rtc::VideoSourceInterface<cricket::VideoFrame> {
129 public:
130 // Get access to the source implementation of cricket::VideoCapturer.
131 // This can be used for receiving frames and state notifications.
132 // But it should not be used for starting or stopping capturing.
133 // TODO(perkj): We are currently trying to replace all internal use of
134 // cricket::VideoCapturer with rtc::VideoSourceInterface. Once that
135 // refactoring is done,
136 // remove this method.
137 virtual cricket::VideoCapturer* GetVideoCapturer() = 0;
138
139 virtual void Stop() = 0;
140 virtual void Restart() = 0;
141
perkj0d3eef22016-03-09 02:39:17 +0100142 // Indicates that parameters suitable for screencasts should be automatically
143 // applied to RtpSenders.
144 // TODO(perkj): Remove these once all known applications have moved to
145 // explicitly setting suitable parameters for screencasts and dont' need this
146 // implicit behavior.
147 virtual bool is_screencast() const = 0;
148
149 // Indicates that the encoder should denoise the video before encoding it.
150 // TODO(perkj): Remove this once denoising is done by the source, and not by
151 // the encoder.
152 virtual bool needs_denoising() const = 0;
perkja3ede6c2016-03-08 01:27:48 +0100153
154 protected:
155 virtual ~VideoTrackSourceInterface() {}
156};
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000157
nissedb25d2e2016-02-26 01:24:58 -0800158class VideoTrackInterface
159 : public MediaStreamTrackInterface,
160 public rtc::VideoSourceInterface<cricket::VideoFrame> {
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000161 public:
nissedb25d2e2016-02-26 01:24:58 -0800162 // AddRenderer and RemoveRenderer are for backwards compatibility
163 // only. They are obsoleted by the methods of
164 // rtc::VideoSourceInterface.
165 virtual void AddRenderer(VideoRendererInterface* renderer) {
166 AddOrUpdateSink(renderer, rtc::VideoSinkWants());
167 }
168 virtual void RemoveRenderer(VideoRendererInterface* renderer) {
169 RemoveSink(renderer);
170 }
171
172 // Register a video sink for this track.
173 void AddOrUpdateSink(rtc::VideoSinkInterface<cricket::VideoFrame>* sink,
174 const rtc::VideoSinkWants& wants) override{};
175 void RemoveSink(
176 rtc::VideoSinkInterface<cricket::VideoFrame>* sink) override{};
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000177
perkja3ede6c2016-03-08 01:27:48 +0100178 virtual VideoTrackSourceInterface* GetSource() const = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000179
180 protected:
181 virtual ~VideoTrackInterface() {}
182};
183
tommi6eca7e32015-12-15 04:27:11 -0800184// Interface for receiving audio data from a AudioTrack.
185class AudioTrackSinkInterface {
186 public:
187 virtual void OnData(const void* audio_data,
188 int bits_per_sample,
189 int sample_rate,
Peter Kasting69558702016-01-12 16:26:35 -0800190 size_t number_of_channels,
tommi6eca7e32015-12-15 04:27:11 -0800191 size_t number_of_frames) = 0;
192
193 protected:
194 virtual ~AudioTrackSinkInterface() {}
195};
196
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000197// AudioSourceInterface is a reference counted source used for AudioTracks.
198// The same source can be used in multiple AudioTracks.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000199class AudioSourceInterface : public MediaSourceInterface {
wu@webrtc.orgb9a088b2014-02-13 23:18:49 +0000200 public:
201 class AudioObserver {
202 public:
203 virtual void OnSetVolume(double volume) = 0;
204
205 protected:
206 virtual ~AudioObserver() {}
207 };
208
209 // TODO(xians): Makes all the interface pure virtual after Chrome has their
210 // implementations.
211 // Sets the volume to the source. |volume| is in the range of [0, 10].
Tommif888bb52015-12-12 01:37:01 +0100212 // TODO(tommi): This method should be on the track and ideally volume should
213 // be applied in the track in a way that does not affect clones of the track.
wu@webrtc.orgb9a088b2014-02-13 23:18:49 +0000214 virtual void SetVolume(double volume) {}
215
216 // Registers/unregisters observer to the audio source.
217 virtual void RegisterAudioObserver(AudioObserver* observer) {}
218 virtual void UnregisterAudioObserver(AudioObserver* observer) {}
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000219
tommi6eca7e32015-12-15 04:27:11 -0800220 // TODO(tommi): Make pure virtual.
221 virtual void AddSink(AudioTrackSinkInterface* sink) {}
222 virtual void RemoveSink(AudioTrackSinkInterface* sink) {}
mallinath@webrtc.org67ee6b92014-02-03 16:57:16 +0000223};
224
henrike@webrtc.org40b3b682014-03-03 18:30:11 +0000225// Interface of the audio processor used by the audio track to collect
226// statistics.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000227class AudioProcessorInterface : public rtc::RefCountInterface {
henrike@webrtc.org40b3b682014-03-03 18:30:11 +0000228 public:
229 struct AudioProcessorStats {
230 AudioProcessorStats() : typing_noise_detected(false),
231 echo_return_loss(0),
232 echo_return_loss_enhancement(0),
233 echo_delay_median_ms(0),
234 aec_quality_min(0.0),
235 echo_delay_std_ms(0) {}
236 ~AudioProcessorStats() {}
237
238 bool typing_noise_detected;
239 int echo_return_loss;
240 int echo_return_loss_enhancement;
241 int echo_delay_median_ms;
242 float aec_quality_min;
243 int echo_delay_std_ms;
244 };
245
246 // Get audio processor statistics.
247 virtual void GetStats(AudioProcessorStats* stats) = 0;
248
249 protected:
250 virtual ~AudioProcessorInterface() {}
251};
252
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000253class AudioTrackInterface : public MediaStreamTrackInterface {
254 public:
255 // TODO(xians): Figure out if the following interface should be const or not.
256 virtual AudioSourceInterface* GetSource() const = 0;
257
henrike@webrtc.org40b3b682014-03-03 18:30:11 +0000258 // Add/Remove a sink that will receive the audio data from the track.
259 virtual void AddSink(AudioTrackSinkInterface* sink) = 0;
260 virtual void RemoveSink(AudioTrackSinkInterface* sink) = 0;
mallinath@webrtc.org67ee6b92014-02-03 16:57:16 +0000261
henrike@webrtc.org40b3b682014-03-03 18:30:11 +0000262 // Get the signal level from the audio track.
263 // Return true on success, otherwise false.
264 // TODO(xians): Change the interface to int GetSignalLevel() and pure virtual
265 // after Chrome has the correct implementation of the interface.
266 virtual bool GetSignalLevel(int* level) { return false; }
267
268 // Get the audio processor used by the audio track. Return NULL if the track
269 // does not have any processor.
270 // TODO(xians): Make the interface pure virtual.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000271 virtual rtc::scoped_refptr<AudioProcessorInterface>
henrike@webrtc.orgb90991d2014-03-04 19:54:57 +0000272 GetAudioProcessor() { return NULL; }
henrike@webrtc.org40b3b682014-03-03 18:30:11 +0000273
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000274 protected:
275 virtual ~AudioTrackInterface() {}
276};
277
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000278typedef std::vector<rtc::scoped_refptr<AudioTrackInterface> >
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000279 AudioTrackVector;
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000280typedef std::vector<rtc::scoped_refptr<VideoTrackInterface> >
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000281 VideoTrackVector;
282
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000283class MediaStreamInterface : public rtc::RefCountInterface,
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000284 public NotifierInterface {
285 public:
286 virtual std::string label() const = 0;
287
288 virtual AudioTrackVector GetAudioTracks() = 0;
289 virtual VideoTrackVector GetVideoTracks() = 0;
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000290 virtual rtc::scoped_refptr<AudioTrackInterface>
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000291 FindAudioTrack(const std::string& track_id) = 0;
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000292 virtual rtc::scoped_refptr<VideoTrackInterface>
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000293 FindVideoTrack(const std::string& track_id) = 0;
294
295 virtual bool AddTrack(AudioTrackInterface* track) = 0;
296 virtual bool AddTrack(VideoTrackInterface* track) = 0;
297 virtual bool RemoveTrack(AudioTrackInterface* track) = 0;
298 virtual bool RemoveTrack(VideoTrackInterface* track) = 0;
299
300 protected:
301 virtual ~MediaStreamInterface() {}
302};
303
304} // namespace webrtc
305
Henrik Kjellander15583c12016-02-10 10:53:12 +0100306#endif // WEBRTC_API_MEDIASTREAMINTERFACE_H_