stream_params.h (12650B)
1 /* 2 * Copyright (c) 2011 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 // This file contains structures for describing SSRCs from a media source such 12 // as a MediaStreamTrack when it is sent across an RTP session. Multiple media 13 // sources may be sent across the same RTP session, each of them will be 14 // described by one StreamParams object 15 // SsrcGroup is used to describe the relationship between the SSRCs that 16 // are used for this media source. 17 // E.x: Consider a source that is sent as 3 simulcast streams 18 // Let the simulcast elements have SSRC 10, 20, 30. 19 // Let each simulcast element use FEC and let the protection packets have 20 // SSRC 11,21,31. 21 // To describe this 4 SsrcGroups are needed, 22 // StreamParams would then contain ssrc = {10,11,20,21,30,31} and 23 // ssrc_groups = {{SIM,{10,20,30}, {FEC,{10,11}, {FEC, {20,21}, {FEC {30,31}}} 24 // Please see RFC 5576. 25 // A spec-compliant way to achieve this is to use RIDs and Simulcast attribute 26 // instead of the ssrc-group. In this method, the StreamParam object will 27 // have multiple RidDescriptions, each corresponding to a simulcast layer 28 // and the media section will have a simulcast attribute that indicates 29 // that these layers are for the same source. This also removes the extra 30 // lines for redundancy streams, as the same RIDs appear in the redundancy 31 // packets. 32 // Note: in the spec compliant simulcast scenario, some of the RIDs might be 33 // alternatives for one another (such as different encodings for same data). 34 // In the context of the StreamParams class, the notion of alternatives does 35 // not exist and all the RIDs will describe different layers of the same source. 36 // When the StreamParams class is used to configure the media engine, simulcast 37 // considerations will be used to remove the alternative layers outside of this 38 // class. 39 // As an example, let the simulcast layers have RID 10, 20, 30. 40 // StreamParams would contain rid = { 10, 20, 30 }. 41 // MediaSection would contain SimulcastDescription specifying these rids. 42 // a=simulcast:send 10;20;30 (or a=simulcast:send 10,20;30 or similar). 43 // See https://tools.ietf.org/html/draft-ietf-mmusic-sdp-simulcast-13 44 // and https://tools.ietf.org/html/draft-ietf-mmusic-rid-15. 45 46 #ifndef MEDIA_BASE_STREAM_PARAMS_H_ 47 #define MEDIA_BASE_STREAM_PARAMS_H_ 48 49 #include <stddef.h> 50 51 #include <cstdint> 52 #include <string> 53 #include <vector> 54 55 #include "absl/algorithm/container.h" 56 #include "media/base/rid_description.h" 57 #include "rtc_base/unique_id_generator.h" 58 59 namespace webrtc { 60 61 extern const char kFecSsrcGroupSemantics[]; 62 extern const char kFecFrSsrcGroupSemantics[]; 63 extern const char kFidSsrcGroupSemantics[]; 64 extern const char kSimSsrcGroupSemantics[]; 65 66 struct SsrcGroup { 67 SsrcGroup(const std::string& usage, const std::vector<uint32_t>& ssrcs); 68 SsrcGroup(const SsrcGroup&); 69 SsrcGroup(SsrcGroup&&); 70 ~SsrcGroup(); 71 SsrcGroup& operator=(const SsrcGroup&); 72 SsrcGroup& operator=(SsrcGroup&&); 73 74 bool operator==(const SsrcGroup& other) const { 75 return (semantics == other.semantics && ssrcs == other.ssrcs); 76 } 77 bool operator!=(const SsrcGroup& other) const { return !(*this == other); } 78 79 bool has_semantics(const std::string& semantics) const; 80 81 std::string ToString() const; 82 83 std::string semantics; // e.g FID, FEC-FR, SIM. 84 std::vector<uint32_t> ssrcs; // SSRCs of this type. 85 }; 86 87 // StreamParams is used to represent a sender/track in a SessionDescription. 88 // In Plan B, this means that multiple StreamParams can exist within one 89 // MediaContentDescription, while in UnifiedPlan this means that there is one 90 // StreamParams per MediaContentDescription. 91 struct StreamParams { 92 StreamParams(); 93 StreamParams(const StreamParams&); 94 StreamParams(StreamParams&&); 95 ~StreamParams(); 96 StreamParams& operator=(const StreamParams&); 97 StreamParams& operator=(StreamParams&&); 98 99 static StreamParams CreateLegacy(uint32_t ssrc) { 100 StreamParams stream; 101 stream.ssrcs.push_back(ssrc); 102 return stream; 103 } 104 105 bool operator==(const StreamParams& other) const; 106 bool operator!=(const StreamParams& other) const { return !(*this == other); } 107 108 uint32_t first_ssrc() const { 109 if (ssrcs.empty()) { 110 return 0; 111 } 112 113 return ssrcs[0]; 114 } 115 bool has_ssrcs() const { return !ssrcs.empty(); } 116 bool has_ssrc(uint32_t ssrc) const { 117 return absl::c_linear_search(ssrcs, ssrc); 118 } 119 void add_ssrc(uint32_t ssrc) { ssrcs.push_back(ssrc); } 120 bool has_ssrc_groups() const { return !ssrc_groups.empty(); } 121 bool has_ssrc_group(const std::string& semantics) const { 122 return (get_ssrc_group(semantics) != NULL); 123 } 124 const SsrcGroup* get_ssrc_group(const std::string& semantics) const { 125 for (const SsrcGroup& ssrc_group : ssrc_groups) { 126 if (ssrc_group.has_semantics(semantics)) { 127 return &ssrc_group; 128 } 129 } 130 return NULL; 131 } 132 133 // Convenience function to add an FID ssrc for a primary_ssrc 134 // that's already been added. 135 bool AddFidSsrc(uint32_t primary_ssrc, uint32_t fid_ssrc) { 136 return AddSecondarySsrc(kFidSsrcGroupSemantics, primary_ssrc, fid_ssrc); 137 } 138 139 // Convenience function to lookup the FID ssrc for a primary_ssrc. 140 // Returns false if primary_ssrc not found or FID not defined for it. 141 bool GetFidSsrc(uint32_t primary_ssrc, uint32_t* fid_ssrc) const { 142 return GetSecondarySsrc(kFidSsrcGroupSemantics, primary_ssrc, fid_ssrc); 143 } 144 145 // Convenience function to add an FEC-FR ssrc for a primary_ssrc 146 // that's already been added. 147 bool AddFecFrSsrc(uint32_t primary_ssrc, uint32_t fecfr_ssrc) { 148 return AddSecondarySsrc(kFecFrSsrcGroupSemantics, primary_ssrc, fecfr_ssrc); 149 } 150 151 // Convenience function to lookup the FEC-FR ssrc for a primary_ssrc. 152 // Returns false if primary_ssrc not found or FEC-FR not defined for it. 153 bool GetFecFrSsrc(uint32_t primary_ssrc, uint32_t* fecfr_ssrc) const { 154 return GetSecondarySsrc(kFecFrSsrcGroupSemantics, primary_ssrc, fecfr_ssrc); 155 } 156 157 // Convenience function to populate the StreamParams with the requested number 158 // of SSRCs along with accompanying FID and FEC-FR ssrcs if requested. 159 // SSRCs are generated using the given generator. 160 void GenerateSsrcs(int num_layers, 161 bool generate_fid, 162 bool generate_fec_fr, 163 UniqueRandomIdGenerator* ssrc_generator); 164 165 // Convenience to get all the SIM SSRCs if there are SIM ssrcs, or 166 // the first SSRC otherwise. 167 void GetPrimarySsrcs(std::vector<uint32_t>* primary_ssrcs) const; 168 169 // Convenience to get all the secondary SSRCs for the given primary ssrcs 170 // of a particular semantic. 171 // If a given primary SSRC does not have a secondary SSRC, the list of 172 // secondary SSRCS will be smaller than the list of primary SSRCs. 173 void GetSecondarySsrcs(const std::string& semantic, 174 const std::vector<uint32_t>& primary_ssrcs, 175 std::vector<uint32_t>* fid_ssrcs) const; 176 177 // Convenience to get all the FID SSRCs for the given primary ssrcs. 178 // If a given primary SSRC does not have a FID SSRC, the list of FID 179 // SSRCS will be smaller than the list of primary SSRCs. 180 void GetFidSsrcs(const std::vector<uint32_t>& primary_ssrcs, 181 std::vector<uint32_t>* fid_ssrcs) const; 182 183 // Stream ids serialized to SDP. 184 std::vector<std::string> stream_ids() const; 185 void set_stream_ids(const std::vector<std::string>& stream_ids); 186 187 // Returns the first stream id or "" if none exist. This method exists only 188 // as temporary backwards compatibility with the old sync_label. 189 std::string first_stream_id() const; 190 191 std::string ToString() const; 192 193 // A unique identifier of the StreamParams object. When the SDP is created, 194 // this comes from the track ID of the sender that the StreamParams object 195 // is associated with. 196 std::string id; 197 // There may be no SSRCs stored in unsignaled case when stream_ids are 198 // signaled with a=msid lines. 199 std::vector<uint32_t> ssrcs; // All SSRCs for this source 200 std::vector<SsrcGroup> ssrc_groups; // e.g. FID, FEC, SIM 201 std::string cname; // RTCP CNAME 202 203 // RID functionality according to 204 // https://tools.ietf.org/html/draft-ietf-mmusic-rid-15 205 // Each layer can be represented by a RID identifier and can also have 206 // restrictions (such as max-width, max-height, etc.) 207 // If the track has multiple layers (ex. Simulcast), each layer will be 208 // represented by a RID. 209 bool has_rids() const { return !rids_.empty(); } 210 const std::vector<RidDescription>& rids() const { return rids_; } 211 void set_rids(const std::vector<RidDescription>& rids) { rids_ = rids; } 212 213 private: 214 bool AddSecondarySsrc(const std::string& semantics, 215 uint32_t primary_ssrc, 216 uint32_t secondary_ssrc); 217 bool GetSecondarySsrc(const std::string& semantics, 218 uint32_t primary_ssrc, 219 uint32_t* secondary_ssrc) const; 220 221 // The stream IDs of the sender that the StreamParams object is associated 222 // with. In Plan B this should always be size of 1, while in Unified Plan this 223 // could be none or multiple stream IDs. 224 std::vector<std::string> stream_ids_; 225 226 std::vector<RidDescription> rids_; 227 }; 228 229 // A Stream can be selected by either id or ssrc. 230 struct StreamSelector { 231 explicit StreamSelector(uint32_t ssrc) : ssrc(ssrc) {} 232 233 explicit StreamSelector(const std::string& streamid) 234 : ssrc(0), streamid(streamid) {} 235 236 bool Matches(const StreamParams& stream) const { 237 if (ssrc == 0) { 238 return stream.id == streamid; 239 } else { 240 return stream.has_ssrc(ssrc); 241 } 242 } 243 244 uint32_t ssrc; 245 std::string streamid; 246 }; 247 248 typedef std::vector<StreamParams> StreamParamsVec; 249 250 template <class Condition> 251 const StreamParams* GetStream(const StreamParamsVec& streams, 252 Condition condition) { 253 auto found = absl::c_find_if(streams, condition); 254 return found == streams.end() ? nullptr : &(*found); 255 } 256 257 template <class Condition> 258 StreamParams* GetStream(StreamParamsVec& streams, Condition condition) { 259 auto found = absl::c_find_if(streams, condition); 260 return found == streams.end() ? nullptr : &(*found); 261 } 262 263 inline bool HasStreamWithNoSsrcs(const StreamParamsVec& streams) { 264 return GetStream(streams, 265 [](const StreamParams& sp) { return !sp.has_ssrcs(); }); 266 } 267 268 inline const StreamParams* GetStreamBySsrc(const StreamParamsVec& streams, 269 uint32_t ssrc) { 270 return GetStream( 271 streams, [&ssrc](const StreamParams& sp) { return sp.has_ssrc(ssrc); }); 272 } 273 274 inline const StreamParams* GetStreamByIds(const StreamParamsVec& streams, 275 const std::string& id) { 276 return GetStream(streams, 277 [&id](const StreamParams& sp) { return sp.id == id; }); 278 } 279 280 inline StreamParams* GetStreamByIds(StreamParamsVec& streams, 281 const std::string& id) { 282 return GetStream(streams, 283 [&id](const StreamParams& sp) { return sp.id == id; }); 284 } 285 286 inline const StreamParams* GetStream(const StreamParamsVec& streams, 287 const StreamSelector& selector) { 288 return GetStream(streams, [&selector](const StreamParams& sp) { 289 return selector.Matches(sp); 290 }); 291 } 292 293 template <class Condition> 294 bool RemoveStream(StreamParamsVec* streams, Condition condition) { 295 auto iter(std::remove_if(streams->begin(), streams->end(), condition)); 296 if (iter == streams->end()) 297 return false; 298 streams->erase(iter, streams->end()); 299 return true; 300 } 301 302 // Removes the stream from streams. Returns true if a stream is 303 // found and removed. 304 inline bool RemoveStream(StreamParamsVec* streams, 305 const StreamSelector& selector) { 306 return RemoveStream(streams, [&selector](const StreamParams& sp) { 307 return selector.Matches(sp); 308 }); 309 } 310 inline bool RemoveStreamBySsrc(StreamParamsVec* streams, uint32_t ssrc) { 311 return RemoveStream( 312 streams, [&ssrc](const StreamParams& sp) { return sp.has_ssrc(ssrc); }); 313 } 314 inline bool RemoveStreamByIds(StreamParamsVec* streams, const std::string& id) { 315 return RemoveStream(streams, 316 [&id](const StreamParams& sp) { return sp.id == id; }); 317 } 318 319 } // namespace webrtc 320 321 322 #endif // MEDIA_BASE_STREAM_PARAMS_H_