1 /*
2  *  Copyright (c) 2017 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_RTP_HEADERS_H_
12 #define API_RTP_HEADERS_H_
13 
14 #include <stddef.h>
15 #include <stdint.h>
16 
17 #include <string>
18 
19 #include "absl/types/optional.h"
20 #include "api/array_view.h"
21 #include "api/units/timestamp.h"
22 #include "api/video/color_space.h"
23 #include "api/video/video_content_type.h"
24 #include "api/video/video_rotation.h"
25 #include "api/video/video_timing.h"
26 #include "common_types.h"  // NOLINT (build/include)
27 
28 namespace webrtc {
29 
30 struct FeedbackRequest {
31   // Determines whether the recv delta as specified in
32   // https://tools.ietf.org/html/draft-holmer-rmcat-transport-wide-cc-extensions-01
33   // should be included.
34   bool include_timestamps;
35   // Include feedback of received packets in the range [sequence_number -
36   // sequence_count + 1, sequence_number]. That is, no feedback will be sent if
37   // sequence_count is zero.
38   int sequence_count;
39 };
40 
41 // The Absolute Capture Time extension is used to stamp RTP packets with a NTP
42 // timestamp showing when the first audio or video frame in a packet was
43 // originally captured. The intent of this extension is to provide a way to
44 // accomplish audio-to-video synchronization when RTCP-terminating intermediate
45 // systems (e.g. mixers) are involved. See:
46 // http://www.webrtc.org/experiments/rtp-hdrext/abs-capture-time
47 struct AbsoluteCaptureTime {
48   // Absolute capture timestamp is the NTP timestamp of when the first frame in
49   // a packet was originally captured. This timestamp MUST be based on the same
50   // clock as the clock used to generate NTP timestamps for RTCP sender reports
51   // on the capture system.
52   //
53   // It’s not always possible to do an NTP clock readout at the exact moment of
54   // when a media frame is captured. A capture system MAY postpone the readout
55   // until a more convenient time. A capture system SHOULD have known delays
56   // (e.g. from hardware buffers) subtracted from the readout to make the final
57   // timestamp as close to the actual capture time as possible.
58   //
59   // This field is encoded as a 64-bit unsigned fixed-point number with the high
60   // 32 bits for the timestamp in seconds and low 32 bits for the fractional
61   // part. This is also known as the UQ32.32 format and is what the RTP
62   // specification defines as the canonical format to represent NTP timestamps.
63   uint64_t absolute_capture_timestamp;
64 
65   // Estimated capture clock offset is the sender’s estimate of the offset
66   // between its own NTP clock and the capture system’s NTP clock. The sender is
67   // here defined as the system that owns the NTP clock used to generate the NTP
68   // timestamps for the RTCP sender reports on this stream. The sender system is
69   // typically either the capture system or a mixer.
70   //
71   // This field is encoded as a 64-bit two’s complement signed fixed-point
72   // number with the high 32 bits for the seconds and low 32 bits for the
73   // fractional part. It’s intended to make it easy for a receiver, that knows
74   // how to estimate the sender system’s NTP clock, to also estimate the capture
75   // system’s NTP clock:
76   //
77   //   Capture NTP Clock = Sender NTP Clock + Capture Clock Offset
78   absl::optional<int64_t> estimated_capture_clock_offset;
79 };
80 
81 inline bool operator==(const AbsoluteCaptureTime& lhs,
82                        const AbsoluteCaptureTime& rhs) {
83   return (lhs.absolute_capture_timestamp == rhs.absolute_capture_timestamp) &&
84          (lhs.estimated_capture_clock_offset ==
85           rhs.estimated_capture_clock_offset);
86 }
87 
88 inline bool operator!=(const AbsoluteCaptureTime& lhs,
89                        const AbsoluteCaptureTime& rhs) {
90   return !(lhs == rhs);
91 }
92 
93 struct RTPHeaderExtension {
94   RTPHeaderExtension();
95   RTPHeaderExtension(const RTPHeaderExtension& other);
96   RTPHeaderExtension& operator=(const RTPHeaderExtension& other);
97 
98   static constexpr int kAbsSendTimeFraction = 18;
99 
GetAbsoluteSendTimestampRTPHeaderExtension100   Timestamp GetAbsoluteSendTimestamp() const {
101     RTC_DCHECK(hasAbsoluteSendTime);
102     RTC_DCHECK(absoluteSendTime < (1ul << 24));
103     return Timestamp::Micros((absoluteSendTime * 1000000ll) /
104                              (1 << kAbsSendTimeFraction));
105   }
106 
GetAbsoluteSendTimeDeltaRTPHeaderExtension107   TimeDelta GetAbsoluteSendTimeDelta(uint32_t previous_sendtime) const {
108     RTC_DCHECK(hasAbsoluteSendTime);
109     RTC_DCHECK(absoluteSendTime < (1ul << 24));
110     RTC_DCHECK(previous_sendtime < (1ul << 24));
111     int32_t delta =
112         static_cast<int32_t>((absoluteSendTime - previous_sendtime) << 8) >> 8;
113     return TimeDelta::Micros((delta * 1000000ll) / (1 << kAbsSendTimeFraction));
114   }
115 
116   bool hasTransmissionTimeOffset;
117   int32_t transmissionTimeOffset;
118   bool hasAbsoluteSendTime;
119   uint32_t absoluteSendTime;
120   absl::optional<AbsoluteCaptureTime> absolute_capture_time;
121   bool hasTransportSequenceNumber;
122   uint16_t transportSequenceNumber;
123   absl::optional<FeedbackRequest> feedback_request;
124 
125   // Audio Level includes both level in dBov and voiced/unvoiced bit. See:
126   // https://tools.ietf.org/html/rfc6464#section-3
127   bool hasAudioLevel;
128   bool voiceActivity;
129   uint8_t audioLevel;
130 
131   // For Coordination of Video Orientation. See
132   // http://www.etsi.org/deliver/etsi_ts/126100_126199/126114/12.07.00_60/
133   // ts_126114v120700p.pdf
134   bool hasVideoRotation;
135   VideoRotation videoRotation;
136 
137   // TODO(ilnik): Refactor this and one above to be absl::optional() and remove
138   // a corresponding bool flag.
139   bool hasVideoContentType;
140   VideoContentType videoContentType;
141 
142   bool has_video_timing;
143   VideoSendTiming video_timing;
144 
145   PlayoutDelay playout_delay = {-1, -1};
146 
147   // For identification of a stream when ssrc is not signaled. See
148   // https://tools.ietf.org/html/draft-ietf-avtext-rid-09
149   // TODO(danilchap): Update url from draft to release version.
150   std::string stream_id;
151   std::string repaired_stream_id;
152 
153   // For identifying the media section used to interpret this RTP packet. See
154   // https://tools.ietf.org/html/draft-ietf-mmusic-sdp-bundle-negotiation-38
155   std::string mid;
156 
157   absl::optional<ColorSpace> color_space;
158 };
159 
160 enum { kRtpCsrcSize = 15 };  // RFC 3550 page 13
161 
162 struct RTPHeader {
163   RTPHeader();
164   RTPHeader(const RTPHeader& other);
165   RTPHeader& operator=(const RTPHeader& other);
166 
167   bool markerBit;
168   uint8_t payloadType;
169   uint16_t sequenceNumber;
170   uint32_t timestamp;
171   uint32_t ssrc;
172   uint8_t numCSRCs;
173   uint32_t arrOfCSRCs[kRtpCsrcSize];
174   size_t paddingLength;
175   size_t headerLength;
176   int payload_type_frequency;
177   RTPHeaderExtension extension;
178 };
179 
180 // RTCP mode to use. Compound mode is described by RFC 4585 and reduced-size
181 // RTCP mode is described by RFC 5506.
182 enum class RtcpMode { kOff, kCompound, kReducedSize };
183 
184 enum NetworkState {
185   kNetworkUp,
186   kNetworkDown,
187 };
188 
189 }  // namespace webrtc
190 
191 #endif  // API_RTP_HEADERS_H_
192