DASH Media Packaging SDK
 All Classes Namespaces Functions Variables Typedefs Enumerator
mpd_builder.h
1 // Copyright 2014 Google Inc. All rights reserved.
2 //
3 // Use of this source code is governed by a BSD-style
4 // license that can be found in the LICENSE file or at
5 // https://developers.google.com/open-source/licenses/bsd
6 //
7 // This file contains the MpdBuilder, AdaptationSet, and Representation class
8 // declarations.
9 // http://goo.gl/UrsSlF
10 //
14 
15 #ifndef MPD_BASE_MPD_BUILDER_H_
16 #define MPD_BASE_MPD_BUILDER_H_
17 
18 #include <stdint.h>
19 
20 #include <list>
21 #include <map>
22 #include <set>
23 #include <string>
24 
25 #include "packager/base/atomic_sequence_num.h"
26 #include "packager/base/gtest_prod_util.h"
27 #include "packager/base/stl_util.h"
28 #include "packager/base/synchronization/lock.h"
29 #include "packager/mpd/base/bandwidth_estimator.h"
30 #include "packager/mpd/base/content_protection_element.h"
31 #include "packager/mpd/base/media_info.pb.h"
32 #include "packager/mpd/base/mpd_options.h"
33 #include "packager/mpd/base/segment_info.h"
34 #include "packager/mpd/base/xml/scoped_xml_ptr.h"
35 
36 // TODO(rkuroiwa): For classes with |id_|, consider removing the field and let
37 // the MPD (XML) generation functions take care of assigning an ID to each
38 // element.
39 namespace edash_packager {
40 
41 namespace media {
42 class File;
43 } // namespace media
44 
45 class AdaptationSet;
46 class Representation;
47 
48 namespace xml {
49 
50 class XmlNode;
51 class RepresentationXmlNode;
52 
53 } // namespace xml
54 
56 class MpdBuilder {
57  public:
58  enum MpdType {
59  kStatic = 0,
60  kDynamic
61  };
62 
66  MpdBuilder(MpdType type, const MpdOptions& mpd_options);
67  virtual ~MpdBuilder();
68 
71  void AddBaseUrl(const std::string& base_url);
72 
77  virtual AdaptationSet* AddAdaptationSet(const std::string& lang);
78 
83  bool WriteMpdToFile(media::File* output_file);
84 
88  virtual bool ToString(std::string* output);
89 
91  MpdType type() const { return type_; }
92 
98  static void MakePathsRelativeToMpd(const std::string& mpd_path,
99  MediaInfo* media_info);
100 
101  private:
102  // DynamicMpdBuilderTest needs to set availabilityStartTime so that the test
103  // doesn't need to depend on current time.
104  friend class DynamicMpdBuilderTest;
105 
106  bool ToStringImpl(std::string* output);
107 
108  // This is a helper method for writing out MPDs, called from WriteMpdToFile()
109  // and ToString().
110  template <typename OutputType>
111  bool WriteMpdToOutput(OutputType* output);
112 
113  // Returns the document pointer to the MPD. This must be freed by the caller
114  // using appropriate xmlDocPtr freeing function.
115  // On failure, this returns NULL.
116  xmlDocPtr GenerateMpd();
117 
118  // Set MPD attributes common to all profiles. Uses non-zero |mpd_options_| to
119  // set attributes for the MPD.
120  void AddCommonMpdInfo(xml::XmlNode* mpd_node);
121 
122  // Adds 'static' MPD attributes and elements to |mpd_node|. This assumes that
123  // the first child element is a Period element.
124  void AddStaticMpdInfo(xml::XmlNode* mpd_node);
125 
126  // Same as AddStaticMpdInfo() but for 'dynamic' MPDs.
127  void AddDynamicMpdInfo(xml::XmlNode* mpd_node);
128 
129  float GetStaticMpdDuration(xml::XmlNode* mpd_node);
130 
131  // Set MPD attributes for dynamic profile MPD. Uses non-zero |mpd_options_| as
132  // well as various calculations to set attributes for the MPD.
133  void SetDynamicMpdAttributes(xml::XmlNode* mpd_node);
134 
135  // Gets the earliest, normalized segment timestamp. Returns true if
136  // successful, false otherwise.
137  bool GetEarliestTimestamp(double* timestamp_seconds);
138 
139  MpdType type_;
140  MpdOptions mpd_options_;
141  std::list<AdaptationSet*> adaptation_sets_;
142  ::STLElementDeleter<std::list<AdaptationSet*> > adaptation_sets_deleter_;
143 
144  std::list<std::string> base_urls_;
145  std::string availability_start_time_;
146 
147  base::Lock lock_;
148  base::AtomicSequenceNumber adaptation_set_counter_;
149  base::AtomicSequenceNumber representation_counter_;
150 
151  DISALLOW_COPY_AND_ASSIGN(MpdBuilder);
152 };
153 
157  public:
158  // The role for this AdaptationSet. These values are used to add a Role
159  // element to the AdaptationSet with schemeIdUri=urn:mpeg:dash:role:2011.
160  // See ISO/IEC 23009-1:2012 section 5.8.5.5.
161  enum Role {
162  kRoleCaption,
163  kRoleSubtitle,
164  kRoleMain,
165  kRoleAlternate,
166  kRoleSupplementary,
167  kRoleCommentary,
168  kRoleDub
169  };
170 
171  virtual ~AdaptationSet();
172 
179  virtual Representation* AddRepresentation(const MediaInfo& media_info);
180 
190  virtual void AddContentProtectionElement(
191  const ContentProtectionElement& element);
192 
204  virtual void UpdateContentProtectionPssh(const std::string& drm_uuid,
205  const std::string& pssh);
206 
211  virtual void AddRole(Role role);
212 
217  xml::ScopedXmlPtr<xmlNode>::type GetXml();
218 
224  virtual void ForceSetSegmentAlignment(bool segment_alignment);
225 
231  virtual void SetGroup(int group_number);
232 
234  virtual int Group() const;
235 
236  // Must be unique in the Period.
237  uint32_t id() const { return id_; }
238 
250  void OnNewSegmentForRepresentation(uint32_t representation_id,
251  uint64_t start_time,
252  uint64_t duration);
253 
266  void OnSetFrameRateForRepresentation(uint32_t representation_id,
267  uint32_t frame_duration,
268  uint32_t timescale);
269 
270  protected:
278  AdaptationSet(uint32_t adaptation_set_id,
279  const std::string& lang,
280  const MpdOptions& mpd_options,
281  MpdBuilder::MpdType mpd_type,
282  base::AtomicSequenceNumber* representation_counter);
283 
284  private:
285  friend class MpdBuilder;
286  template <MpdBuilder::MpdType type>
287  friend class MpdBuilderTest;
288 
289  // kSegmentAlignmentUnknown means that it is uncertain if the
290  // (sub)segments are aligned or not.
291  // kSegmentAlignmentTrue means that it is certain that the all the (current)
292  // segments added to the adaptation set are aligned.
293  // kSegmentAlignmentFalse means that it is it is certain that some segments
294  // are not aligned. This is useful to disable the computation for
295  // segment alignment, once it is certain that some segments are not aligned.
296  enum SegmentAligmentStatus {
297  kSegmentAlignmentUnknown,
298  kSegmentAlignmentTrue,
299  kSegmentAlignmentFalse
300  };
301 
302  // This maps Representations (IDs) to a list of start times of the segments.
303  // e.g.
304  // If Representation 1 has start time 0, 100, 200 and Representation 2 has
305  // start times 0, 200, 400, then the map contains:
306  // 1 -> [0, 100, 200]
307  // 2 -> [0, 200, 400]
308  typedef std::map<uint32_t, std::list<uint64_t> > RepresentationTimeline;
309 
310  // Gets the earliest, normalized segment timestamp. Returns true if
311  // successful, false otherwise.
312  bool GetEarliestTimestamp(double* timestamp_seconds);
313 
321  void CheckLiveSegmentAlignment(uint32_t representation_id,
322  uint64_t start_time,
323  uint64_t duration);
324 
325  // Checks representation_segment_start_times_ and sets segments_aligned_.
326  // Use this for VOD, do not use for Live.
327  void CheckVodSegmentAlignment();
328 
329  // Records the framerate of a Representation.
330  void RecordFrameRate(uint32_t frame_duration, uint32_t timescale);
331 
332  std::list<ContentProtectionElement> content_protection_elements_;
333  std::list<Representation*> representations_;
334  ::STLElementDeleter<std::list<Representation*> > representations_deleter_;
335 
336  base::Lock lock_;
337 
338  base::AtomicSequenceNumber* const representation_counter_;
339 
340  const uint32_t id_;
341  const std::string lang_;
342  const MpdOptions& mpd_options_;
343  const MpdBuilder::MpdType mpd_type_;
344 
345  // The group attribute for the AdaptationSet. If the value is negative,
346  // no group number is specified.
347  // Note that group 0 is a special group number.
348  int group_;
349 
350  // Video widths and heights of Representations. Note that this is a set; if
351  // there is only 1 resolution, then @width & @height should be set, otherwise
352  // @maxWidth & @maxHeight should be set for DASH IOP.
353  std::set<uint32_t> video_widths_;
354  std::set<uint32_t> video_heights_;
355 
356  // Video representations' frame rates.
357  // The frame rate notation for MPD is <integer>/<integer> (where the
358  // denominator is optional). This means the frame rate could be non-whole
359  // rational value, therefore the key is of type double.
360  // Value is <integer>/<integer> in string form.
361  // So, key == CalculatedValue(value)
362  std::map<double, std::string> video_frame_rates_;
363 
364  // contentType attribute of AdaptationSet.
365  // Determined by examining the MediaInfo passed to AddRepresentation().
366  std::string content_type_;
367 
368  // This does not have to be a set, it could be a list or vector because all we
369  // really care is whether there is more than one entry.
370  // Contains one entry if all the Representations have the same picture aspect
371  // ratio (@par attribute for AdaptationSet).
372  // There will be more than one entry if there are multiple picture aspect
373  // ratios.
374  // The @par attribute should only be set if there is exactly one entry
375  // in this set.
376  std::set<std::string> picture_aspect_ratio_;
377 
378  // The roles of this AdaptationSet.
379  std::set<Role> roles_;
380 
381  // True iff all the segments are aligned.
382  SegmentAligmentStatus segments_aligned_;
383  bool force_set_segment_alignment_;
384 
385  // Keeps track of segment start times of Representations.
386  // For VOD, this will not be cleared, all the segment start times are
387  // stored in this. This should not out-of-memory for a reasonable length
388  // video and reasonable subsegment length.
389  // For Live, the entries are deleted (see CheckLiveSegmentAlignment()
390  // implementation comment) because storing the entire timeline is not
391  // reasonable and may cause an out-of-memory problem.
392  RepresentationTimeline representation_segment_start_times_;
393 
394  DISALLOW_COPY_AND_ASSIGN(AdaptationSet);
395 };
396 
398  public:
401 
406  virtual void OnNewSegmentForRepresentation(uint64_t start_time,
407  uint64_t duration) = 0;
408 
413  virtual void OnSetFrameRateForRepresentation(uint32_t frame_duration,
414  uint32_t timescale) = 0;
415 };
416 
420  public:
421  virtual ~Representation();
422 
426  bool Init();
427 
438  virtual void AddContentProtectionElement(
439  const ContentProtectionElement& element);
440 
452  virtual void UpdateContentProtectionPssh(const std::string& drm_uuid,
453  const std::string& pssh);
454 
463  virtual void AddNewSegment(uint64_t start_time,
464  uint64_t duration,
465  uint64_t size);
466 
472  virtual void SetSampleDuration(uint32_t sample_duration);
473 
475  xml::ScopedXmlPtr<xmlNode>::type GetXml();
476 
478  uint32_t id() const { return id_; }
479 
480  protected:
490  const MediaInfo& media_info,
491  const MpdOptions& mpd_options,
492  uint32_t representation_id,
493  scoped_ptr<RepresentationStateChangeListener> state_change_listener);
494 
495  private:
496  friend class AdaptationSet;
497  template <MpdBuilder::MpdType type>
498  friend class MpdBuilderTest;
499 
500  bool AddLiveInfo(xml::RepresentationXmlNode* representation);
501 
502  // Returns true if |media_info_| has required fields to generate a valid
503  // Representation. Otherwise returns false.
504  bool HasRequiredMediaInfoFields();
505 
506  // Return false if the segment should be considered a new segment. True if the
507  // segment is contiguous.
508  bool IsContiguous(uint64_t start_time,
509  uint64_t duration,
510  uint64_t size) const;
511 
512  // Remove elements from |segment_infos_| if
513  // mpd_options_.time_shift_buffer_depth is specified. Increments
514  // |start_number_| by the number of segments removed.
515  void SlideWindow();
516 
517  // Note: Because 'mimeType' is a required field for a valid MPD, these return
518  // strings.
519  std::string GetVideoMimeType() const;
520  std::string GetAudioMimeType() const;
521  std::string GetTextMimeType() const;
522 
523  // Gets the earliest, normalized segment timestamp. Returns true if
524  // successful, false otherwise.
525  bool GetEarliestTimestamp(double* timestamp_seconds);
526 
527  // Init() checks that only one of VideoInfo, AudioInfo, or TextInfo is set. So
528  // any logic using this can assume only one set.
529  MediaInfo media_info_;
530  std::list<ContentProtectionElement> content_protection_elements_;
531  std::list<SegmentInfo> segment_infos_;
532 
533  base::Lock lock_;
534 
535  const uint32_t id_;
536  std::string mime_type_;
537  std::string codecs_;
538  BandwidthEstimator bandwidth_estimator_;
539  const MpdOptions& mpd_options_;
540 
541  // startNumber attribute for SegmentTemplate.
542  // Starts from 1.
543  uint32_t start_number_;
544 
545  // If this is not null, then Representation is responsible for calling the
546  // right methods at right timings.
547  scoped_ptr<RepresentationStateChangeListener> state_change_listener_;
548 
549  DISALLOW_COPY_AND_ASSIGN(Representation);
550 };
551 
552 } // namespace edash_packager
553 
554 #endif // MPD_BASE_MPD_BUILDER_H_
MpdType type() const
Definition: mpd_builder.h:91
virtual void AddNewSegment(uint64_t start_time, uint64_t duration, uint64_t size)
AdaptationSet(uint32_t adaptation_set_id, const std::string &lang, const MpdOptions &mpd_options, MpdBuilder::MpdType mpd_type, base::AtomicSequenceNumber *representation_counter)
Definition: mpd_builder.cc:652
Defines Mpd Options.
Definition: mpd_options.h:13
virtual int Group() const
Definition: mpd_builder.cc:816
virtual AdaptationSet * AddAdaptationSet(const std::string &lang)
Definition: mpd_builder.cc:408
Define an abstract file interface.
Definition: file.h:22
xml::ScopedXmlPtr< xmlNode >::type GetXml()
static void MakePathsRelativeToMpd(const std::string &mpd_path, MediaInfo *media_info)
Definition: mpd_builder.cc:624
This class generates DASH MPDs (Media Presentation Descriptions).
Definition: mpd_builder.h:56
virtual void ForceSetSegmentAlignment(bool segment_alignment)
Definition: mpd_builder.cc:806
virtual void SetSampleDuration(uint32_t sample_duration)
void AddBaseUrl(const std::string &base_url)
Definition: mpd_builder.cc:403
virtual void UpdateContentProtectionPssh(const std::string &drm_uuid, const std::string &pssh)
Representation(const MediaInfo &media_info, const MpdOptions &mpd_options, uint32_t representation_id, scoped_ptr< RepresentationStateChangeListener > state_change_listener)
virtual void SetGroup(int group_number)
Definition: mpd_builder.cc:812
virtual void OnNewSegmentForRepresentation(uint64_t start_time, uint64_t duration)=0
xml::ScopedXmlPtr< xmlNode >::type GetXml()
Definition: mpd_builder.cc:736
virtual void AddContentProtectionElement(const ContentProtectionElement &element)
virtual void OnSetFrameRateForRepresentation(uint32_t frame_duration, uint32_t timescale)=0
RepresentationType in MPD.
Definition: xml_node.h:128
bool WriteMpdToFile(media::File *output_file)
Definition: mpd_builder.cc:420
void OnSetFrameRateForRepresentation(uint32_t representation_id, uint32_t frame_duration, uint32_t timescale)
Definition: mpd_builder.cc:840
virtual Representation * AddRepresentation(const MediaInfo &media_info)
Definition: mpd_builder.cc:671
virtual void UpdateContentProtectionPssh(const std::string &drm_uuid, const std::string &pssh)
Definition: mpd_builder.cc:723
virtual bool ToString(std::string *output)
Definition: mpd_builder.cc:426
virtual void AddRole(Role role)
Definition: mpd_builder.cc:730
MpdBuilder(MpdType type, const MpdOptions &mpd_options)
Definition: mpd_builder.cc:396
virtual void AddContentProtectionElement(const ContentProtectionElement &element)
Definition: mpd_builder.cc:716
void OnNewSegmentForRepresentation(uint32_t representation_id, uint64_t start_time, uint64_t duration)
Definition: mpd_builder.cc:827