1 /*
2  * libjingle
3  * Copyright 2011 Google Inc.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions are met:
7  *
8  *  1. Redistributions of source code must retain the above copyright notice,
9  *     this list of conditions and the following disclaimer.
10  *  2. Redistributions in binary form must reproduce the above copyright notice,
11  *     this list of conditions and the following disclaimer in the documentation
12  *     and/or other materials provided with the distribution.
13  *  3. The name of the author may not be used to endorse or promote products
14  *     derived from this software without specific prior written permission.
15  *
16  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
17  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
18  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
19  * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
20  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
21  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
22  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
23  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
24  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
25  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26  */
27 
28 // This file contains structures for describing SSRCs from a media source such
29 // as a MediaStreamTrack when it is sent across an RTP session. Multiple media
30 // sources may be sent across the same RTP session, each of them will be
31 // described by one StreamParams object
32 // SsrcGroup is used to describe the relationship between the SSRCs that
33 // are used for this media source.
34 // E.x: Consider a source that is sent as 3 simulcast streams
35 // Let the simulcast elements have SSRC 10, 20, 30.
36 // Let each simulcast element use FEC and let the protection packets have
37 // SSRC 11,21,31.
38 // To describe this 4 SsrcGroups are needed,
39 // StreamParams would then contain ssrc = {10,11,20,21,30,31} and
40 // ssrc_groups = {{SIM,{10,20,30}, {FEC,{10,11}, {FEC, {20,21}, {FEC {30,31}}}
41 // Please see RFC 5576.
42 
43 #ifndef TALK_MEDIA_BASE_STREAMPARAMS_H_
44 #define TALK_MEDIA_BASE_STREAMPARAMS_H_
45 
46 #include <algorithm>
47 #include <set>
48 #include <string>
49 #include <vector>
50 
51 #include "webrtc/base/basictypes.h"
52 #include "webrtc/base/constructormagic.h"
53 
54 namespace cricket {
55 
56 extern const char kFecSsrcGroupSemantics[];
57 extern const char kFidSsrcGroupSemantics[];
58 extern const char kSimSsrcGroupSemantics[];
59 
60 struct SsrcGroup {
SsrcGroupSsrcGroup61   SsrcGroup(const std::string& usage, const std::vector<uint32_t>& ssrcs)
62       : semantics(usage), ssrcs(ssrcs) {}
63 
64   bool operator==(const SsrcGroup& other) const {
65     return (semantics == other.semantics && ssrcs == other.ssrcs);
66   }
67   bool operator!=(const SsrcGroup &other) const {
68     return !(*this == other);
69   }
70 
71   bool has_semantics(const std::string& semantics) const;
72 
73   std::string ToString() const;
74 
75   std::string semantics;  // e.g FIX, FEC, SIM.
76   std::vector<uint32_t> ssrcs;  // SSRCs of this type.
77 };
78 
79 struct StreamParams {
CreateLegacyStreamParams80   static StreamParams CreateLegacy(uint32_t ssrc) {
81     StreamParams stream;
82     stream.ssrcs.push_back(ssrc);
83     return stream;
84   }
85 
86   bool operator==(const StreamParams& other) const {
87     return (groupid == other.groupid &&
88             id == other.id &&
89             ssrcs == other.ssrcs &&
90             ssrc_groups == other.ssrc_groups &&
91             type == other.type &&
92             display == other.display &&
93             cname == other.cname &&
94             sync_label == other.sync_label);
95   }
96   bool operator!=(const StreamParams &other) const {
97     return !(*this == other);
98   }
99 
first_ssrcStreamParams100   uint32_t first_ssrc() const {
101     if (ssrcs.empty()) {
102       return 0;
103     }
104 
105     return ssrcs[0];
106   }
has_ssrcsStreamParams107   bool has_ssrcs() const {
108     return !ssrcs.empty();
109   }
has_ssrcStreamParams110   bool has_ssrc(uint32_t ssrc) const {
111     return std::find(ssrcs.begin(), ssrcs.end(), ssrc) != ssrcs.end();
112   }
add_ssrcStreamParams113   void add_ssrc(uint32_t ssrc) { ssrcs.push_back(ssrc); }
has_ssrc_groupsStreamParams114   bool has_ssrc_groups() const {
115     return !ssrc_groups.empty();
116   }
has_ssrc_groupStreamParams117   bool has_ssrc_group(const std::string& semantics) const {
118     return (get_ssrc_group(semantics) != NULL);
119   }
get_ssrc_groupStreamParams120   const SsrcGroup* get_ssrc_group(const std::string& semantics) const {
121     for (std::vector<SsrcGroup>::const_iterator it = ssrc_groups.begin();
122          it != ssrc_groups.end(); ++it) {
123       if (it->has_semantics(semantics)) {
124         return &(*it);
125       }
126     }
127     return NULL;
128   }
129 
130   // Convenience function to add an FID ssrc for a primary_ssrc
131   // that's already been added.
AddFidSsrcStreamParams132   inline bool AddFidSsrc(uint32_t primary_ssrc, uint32_t fid_ssrc) {
133     return AddSecondarySsrc(kFidSsrcGroupSemantics, primary_ssrc, fid_ssrc);
134   }
135 
136   // Convenience function to lookup the FID ssrc for a primary_ssrc.
137   // Returns false if primary_ssrc not found or FID not defined for it.
GetFidSsrcStreamParams138   inline bool GetFidSsrc(uint32_t primary_ssrc, uint32_t* fid_ssrc) const {
139     return GetSecondarySsrc(kFidSsrcGroupSemantics, primary_ssrc, fid_ssrc);
140   }
141 
142   // Convenience to get all the SIM SSRCs if there are SIM ssrcs, or
143   // the first SSRC otherwise.
144   void GetPrimarySsrcs(std::vector<uint32_t>* ssrcs) const;
145 
146   // Convenience to get all the FID SSRCs for the given primary ssrcs.
147   // If a given primary SSRC does not have a FID SSRC, the list of FID
148   // SSRCS will be smaller than the list of primary SSRCs.
149   void GetFidSsrcs(const std::vector<uint32_t>& primary_ssrcs,
150                    std::vector<uint32_t>* fid_ssrcs) const;
151 
152   std::string ToString() const;
153 
154   // Resource of the MUC jid of the participant of with this stream.
155   // For 1:1 calls, should be left empty (which means remote streams
156   // and local streams should not be mixed together).
157   std::string groupid;
158   // Unique per-groupid, not across all groupids
159   std::string id;
160   std::vector<uint32_t> ssrcs;         // All SSRCs for this source
161   std::vector<SsrcGroup> ssrc_groups;  // e.g. FID, FEC, SIM
162   // Examples: "camera", "screencast"
163   std::string type;
164   // Friendly name describing stream
165   std::string display;
166   std::string cname;  // RTCP CNAME
167   std::string sync_label;  // Friendly name of cname.
168 
169  private:
170   bool AddSecondarySsrc(const std::string& semantics,
171                         uint32_t primary_ssrc,
172                         uint32_t secondary_ssrc);
173   bool GetSecondarySsrc(const std::string& semantics,
174                         uint32_t primary_ssrc,
175                         uint32_t* secondary_ssrc) const;
176 };
177 
178 // A Stream can be selected by either groupid+id or ssrc.
179 struct StreamSelector {
StreamSelectorStreamSelector180   explicit StreamSelector(uint32_t ssrc) : ssrc(ssrc) {}
181 
StreamSelectorStreamSelector182   StreamSelector(const std::string& groupid,
183                  const std::string& streamid) :
184       ssrc(0),
185       groupid(groupid),
186       streamid(streamid) {
187   }
188 
MatchesStreamSelector189   bool Matches(const StreamParams& stream) const {
190     if (ssrc == 0) {
191       return stream.groupid == groupid && stream.id == streamid;
192     } else {
193       return stream.has_ssrc(ssrc);
194     }
195   }
196 
197   uint32_t ssrc;
198   std::string groupid;
199   std::string streamid;
200 };
201 
202 typedef std::vector<StreamParams> StreamParamsVec;
203 
204 // A collection of audio and video and data streams. Most of the
205 // methods are merely for convenience. Many of these methods are keyed
206 // by ssrc, which is the source identifier in the RTP spec
207 // (http://tools.ietf.org/html/rfc3550).
208 // TODO(pthatcher):  Add basic unit test for these.
209 // See https://code.google.com/p/webrtc/issues/detail?id=4107
210 struct MediaStreams {
211  public:
MediaStreamsMediaStreams212   MediaStreams() {}
213   void CopyFrom(const MediaStreams& sources);
214 
emptyMediaStreams215   bool empty() const {
216     return audio_.empty() && video_.empty() && data_.empty();
217   }
218 
mutable_audioMediaStreams219   std::vector<StreamParams>* mutable_audio() { return &audio_; }
mutable_videoMediaStreams220   std::vector<StreamParams>* mutable_video() { return &video_; }
mutable_dataMediaStreams221   std::vector<StreamParams>* mutable_data() { return &data_; }
audioMediaStreams222   const std::vector<StreamParams>& audio() const { return audio_; }
videoMediaStreams223   const std::vector<StreamParams>& video() const { return video_; }
dataMediaStreams224   const std::vector<StreamParams>& data() const { return data_; }
225 
226   // Gets a stream, returning true if found.
227   bool GetAudioStream(
228       const StreamSelector& selector, StreamParams* stream);
229   bool GetVideoStream(
230       const StreamSelector& selector, StreamParams* stream);
231   bool GetDataStream(
232       const StreamSelector& selector, StreamParams* stream);
233   // Adds a stream.
234   void AddAudioStream(const StreamParams& stream);
235   void AddVideoStream(const StreamParams& stream);
236   void AddDataStream(const StreamParams& stream);
237   // Removes a stream, returning true if found and removed.
238   bool RemoveAudioStream(const StreamSelector& selector);
239   bool RemoveVideoStream(const StreamSelector& selector);
240   bool RemoveDataStream(const StreamSelector& selector);
241 
242  private:
243   std::vector<StreamParams> audio_;
244   std::vector<StreamParams> video_;
245   std::vector<StreamParams> data_;
246 
247   RTC_DISALLOW_COPY_AND_ASSIGN(MediaStreams);
248 };
249 
250 // A request for a specific format of a specific stream.
251 struct StaticVideoView {
StaticVideoViewStaticVideoView252   StaticVideoView(const StreamSelector& selector,
253                   int width, int height, int framerate)
254       : selector(selector),
255         width(width),
256         height(height),
257         framerate(framerate),
258         preference(0) {
259   }
260 
261   StreamSelector selector;
262   int width;
263   int height;
264   int framerate;
265   int preference;
266 };
267 
268 typedef std::vector<StaticVideoView> StaticVideoViews;
269 
270 // A request for several streams in various formats.
271 struct ViewRequest {
272   StaticVideoViews static_video_views;
273 };
274 
275 template <class Condition>
GetStream(const StreamParamsVec & streams,Condition condition)276 const StreamParams* GetStream(const StreamParamsVec& streams,
277                               Condition condition) {
278   StreamParamsVec::const_iterator found =
279       std::find_if(streams.begin(), streams.end(), condition);
280   return found == streams.end() ? nullptr : &(*found);
281 }
282 
GetStreamBySsrc(const StreamParamsVec & streams,uint32_t ssrc)283 inline const StreamParams* GetStreamBySsrc(const StreamParamsVec& streams,
284                                            uint32_t ssrc) {
285   return GetStream(streams,
286       [&ssrc](const StreamParams& sp) { return sp.has_ssrc(ssrc); });
287 }
288 
GetStreamByIds(const StreamParamsVec & streams,const std::string & groupid,const std::string & id)289 inline const StreamParams* GetStreamByIds(const StreamParamsVec& streams,
290                                           const std::string& groupid,
291                                           const std::string& id) {
292   return GetStream(streams,
293       [&groupid, &id](const StreamParams& sp) {
294         return sp.groupid == groupid && sp.id == id;
295       });
296 }
297 
GetStream(const StreamParamsVec & streams,const StreamSelector & selector)298 inline const StreamParams* GetStream(const StreamParamsVec& streams,
299                                      const StreamSelector& selector) {
300   return GetStream(streams,
301       [&selector](const StreamParams& sp) { return selector.Matches(sp); });
302 }
303 
304 template <class Condition>
RemoveStream(StreamParamsVec * streams,Condition condition)305 bool RemoveStream(StreamParamsVec* streams, Condition condition) {
306   auto iter(std::remove_if(streams->begin(), streams->end(), condition));
307   if (iter == streams->end())
308     return false;
309   streams->erase(iter, streams->end());
310   return true;
311 }
312 
313 // Removes the stream from streams. Returns true if a stream is
314 // found and removed.
RemoveStream(StreamParamsVec * streams,const StreamSelector & selector)315 inline bool RemoveStream(StreamParamsVec* streams,
316                   const StreamSelector& selector) {
317   return RemoveStream(streams,
318       [&selector](const StreamParams& sp) { return selector.Matches(sp); });
319 }
RemoveStreamBySsrc(StreamParamsVec * streams,uint32_t ssrc)320 inline bool RemoveStreamBySsrc(StreamParamsVec* streams, uint32_t ssrc) {
321   return RemoveStream(streams,
322       [&ssrc](const StreamParams& sp) { return sp.has_ssrc(ssrc); });
323 }
RemoveStreamByIds(StreamParamsVec * streams,const std::string & groupid,const std::string & id)324 inline bool RemoveStreamByIds(StreamParamsVec* streams,
325                               const std::string& groupid,
326                               const std::string& id) {
327   return RemoveStream(streams,
328       [&groupid, &id](const StreamParams& sp) {
329         return sp.groupid == groupid && sp.id == id;
330       });
331 }
332 
333 // Checks if |sp| defines parameters for a single primary stream. There may
334 // be an RTX stream associated with the primary stream. Leaving as non-static so
335 // we can test this function.
336 bool IsOneSsrcStream(const StreamParams& sp);
337 
338 // Checks if |sp| defines parameters for one Simulcast stream. There may be RTX
339 // streams associated with the simulcast streams. Leaving as non-static so we
340 // can test this function.
341 bool IsSimulcastStream(const StreamParams& sp);
342 
343 }  // namespace cricket
344 
345 #endif  // TALK_MEDIA_BASE_STREAMPARAMS_H_
346