jamie/bwavfile
1
0
Fork 0
mirror of https://github.com/iluvcapra/bwavfile.git synced 2025-12-31 17:00:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

Updated doucmentation to proper comment style

Browse Source
This commit is contained in:
Jamie Hardt
2021-01-01 12:09:26 -08:00
parent 62c9aa7262
commit 28b9272456
2 changed files with 100 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files

210
src/wavereader.rs
View File

@@ -69,12 +69,11 @@ pub struct WaveReader<R: Read + Seek> {
}
impl WaveReader<File> {
/**
* Open a file for reading.
*
* A convenience that opens `path` and calls `Self::new()`
*
*/
/// Open a file for reading.
///
/// A convenience that opens `path` and calls `Self::new()`
pub fn open(path: &str) -> Result<Self, ParserError> {
let inner = File::open(path)?;
return Ok( Self::new(inner)? )
@@ -82,48 +81,45 @@ impl WaveReader<File> {
}
impl<R: Read + Seek> WaveReader<R> {
/**
* Wrap a `Read` struct in a new `WaveReader`.
*
* This is the primary entry point into the `WaveReader` interface. The
* stream passed as `inner` must be at the beginning of the header of the
* WAVE data. For a .wav file, this means it must be at the start of the
* file.
*
* This function does a minimal validation on the provided stream and
* 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 impossible.
*
* ```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)
* }
*
* ```
*
*/
/// Wrap a `Read` struct in a new `WaveReader`.
///
/// This is the primary entry point into the `WaveReader` interface. The
/// stream passed as `inner` must be at the beginning of the header of the
/// WAVE data. For a .wav file, this means it must be at the start of the
/// file.
///
/// This function does a minimal validation on the provided stream and
/// 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 impossible.
/// ```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<Self,ParserError> {
let mut retval = Self { inner };
retval.validate_readable()?;
Ok(retval)
}
/**
* Unwrap the inner reader.
*/
/// Unwrap the inner reader.
pub fn into_inner(self) -> R {
return self.inner;
}
@@ -137,9 +133,8 @@ impl<R: Read + Seek> WaveReader<R> {
Ok(AudioFrameReader::new(self.inner, format, audio_chunk_reader.0, audio_chunk_reader.1)?)
}
/**
* The count of audio frames in the file.
*/
/// The count of audio frames in the file.
pub fn frame_length(&mut self) -> Result<u64, ParserError> {
let (_, data_length ) = self.get_chunk_extent_at_index(DATA_SIG, 0)?;
let format = self.format()?;
@@ -155,7 +150,6 @@ impl<R: Read + Seek> WaveReader<R> {
self.inner.read_wave_fmt()
}
///
/// The Broadcast-WAV metadata record for this file, if present.
///
pub fn broadcast_extension(&mut self) -> Result<Option<Bext>, ParserError> {
@@ -285,35 +279,33 @@ impl<R: Read + Seek> WaveReader<R> {
}
}
/**
* Validate minimal WAVE file.
*
* `Ok(())` if the source is `validate_readable()` AND
*
* - Contains _only_ a `fmt` chunk and `data` chunk, with no other chunks present
* - `fmt` chunk is exactly 16 bytes long and begins _exactly_ at file offset 12
* - `data` content begins _exactly_ at file offset 36
* - is not an RF64/BW64
*
* 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.
*
* ### Examples
*
* ```
* # 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!");
* ```
*/
/// Validate minimal WAVE file.
///
/// `Ok(())` if the source is `validate_readable()` AND
///
/// - Contains _only_ a `fmt` chunk and `data` chunk, with no other chunks present
/// - `fmt` chunk is exactly 16 bytes long and begins _exactly_ at file offset 12
/// - `data` content begins _exactly_ at file offset 36
/// - is not an RF64/BW64
///
/// 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.
///
/// ### Examples
///
/// ```
/// # 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()?;
@@ -327,39 +319,37 @@ impl<R: Read + Seek> WaveReader<R> {
}
}
/**
* Validate Broadcast-WAVE file format
*
* Returns `Ok(())` if `validate_readable()` and file contains a
* Broadcast-WAV metadata record (a `bext` chunk).
*
* ### Examples
*
* ```
* # 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");
* ```
*/
/// Validate Broadcast-WAVE file format
///
/// Returns `Ok(())` if `validate_readable()` and file contains a
/// Broadcast-WAV metadata record (a `bext` chunk).
///
/// ### Examples
///
/// ```
/// # 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()?;
let (_, _) = self.get_chunk_extent_at_index(BEXT_SIG, 0)?;
Ok(())
}
/**
* Verify data is aligned to a block boundary.
*
* Returns `Ok(())` if `validate_readable()` and the start of the
* `data` chunk's content begins at 0x4000.
*/
///
/// Verify data is aligned to a block boundary.
///
/// Returns `Ok(())` if `validate_readable()` and the start of the
/// `data` chunk's content begins at 0x4000.
pub fn validate_data_chunk_alignment(&mut self) -> Result<() , ParserError> {
self.validate_readable()?;
let (start, _) = self.get_chunk_extent_at_index(DATA_SIG, 0)?;
@@ -370,15 +360,13 @@ impl<R: Read + Seek> WaveReader<R> {
}
}
/**
* Verify audio data can be appended immediately to this file.
*
* Returns `Ok(())` if:
* - `validate_readable()`
* - there is a `JUNK` or `FLLR` immediately at the beginning of the chunk
* list adequately large enough to be overwritten by a `ds64` (92 bytes)
* - `data` is the final chunk
*/
/// Verify audio data can be appended immediately to this file.
///
/// Returns `Ok(())` if:
/// - `validate_readable()`
/// - there is a `JUNK` or `FLLR` immediately at the beginning of the chunk
/// list adequately large enough to be overwritten by a `ds64` (92 bytes)
/// - `data` is the final chunk
pub fn validate_prepared_for_append(&mut self) -> Result<(), ParserError> {
self.validate_readable()?;