Mirror-Tools
/
shaka-packager
mirror of https://github.com/shaka-project/shaka-packager.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Doxygen doc for MPD generation classes. 

Change-Id: I8d28d05395732684f8c8fc73a8a40656ffa26a74
This commit is contained in:
Rintaro Kuroiwa 2014-02-06 13:20:36 -08:00 committed by Thomas Inskip
parent e4a6cf4edd
commit e5aea1b016
6 changed files with 142 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
mpd/base/content_protection_element.h
View File

@ -17,6 +17,8 @@
namespace dash_packager {
/// Structure to represent <ContentProtection> element in DASH MPD spec (ISO
/// 23009-1:2012 MPD and Segment Formats).
struct ContentProtectionElement {
ContentProtectionElement();
~ContentProtectionElement();

9
mpd/base/mpd_builder.cc
View File

@ -105,15 +105,6 @@ AdaptationSet* MpdBuilder::AddAdaptationSet() {
return adaptation_set.release();
}
bool MpdBuilder::WriteMpd() {
base::AutoLock scoped_lock(lock_);
std::string mpd;
bool result = ToStringImpl(&mpd);
// NOTE: Write to file, after interface change.
return result;
}
bool MpdBuilder::ToString(std::string* output) {
base::AutoLock scoped_lock(lock_);
return ToStringImpl(output);

74
mpd/base/mpd_builder.h
View File

@ -7,7 +7,6 @@
// This file contains the MpdBuilder, AdaptationSet, and Representation class
// declarations.
// http://goo.gl/UrsSlF
#ifndef MPD_BASE_MPD_BUILDER_H_
#define MPD_BASE_MPD_BUILDER_H_
@ -34,6 +33,7 @@ class XmlNode;
} // namespace xml
/// This class generates DASH MPDs (Media Presentation Descriptions).
class MpdBuilder {
public:
enum MpdType {
@ -41,16 +41,23 @@ class MpdBuilder {
kDynamic
};
/// Constructs MpdBuilder.
/// @param type indicates whether the MPD should be for VOD or live content
/// (kStatic for VOD profile, or kDynamic for live profile).
explicit MpdBuilder(MpdType type);
~MpdBuilder();
/// Add <BaseURL> entry to the MPD.
/// @param base_url URL for <BaseURL> entry.
void AddBaseUrl(const std::string& base_url);
// The returned pointer is owned by this object.
/// Adds <AdaptationSet> to the MPD.
/// @return The new adaptation set, which is owned by this instance.
AdaptationSet* AddAdaptationSet();
// This will write to stdout until File interface is defined.
bool WriteMpd();
/// Writes the MPD to the given string.
/// @param[out] output is an output string where the MPD gets written.
/// @return true on success, false otherwise.
bool ToString(std::string* output);
private:
@ -79,23 +86,35 @@ class MpdBuilder {
DISALLOW_COPY_AND_ASSIGN(MpdBuilder);
};
/// AdaptationSet class provides methods to add Representations and
/// <ContentProtection> elements to the AdaptationSet element.
class AdaptationSet {
public:
/// @param adaptation_set_id is an ID number for this AdaptationSet.
/// @param representation_counter is a Counter for assigning ID numbers to
/// Representation. It can not be NULL.
AdaptationSet(uint32 adaptation_set_id,
base::AtomicSequenceNumber* representation_counter);
~AdaptationSet();
// The returned pointer is owned by this object.
/// Create a Representation instance using @a media_info.
/// @param media_info is a MediaInfo object used to initialize the returned
/// Representation instance.
/// @return On success, returns a pointer to Representation. Otherwise returns
/// NULL. The returned pointer is owned by the AdaptationSet instance.
Representation* AddRepresentation(const MediaInfo& media_info);
// If |element| has {value, schemeIdUri} set and has
// {“value”, “schemeIdUri”} as key for additional_attributes,
// then the former is used.
/// Add a ContenProtection element to the adaptation set.
/// @param element contains the ContentProtection element contents.
/// If @a element has {value, schemeIdUri} set and has
/// {“value”, “schemeIdUri”} as key for @a additional_attributes,
/// then the former is used.
void AddContentProtectionElement(const ContentProtectionElement& element);
// Makes a copy of AdaptationSet xml element with its child elements, which
// are Representation elements. On success this returns non-NULL ScopedXmlPtr,
// otherwise returns NULL ScopedXmlPtr.
/// Makes a copy of AdaptationSet xml element with its child Representation
/// and ContentProtection elements.
/// @return On success returns a non-NULL ScopedXmlPtr. Otherwise returns a
/// NULL ScopedXmlPtr.
xml::ScopedXmlPtr<xmlNode>::type GetXml();
// Must be unique in the Period.
@ -117,35 +136,46 @@ class AdaptationSet {
DISALLOW_COPY_AND_ASSIGN(AdaptationSet);
};
// In |media_info|, ContentProtectionXml::{schemeIdUri,value} takes precedence
// over schemeIdUri and value specified in ContentProtectionXml::attributes.
/// Representation class contains references to a single media stream, as
/// well as optional ContentProtection elements for that stream.
class Representation {
public:
/// @param media_info is a MediaInfo containing information on the media.
/// @param representation_id is the numeric ID for the <Representation>.
Representation(const MediaInfo& media_info, uint32 representation_id);
~Representation();
/// Tries to initialize the instance. If this does not succeed, the instance
/// should not be used.
/// @return true on success, false otherwise.
bool Init();
// If |element| has {value, schemeIdUri} set and has
// {“value”, “schemeIdUri”} as key for additional_attributes,
// then the former is used.
/// Add a ContenProtection element to the representation.
/// @param element contains the ContentProtection element contents.
/// If @a element has {value, schemeIdUri} set and has
/// {“value”, “schemeIdUri”} as key for @a additional_attributes,
/// then the former is used.
void AddContentProtectionElement(const ContentProtectionElement& element);
/// Add a media segment to the representation.
/// @param start_time is the start time for the segment, in units of the
/// stream's time scale.
/// @param duration is the duration of the segment, in units of the stream's
/// time scale.
/// @return true on success, false otherwise.
bool AddNewSegment(uint64 start_time, uint64 duration);
// Makes a copy of the current XML. Note that this is a copy. The caller is
// responsible for cleaning up the allocated resource.
/// @return Copy of <Representation>.
xml::ScopedXmlPtr<xmlNode>::type GetXml();
// Must be unique amongst other Representations in the MPD file.
// As the MPD spec says.
/// @return ID number for <Representation>.
uint32 id() const {
return id_;
}
private:
// Returns whether |media_info_| has required fields to generate a valid
// Representation. Returns true on success, otherwise returns false.
// Returns true if |media_info_| has required fields to generate a valid
// Representation. Otherwise returns false.
bool HasRequiredMediaInfoFields();
// Note: Because 'mimeType' is a required field for a valid MPD, these return

42
mpd/base/mpd_notifier.h
View File

@ -18,34 +18,48 @@ namespace dash_packager {
class ContentProtectionElement;
class MediaInfo;
/// Interface for publish/subscribe publisher class which notifies MpdBuilder
/// of media-related events.
class MpdNotifier {
public:
MpdNotifier() {};
virtual ~MpdNotifier() {};
// Initializes the notifier. For example, if this notifier uses a network for
// notification, then this would setup connection with the remote host.
/// Initializes the notifier. For example, if this notifier uses a network for
/// notification, then this would set up the connection with the remote host.
/// @return true on success, false otherwise.
virtual bool Init() = 0;
// Notifies the MpdBuilder that there is a new container along with
// |media_info|. Live may have multiple "files" but those should be notified
// via NotifyNewSegment().
// On success this populates |container_id| for the container and returns true,
// otherwise returns false.
/// Notifies the MpdBuilder that there is a new container along with
/// @a media_info. Live may have multiple files (segments) but those should be
/// notified via NotifyNewSegment().
/// @param media_info is the MediaInfo that will be passed to MpdBuilder.
/// @param[out] container_id is the numeric ID of the container, possibly for
/// NotifyNewSegment() and AddContentProtectionElement(). Only
/// populated on success.
/// @return true on success, false otherwise.
virtual bool NotifyNewContainer(const MediaInfo& media_info,
uint32* container_id) = 0;
// Only for Live. Notifies MpdBuilder that there is a new segment ready that
// starts from |start_time| for |duration|.
// |container_id| must be an ID number populated by calling
// NotifyNewContainer().
/// Notifies MpdBuilder that there is a new segment ready. Used only for live
/// profile.
/// @param container_id Container ID obtained from calling
/// NotifyNewContainer().
/// @param start_time is the start time of the new segment, in units of the
/// stream's time scale.
/// @param duration is the duration of the new segment, in units of the
/// stream's time scale..
/// @return true on success, false otherwise.
virtual bool NotifyNewSegment(uint32 container_id,
uint64 start_time,
uint64 duration) = 0;
// Adds content protection information to the MPD.
// |container_id| must be an ID number populated by calling
// NotifyNewContainer().
/// Adds content protection information to the MPD.
/// @param container_id is the nummeric container ID obtained from calling
/// NotifyNewContainer().
/// @param content_protection_element New ContentProtection element
/// specification.
/// @return true on success, false otherwise.
virtual bool AddContentProtectionElement(
uint32 container_id,
const ContentProtectionElement& content_protection_element) = 0;

3
mpd/base/xml/scoped_xml_ptr.h
View File

@ -17,6 +17,8 @@
namespace dash_packager {
namespace xml {
/// Deleter functor for deleting libxml2 pointers. This is used with
/// ScopedXmlPtr.
struct XmlDeleter {
// Called by scoped_ptr. http://goo.gl/YaLbcS
inline void operator()(xmlSchemaParserCtxtPtr ptr) const {
@ -33,6 +35,7 @@ struct XmlDeleter {
// C++11 allows template alias but standards before it do not. This struct is
// for aliasing scoped_ptr with libxml2 object deleter.
/// scoped_ptr for libxml2 resources.
template <typename XmlType>
struct ScopedXmlPtr {
typedef scoped_ptr<XmlType, XmlDeleter> type;

81
mpd/base/xml/xml_node.h
View File

@ -21,40 +21,59 @@
namespace dash_packager {
namespace xml {
// These classes are wrapper classes for XML elements for generating MPD.
// None of the pointer parameters should be NULL. None of the methods are meant
// to be overridden.
/// These classes are wrapper classes for XML elements for generating MPD.
/// None of the pointer parameters should be NULL. None of the methods are meant
/// to be overridden.
class XmlNode {
public:
// Makes an XML element with |name|. |name| should not be NULL.
/// Make an XML element.
/// @param name is the name of the element, which should not be NULL.
explicit XmlNode(const char* name);
virtual ~XmlNode();
// The ownership transfers to this object. On failure, this method will
// destruct |child|.
/// Add a child element to this element.
/// @param child is a xmlNode to add as a child for this element. Ownership
/// of the child node is transferred.
/// @return true on success, false otherwise.
bool AddChild(ScopedXmlPtr<xmlNode>::type child);
/// Set a string attribute.
/// @param attribute_name The name (lhs) of the attribute.
/// @param attribute The value (rhs) of the attribute.
void SetStringAttribute(const char* attribute_name,
const std::string& attribute);
/// Sets an interger attribute.
/// @param attribute_name The name (lhs) of the attribute.
/// @param number The value (rhs) of the attribute.
void SetIntegerAttribute(const char* attribute_name, uint64 number);
/// Set a floating point number attribute.
/// @param attribute_name is the name of the attribute to set.
/// @param number is the value (rhs) of the attribute.
void SetFloatingPointAttribute(const char* attribute_name, double number);
/// Sets 'id=@a id' attribute.
/// @param id is the ID for this element.
void SetId(uint32 id);
// This is like 'innerHTML' setter.
// This function does not work well with AddChild(). Use either AddChild() or
// SetContent() when setting the content of this node.
/// Set the contents of an XML element using a string.
/// Note: This function does not work well with AddChild(). Use either
/// AddChild() or SetContent() when setting the content of this node.
/// @param content is a string containing the text-encoded child elements to
/// be added to the element.
void SetContent(const std::string& content);
// Ownership transfer. After calling this method, calling any methods of
// this object, except the destructor, is undefined.
/// Transfer the ownership of the xmlNodePtr. After calling this method, the
/// behavior of any methods, except the destructor, is undefined.
/// @return The resource of this object.
ScopedXmlPtr<xmlNode>::type PassScopedPtr();
// Release the xmlNodePtr of this object. After calling this method, calling
// any methods of this object, except the destructor, is undefined.
/// Release the xmlNodePtr of this object. After calling this method, the
/// behavior of any methods, except the destructor, is undefined.
xmlNodePtr Release();
/// @return Raw pointer to the element.
xmlNodePtr GetRawPtr();
private:
@ -63,17 +82,19 @@ class XmlNode {
DISALLOW_COPY_AND_ASSIGN(XmlNode);
};
// This corresponds to RepresentationBaseType in MPD. RepresentationBaseType is
// not a concrete element type so this should not get instantiated on its own.
// AdaptationSet and Representation are subtypes of this.
/// This corresponds to RepresentationBaseType in MPD. RepresentationBaseType is
/// not a concrete element type so this should not get instantiated on its own.
/// AdaptationSet and Representation are subtypes of this.
class RepresentationBaseXmlNode : public XmlNode {
public:
virtual ~RepresentationBaseXmlNode();
bool AddContentProtectionElements(
const std::list<ContentProtectionElement>& content_protection_elements);
// Return true on success. If content_protections size is 0 in |media_info|,
// this will return true. Otherwise return false.
/// Add a ContentProtection elements to this element.
/// @param media_info is a MediaInfo containing the ContentProtection
/// elements to add.
/// @return true on success, false otherwise.
bool AddContentProtectionElementsFromMediaInfo(const MediaInfo& media_info);
protected:
@ -86,7 +107,7 @@ class RepresentationBaseXmlNode : public XmlNode {
DISALLOW_COPY_AND_ASSIGN(RepresentationBaseXmlNode);
};
// AdaptationSetType in MPD.
/// AdaptationSetType specified in MPD.
class AdaptationSetXmlNode : public RepresentationBaseXmlNode {
public:
AdaptationSetXmlNode();
@ -96,7 +117,7 @@ class AdaptationSetXmlNode : public RepresentationBaseXmlNode {
DISALLOW_COPY_AND_ASSIGN(AdaptationSetXmlNode);
};
// RepresentationType in MPD.
/// RepresentationType in MPD.
class RepresentationXmlNode : public RepresentationBaseXmlNode {
public:
typedef ::google::protobuf::RepeatedPtrField<MediaInfo_VideoInfo>
@ -108,17 +129,29 @@ class RepresentationXmlNode : public RepresentationBaseXmlNode {
RepresentationXmlNode();
virtual ~RepresentationXmlNode();
// Returns true if successfully set attributes and children elements (if
// applicable). repeated info of size 0 is valid input.
/// Adds video metadata to the MPD.
/// @param repeated_video_info constains the VideoInfos for Representation.
/// Input of size 0 is valid.
/// @return true if successfully set attributes and children elements (if
/// applicable), false otherwise.
bool AddVideoInfo(const RepeatedVideoInfo& repeated_video_info);
/// Adds audio metadata to the MPD.
/// @param repeated_audio_info constains the AudioInfos for Representation.
/// Input of size 0 is valid.
/// @return true if successfully set attributes and children elements (if
/// applicable), false otherwise.
bool AddAudioInfo(const RepeatedAudioInfo& repeated_audio_info);
// Check MediaInfo protobuf definition for which fields are specific to VOD.
/// Adds fields that are specific to VOD. This ignores @a media_info fields for
/// Live.
/// @param media_info is a MediaInfo with VOD information.
/// @return true on success, false otherwise.
bool AddVODOnlyInfo(const MediaInfo& media_info);
private:
// Add AudioChannelConfiguration elements. This will add multiple
// AudioChannelConfiguration if |repeated_audio_info| contains multiple
// AudioChannelConfiguration if @a repeated_audio_info contains multiple
// distinct channel configs (e.g. 2 channels and 6 channels adds 2 elements).
bool AddAudioChannelInfo(const RepeatedAudioInfo& repeated_audio_info);