webm_iterable/
lib.rs

1//!
2//! This crate was built to ease parsing files encoded in a Matroska container, such as [WebMs][webm] or [MKVs][mkv].
3//!
4//! The main content provided by this crate is the [`MatroskaSpec`] enum.  Otherwise, this crate simply provides type aliases in the form of [`WebmIterator`] and [`WebmWriter`].
5//! 
6//! [webm]: https://www.webmproject.org/
7//! [mkv]: http://www.matroska.org/technical/specs/index.html
8//! 
9//!
10//! # Example Usage
11//! 
12//! The following examples show how to read, modify, and write webm files using this library.
13//! 
14//! ## Example 1
15//! The following example reads a media file into memory and decodes it.
16//! 
17//! ```
18//! use std::fs::File;
19//! use webm_iterable::WebmIterator;
20//! 
21//! fn main() -> Result<(), Box<dyn std::error::Error>> {
22//!     let mut src = File::open("media/test.webm").unwrap();
23//!     let tag_iterator = WebmIterator::new(&mut src, &[]);
24//! 
25//!     for tag in tag_iterator {
26//!         println!("[{:?}]", tag?);
27//!     }
28//! 
29//!     Ok(())
30//! }
31//! ```
32//! 
33//! ## Example 2
34//! This next example does the same thing, but keeps track of the number of times each tag appears in the file.
35//! 
36//! ```
37//! use std::fs::File;
38//! use std::collections::HashMap;
39//! use webm_iterable::WebmIterator;
40//! use webm_iterable::matroska_spec::EbmlTag;
41//! 
42//! fn main() -> Result<(), Box<dyn std::error::Error>> {
43//!     let mut src = File::open("media/test.webm").unwrap();
44//!     let tag_iterator = WebmIterator::new(&mut src, &[]);
45//!     let mut tag_counts = HashMap::new();
46//! 
47//!     for tag in tag_iterator {
48//!         let count = tag_counts.entry(tag?.get_id()).or_insert(0);
49//!         *count += 1;
50//!     }
51//!     
52//!     println!("{:?}", tag_counts);
53//!     Ok(())
54//! }
55//! ```
56//! 
57//! ## Example 3
58//! This example grabs the audio from a webm and stores the result in a new file.  The logic in this example is rather advanced - an explanation follows the code.
59//! 
60//! ```no_run
61//! use std::fs::File;
62//! use std::convert::TryInto;
63//! 
64//! use webm_iterable::{
65//!     WebmIterator, 
66//!     WebmWriter,
67//!     matroska_spec::{MatroskaSpec, Master, Block, EbmlSpecification, EbmlTag},
68//! };
69//! 
70//! fn main() -> Result<(), Box<dyn std::error::Error>> {
71//!     // 1
72//!     let mut src = File::open("media/audiosample.webm").unwrap();
73//!     let tag_iterator = WebmIterator::new(&mut src, &[MatroskaSpec::TrackEntry(Master::Start)]);
74//!     let mut dest = File::create("media/audioout.webm").unwrap();
75//!     let mut tag_writer = WebmWriter::new(&mut dest);
76//!     let mut stripped_tracks = Vec::new();
77//! 
78//!     // 2
79//!     for tag in tag_iterator {
80//!         let tag = tag?;
81//!         match tag {
82//!             // 3
83//!             MatroskaSpec::TrackEntry(master) => {
84//!                 let children = master.get_children();
85//!                 let is_audio_track = |tag: &MatroskaSpec| {
86//!                     if let MatroskaSpec::TrackType(val) = tag {
87//!                         return *val != 2;
88//!                     } else {
89//!                         false
90//!                     }
91//!                 };
92//! 
93//!                 if children.iter().any(is_audio_track) {
94//!                     let track_number_variant = children.iter().find(|c| matches!(c, MatroskaSpec::TrackNumber(_))).expect("should have a track number child");
95//!                     let track_number = track_number_variant.as_unsigned_int().expect("TrackNumber is an unsigned int variant");
96//!                     stripped_tracks.push(*track_number);
97//!                 } else {
98//!                     tag_writer.write(&MatroskaSpec::TrackEntry(Master::Full(children)))?;
99//!                 }
100//!             },
101//!             // 4
102//!             MatroskaSpec::Block(ref data) => {
103//!                 let block: Block = data.try_into()?;
104//!                 if !stripped_tracks.iter().any(|t| *t == block.track) {
105//!                     tag_writer.write(&tag)?;
106//!                 }
107//!             },
108//!             MatroskaSpec::SimpleBlock(ref data) => {
109//!                 let block: Block = data.try_into()?;
110//!                 if !stripped_tracks.iter().any(|t| *t == block.track) {
111//!                     tag_writer.write(&tag)?;
112//!                 }
113//!             },
114//!             // 5
115//!             _ => {
116//!                 tag_writer.write(&tag)?;
117//!             }
118//!         }
119//!     }
120//!     
121//!     Ok(())
122//! }
123//! ```
124//! 
125//! In the above example, we (1) build our iterator and writer based on local file paths and declare useful local variables, (2) iterate over the tags in the webm file, (3) identify any tracks that are not audio and store their numbers in the `stripped_tracks` variable; if they are audio, we write the "TrackEntry" out, (4) only write block data for tracks that are audio, and (5) write all other tags to the output destination.
126//! 
127//! __Notes__
128//! * Notice the second parameter passed into the `WebmIterator::new()` function.  This parameter tells the decoder which "master" tags should be read as [`Master::Full`][`crate::matroska_spec::Master::Full`] variants rather than the standard [`Master::Start`][`crate::matroska_spec::Master::Start`] and [`Master::End`][`crate::matroska_spec::Master::End`] variants.  This greatly simplifies our iteration loop logic as we don't have to maintain an internal buffer for the "TrackEntry" tags that we are interested in processing.
129//! 
130
131use ebml_iterable::{TagIterator, TagWriter};
132
133#[cfg(feature = "futures")]
134use ebml_iterable::nonblocking::TagIteratorAsync;
135
136pub use ebml_iterable::iterator;
137pub use ebml_iterable::WriteOptions;
138pub mod errors;
139pub mod matroska_spec;
140
141use matroska_spec::MatroskaSpec;
142
143///
144/// Alias for [`ebml_iterable::TagIterator`] using [`MatroskaSpec`] as the generic type.
145///
146/// This implements Rust's standard [`Iterator`] trait. The struct can be created with the `new` function on any source that implements the [`std::io::Read`] trait. The iterator outputs [`MatroskaSpec`] variants containing the tag data. See the [ebml-iterable](https://crates.io/crates/ebml_iterable) docs for more information if needed.
147///
148/// Note: The `with_capacity` method can be used to construct a `WebmIterator` with a specified default buffer size.  This is only useful as a microoptimization to memory management if you know the maximum tag size of the file you're reading.
149///
150pub type WebmIterator<R> = TagIterator<R, MatroskaSpec>;
151
152///
153/// Alias for [`ebml_iterable::TagIteratorAsync`] using [`MatroskaSpec`] as the generic type.
154///
155/// This Can be transformed into a [`Stream`] using [`into_stream`]. The struct can be created with the [`new()`] function on any source that implements the [`futures::AsyncRead`] trait. The stream outputs [`MatroskaSpec`] variants containing the tag data. See the [ebml-iterable](https://crates.io/crates/ebml_iterable) docs for more information if needed.
156///
157#[cfg(feature="futures")]
158pub type WebmIteratorAsync<R> = TagIteratorAsync<R, MatroskaSpec>;
159
160///
161/// Alias for [`ebml_iterable::TagWriter`].
162///
163/// This can be used to write webm files from tag data. This struct can be created with the `new` function on any source that implements the [`std::io::Write`] trait. See the [ebml-iterable](https://crates.io/crates/ebml_iterable) docs for more information if needed.
164///
165pub type WebmWriter<W> = TagWriter<W>;
166
167#[cfg(test)]
168mod tests {
169    use std::io::Cursor;
170
171    use super::matroska_spec::{MatroskaSpec, Master};
172    use super::WebmWriter;
173    use super::WebmIterator;
174
175    #[test]
176    fn basic_tag_stream_write_and_iterate() {
177        let tags: Vec<MatroskaSpec> = vec![
178            MatroskaSpec::Ebml(Master::Start),
179            MatroskaSpec::Ebml(Master::End),
180            MatroskaSpec::Segment(Master::Start),
181            MatroskaSpec::Tracks(Master::Start),
182            MatroskaSpec::TrackEntry(Master::Start),
183            MatroskaSpec::TrackType(0x01),
184            MatroskaSpec::TrackEntry(Master::End),
185            MatroskaSpec::Tracks(Master::End),
186            MatroskaSpec::Cluster(Master::Full(vec![
187                MatroskaSpec::Position(0x02),
188                ])),
189            MatroskaSpec::Segment(Master::End),
190        ];
191
192        let mut dest = Cursor::new(Vec::new());
193        let mut writer = WebmWriter::new(&mut dest);
194
195        for tag in tags {
196            writer.write(&tag).expect("Test shouldn't error");
197        }
198
199        println!("dest {:?}", dest);
200
201        let mut src = Cursor::new(dest.get_ref().to_vec());
202        let reader = WebmIterator::new(&mut src, &[]);
203        let tags: Vec<MatroskaSpec> = reader.map(|i| i.unwrap()).collect();
204
205        println!("tags {:?}", tags);
206
207        assert_eq!(MatroskaSpec::Ebml(Master::Start), tags[0]);
208        assert_eq!(MatroskaSpec::Ebml(Master::End), tags[1]);
209        assert_eq!(MatroskaSpec::Segment(Master::Start), tags[2]);
210        assert_eq!(MatroskaSpec::Tracks(Master::Start), tags[3]);
211        assert_eq!(MatroskaSpec::TrackEntry(Master::Start), tags[4]);
212        assert_eq!(MatroskaSpec::TrackType(0x01), tags[5]);
213        assert_eq!(MatroskaSpec::TrackEntry(Master::End), tags[6]);
214        assert_eq!(MatroskaSpec::Tracks(Master::End), tags[7]);
215        assert_eq!(MatroskaSpec::Cluster(Master::Start), tags[8]);
216        assert_eq!(MatroskaSpec::Position(0x02), tags[9]);
217        assert_eq!(MatroskaSpec::Cluster(Master::End), tags[10]);
218        assert_eq!(MatroskaSpec::Segment(Master::End), tags[11]);
219    }
220}
webm_iterable/lib.rs

webm_iterable/
lib.rs
