mirrors/m3u8-rs
1
1
Fork 0
mirror of https://github.com/rutgersc/m3u8-rs.git synced 2025-03-13 09:42:39 +00:00
Code Issues Projects Releases Wiki Activity

Move the crate docs to the root of the crate so they actually show up

Browse source 
And also fix all the broken links while we're at it.
This commit is contained in:
Sebastian Dröge 2021-11-18 15:04:17 +02:00
parent 51fcb70113
commit 2432846064
3 changed files with 83 additions and 99 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

67
src/lib.rs
View file

@ -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<u8> = 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<u8> = 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<u8> = 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; mod playlist;
pub use playlist::*; pub use playlist::*;

72
src/parser.rs
View file

@ -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<u8> = 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<u8> = 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<u8> = 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::branch::alt;
use nom::bytes::complete::{is_a, is_not, tag, take, take_until, take_while1}; use nom::bytes::complete::{is_a, is_not, tag, take, take_until, take_while1};
use nom::character::complete::{ use nom::character::complete::{
@ -91,7 +23,7 @@ use std::string;
/// ///
/// ``` /// ```
/// use std::io::Read; /// 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 file = std::fs::File::open("playlist.m3u8").unwrap();
/// let mut bytes: Vec<u8> = Vec::new(); /// let mut bytes: Vec<u8> = Vec::new();
@ -122,7 +54,7 @@ pub fn parse_playlist(input: &[u8]) -> IResult<&[u8], Playlist> {
/// # Examples /// # Examples
/// ///
/// ``` /// ```
/// use m3u8_rs::playlist::{Playlist}; /// use m3u8_rs::Playlist;
/// use std::io::Read; /// use std::io::Read;
/// ///
/// let mut file = std::fs::File::open("playlist.m3u8").unwrap(); /// let mut file = std::fs::File::open("playlist.m3u8").unwrap();

43
src/playlist.rs
View file

@ -65,8 +65,7 @@ impl Playlist {
// Master Playlist // Master Playlist
// ----------------------------------------------------------------------------------------------- // -----------------------------------------------------------------------------------------------
/// A [Master Playlist] /// A [Master Playlist](https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.4)
/// (https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.4)
/// provides a set of Variant Streams, each of which /// provides a set of Variant Streams, each of which
/// describes a different version of the same content. /// describes a different version of the same content.
#[derive(Debug, Default, PartialEq, Clone)] #[derive(Debug, Default, PartialEq, Clone)]
@ -116,11 +115,8 @@ impl MasterPlaylist {
} }
} }
/// [`#EXT-X-STREAM-INF:<attribute-list> /// [`#EXT-X-STREAM-INF:<attribute-list> <URI>`](https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.4.2)
/// <URI>`] /// [`#EXT-X-I-FRAME-STREAM-INF:<attribute-list>`](https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.4.3)
/// (https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.4.2)
/// [`#EXT-X-I-FRAME-STREAM-INF:<attribute-list>`]
/// (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 /// A Variant Stream includes a Media Playlist that specifies media
/// encoded at a particular bit rate, in a particular format, and at a /// encoded at a particular bit rate, in a particular format, and at a
@ -197,8 +193,7 @@ impl VariantStream {
} }
} }
/// [`#EXT-X-MEDIA:<attribute-list>`] /// [`#EXT-X-MEDIA:<attribute-list>`](https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.4.1)
/// (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 /// 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 /// 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:<attribute-list>`] /// [`#EXT-X-SESSION-KEY:<attribute-list>`](https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.4.5)
/// (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 /// The EXT-X-SESSION-KEY tag allows encryption keys from Media Playlists
/// to be specified in a Master Playlist. This allows the client to /// to be specified in a Master Playlist. This allows the client to
/// preload these keys without having to read the Media Playlist(s) first. /// preload these keys without having to read the Media Playlist(s) first.
@ -336,8 +330,7 @@ pub enum SessionDataField {
Uri(String), Uri(String),
} }
/// [`#EXT-X-SESSION-DATA:<attribute-list>`] /// [`#EXT-X-SESSION-DATA:<attribute-list>`](https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.4.4)
/// (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 /// The EXT-X-SESSION-DATA tag allows arbitrary session data to be carried
/// in a Master Playlist. /// in a Master Playlist.
#[derive(Debug, PartialEq, Clone)] #[derive(Debug, PartialEq, Clone)]
@ -399,8 +392,7 @@ impl SessionData {
// Media Playlist // Media Playlist
// ----------------------------------------------------------------------------------------------- // -----------------------------------------------------------------------------------------------
/// A [Media Playlist] /// A [Media Playlist](https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.3)
/// (https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.3)
/// contains a list of Media Segments, which when played /// contains a list of Media Segments, which when played
/// sequentially will play the multimedia presentation. /// sequentially will play the multimedia presentation.
#[derive(Debug, Default, PartialEq, Clone)] #[derive(Debug, Default, PartialEq, Clone)]
@ -463,8 +455,7 @@ impl MediaPlaylist {
} }
} }
/// [`#EXT-X-PLAYLIST-TYPE:<EVENT|VOD>`] /// [`#EXT-X-PLAYLIST-TYPE:<EVENT|VOD>`](https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.3.5)
/// (https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.3.5)
#[derive(Debug, PartialEq, Clone)] #[derive(Debug, PartialEq, Clone)]
pub enum MediaPlaylistType { pub enum MediaPlaylistType {
Event, Event,
@ -577,8 +568,7 @@ impl MediaSegment {
} }
} }
/// [`#EXT-X-KEY:<attribute-list>`] /// [`#EXT-X-KEY:<attribute-list>`](https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.2.4)
/// (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 /// Media Segments MAY be encrypted. The EXT-X-KEY tag specifies how to
/// decrypt them. It applies to every Media Segment that appears between /// decrypt them. It applies to every Media Segment that appears between
@ -615,12 +605,10 @@ impl Key {
} }
} }
/// [`#EXT-X-MAP:<attribute-list>`] /// [`#EXT-X-MAP:<attribute-list>`](https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.2.5)
/// (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 /// The EXT-X-MAP tag specifies how to obtain the Media Initialization Section
/// [(Section 3)] /// [(Section 3)](https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-3)
/// (https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-3)
/// required to parse the applicable Media Segments. /// required to parse the applicable Media Segments.
/// It applies to every Media Segment that appears after it in the /// 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 /// Playlist until the next EXT-X-MAP tag or until the end of the
@ -642,8 +630,7 @@ impl Map {
} }
} }
/// [`#EXT-X-BYTERANGE:<n>[@<o>]`] /// [`#EXT-X-BYTERANGE:<n>[@<o>]`](https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.2.2)
/// (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 /// 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 /// of the resource identified by its URI. It applies only to the next
@ -664,8 +651,7 @@ impl ByteRange {
} }
} }
/// [`#EXT-X-DATERANGE:<attribute-list>`] /// [`#EXT-X-DATERANGE:<attribute-list>`](https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.2.7)
/// (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 /// 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 / /// defined by a starting and ending date) with a set of attribute /
@ -686,8 +672,7 @@ pub struct DateRange {
// Rest // Rest
// ----------------------------------------------------------------------------------------------- // -----------------------------------------------------------------------------------------------
/// [`#EXT-X-START:<attribute-list>`] /// [`#EXT-X-START:<attribute-list>`](https://tools.ietf.org/html/draft-pantos-http-live-streaming-19#section-4.3.5.2)
/// (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 /// The EXT-X-START tag indicates a preferred point at which to start
/// playing a Playlist. By default, clients SHOULD start playback at /// playing a Playlist. By default, clients SHOULD start playback at