From fba770a00ec76bc7217fd7e2bec014c6fb12bf6b Mon Sep 17 00:00:00 2001 From: Alfred Gutierrez Date: Mon, 14 Sep 2020 19:48:00 -0700 Subject: [PATCH] Updating docs (#32) * Updating docs. * Fix docs tests and update to 0.7.0. --- Cargo.toml | 16 ++++------- README.md | 25 ++++++++++++----- src/lib.rs | 68 +++++++++++++++++++++++++++++++++++++++++++++++ src/mp4box/mod.rs | 49 ++++++++++++++++++++++++++++++++++ 4 files changed, 140 insertions(+), 18 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index bdffde9..6aa7f9e 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -3,18 +3,12 @@ name = "mp4" version = "0.6.0" authors = ["Alf "] edition = "2018" - -description = """ -MP4 reader and writer library in Rust. -""" - -documentation = "https://docs.rs/mp4rs" +description = "MP4 reader and writer library in Rust." +documentation = "https://docs.rs/mp4" readme = "README.md" -homepage = "https://github.com/alfg/mp4rs" -repository = "https://github.com/alfg/mp4rs" - -keywords = ["mp4", "isobmff", "video", "multimedia"] - +homepage = "https://github.com/alfg/mp4-rust" +repository = "https://github.com/alfg/mp4-rust" +keywords = ["mp4", "iso-mp4", "isobmff", "video", "multimedia"] license = "MIT" [dependencies] diff --git a/README.md b/README.md index 6e532eb..83350be 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ -# mp4rs +# mp4 > MP4 Reader and Writer in Rust 🦀 -`mp4rs` is a Rust library to read and write ISO-MP4 files. This package contains MPEG-4 specifications defined in parts: +`mp4` is a Rust library to read and write ISO-MP4 files. This package contains MPEG-4 specifications defined in parts: * [ISO/IEC 14496-12](https://en.wikipedia.org/wiki/MPEG-4_Part_14) - ISO Base Media File Format (QuickTime, MPEG-4, etc) * [ISO/IEC 14496-14](https://en.wikipedia.org/wiki/MPEG-4_Part_14) - MP4 file format * ISO/IEC 14496-17 - Streaming text format @@ -10,8 +10,9 @@ https://crates.io/crates/mp4 [![Crates.io](https://img.shields.io/crates/v/mp4)](https://crates.io/crates/mp4) [![Crates.io](https://img.shields.io/crates/d/mp4)](https://crates.io/crates/mp4) -[![Build Status](https://travis-ci.org/alfg/mp4rs.svg?branch=master)](https://travis-ci.org/alfg/mp4rs) -[![Rust](https://github.com/alfg/mp4rs/workflows/Rust/badge.svg)](https://github.com/alfg/mp4rs/actions) +[![Docs](https://img.shields.io/badge/docs-online-5023dd.svg?style=flat-square)](https://docs.rs/mp4) +[![Build Status](https://travis-ci.org/alfg/mp4-rust.svg?branch=master)](https://travis-ci.org/alfg/mp4-rust) +[![Rust](https://github.com/alfg/mp4-rust/workflows/Rust/badge.svg)](https://github.com/alfg/mp4-rust/actions) #### Example ```rust @@ -20,7 +21,7 @@ use std::io::{BufReader}; use mp4::{Result}; fn main() -> Result<()> { - let f = File::open("example.mp4").unwrap(); + let f = File::open("tests/samples/minimal.mp4").unwrap(); let size = f.metadata()?.len(); let reader = BufReader::new(f); @@ -59,8 +60,8 @@ See [examples/](examples/) for more examples. #### Install Add to your `Cargo.toml`: -``` -mp4 = "0.6.0" +```toml +mp4 = "0.7.0" ``` #### Documentation @@ -104,6 +105,13 @@ cargo bench View HTML report at `target/criterion/report/index.html` +#### Generate Docs +``` +cargo docs +``` + +View at `target/doc/mp4/index.html` + ## Web Assembly See the [mp4-inspector](https://github.com/alfg/mp4-inspector) project as a reference for using this library in Javascript via Web Assembly. @@ -114,3 +122,6 @@ See the [mp4-inspector](https://github.com/alfg/mp4-inspector) project as a refe ## License MIT + +[docs]: https://docs.rs/mp4 +[docs-badge]: https://img.shields.io/badge/docs-online-5023dd.svg?style=flat-square diff --git a/src/lib.rs b/src/lib.rs index 5cfa938..c542f80 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,3 +1,71 @@ +//! `mp4` is a Rust library to read and write ISO-MP4 files. +//! +//! This package contains MPEG-4 specifications defined in parts: +//! * ISO/IEC 14496-12 - ISO Base Media File Format (QuickTime, MPEG-4, etc) +//! * ISO/IEC 14496-14 - MP4 file format +//! * ISO/IEC 14496-17 - Streaming text format +//! +//! See: [mp4box] for supported MP4 atoms. +//! +//! ### Example +//! +//! ``` +//! use std::fs::File; +//! use std::io::{BufReader}; +//! use mp4::{Result}; +//! +//! fn main() -> Result<()> { +//! let f = File::open("tests/samples/minimal.mp4").unwrap(); +//! let size = f.metadata()?.len(); +//! let reader = BufReader::new(f); +//! +//! let mp4 = mp4::Mp4Reader::read_header(reader, size)?; +//! +//! // Print boxes. +//! println!("major brand: {}", mp4.ftyp.major_brand); +//! println!("timescale: {}", mp4.moov.mvhd.timescale); +//! +//! // Use available methods. +//! println!("size: {}", mp4.size()); +//! +//! let mut compatible_brands = String::new(); +//! for brand in mp4.compatible_brands().iter() { +//! compatible_brands.push_str(&brand.to_string()); +//! compatible_brands.push_str(","); +//! } +//! println!("compatible brands: {}", compatible_brands); +//! println!("duration: {:?}", mp4.duration()); +//! +//! // Track info. +//! for track in mp4.tracks().iter() { +//! println!( +//! "track: #{}({}) {} : {}", +//! track.track_id(), +//! track.language(), +//! track.track_type()?, +//! track.box_type()?, +//! ); +//! } +//! Ok(()) +//! } +//! ``` +//! +//! See [examples] for more examples. +//! +//! # Installation +//! +//! Add the following to your `Cargo.toml` file: +//! +//! ```toml +//! [dependencies] +//! mp4 = "0.7.0" +//! ``` +//! +//! [mp4box]: https://github.com/alfg/mp4-rust/blob/master/src/mp4box/mod.rs +//! [examples]: https://github.com/alfg/mp4-rust/examples +#![doc(html_root_url = "https://docs.rs/mp4/*")] + + use std::io::{BufReader}; use std::fs::File; diff --git a/src/mp4box/mod.rs b/src/mp4box/mod.rs index f05c4b8..a5319bd 100644 --- a/src/mp4box/mod.rs +++ b/src/mp4box/mod.rs @@ -1,3 +1,52 @@ +//! All ISO-MP4 boxes (atoms) and operations. +//! +//! * [ISO/IEC 14496-12](https://en.wikipedia.org/wiki/MPEG-4_Part_14) - ISO Base Media File Format (QuickTime, MPEG-4, etc) +//! * [ISO/IEC 14496-14](https://en.wikipedia.org/wiki/MPEG-4_Part_14) - MP4 file format +//! * ISO/IEC 14496-17 - Streaming text format +//! +//! http://developer.apple.com/documentation/QuickTime/QTFF/index.html +//! http://www.adobe.com/devnet/video/articles/mp4_movie_atom.html +//! http://mp4ra.org/#/atoms +//! +//! Supported Atoms: +//! ftyp +//! moov +//! mvhd +//! trak +//! tkhd +//! mdia +//! mdhd +//! hdlr +//! minf +//! stbl +//! stsd +//! avc1 +//! hev1 +//! mp4a +//! tx3g +//! stts +//! stsc +//! stsz +//! stss +//! stco +//! co64 +//! ctts +//! smhd +//! vmhd +//! edts +//! elst +//! mvex +//! mehd +//! trex +//! moof +//! mfhd +//! traf +//! tfhd +//! trun +//! mdat +//! free +//! + use byteorder::{BigEndian, ReadBytesExt, WriteBytesExt}; use std::convert::TryInto; use std::io::{Read, Seek, SeekFrom, Write};