quick_m3u8/reader.rs
1use crate::{
2 config::ParsingOptions,
3 error::{ReaderBytesError, ReaderStrError},
4 line::{HlsLine, parse_bytes_with_custom, parse_with_custom},
5 tag::{CustomTag, NoCustomTag},
6};
7use std::marker::PhantomData;
8
9/// A reader that parses lines of input HLS playlist data.
10///
11/// The `Reader` is the primary intended structure provided by the library for parsing HLS playlist
12/// data. The user has the flexibility to define which of the library provided HLS tags should be
13/// parsed as well as define a custom tag type to be extracted during parsing.
14///
15/// ## Basic usage
16///
17/// A reader can take an input `&str` (or `&[u8]`) and sequentially parse information about HLS
18/// lines. For example, you could use the `Reader` to build up a media playlist:
19/// ```
20/// # use quick_m3u8::{HlsLine, Reader};
21/// # use quick_m3u8::config::ParsingOptions;
22/// # use quick_m3u8::tag::{
23/// # hls::{self, DiscontinuitySequence, MediaSequence, Targetduration, Version, M3u},
24/// # KnownTag,
25/// # };
26/// # let playlist = r#"#EXTM3U
27/// # #EXT-X-TARGETDURATION:4
28/// # #EXT-X-MEDIA-SEQUENCE:541647
29/// # #EXT-X-VERSION:6
30/// # "#;
31/// #[derive(Debug, PartialEq)]
32/// struct MediaPlaylist<'a> {
33/// version: u64,
34/// targetduration: u64,
35/// media_sequence: u64,
36/// discontinuity_sequence: u64,
37/// // etc.
38/// lines: Vec<HlsLine<'a>>,
39/// }
40/// let mut reader = Reader::from_str(playlist, ParsingOptions::default());
41///
42/// let mut version = None;
43/// let mut targetduration = None;
44/// let mut media_sequence = 0;
45/// let mut discontinuity_sequence = 0;
46/// // etc.
47/// let mut lines = Vec::new();
48///
49/// // Validate playlist header
50/// match reader.read_line() {
51/// Ok(Some(HlsLine::KnownTag(KnownTag::Hls(hls::Tag::M3u(tag))))) => {
52/// lines.push(HlsLine::from(tag))
53/// }
54/// _ => return Err(format!("missing playlist header").into()),
55/// }
56///
57/// loop {
58/// match reader.read_line() {
59/// Ok(Some(line)) => match line {
60/// HlsLine::KnownTag(KnownTag::Hls(hls::Tag::Version(tag))) => {
61/// version = Some(tag.version());
62/// lines.push(HlsLine::from(tag));
63/// }
64/// HlsLine::KnownTag(KnownTag::Hls(hls::Tag::Targetduration(tag))) => {
65/// targetduration = Some(tag.target_duration());
66/// lines.push(HlsLine::from(tag));
67/// }
68/// HlsLine::KnownTag(KnownTag::Hls(hls::Tag::MediaSequence(tag))) => {
69/// media_sequence = tag.media_sequence();
70/// lines.push(HlsLine::from(tag));
71/// }
72/// HlsLine::KnownTag(KnownTag::Hls(hls::Tag::DiscontinuitySequence(tag))) => {
73/// discontinuity_sequence = tag.discontinuity_sequence();
74/// lines.push(HlsLine::from(tag));
75/// }
76/// // etc.
77/// _ => lines.push(line),
78/// },
79/// Ok(None) => break, // End of playlist
80/// Err(e) => return Err(format!("problem reading line: {e}").into()),
81/// }
82/// }
83///
84/// let version = version.unwrap_or(1);
85/// let Some(targetduration) = targetduration else {
86/// return Err("missing required EXT-X-TARGETDURATION".into());
87/// };
88/// let media_playlist = MediaPlaylist {
89/// version,
90/// targetduration,
91/// media_sequence,
92/// discontinuity_sequence,
93/// lines,
94/// };
95///
96/// assert_eq!(
97/// media_playlist,
98/// MediaPlaylist {
99/// version: 6,
100/// targetduration: 4,
101/// media_sequence: 541647,
102/// discontinuity_sequence: 0,
103/// lines: vec![
104/// // --snip--
105/// # HlsLine::from(M3u),
106/// # HlsLine::from(Targetduration::new(4)),
107/// # HlsLine::from(MediaSequence::new(541647)),
108/// # HlsLine::from(Version::new(6)),
109/// ],
110/// }
111/// );
112///
113/// # Ok::<(), Box<dyn std::error::Error>>(())
114/// ```
115///
116/// ## Configuring known tags
117///
118/// It is quite common that a user does not need to support parsing of all HLS tags for their use-
119/// case. To support this better the `Reader` allows for configuration of what HLS tags are
120/// considered "known" by the library. While it may sound strange to configure for less information
121/// to be parsed, doing so can have significant performance benefits, and at no loss if the
122/// information is not needed anyway. Unknown tags make no attempt to parse or validate the value
123/// portion of the tag (the part after `:`) and just provide the name of the tag along with the line
124/// up to (and not including) the new line characters. To provide some indication of the performance
125/// difference, running locally (as of commit `6fcc38a67bf0eee0769b7e85f82599d1da6eb56d`), the
126/// benchmarks show that on a very large media playlist parsing with all tags can be around 2x
127/// slower than parsing with no tags (`2.3842 ms` vs `1.1364 ms`):
128/// ```sh
129/// Large playlist, all tags, using Reader::from_str, no writing
130/// time: [2.3793 ms 2.3842 ms 2.3891 ms]
131/// Large playlist, no tags, using Reader::from_str, no writing
132/// time: [1.1357 ms 1.1364 ms 1.1372 ms]
133/// ```
134///
135/// For example, let's say that we are updating a playlist to add in HLS interstitial daterange,
136/// based on SCTE35-OUT information in an upstream playlist. The only tag we need to know about for
137/// this is EXT-X-DATERANGE, so we can configure our reader to only consider this tag during parsing
138/// which provides a benefit in terms of processing time.
139/// ```
140/// # use quick_m3u8::{
141/// # Reader, HlsLine, Writer,
142/// # config::ParsingOptionsBuilder,
143/// # tag::KnownTag,
144/// # tag::hls::{self, Cue, Daterange, ExtensionAttributeValue},
145/// # };
146/// # use std::{borrow::Cow, error::Error, io::Write};
147/// # fn advert_id_from_scte35_out(_: &str) -> Option<String> { None }
148/// # fn advert_uri_from_id(_: &str) -> String { String::new() }
149/// # fn duration_from_daterange(_: &Daterange) -> f64 { 0.0 }
150/// # let output = Vec::new();
151/// # let upstream_playlist = b"";
152/// let mut reader = Reader::from_bytes(
153/// upstream_playlist,
154/// ParsingOptionsBuilder::new()
155/// .with_parsing_for_daterange()
156/// .build(),
157/// );
158/// let mut writer = Writer::new(output);
159///
160/// loop {
161/// match reader.read_line() {
162/// Ok(Some(HlsLine::KnownTag(KnownTag::Hls(hls::Tag::Daterange(tag))))) => {
163/// if let Some(advert_id) = tag.scte35_out().and_then(advert_id_from_scte35_out) {
164/// let id = format!("ADVERT:{}", tag.id());
165/// let builder = Daterange::builder()
166/// .with_id(id)
167/// .with_start_date(tag.start_date())
168/// .with_class("com.apple.hls.interstitial")
169/// .with_cue(Cue::Once)
170/// .with_extension_attribute(
171/// "X-ASSET-URI",
172/// ExtensionAttributeValue::QuotedString(Cow::Owned(
173/// advert_uri_from_id(&advert_id),
174/// )),
175/// )
176/// .with_extension_attribute(
177/// "X-RESTRICT",
178/// ExtensionAttributeValue::QuotedString(Cow::Borrowed("SKIP,JUMP")),
179/// );
180/// let interstitial_daterange = if duration_from_daterange(&tag) == 0.0 {
181/// builder
182/// .with_extension_attribute(
183/// "X-RESUME-OFFSET",
184/// ExtensionAttributeValue::SignedDecimalFloatingPoint(0.0),
185/// )
186/// .finish()
187/// } else {
188/// builder.finish()
189/// };
190/// writer.write_line(HlsLine::from(interstitial_daterange))?;
191/// } else {
192/// writer.write_line(HlsLine::from(tag))?;
193/// }
194/// }
195/// Ok(Some(line)) => {
196/// writer.write_line(line)?;
197/// }
198/// Ok(None) => break, // End of playlist
199/// Err(e) => {
200/// writer.get_mut().write_all(e.errored_line)?;
201/// }
202/// };
203/// }
204///
205/// writer.into_inner().flush()?;
206/// # Ok::<(), Box<dyn Error>>(())
207/// ```
208///
209/// ## Custom tag reading
210///
211/// We can also configure the `Reader` to accept parsing of custom defined tags. Using the same idea
212/// as above, we can imagine that instead of EXT-X-DATERANGE in the upstream playlist, we want to
213/// depend on the EXT-X-SCTE35 tag that is defined within the SCTE35 specification. This tag is not
214/// defined in the HLS specification; however, we can define it here, and use it when it comes to
215/// parsing and utilizing that data. Below is a modified version of the above HLS interstitials
216/// example that instead relies on a custom defined `Scte35Tag` (though I leave the details of
217/// `TryFrom<ParsedTag>` unfilled for sake of simplicity in this example). Note, when defining a
218/// that the reader should use a custom tag, utilize `std::marker::PhantomData` to specify what the
219/// type of the custom tag is.
220/// ```
221/// # use quick_m3u8::{
222/// # Reader, HlsLine, Writer,
223/// # config::ParsingOptionsBuilder,
224/// # date::DateTime,
225/// # tag::{KnownTag, UnknownTag, CustomTag, WritableCustomTag, WritableTag},
226/// # tag::hls::{self, Cue, Daterange, ExtensionAttributeValue},
227/// # error::ValidationError,
228/// # };
229/// # use std::{borrow::Cow, error::Error, io::Write, marker::PhantomData};
230/// # fn advert_id_from_scte35_out(_: &str) -> Option<String> { None }
231/// # fn advert_uri_from_id(_: &str) -> String { String::new() }
232/// # fn generate_uuid() -> &'static str { "" }
233/// # fn calculate_start_date_based_on_inf_durations() -> DateTime { todo!() }
234/// # let output: Vec<u8> = Vec::new();
235/// # let upstream_playlist = b"";
236/// #[derive(Debug, PartialEq, Clone)]
237/// struct Scte35Tag<'a> {
238/// cue: &'a str,
239/// duration: Option<f64>,
240/// elapsed: Option<f64>,
241/// id: Option<&'a str>,
242/// time: Option<f64>,
243/// type_id: Option<u64>,
244/// upid: Option<&'a str>,
245/// blackout: Option<BlackoutValue>,
246/// cue_out: Option<CueOutValue>,
247/// cue_in: bool,
248/// segne: Option<(u64, u64)>,
249/// }
250/// #[derive(Debug, PartialEq, Clone)]
251/// enum BlackoutValue {
252/// Yes,
253/// No,
254/// Maybe,
255/// }
256/// #[derive(Debug, PartialEq, Clone)]
257/// enum CueOutValue {
258/// Yes,
259/// No,
260/// Cont,
261/// }
262/// impl<'a> TryFrom<UnknownTag<'a>> for Scte35Tag<'a> { // --snip--
263/// # type Error = ValidationError;
264/// # fn try_from(value: UnknownTag<'a>) -> Result<Self, Self::Error> {
265/// # todo!()
266/// # }
267/// }
268/// impl<'a> CustomTag<'a> for Scte35Tag<'a> {
269/// fn is_known_name(name: &str) -> bool {
270/// name == "-X-SCTE35"
271/// }
272/// }
273/// impl<'a> WritableCustomTag<'a> for Scte35Tag<'a> { // --snip--
274/// # fn into_writable_tag(self) -> WritableTag<'a> {
275/// # todo!()
276/// # }
277/// }
278/// #
279/// # let output: Vec<u8> = Vec::new();
280/// # let upstream_playlist = b"";
281///
282/// let mut reader = Reader::with_custom_from_bytes(
283/// upstream_playlist,
284/// ParsingOptionsBuilder::new().build(),
285/// PhantomData::<Scte35Tag>,
286/// );
287/// let mut writer = Writer::new(output);
288///
289/// loop {
290/// match reader.read_line() {
291/// Ok(Some(HlsLine::KnownTag(KnownTag::Custom(tag)))) => {
292/// if let Some(advert_id) = advert_id_from_scte35_out(tag.as_ref().cue) {
293/// let tag_ref = tag.as_ref();
294/// let id = format!("ADVERT:{}", tag_ref.id.unwrap_or(generate_uuid()));
295/// let start_date = calculate_start_date_based_on_inf_durations();
296/// let builder = Daterange::builder()
297/// .with_id(id)
298/// .with_start_date(start_date)
299/// .with_class("com.apple.hls.interstitial")
300/// .with_cue(Cue::Once)
301/// .with_extension_attribute(
302/// "X-ASSET-URI",
303/// ExtensionAttributeValue::QuotedString(Cow::Owned(
304/// advert_uri_from_id(&advert_id),
305/// )),
306/// )
307/// .with_extension_attribute(
308/// "X-RESTRICT",
309/// ExtensionAttributeValue::QuotedString(Cow::Borrowed("SKIP,JUMP")),
310/// );
311/// let interstitial_daterange = if tag_ref.duration == Some(0.0) {
312/// builder
313/// .with_extension_attribute(
314/// "X-RESUME-OFFSET",
315/// ExtensionAttributeValue::SignedDecimalFloatingPoint(0.0),
316/// )
317/// .finish()
318/// } else {
319/// builder.finish()
320/// };
321/// writer.write_line(HlsLine::from(interstitial_daterange))?;
322/// } else {
323/// writer.write_custom_line(HlsLine::from(tag))?;
324/// }
325/// }
326/// Ok(Some(line)) => {
327/// writer.write_custom_line(line)?;
328/// }
329/// Ok(None) => break, // End of playlist
330/// Err(e) => {
331/// writer.get_mut().write_all(e.errored_line)?;
332/// }
333/// };
334/// }
335///
336/// writer.into_inner().flush()?;
337///
338/// # Ok::<(), Box<dyn Error>>(())
339/// ```
340#[derive(Debug)]
341pub struct Reader<R, Custom> {
342 inner: R,
343 options: ParsingOptions,
344 _marker: PhantomData<Custom>,
345}
346
347macro_rules! impl_reader {
348 ($type:ty, $parse_fn:ident, $from_fn_ident:ident, $from_custom_fn_ident:ident, $error_type:ident) => {
349 impl<'a> Reader<&'a $type, NoCustomTag> {
350 /// Creates a reader without custom tag parsing support (in this case, the generic
351 /// `Custom` type is [`NoCustomTag`]).
352 pub fn $from_fn_ident(data: &'a $type, options: ParsingOptions) -> Self {
353 Self {
354 inner: data,
355 options,
356 _marker: PhantomData::<NoCustomTag>,
357 }
358 }
359 }
360 impl<'a, Custom> Reader<&'a $type, Custom>
361 where
362 Custom: CustomTag<'a>,
363 {
364 /// Creates a reader that supports custom tag parsing for the type specified by the
365 /// `PhatomData`.
366 pub fn $from_custom_fn_ident(
367 str: &'a $type,
368 options: ParsingOptions,
369 custom: PhantomData<Custom>,
370 ) -> Self {
371 Self {
372 inner: str,
373 options,
374 _marker: custom,
375 }
376 }
377
378 /// Returns the inner data of the reader.
379 pub fn into_inner(self) -> &'a $type {
380 self.inner
381 }
382
383 /// Reads a single HLS line from the reference data.
384 pub fn read_line(&mut self) -> Result<Option<HlsLine<'a, Custom>>, $error_type<'a>> {
385 if self.inner.is_empty() {
386 return Ok(None);
387 };
388 match $parse_fn(self.inner, &self.options) {
389 Ok(slice) => {
390 let parsed = slice.parsed;
391 let remaining = slice.remaining;
392 std::mem::swap(&mut self.inner, &mut remaining.unwrap_or_default());
393 Ok(Some(parsed))
394 }
395 Err(error) => {
396 let remaining = error.errored_line_slice.remaining;
397 std::mem::swap(&mut self.inner, &mut remaining.unwrap_or_default());
398 Err($error_type {
399 errored_line: error.errored_line_slice.parsed,
400 error: error.error,
401 })
402 }
403 }
404 }
405 }
406 };
407}
408
409impl_reader!(
410 str,
411 parse_with_custom,
412 from_str,
413 with_custom_from_str,
414 ReaderStrError
415);
416impl_reader!(
417 [u8],
418 parse_bytes_with_custom,
419 from_bytes,
420 with_custom_from_bytes,
421 ReaderBytesError
422);
423
424#[cfg(test)]
425mod tests {
426 use super::*;
427 use crate::{
428 config::ParsingOptionsBuilder,
429 error::{ParseTagValueError, SyntaxError, UnknownTagSyntaxError, ValidationError},
430 tag::{
431 CustomTagAccess, TagValue, UnknownTag,
432 hls::{Endlist, Inf, M3u, Targetduration, Version},
433 },
434 };
435 use pretty_assertions::assert_eq;
436
437 macro_rules! reader_test {
438 ($reader:tt, $method:tt, $expectation:expr $(, $buf:ident)?) => {
439 for i in 0..=11 {
440 let line = $reader.$method($(&mut $buf)?).unwrap();
441 match i {
442 0 => assert_eq!(Some(HlsLine::from(M3u)), line),
443 1 => assert_eq!(Some(HlsLine::from(Targetduration::new(10))), line),
444 2 => assert_eq!(Some(HlsLine::from(Version::new(3))), line),
445 3 => assert_eq!($expectation, line),
446 4 => assert_eq!(Some(HlsLine::from(Inf::new(9.009, String::new()))), line),
447 5 => assert_eq!(
448 Some(HlsLine::Uri("http://media.example.com/first.ts".into())),
449 line
450 ),
451 6 => assert_eq!(Some(HlsLine::from(Inf::new(9.009, String::new()))), line),
452 7 => assert_eq!(
453 Some(HlsLine::Uri("http://media.example.com/second.ts".into())),
454 line
455 ),
456 8 => assert_eq!(Some(HlsLine::from(Inf::new(3.003, String::new()))), line),
457 9 => assert_eq!(
458 Some(HlsLine::Uri("http://media.example.com/third.ts".into())),
459 line
460 ),
461 10 => assert_eq!(Some(HlsLine::from(Endlist)), line),
462 11 => assert_eq!(None, line),
463 _ => panic!(),
464 }
465 }
466 };
467 }
468
469 #[test]
470 fn reader_from_str_should_read_as_expected() {
471 let mut reader = Reader::from_str(
472 EXAMPLE_MANIFEST,
473 ParsingOptionsBuilder::new()
474 .with_parsing_for_all_tags()
475 .build(),
476 );
477 reader_test!(
478 reader,
479 read_line,
480 Some(HlsLine::from(UnknownTag {
481 name: "-X-EXAMPLE-TAG",
482 value: Some(TagValue(b"MEANING-OF-LIFE=42,QUESTION=\"UNKNOWN\"")),
483 original_input: &EXAMPLE_MANIFEST.as_bytes()[50..],
484 validation_error: None,
485 }))
486 );
487 }
488
489 #[test]
490 fn reader_from_buf_read_should_read_as_expected() {
491 let inner = EXAMPLE_MANIFEST.as_bytes();
492 let mut reader = Reader::from_bytes(
493 inner,
494 ParsingOptionsBuilder::new()
495 .with_parsing_for_all_tags()
496 .build(),
497 );
498 reader_test!(
499 reader,
500 read_line,
501 Some(HlsLine::from(UnknownTag {
502 name: "-X-EXAMPLE-TAG",
503 value: Some(TagValue(b"MEANING-OF-LIFE=42,QUESTION=\"UNKNOWN\"")),
504 original_input: &EXAMPLE_MANIFEST.as_bytes()[50..],
505 validation_error: None,
506 }))
507 );
508 }
509
510 #[test]
511 fn reader_from_str_with_custom_should_read_as_expected() {
512 let mut reader = Reader::with_custom_from_str(
513 EXAMPLE_MANIFEST,
514 ParsingOptionsBuilder::new()
515 .with_parsing_for_all_tags()
516 .build(),
517 PhantomData::<ExampleTag>,
518 );
519 reader_test!(
520 reader,
521 read_line,
522 Some(HlsLine::from(CustomTagAccess {
523 custom_tag: ExampleTag::new(42, "UNKNOWN"),
524 is_dirty: false,
525 original_input: EXAMPLE_MANIFEST[50..].as_bytes(),
526 }))
527 );
528 }
529
530 #[test]
531 fn reader_from_buf_with_custom_read_should_read_as_expected() {
532 let inner = EXAMPLE_MANIFEST.as_bytes();
533 let mut reader = Reader::with_custom_from_bytes(
534 inner,
535 ParsingOptionsBuilder::new()
536 .with_parsing_for_all_tags()
537 .build(),
538 PhantomData::<ExampleTag>,
539 );
540 reader_test!(
541 reader,
542 read_line,
543 Some(HlsLine::from(CustomTagAccess {
544 custom_tag: ExampleTag::new(42, "UNKNOWN"),
545 is_dirty: false,
546 original_input: EXAMPLE_MANIFEST[50..].as_bytes(),
547 }))
548 );
549 }
550
551 #[test]
552 fn when_reader_fails_it_moves_to_next_line() {
553 let input = concat!("#EXTM3U\n", "#EXT\n", "#Comment");
554 let mut reader = Reader::from_bytes(
555 input.as_bytes(),
556 ParsingOptionsBuilder::new()
557 .with_parsing_for_all_tags()
558 .build(),
559 );
560 assert_eq!(Ok(Some(HlsLine::from(M3u))), reader.read_line());
561 assert_eq!(
562 Err(ReaderBytesError {
563 errored_line: b"#EXT",
564 error: SyntaxError::from(UnknownTagSyntaxError::UnexpectedNoTagName)
565 }),
566 reader.read_line()
567 );
568 assert_eq!(
569 Ok(Some(HlsLine::Comment("Comment".into()))),
570 reader.read_line()
571 );
572 }
573
574 // Example custom tag implementation for the tests above.
575 #[derive(Debug, PartialEq, Clone)]
576 struct ExampleTag<'a> {
577 answer: u64,
578 question: &'a str,
579 }
580 impl ExampleTag<'static> {
581 fn new(answer: u64, question: &'static str) -> Self {
582 Self { answer, question }
583 }
584 }
585 impl<'a> TryFrom<UnknownTag<'a>> for ExampleTag<'a> {
586 type Error = ValidationError;
587 fn try_from(tag: UnknownTag<'a>) -> Result<Self, Self::Error> {
588 let mut attribute_list = tag
589 .value()
590 .ok_or(ParseTagValueError::UnexpectedEmpty)?
591 .try_as_attribute_list()?;
592 let Some(answer) = attribute_list
593 .remove("MEANING-OF-LIFE")
594 .and_then(|v| v.unquoted())
595 .and_then(|v| v.try_as_decimal_integer().ok())
596 else {
597 return Err(ValidationError::MissingRequiredAttribute("MEANING-OF-LIFE"));
598 };
599 let Some(question) = attribute_list.remove("QUESTION").and_then(|v| v.quoted()) else {
600 return Err(ValidationError::MissingRequiredAttribute("QUESTION"));
601 };
602 Ok(Self { answer, question })
603 }
604 }
605 impl<'a> CustomTag<'a> for ExampleTag<'a> {
606 fn is_known_name(name: &str) -> bool {
607 name == "-X-EXAMPLE-TAG"
608 }
609 }
610}
611
612#[cfg(test)]
613// Example taken from HLS specification with one custom tag added.
614// https://datatracker.ietf.org/doc/html/draft-pantos-hls-rfc8216bis-17#section-9.1
615const EXAMPLE_MANIFEST: &str = r#"#EXTM3U
616#EXT-X-TARGETDURATION:10
617#EXT-X-VERSION:3
618#EXT-X-EXAMPLE-TAG:MEANING-OF-LIFE=42,QUESTION="UNKNOWN"
619#EXTINF:9.009,
620http://media.example.com/first.ts
621#EXTINF:9.009,
622http://media.example.com/second.ts
623#EXTINF:3.003,
624http://media.example.com/third.ts
625#EXT-X-ENDLIST
626"#;