blob: a6ee546d9ecd32db76c31a2c22f4b952e2867e19 [file] [log] [blame]
deadbeef6979b022015-09-24 16:47:53 -07001/*
kjellanderb24317b2016-02-10 07:54:43 -08002 * Copyright 2015 The WebRTC project authors. All Rights Reserved.
deadbeef6979b022015-09-24 16:47:53 -07003 *
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.
deadbeef6979b022015-09-24 16:47:53 -07009 */
10
deadbeef70ab1a12015-09-28 16:53:55 -070011// This file contains interfaces for RtpReceivers
12// http://w3c.github.io/webrtc-pc/#rtcrtpreceiver-interface
13
Steve Anton10542f22019-01-11 09:11:00 -080014#ifndef API_RTP_RECEIVER_INTERFACE_H_
15#define API_RTP_RECEIVER_INTERFACE_H_
deadbeef70ab1a12015-09-28 16:53:55 -070016
17#include <string>
hbos8d609f62017-04-10 07:39:05 -070018#include <vector>
deadbeef70ab1a12015-09-28 16:53:55 -070019
Steve Anton10542f22019-01-11 09:11:00 -080020#include "api/crypto/frame_decryptor_interface.h"
Harald Alvestrand4a7b3ac2019-01-17 10:39:40 +010021#include "api/dtls_transport_interface.h"
Steve Anton10542f22019-01-11 09:11:00 -080022#include "api/media_stream_interface.h"
23#include "api/media_types.h"
Mirko Bonadei92ea95e2017-09-15 06:47:31 +020024#include "api/proxy.h"
Steve Anton10542f22019-01-11 09:11:00 -080025#include "api/rtp_parameters.h"
Mirko Bonadeid9708072019-01-25 20:26:48 +010026#include "api/scoped_refptr.h"
Johannes Kronb5d91832019-05-21 13:19:22 +020027#include "rtc_base/deprecation.h"
Steve Anton10542f22019-01-11 09:11:00 -080028#include "rtc_base/ref_count.h"
deadbeef70ab1a12015-09-28 16:53:55 -070029
30namespace webrtc {
31
hbos8d609f62017-04-10 07:39:05 -070032enum class RtpSourceType {
33 SSRC,
34 CSRC,
35};
36
37class RtpSource {
38 public:
39 RtpSource() = delete;
Johannes Kronb5d91832019-05-21 13:19:22 +020040
zstein2b706342017-08-24 14:52:17 -070041 RtpSource(int64_t timestamp_ms,
42 uint32_t source_id,
43 RtpSourceType source_type,
Johannes Kronb5d91832019-05-21 13:19:22 +020044 absl::optional<uint8_t> audio_level,
45 uint32_t rtp_timestamp);
46
Danil Chapovalov2a5ce2b2018-02-07 09:38:31 +010047 RtpSource(const RtpSource&);
48 RtpSource& operator=(const RtpSource&);
49 ~RtpSource();
zstein2b706342017-08-24 14:52:17 -070050
hbos8d609f62017-04-10 07:39:05 -070051 int64_t timestamp_ms() const { return timestamp_ms_; }
52 void update_timestamp_ms(int64_t timestamp_ms) {
53 RTC_DCHECK_LE(timestamp_ms_, timestamp_ms);
54 timestamp_ms_ = timestamp_ms;
55 }
56
57 // The identifier of the source can be the CSRC or the SSRC.
58 uint32_t source_id() const { return source_id_; }
59
60 // The source can be either a contributing source or a synchronization source.
61 RtpSourceType source_type() const { return source_type_; }
62
Danil Chapovalov0bc58cf2018-06-21 13:32:56 +020063 absl::optional<uint8_t> audio_level() const { return audio_level_; }
64 void set_audio_level(const absl::optional<uint8_t>& level) {
zstein2b706342017-08-24 14:52:17 -070065 audio_level_ = level;
66 }
hbos8d609f62017-04-10 07:39:05 -070067
Johannes Kronb5d91832019-05-21 13:19:22 +020068 uint32_t rtp_timestamp() const { return rtp_timestamp_; }
69
zhihuang04262222017-04-11 11:28:10 -070070 bool operator==(const RtpSource& o) const {
71 return timestamp_ms_ == o.timestamp_ms() && source_id_ == o.source_id() &&
Johannes Kronb5d91832019-05-21 13:19:22 +020072 source_type_ == o.source_type() && audio_level_ == o.audio_level_ &&
73 rtp_timestamp_ == o.rtp_timestamp();
zhihuang04262222017-04-11 11:28:10 -070074 }
75
hbos8d609f62017-04-10 07:39:05 -070076 private:
77 int64_t timestamp_ms_;
78 uint32_t source_id_;
79 RtpSourceType source_type_;
Danil Chapovalov0bc58cf2018-06-21 13:32:56 +020080 absl::optional<uint8_t> audio_level_;
Johannes Kronb5d91832019-05-21 13:19:22 +020081 uint32_t rtp_timestamp_;
hbos8d609f62017-04-10 07:39:05 -070082};
83
zhihuang184a3fd2016-06-14 11:47:14 -070084class RtpReceiverObserverInterface {
85 public:
Taylor Brandstetterba29c6a2016-06-27 16:30:35 -070086 // Note: Currently if there are multiple RtpReceivers of the same media type,
87 // they will all call OnFirstPacketReceived at once.
88 //
89 // In the future, it's likely that an RtpReceiver will only call
90 // OnFirstPacketReceived when a packet is received specifically for its
91 // SSRC/mid.
zhihuang184a3fd2016-06-14 11:47:14 -070092 virtual void OnFirstPacketReceived(cricket::MediaType media_type) = 0;
93
94 protected:
95 virtual ~RtpReceiverObserverInterface() {}
96};
97
deadbeef70ab1a12015-09-28 16:53:55 -070098class RtpReceiverInterface : public rtc::RefCountInterface {
99 public:
100 virtual rtc::scoped_refptr<MediaStreamTrackInterface> track() const = 0;
Harald Alvestrand4a7b3ac2019-01-17 10:39:40 +0100101
102 // The dtlsTransport attribute exposes the DTLS transport on which the
103 // media is received. It may be null.
104 // https://w3c.github.io/webrtc-pc/#dom-rtcrtpreceiver-transport
105 // TODO(https://bugs.webrtc.org/907849) remove default implementation
106 virtual rtc::scoped_refptr<DtlsTransportInterface> dtls_transport() const;
107
Henrik Boström9e6fd2b2017-11-21 13:41:51 +0100108 // The list of streams that |track| is associated with. This is the same as
109 // the [[AssociatedRemoteMediaStreams]] internal slot in the spec.
Henrik Boström199e27b2018-07-04 20:51:53 +0200110 // https://w3c.github.io/webrtc-pc/#dfn-associatedremotemediastreams
Henrik Boström9e6fd2b2017-11-21 13:41:51 +0100111 // TODO(hbos): Make pure virtual as soon as Chromium's mock implements this.
Henrik Boström199e27b2018-07-04 20:51:53 +0200112 // TODO(https://crbug.com/webrtc/9480): Remove streams() in favor of
113 // stream_ids() as soon as downstream projects are no longer dependent on
114 // stream objects.
115 virtual std::vector<std::string> stream_ids() const;
Danil Chapovalov2a5ce2b2018-02-07 09:38:31 +0100116 virtual std::vector<rtc::scoped_refptr<MediaStreamInterface>> streams() const;
deadbeef70ab1a12015-09-28 16:53:55 -0700117
Taylor Brandstetterba29c6a2016-06-27 16:30:35 -0700118 // Audio or video receiver?
119 virtual cricket::MediaType media_type() const = 0;
120
deadbeef70ab1a12015-09-28 16:53:55 -0700121 // Not to be confused with "mid", this is a field we can temporarily use
122 // to uniquely identify a receiver until we implement Unified Plan SDP.
123 virtual std::string id() const = 0;
124
Taylor Brandstetterdb0cd9e2016-05-16 11:40:30 -0700125 // The WebRTC specification only defines RTCRtpParameters in terms of senders,
126 // but this API also applies them to receivers, similar to ORTC:
127 // http://ortc.org/wp-content/uploads/2016/03/ortc.html#rtcrtpparameters*.
128 virtual RtpParameters GetParameters() const = 0;
deadbeefb10f32f2017-02-08 01:38:21 -0800129 // Currently, doesn't support changing any parameters, but may in the future.
Taylor Brandstetterdb0cd9e2016-05-16 11:40:30 -0700130 virtual bool SetParameters(const RtpParameters& parameters) = 0;
131
Taylor Brandstetterba29c6a2016-06-27 16:30:35 -0700132 // Does not take ownership of observer.
133 // Must call SetObserver(nullptr) before the observer is destroyed.
zhihuang184a3fd2016-06-14 11:47:14 -0700134 virtual void SetObserver(RtpReceiverObserverInterface* observer) = 0;
135
Ruslan Burakov4bac79e2019-04-03 19:55:33 +0200136 // Sets the jitter buffer minimum delay until media playout. Actual observed
137 // delay may differ depending on the congestion control. |delay_seconds| is a
138 // positive value including 0.0 measured in seconds. |nullopt| means default
Ruslan Burakov428dcb22019-04-18 17:49:49 +0200139 // value must be used.
Ruslan Burakov4bac79e2019-04-03 19:55:33 +0200140 virtual void SetJitterBufferMinimumDelay(
Ruslan Burakov428dcb22019-04-18 17:49:49 +0200141 absl::optional<double> delay_seconds) = 0;
Ruslan Burakov4bac79e2019-04-03 19:55:33 +0200142
hbos8d609f62017-04-10 07:39:05 -0700143 // TODO(zhihuang): Remove the default implementation once the subclasses
144 // implement this. Currently, the only relevant subclass is the
145 // content::FakeRtpReceiver in Chromium.
Danil Chapovalov2a5ce2b2018-02-07 09:38:31 +0100146 virtual std::vector<RtpSource> GetSources() const;
147
Benjamin Wrightd81ac952018-08-29 17:02:10 -0700148 // Sets a user defined frame decryptor that will decrypt the entire frame
149 // before it is sent across the network. This will decrypt the entire frame
150 // using the user provided decryption mechanism regardless of whether SRTP is
151 // enabled or not.
152 virtual void SetFrameDecryptor(
153 rtc::scoped_refptr<FrameDecryptorInterface> frame_decryptor);
154
155 // Returns a pointer to the frame decryptor set previously by the
156 // user. This can be used to update the state of the object.
157 virtual rtc::scoped_refptr<FrameDecryptorInterface> GetFrameDecryptor() const;
158
deadbeef70ab1a12015-09-28 16:53:55 -0700159 protected:
Danil Chapovalov2a5ce2b2018-02-07 09:38:31 +0100160 ~RtpReceiverInterface() override = default;
deadbeef70ab1a12015-09-28 16:53:55 -0700161};
162
163// Define proxy for RtpReceiverInterface.
deadbeefb10f32f2017-02-08 01:38:21 -0800164// TODO(deadbeef): Move this to .cc file and out of api/. What threads methods
165// are called on is an implementation detail.
nisse72c8d2b2016-04-15 03:49:07 -0700166BEGIN_SIGNALING_PROXY_MAP(RtpReceiver)
Yves Gerey665174f2018-06-19 15:03:05 +0200167PROXY_SIGNALING_THREAD_DESTRUCTOR()
168PROXY_CONSTMETHOD0(rtc::scoped_refptr<MediaStreamTrackInterface>, track)
Harald Alvestrand4a7b3ac2019-01-17 10:39:40 +0100169PROXY_CONSTMETHOD0(rtc::scoped_refptr<DtlsTransportInterface>, dtls_transport)
Henrik Boström5b147782018-12-04 11:25:05 +0100170PROXY_CONSTMETHOD0(std::vector<std::string>, stream_ids)
Yves Gerey665174f2018-06-19 15:03:05 +0200171PROXY_CONSTMETHOD0(std::vector<rtc::scoped_refptr<MediaStreamInterface>>,
172 streams)
173PROXY_CONSTMETHOD0(cricket::MediaType, media_type)
174PROXY_CONSTMETHOD0(std::string, id)
Nico Weber22f99252019-02-20 10:13:16 -0500175PROXY_CONSTMETHOD0(RtpParameters, GetParameters)
Yves Gerey665174f2018-06-19 15:03:05 +0200176PROXY_METHOD1(bool, SetParameters, const RtpParameters&)
Nico Weber22f99252019-02-20 10:13:16 -0500177PROXY_METHOD1(void, SetObserver, RtpReceiverObserverInterface*)
Ruslan Burakov4bac79e2019-04-03 19:55:33 +0200178PROXY_METHOD1(void, SetJitterBufferMinimumDelay, absl::optional<double>)
Nico Weber22f99252019-02-20 10:13:16 -0500179PROXY_CONSTMETHOD0(std::vector<RtpSource>, GetSources)
Benjamin Wrightd81ac952018-08-29 17:02:10 -0700180PROXY_METHOD1(void,
181 SetFrameDecryptor,
Nico Weber22f99252019-02-20 10:13:16 -0500182 rtc::scoped_refptr<FrameDecryptorInterface>)
Benjamin Wrightd81ac952018-08-29 17:02:10 -0700183PROXY_CONSTMETHOD0(rtc::scoped_refptr<FrameDecryptorInterface>,
Nico Weber22f99252019-02-20 10:13:16 -0500184 GetFrameDecryptor)
Yves Gerey665174f2018-06-19 15:03:05 +0200185END_PROXY_MAP()
deadbeef70ab1a12015-09-28 16:53:55 -0700186
187} // namespace webrtc
188
Steve Anton10542f22019-01-11 09:11:00 -0800189#endif // API_RTP_RECEIVER_INTERFACE_H_