From 24328460644fd5bcd01d6231f0b6fb6051d18fa3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebastian=20Dr=C3=B6ge?= Date: Thu, 18 Nov 2021 15:04:17 +0200 Subject: [PATCH] Move the crate docs to the root of the crate so they actually show up And also fix all the broken links while we're at it. --- src/lib.rs | 67 +++++++++++++++++++++++++++++++++++++++++++++ src/parser.rs | 72 ++----------------------------------------------- src/playlist.rs | 43 ++++++++++------------------- 3 files changed, 83 insertions(+), 99 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index f48840d..4d9b79e 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,3 +1,70 @@ +//! A library to parse m3u8 playlists [HTTP Live Streaming](https://tools.ietf.org/html/draft-pantos-http-live-streaming-19). +//! +//! # Examples +//! +//! Parsing a playlist and let the parser figure out if it's a media or master playlist. +//! +//! ``` +//! use m3u8_rs::Playlist; +//! use nom::IResult; +//! use std::io::Read; +//! +//! let mut file = std::fs::File::open("playlist.m3u8").unwrap(); +//! let mut bytes: Vec = Vec::new(); +//! file.read_to_end(&mut bytes).unwrap(); +//! +//! match m3u8_rs::parse_playlist(&bytes) { +//! Result::Ok((i, Playlist::MasterPlaylist(pl))) => println!("Master playlist:\n{:?}", pl), +//! Result::Ok((i, Playlist::MediaPlaylist(pl))) => println!("Media playlist:\n{:?}", pl), +//! Result::Err(e) => panic!("Parsing error: \n{}", e), +//! } +//! ``` +//! +//! Parsing a master playlist directly +//! +//! ``` +//! use std::io::Read; +//! use nom::IResult; +//! +//! let mut file = std::fs::File::open("masterplaylist.m3u8").unwrap(); +//! let mut bytes: Vec = Vec::new(); +//! file.read_to_end(&mut bytes).unwrap(); +//! +//! if let Result::Ok((_, pl)) = m3u8_rs::parse_master_playlist(&bytes) { +//! println!("{:?}", pl); +//! } +//! ``` +//! +//! Creating a playlist and writing it back to a vec/file +//! +//! ``` +//! use m3u8_rs::{MediaPlaylist, MediaPlaylistType, MediaSegment}; +//! +//! let playlist = MediaPlaylist { +//! version: 6, +//! target_duration: 3.0, +//! media_sequence: 338559, +//! discontinuity_sequence: 1234, +//! end_list: true, +//! playlist_type: Some(MediaPlaylistType::Vod), +//! segments: vec![ +//! MediaSegment { +//! uri: "20140311T113819-01-338559live.ts".into(), +//! duration: 2.002, +//! title: Some("title".into()), +//! ..Default::default() +//! }, +//! ], +//! ..Default::default() +//! }; +//! +//! //let mut v: Vec = Vec::new(); +//! //playlist.write_to(&mut v).unwrap(); +//! +//! //let mut file = std::fs::File::open("playlist.m3u8").unwrap(); +//! //playlist.write_to(&mut file).unwrap(); +//! ``` + mod playlist; pub use playlist::*; diff --git a/src/parser.rs b/src/parser.rs index e7f2a63..c877e4b 100644 --- a/src/parser.rs +++ b/src/parser.rs @@ -1,71 +1,3 @@ -//! A library to parse m3u8 playlists (HTTP Live Streaming) [link] -//! (https://tools.ietf.org/html/draft-pantos-http-live-streaming-19). -//! -//! # Examples -//! -//! Parsing a playlist and let the parser figure out if it's a media or master playlist. -//! -//! ``` -//! use m3u8_rs::playlist::Playlist; -//! use nom::IResult; -//! use std::io::Read; -//! -//! let mut file = std::fs::File::open("playlist.m3u8").unwrap(); -//! let mut bytes: Vec = Vec::new(); -//! file.read_to_end(&mut bytes).unwrap(); -//! -//! match m3u8_rs::parse_playlist(&bytes) { -//! Result::Ok((i, Playlist::MasterPlaylist(pl))) => println!("Master playlist:\n{:?}", pl), -//! Result::Ok((i, Playlist::MediaPlaylist(pl))) => println!("Media playlist:\n{:?}", pl), -//! Result::Err(e) => panic!("Parsing error: \n{}", e), -//! } -//! ``` -//! -//! Parsing a master playlist directly -//! -//! ``` -//! use std::io::Read; -//! use nom::IResult; -//! -//! let mut file = std::fs::File::open("masterplaylist.m3u8").unwrap(); -//! let mut bytes: Vec = Vec::new(); -//! file.read_to_end(&mut bytes).unwrap(); -//! -//! if let Result::Ok((_, pl)) = m3u8_rs::parse_master_playlist(&bytes) { -//! println!("{:?}", pl); -//! } -//! ``` -//! -//! Creating a playlist and writing it back to a vec/file -//! -//! ``` -//! use m3u8_rs::playlist::{MediaPlaylist, MediaPlaylistType, MediaSegment}; -//! -//! let playlist = MediaPlaylist { -//! version: 6, -//! target_duration: 3.0, -//! media_sequence: 338559, -//! discontinuity_sequence: 1234, -//! end_list: true, -//! playlist_type: Some(MediaPlaylistType::Vod), -//! segments: vec![ -//! MediaSegment { -//! uri: "20140311T113819-01-338559live.ts".into(), -//! duration: 2.002, -//! title: Some("title".into()), -//! ..Default::default() -//! }, -//! ], -//! ..Default::default() -//! }; -//! -//! //let mut v: Vec = Vec::new(); -//! //playlist.write_to(&mut v).unwrap(); -//! -//! //let mut file = std::fs::File::open("playlist.m3u8").unwrap(); -//! //playlist.write_to(&mut file).unwrap(); -//! ``` - use nom::branch::alt; use nom::bytes::complete::{is_a, is_not, tag, take, take_until, take_while1}; use nom::character::complete::{ @@ -91,7 +23,7 @@ use std::string; /// /// ``` /// use std::io::Read; -/// use m3u8_rs::playlist::{Playlist}; +/// use m3u8_rs::Playlist; /// /// let mut file = std::fs::File::open("playlist.m3u8").unwrap(); /// let mut bytes: Vec = Vec::new(); @@ -122,7 +54,7 @@ pub fn parse_playlist(input: &[u8]) -> IResult<&[u8], Playlist> { /// # Examples /// /// ``` -/// use m3u8_rs::playlist::{Playlist}; +/// use m3u8_rs::Playlist; /// use std::io::Read; /// /// let mut file = std::fs::File::open("playlist.m3u8").unwrap(); diff --git a/src/playlist.rs b/src/playlist.rs index 3918936..5e02161 100644 --- a/src/playlist.rs +++ b/src/playlist.rs @@ -65,8 +65,7 @@ impl Playlist { // Master Playlist // ----------------------------------------------------------------------------------------------- -/// A [Master Playlist] -/// (https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.4) +/// A [Master Playlist](https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.4) /// provides a set of Variant Streams, each of which /// describes a different version of the same content. #[derive(Debug, Default, PartialEq, Clone)] @@ -116,11 +115,8 @@ impl MasterPlaylist { } } -/// [`#EXT-X-STREAM-INF: -/// `] -/// (https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.4.2) -/// [`#EXT-X-I-FRAME-STREAM-INF:`] -/// (https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.4.3) +/// [`#EXT-X-STREAM-INF: `](https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.4.2) +/// [`#EXT-X-I-FRAME-STREAM-INF:`](https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.4.3) /// /// A Variant Stream includes a Media Playlist that specifies media /// encoded at a particular bit rate, in a particular format, and at a @@ -197,8 +193,7 @@ impl VariantStream { } } -/// [`#EXT-X-MEDIA:`] -/// (https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.4.1) +/// [`#EXT-X-MEDIA:`](https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.4.1) /// /// The EXT-X-MEDIA tag is used to relate Media Playlists that contain /// alternative Renditions (Section 4.3.4.2.1) of the same content. For @@ -314,8 +309,7 @@ impl fmt::Display for AlternativeMediaType { } } -/// [`#EXT-X-SESSION-KEY:`] -/// (https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.4.5) +/// [`#EXT-X-SESSION-KEY:`](https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.4.5) /// The EXT-X-SESSION-KEY tag allows encryption keys from Media Playlists /// to be specified in a Master Playlist. This allows the client to /// preload these keys without having to read the Media Playlist(s) first. @@ -336,8 +330,7 @@ pub enum SessionDataField { Uri(String), } -/// [`#EXT-X-SESSION-DATA:`] -/// (https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.4.4) +/// [`#EXT-X-SESSION-DATA:`](https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.4.4) /// The EXT-X-SESSION-DATA tag allows arbitrary session data to be carried /// in a Master Playlist. #[derive(Debug, PartialEq, Clone)] @@ -399,8 +392,7 @@ impl SessionData { // Media Playlist // ----------------------------------------------------------------------------------------------- -/// A [Media Playlist] -/// (https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.3) +/// A [Media Playlist](https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.3) /// contains a list of Media Segments, which when played /// sequentially will play the multimedia presentation. #[derive(Debug, Default, PartialEq, Clone)] @@ -463,8 +455,7 @@ impl MediaPlaylist { } } -/// [`#EXT-X-PLAYLIST-TYPE:`] -/// (https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.3.5) +/// [`#EXT-X-PLAYLIST-TYPE:`](https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.3.5) #[derive(Debug, PartialEq, Clone)] pub enum MediaPlaylistType { Event, @@ -577,8 +568,7 @@ impl MediaSegment { } } -/// [`#EXT-X-KEY:`] -/// (https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.2.4) +/// [`#EXT-X-KEY:`](https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.2.4) /// /// Media Segments MAY be encrypted. The EXT-X-KEY tag specifies how to /// decrypt them. It applies to every Media Segment that appears between @@ -615,12 +605,10 @@ impl Key { } } -/// [`#EXT-X-MAP:`] -/// (https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.2.5) +/// [`#EXT-X-MAP:`](https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.2.5) /// /// The EXT-X-MAP tag specifies how to obtain the Media Initialization Section -/// [(Section 3)] -/// (https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-3) +/// [(Section 3)](https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-3) /// required to parse the applicable Media Segments. /// It applies to every Media Segment that appears after it in the /// Playlist until the next EXT-X-MAP tag or until the end of the @@ -642,8 +630,7 @@ impl Map { } } -/// [`#EXT-X-BYTERANGE:[@]`] -/// (https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.2.2) +/// [`#EXT-X-BYTERANGE:[@]`](https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.2.2) /// /// The EXT-X-BYTERANGE tag indicates that a Media Segment is a sub-range /// of the resource identified by its URI. It applies only to the next @@ -664,8 +651,7 @@ impl ByteRange { } } -/// [`#EXT-X-DATERANGE:`] -/// (https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.2.7) +/// [`#EXT-X-DATERANGE:`](https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.2.7) /// /// The EXT-X-DATERANGE tag associates a Date Range (i.e. a range of time /// defined by a starting and ending date) with a set of attribute / @@ -686,8 +672,7 @@ pub struct DateRange { // Rest // ----------------------------------------------------------------------------------------------- -/// [`#EXT-X-START:`] -/// (https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.5.2) +/// [`#EXT-X-START:`](https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.5.2) /// /// The EXT-X-START tag indicates a preferred point at which to start /// playing a Playlist. By default, clients SHOULD start playback at