tags.h 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377
  1. // Copyright 2021 The Chromium Authors. All rights reserved.
  2. // Use of this source code is governed by a BSD-style license that can be
  3. // found in the LICENSE file.
  4. #ifndef MEDIA_FORMATS_HLS_TAGS_H_
  5. #define MEDIA_FORMATS_HLS_TAGS_H_
  6. #include "base/time/time.h"
  7. #include "media/base/media_export.h"
  8. #include "media/formats/hls/parse_status.h"
  9. #include "media/formats/hls/tag_name.h"
  10. #include "media/formats/hls/types.h"
  11. #include "media/formats/hls/variable_dictionary.h"
  12. #include "third_party/abseil-cpp/absl/types/optional.h"
  13. namespace media::hls {
  14. class TagItem;
  15. // All currently implemented HLS tag types.
  16. // For organization, these appear in the same order as in `tag_name.h`.
  17. // Represents the contents of the #EXTM3U tag
  18. struct MEDIA_EXPORT M3uTag {
  19. static constexpr auto kName = CommonTagName::kM3u;
  20. static ParseStatus::Or<M3uTag> Parse(TagItem);
  21. };
  22. // Represents the contents of the #EXT-X-DEFINE tag
  23. struct MEDIA_EXPORT XDefineTag {
  24. static constexpr auto kName = CommonTagName::kXDefine;
  25. static ParseStatus::Or<XDefineTag> Parse(TagItem);
  26. // Constructs an XDefineTag representing a variable definition.
  27. static XDefineTag CreateDefinition(types::VariableName name,
  28. base::StringPiece value);
  29. // Constructs an XDefineTag representing an imported variable definition.
  30. static XDefineTag CreateImport(types::VariableName name);
  31. // The name of the variable being defined.
  32. types::VariableName name;
  33. // The value of the variable. If this is `nullopt`, then the value
  34. // is being IMPORT-ed and must be defined in the parent playlist.
  35. absl::optional<base::StringPiece> value;
  36. };
  37. // Represents the contents of the #EXT-X-INDEPENDENT-SEGMENTS tag
  38. struct MEDIA_EXPORT XIndependentSegmentsTag {
  39. static constexpr auto kName = CommonTagName::kXIndependentSegments;
  40. static ParseStatus::Or<XIndependentSegmentsTag> Parse(TagItem);
  41. };
  42. // Represents the contents of the #EXT-X-VERSION tag
  43. struct MEDIA_EXPORT XVersionTag {
  44. static constexpr auto kName = CommonTagName::kXVersion;
  45. static ParseStatus::Or<XVersionTag> Parse(TagItem);
  46. types::DecimalInteger version;
  47. };
  48. enum class MediaType {
  49. kAudio,
  50. kVideo,
  51. kSubtitles,
  52. kClosedCaptions,
  53. };
  54. // Represents the contents of the #EXT-X-MEDIA tag
  55. struct MEDIA_EXPORT XMediaTag {
  56. static constexpr auto kName = MultivariantPlaylistTagName::kXMedia;
  57. static ParseStatus::Or<XMediaTag> Parse(
  58. TagItem,
  59. const VariableDictionary& variable_dict,
  60. VariableDictionary::SubstitutionBuffer& sub_buffer);
  61. struct CtorArgs;
  62. explicit XMediaTag(CtorArgs);
  63. ~XMediaTag();
  64. XMediaTag(const XMediaTag&);
  65. XMediaTag(XMediaTag&&);
  66. XMediaTag& operator=(const XMediaTag&);
  67. XMediaTag& operator=(XMediaTag&&);
  68. // The type of media this tag represents.
  69. MediaType type;
  70. // The URI of the media playlist for this rendition. This is required if
  71. // `type` is `kSubtitles`, optional if the type is `kAudio` or `kVideo`,
  72. // and absent in the case of `kClosedCaptions`. The absence of this value for
  73. // `kVideo` indicates that the media data is included in the primary rendition
  74. // of any associated variants, and the absence of this value for `kAudio`
  75. // indicates that the media data is included in every video rendition of any
  76. // associated variants.
  77. absl::optional<ResolvedSourceString> uri;
  78. // For renditions with type `kClosedCaptions`, this specifies a rendition
  79. // within the segments of an associated media playlist. For all other types
  80. // this will be empty.
  81. absl::optional<types::InstreamId> instream_id;
  82. // Indicates the group to which this rendition belongs.
  83. ResolvedSourceString group_id;
  84. // This identifies the primary language used in the rendition.
  85. absl::optional<ResolvedSourceString> language;
  86. // This identifies a language that is associated with the rendition, in a
  87. // different role than `language`.
  88. absl::optional<ResolvedSourceString> associated_language;
  89. // A human-readable description of this rendition.
  90. ResolvedSourceString name;
  91. // A stable identifier for URI of this rendition within a multivariant
  92. // playlist. All renditions with the same URI SHOULD use the same
  93. // stable-rendition-id.
  94. absl::optional<types::StableId> stable_rendition_id;
  95. // Indicates whether the client should play this rendition in the absence of
  96. // information from the user indicating a different choice.
  97. bool is_default = false;
  98. // Indicates that the client may choose to play this rendition in the absence
  99. // of an explicit user preference.
  100. bool autoselect = false;
  101. // Indicates that this rendition contains content that is considered essential
  102. // to play. This will always be false if the type is not `kSubtitles`.
  103. bool forced = false;
  104. // A sequence of media characteristic tags, indicating a characteristic of the
  105. // rendition.
  106. std::vector<std::string> characteristics;
  107. // Contains channel information for this rendition. The only type with channel
  108. // information currently defined is `kAudio`, others are ignored for
  109. // forward-compatibility.
  110. absl::optional<types::AudioChannels> channels;
  111. };
  112. // Represents the contents of the #EXT-X-STREAM-INF tag
  113. struct MEDIA_EXPORT XStreamInfTag {
  114. static constexpr auto kName = MultivariantPlaylistTagName::kXStreamInf;
  115. static ParseStatus::Or<XStreamInfTag> Parse(
  116. TagItem,
  117. const VariableDictionary& variable_dict,
  118. VariableDictionary::SubstitutionBuffer& sub_buffer);
  119. XStreamInfTag();
  120. ~XStreamInfTag();
  121. XStreamInfTag(const XStreamInfTag&);
  122. XStreamInfTag(XStreamInfTag&&);
  123. XStreamInfTag& operator=(const XStreamInfTag&);
  124. XStreamInfTag& operator=(XStreamInfTag&&);
  125. // The peak segment bitrate of the stream this tag applies to, in bits per
  126. // second.
  127. types::DecimalInteger bandwidth = 0;
  128. // The average segment bitrate of the stream this tag applies to, in bits per
  129. // second.
  130. absl::optional<types::DecimalInteger> average_bandwidth;
  131. // An abstract, relative measure of the quality-of-experience of the stream
  132. // this tag applies to. The determination of this number is up to the playlist
  133. // author, however higher scores must indicate a better playback experience.
  134. absl::optional<types::DecimalFloatingPoint> score;
  135. // A comma-separated list of formats, where each format specifies a media
  136. // sample type that is present is one or more renditions of the variant stream
  137. // this tag applies to. According to the spec this *should* be present on
  138. // every instance of this tag, but in practice it's not. It's represented as
  139. // optional here so that the caller may decide how they wish to handle its
  140. // absence.
  141. absl::optional<std::string> codecs;
  142. // The optimal pixel resolution at which to display all video in this variant
  143. // stream.
  144. absl::optional<types::DecimalResolution> resolution;
  145. // This describes the maximum framerate for all video in this variant stream.
  146. absl::optional<types::DecimalFloatingPoint> frame_rate;
  147. };
  148. // Represents the contents of the #EXTINF tag
  149. struct MEDIA_EXPORT InfTag {
  150. static constexpr auto kName = MediaPlaylistTagName::kInf;
  151. static ParseStatus::Or<InfTag> Parse(TagItem);
  152. // Target duration of the media segment.
  153. base::TimeDelta duration;
  154. // Human-readable title of the media segment.
  155. SourceString title;
  156. };
  157. // Represents the contents of the #EXT-X-BITRATE tag.
  158. struct MEDIA_EXPORT XBitrateTag {
  159. static constexpr auto kName = MediaPlaylistTagName::kXBitrate;
  160. static ParseStatus::Or<XBitrateTag> Parse(TagItem);
  161. // The approximate bitrate of the following media segments, (except those that
  162. // have the EXT-X-BYTERANGE tag) expressed in kilobits per second. The value
  163. // must be within +-10% of the actual segment bitrate.
  164. types::DecimalInteger bitrate;
  165. };
  166. // Represents the contents of the #EXT-X-BYTERANGE tag.
  167. struct MEDIA_EXPORT XByteRangeTag {
  168. static constexpr auto kName = MediaPlaylistTagName::kXByteRange;
  169. static ParseStatus::Or<XByteRangeTag> Parse(TagItem);
  170. types::ByteRangeExpression range;
  171. };
  172. // Represents the contents of the #EXT-X-DISCONTINUITY tag
  173. struct MEDIA_EXPORT XDiscontinuityTag {
  174. static constexpr auto kName = MediaPlaylistTagName::kXDiscontinuity;
  175. static ParseStatus::Or<XDiscontinuityTag> Parse(TagItem);
  176. };
  177. // Represents the contents of the #EXT-X-DISCONTINUITY-SEQUENCE tag.
  178. struct MEDIA_EXPORT XDiscontinuitySequenceTag {
  179. static constexpr auto kName = MediaPlaylistTagName::kXDiscontinuitySequence;
  180. static ParseStatus::Or<XDiscontinuitySequenceTag> Parse(TagItem);
  181. // Indicates the discontinuity sequence number to assign to the first media
  182. // segment in this playlist. These numbers are useful for synchronizing
  183. // between variant stream timelines.
  184. types::DecimalInteger number;
  185. };
  186. // Represents the contents of the #EXT-X-ENDLIST tag
  187. struct MEDIA_EXPORT XEndListTag {
  188. static constexpr auto kName = MediaPlaylistTagName::kXEndList;
  189. static ParseStatus::Or<XEndListTag> Parse(TagItem);
  190. };
  191. // Represents the contents of the #EXT-X-GAP tag
  192. struct MEDIA_EXPORT XGapTag {
  193. static constexpr auto kName = MediaPlaylistTagName::kXGap;
  194. static ParseStatus::Or<XGapTag> Parse(TagItem);
  195. };
  196. // Represents the contents of the #EXT-X-I-FRAMES-ONLY tag
  197. struct MEDIA_EXPORT XIFramesOnlyTag {
  198. static constexpr auto kName = MediaPlaylistTagName::kXIFramesOnly;
  199. static ParseStatus::Or<XIFramesOnlyTag> Parse(TagItem);
  200. };
  201. // Represents the contents of the #EXT-X-MAP tag.
  202. struct MEDIA_EXPORT XMapTag {
  203. static constexpr auto kName = MediaPlaylistTagName::kXMap;
  204. static ParseStatus::Or<XMapTag> Parse(
  205. TagItem,
  206. const VariableDictionary& variable_dict,
  207. VariableDictionary::SubstitutionBuffer& sub_buffer);
  208. // The URI of the resource containing the media initialization section.
  209. ResolvedSourceString uri;
  210. // This specifies a byte range into the resource containing the media
  211. // initialization section.
  212. absl::optional<types::ByteRangeExpression> byte_range;
  213. };
  214. // Represents the contents of the #EXT-X-MEDIA-SEQUENCE tag.
  215. struct MEDIA_EXPORT XMediaSequenceTag {
  216. static constexpr auto kName = MediaPlaylistTagName::kXMediaSequence;
  217. static ParseStatus::Or<XMediaSequenceTag> Parse(TagItem);
  218. // Indicates the media sequence number to assign to the first media segment in
  219. // this playlist. These numbers are useful for validating the same media
  220. // playlist across reloads, but not for synchronizing media segments between
  221. // playlists.
  222. types::DecimalInteger number;
  223. };
  224. // Represents the contents of the #EXT-X-PART tag.
  225. struct MEDIA_EXPORT XPartTag {
  226. static constexpr auto kName = MediaPlaylistTagName::kXPart;
  227. static ParseStatus::Or<XPartTag> Parse(
  228. TagItem,
  229. const VariableDictionary& variable_dict,
  230. VariableDictionary::SubstitutionBuffer& sub_buffer);
  231. // The resource URI for the partial segment.
  232. ResolvedSourceString uri;
  233. // The duration of the partial segment.
  234. base::TimeDelta duration;
  235. // If this partial segment is a subrange of its resource, this defines the
  236. // subrange.
  237. absl::optional<types::ByteRangeExpression> byte_range;
  238. // Whether the partial segment contains an independent frame.
  239. bool independent = false;
  240. // Whether this partial segment is unavailable, similar to EXT-X-GAP for media
  241. // segments.
  242. bool gap = false;
  243. };
  244. // Represents the contents of the #EXT-PART-INF tag.
  245. struct MEDIA_EXPORT XPartInfTag {
  246. static constexpr auto kName = MediaPlaylistTagName::kXPartInf;
  247. static ParseStatus::Or<XPartInfTag> Parse(TagItem);
  248. // This value indicates the target duration for partial media segments.
  249. base::TimeDelta target_duration;
  250. };
  251. enum class PlaylistType {
  252. // Indicates that this playlist may have segments appended upon reloading
  253. // (until the #EXT-X-ENDLIST tag appears), but segments will not be removed.
  254. kEvent,
  255. // Indicates that this playlist is static, and will not have segments appended
  256. // or removed.
  257. kVOD,
  258. };
  259. // Represents the contents of the #EXT-X-PLAYLIST-TYPE tag
  260. struct MEDIA_EXPORT XPlaylistTypeTag {
  261. static constexpr auto kName = MediaPlaylistTagName::kXPlaylistType;
  262. static ParseStatus::Or<XPlaylistTypeTag> Parse(TagItem);
  263. PlaylistType type;
  264. };
  265. // Represents the contents of the #EXT-X-SERVER-CONTROL tag.
  266. struct MEDIA_EXPORT XServerControlTag {
  267. static constexpr auto kName = MediaPlaylistTagName::kXServerControl;
  268. static ParseStatus::Or<XServerControlTag> Parse(TagItem);
  269. // This value (given by the 'CAN-SKIP-UNTIL' attribute) represents the
  270. // distance from the last media segment that the server is able
  271. // to produce a playlist delta update.
  272. absl::optional<base::TimeDelta> skip_boundary;
  273. // This indicates whether the server supports skipping EXT-X-DATERANGE tags
  274. // older than the skip boundary when producing playlist delta updates.
  275. bool can_skip_dateranges = false;
  276. // This indicates the distance from the end of the playlist
  277. // at which clients should begin playback. This MUST be at least three times
  278. // the playlist's target duration.
  279. absl::optional<base::TimeDelta> hold_back;
  280. // This indicates the distance from the end of the playlist
  281. // at which clients should begin playback when playing in low-latency mode.
  282. // This value MUST be at least twice the playlist's partial segment target
  283. // duration, and SHOULD be at least three times that.
  284. absl::optional<base::TimeDelta> part_hold_back;
  285. // This indicates whether the server supports blocking playlist reloads.
  286. bool can_block_reload = false;
  287. };
  288. // Represents the contents of the #EXT-X-TARGETDURATION tag.
  289. struct MEDIA_EXPORT XTargetDurationTag {
  290. static constexpr auto kName = MediaPlaylistTagName::kXTargetDuration;
  291. static ParseStatus::Or<XTargetDurationTag> Parse(TagItem);
  292. // The upper bound on the duration of all media segments in the
  293. // media playlist. The EXTINF duration of each Media Segment in a Playlist
  294. // file, when rounded to the nearest integer, MUST be less than or equal to
  295. // this duration.
  296. base::TimeDelta duration;
  297. };
  298. } // namespace media::hls
  299. #endif // MEDIA_FORMATS_HLS_TAGS_H_