From 1f1870fb41c1ffdd875a4c5b58236ed19c4e830a Mon Sep 17 00:00:00 2001 From: Jamie Hardt Date: Fri, 20 Nov 2020 19:13:53 -0800 Subject: [PATCH] Added much documentation --- src/audio_frame_reader.rs | 4 ++-- src/lib.rs | 11 ++++++++++ src/validation.rs | 30 +++++++++++++++++++++++++-- src/wavereader.rs | 43 ++++++++++++++++++++++++++++++++++++--- 4 files changed, 81 insertions(+), 7 deletions(-) diff --git a/src/audio_frame_reader.rs b/src/audio_frame_reader.rs index d5f9bca..edbf58c 100644 --- a/src/audio_frame_reader.rs +++ b/src/audio_frame_reader.rs @@ -34,7 +34,7 @@ impl AudioFrameReader { vec![0i32; self.format.channel_count as usize] } - pub fn read_integer_frame(&mut self, buffer:&mut [i32]) -> Result<(),Error> { + pub fn read_integer_frame(&mut self, buffer:&mut [i32]) -> Result { assert!(buffer.len() as u16 == self.format.channel_count, "read_integer_frame was called with a mis-sized buffer, expected {}, was {}", self.format.channel_count, buffer.len()); @@ -52,7 +52,7 @@ impl AudioFrameReader { } } - Ok( () ) + Ok( 1 ) } } diff --git a/src/lib.rs b/src/lib.rs index 427fddc..8dde669 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,6 +1,17 @@ extern crate encoding; extern crate byteorder; +/**! + * bwavfile + * + * Rust Wave File Reader/Writer with Broadcast-WAV, MBWF and RF64 Support + * + * This crate is currently a work-in-progress (I'm using it to teach myself + * rust) so the interface may change dramatically and not all features work. + * + !*/ + + mod parser; mod fourcc; mod errors; diff --git a/src/validation.rs b/src/validation.rs index fd9b301..a823436 100644 --- a/src/validation.rs +++ b/src/validation.rs @@ -1,11 +1,10 @@ use super::parser::{Parser}; use super::fourcc::{FourCC, FMT__SIG,DATA_SIG, BEXT_SIG, JUNK_SIG, FLLR_SIG}; use super::errors::Error as ParserError; -use super::wavereader::WaveReader; +use super::wavereader::{WaveReader}; use std::io::{Read,Seek}; - impl WaveReader { /** * Returns without `Err` if the source meets the minimum standard of @@ -34,6 +33,20 @@ impl WaveReader { * * Some clients require a WAVE file to only contain format and data without any other * metadata and this function is provided to validate this condition. + * + * ``` + * # use bwavfile::WaveReader; + * + * let mut w = WaveReader::open("tests/media/ff_minimal.wav").unwrap(); + * w.validate_minimal().expect("Minimal wav did not validate not minimal!"); + * ``` + * + * ``` + * # use bwavfile::WaveReader; + * + * let mut x = WaveReader::open("tests/media/pt_24bit_51.wav").unwrap(); + * x.validate_minimal().expect_err("Complex WAV validated minimal!"); + * ``` */ pub fn validate_minimal(&mut self) -> Result<(), ParserError> { self.validate_readable()?; @@ -53,6 +66,19 @@ impl WaveReader { * * Returns without `Err` if `validate_readable()` and file contains a * Broadcast-WAV metadata record (a `bext` chunk). + * + * ``` + * # use bwavfile::WaveReader; + * + * let mut w = WaveReader::open("tests/media/ff_bwav_stereo.wav").unwrap(); + * w.validate_broadcast_wave().expect("BWAVE file did not validate BWAVE"); + * + * let mut x = WaveReader::open("tests/media/pt_24bit.wav").unwrap(); + * x.validate_broadcast_wave().expect("BWAVE file did not validate BWAVE"); + * + * let mut y = WaveReader::open("tests/media/audacity_16bit.wav").unwrap(); + * y.validate_broadcast_wave().expect_err("Plain WAV file DID validate BWAVE"); + * ``` */ pub fn validate_broadcast_wave(&mut self) -> Result<(), ParserError> { self.validate_readable()?; diff --git a/src/wavereader.rs b/src/wavereader.rs index b9883b6..c65909e 100644 --- a/src/wavereader.rs +++ b/src/wavereader.rs @@ -9,14 +9,30 @@ use super::chunks::{WaveFmt, Bext}; use super::audio_frame_reader::AudioFrameReader; use super::chunks::ReadBWaveChunks; //use super::validation; -use std::io::SeekFrom::{Start}; +//use std::io::SeekFrom::{Start}; use std::io::{Read, Seek}; /** * Wave, Broadcast-WAV and RF64/BW64 parser/reader. * - + * ``` + * use bwavfile::WaveReader; + * let mut r = WaveReader::open("tests/media/ff_silence.wav").unwrap(); + * + * let format = r.format().unwrap(); + * assert_eq!(format.sample_rate, 44100); + * assert_eq!(format.channel_count, 1); + * + * let mut frame_reader = r.audio_frame_reader().unwrap(); + * let mut buffer = frame_reader.create_frame_buffer(); + * + * let read = frame_reader.read_integer_frame(&mut buffer).unwrap(); + * + * assert_eq!(buffer, [0i32]); + * assert_eq!(read, 1); + * + * ``` */ #[derive(Debug)] pub struct WaveReader { @@ -28,6 +44,7 @@ impl WaveReader { * Open a file for reading. * * A convenience that opens `path` and calls `Self::new()` + * */ pub fn open(path: &str) -> Result { let inner = File::open(path)?; @@ -48,6 +65,26 @@ impl WaveReader { * will return an `Err(errors::Error)` immediately if there is a structural * inconsistency that makes the stream unreadable or if it's missing * essential components that make interpreting the audio data impoossible. + * + * ```rust + * use std::fs::File; + * use std::io::{Error,ErrorKind}; + * use bwavfile::{WaveReader, Error as WavError}; + * + * let f = File::open("tests/media/error.wav").unwrap(); + * + * let reader = WaveReader::new(f); + * + * match reader { + * Ok(_) => panic!("error.wav should not be openable"), + * Err( WavError::IOError( e ) ) => { + * assert_eq!(e.kind(), ErrorKind::UnexpectedEof) + * } + * Err(e) => panic!("Unexpected error was returned {:?}", e) + * } + * + * ``` + * */ pub fn new(inner: R) -> Result { let mut retval = Self { inner }; @@ -56,7 +93,7 @@ impl WaveReader { } /** - * Unwrap and reliqnish ownership of the inner reader. + * Unwrap the inner reader. */ pub fn into_inner(self) -> R { return self.inner;