Nudged version 0.1.5

Cargo.lock

@@ -2,7 +2,7 @@
 # It is not intended for manual editing.
 [[package]]
 name = "bwavfile"
-version = "0.1.4"
+version = "0.1.5"
 dependencies = [
  "byteorder",
  "encoding",

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "bwavfile"
-version = "0.1.4"
+version = "0.1.5"
 authors = ["Jamie Hardt <jamiehardt@me.com>"]
 edition = "2018"
 license = "MIT"

src/audio_frame_reader.rs

@@ -6,6 +6,7 @@ use byteorder::ReadBytesExt;
 
 use super::fmt::{WaveFmt};
 use super::errors::Error;
+use super::CommonFormat;
 
 /// Read audio frames
 /// 
@@ -34,7 +35,7 @@ impl<R: Read + Seek> AudioFrameReader<R> {
             format.block_alignment, (format.bits_per_sample / 8 ) * format.channel_count);
         
 
-        assert!(format.tag == 0x01 , 
+        assert!(format.common_format() == CommonFormat::IntegerPCM , 
                 "Unsupported format tag {:?}", format.tag);
                 
         AudioFrameReader { inner , format }
@@ -43,6 +44,8 @@ impl<R: Read + Seek> AudioFrameReader<R> {
     /// Locate the read position to a different frame
     /// 
     /// Seeks within the audio stream.
+    /// 
+    /// Returns the new location of the read position.
     pub fn locate(&mut self, to :u64) -> Result<u64,Error> {
         let position = to * self.format.block_alignment as u64;
         let seek_result = self.inner.seek(Start(position))?;
@@ -62,6 +65,15 @@ impl<R: Read + Seek> AudioFrameReader<R> {
     /// A single frame is read from the audio stream and the read location
     /// is advanced one frame.
     /// 
+    /// Regardless of the number of bits in the audio sample, this method
+    /// always writes `i32` samples back to the buffer. These samples are 
+    /// written back "left-aligned" so samples that are shorter than i32
+    /// will leave the MSB bits empty. 
+    /// 
+    /// For example: A full-code sample in 16 bit (0xFFFF) will be written 
+    /// back to the buffer as 0x0000FFFF.
+    ///  
+    /// 
     /// ### Panics
     /// 
     /// The `buffer` must have a number of elements equal to the number of 

src/common_format.rs

@@ -48,12 +48,25 @@ fn uuid_from_basic_tag(tag: u16) -> Uuid {
 ///
 #[derive(Debug, Copy, Clone, PartialEq)]
 pub enum CommonFormat {
+    /// Integer linear PCM
     IntegerPCM,
+ 
+    /// IEEE Floating-point Linear PCM
     IeeeFloatPCM,
+ 
+    /// MPEG
     Mpeg,
+ 
+    /// Ambisonic B-Format Linear PCM
     AmbisonicBFormatIntegerPCM,
+ 
+    /// Ambisonic B-Format Float PCM
     AmbisonicBFormatIeeeFloatPCM,
+ 
+    /// An unknown format identified by a basic format tag.
     UnknownBasic(u16),
+ 
+    /// An unknown format identified by an extension UUID.
     UnknownExtended(Uuid),
 }
 

src/fmt.rs

@@ -23,16 +23,16 @@ pub struct ADMAudioID {
 /// Describes a single channel in a WAV file.
 pub struct ChannelDescriptor {
     /// Index, the offset of this channel's samples in one frame.
-    index: u16,
+    pub index: u16,
 
     /// Channel assignment
     /// 
     /// This is either implied (in the case of mono or stereo wave files) or
     /// explicitly given in `WaveFormatExtentended` for files with more tracks.
-    speaker: ChannelMask,
+    pub speaker: ChannelMask,
 
     /// ADM audioTrackUIDs
-    adm_track_audio_ids: Vec<ADMAudioID>,
+    pub adm_track_audio_ids: Vec<ADMAudioID>,
 }
 
 
@@ -197,10 +197,15 @@ impl WaveFmt {
         }
     }
 
+    /// Format or codec of the file's audio data.
+    /// 
+    /// The `CommonFormat` unifies the format tag and the format extension GUID. Use this
+    /// method to determine the codec.
     pub fn common_format(&self) -> CommonFormat {
         CommonFormat::make( self.tag, self.extended_format.map(|ext| ext.type_guid))
     }
 
+    /// Channel descriptors for each channel.
     pub fn channels(&self) -> Vec<ChannelDescriptor> {
         match self.channel_count {
             1 => vec![

src/lib.rs

@@ -121,6 +121,6 @@ mod wavewriter;
 pub use errors::Error;
 pub use wavereader::{WaveReader};
 pub use bext::Bext;
-pub use fmt::{WaveFmt, WaveFmtExtended, ChannelDescriptor};
+pub use fmt::{WaveFmt, WaveFmtExtended, ChannelDescriptor, ChannelMask};
 pub use common_format::CommonFormat;
 pub use audio_frame_reader::AudioFrameReader;

src/wavereader.rs

@@ -5,7 +5,7 @@ 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::raw_chunk_reader::RawChunkReader;
-use super::fmt::WaveFmt;
+use super::fmt::{WaveFmt, ChannelDescriptor, ChannelMask};
 use super::bext::Bext;
 use super::audio_frame_reader::AudioFrameReader;
 use super::chunks::ReadBWaveChunks;
@@ -132,6 +132,37 @@ impl<R: Read + Seek> WaveReader<R> {
         self.chunk_reader(BEXT_SIG, 0)?.read_bext()
     }
 
+    /// Describe the channels in this file
+    /// 
+    /// Returns a vector of channel descriptors, one for each channel
+    /// 
+    /// ```rust
+    /// # use bwavfile::WaveReader;
+    /// # use bwavfile::ChannelMask;
+    /// let mut f = WaveReader::open("tests/media/pt_24bit_51.wav").unwrap();
+    /// 
+    /// let chans = f.channels().unwrap();
+    /// assert_eq!(chans[0].index, 0);
+    /// assert_eq!(chans[0].speaker, ChannelMask::FrontLeft);
+    /// assert_eq!(chans[3].index, 3);
+    /// assert_eq!(chans[3].speaker, ChannelMask::LowFrequency);
+    /// assert_eq!(chans[4].speaker, ChannelMask::BackLeft);
+    /// ```
+    pub fn channels(&mut self) -> Result<Vec<ChannelDescriptor>, ParserError> {
+        
+        let format = self.format()?;
+        let channel_masks : Vec<ChannelMask> = match (format.channel_count, format.extended_format) {
+            (1,_) => vec![ChannelMask::FrontCenter],
+            (2,_) => vec![ChannelMask::FrontLeft, ChannelMask::FrontRight],
+            (n,Some(x)) => ChannelMask::channels(x.channel_mask, n),
+            (n,_) => vec![ChannelMask::DirectOut; n as usize]
+        };
+
+        Ok( (0..format.channel_count).zip(channel_masks)
+            .map(|(i,m)| ChannelDescriptor { index: i, speaker:m, adm_track_audio_ids: vec![] } )
+            .collect() )
+    }
+
     /**
     * Validate file is readable.
     * 

tests/ffprobe_media_tests.json

@@ -1,4 +1,57 @@
 [
+  {
+    "streams": [
+      {
+        "index": 0,
+        "codec_name": "pcm_s24le",
+        "codec_long_name": "PCM signed 24-bit little-endian",
+        "codec_type": "audio",
+        "codec_time_base": "1/48000",
+        "codec_tag_string": "[1][0][0][0]",
+        "codec_tag": "0x0001",
+        "sample_fmt": "s32",
+        "sample_rate": "48000",
+        "channels": 2,
+        "channel_layout": "stereo",
+        "bits_per_sample": 24,
+        "r_frame_rate": "0/0",
+        "avg_frame_rate": "0/0",
+        "time_base": "1/48000",
+        "duration_ts": 4800,
+        "duration": "0.100000",
+        "bit_rate": "2304000",
+        "bits_per_raw_sample": "24",
+        "disposition": {
+          "default": 0,
+          "dub": 0,
+          "original": 0,
+          "comment": 0,
+          "lyrics": 0,
+          "karaoke": 0,
+          "forced": 0,
+          "hearing_impaired": 0,
+          "visual_impaired": 0,
+          "clean_effects": 0,
+          "attached_pic": 0,
+          "timed_thumbnails": 0
+        }
+      }
+    ],
+    "format": {
+      "filename": "tests/media/ff_pink.wav",
+      "nb_streams": 1,
+      "nb_programs": 0,
+      "format_name": "wav",
+      "format_long_name": "WAV / WAVE (Waveform Audio)",
+      "duration": "0.100000",
+      "size": "28902",
+      "bit_rate": "2312160",
+      "probe_score": 99,
+      "tags": {
+        "encoder": "Lavf58.45.100"
+      }
+    }
+  },
   {
     "streams": [
       {

tests/integration_test.rs

@@ -2,6 +2,7 @@ extern crate bwavfile;
 
 use bwavfile::WaveReader;
 use bwavfile::Error;
+use bwavfile::{ ChannelMask}; 
 
 #[test]
 fn test_open() {
@@ -75,3 +76,84 @@ fn test_minimal_wave()  {
         assert!(true);
     }
 }
+
+#[test]
+fn test_read() {
+    let path = "tests/media/audacity_16bit.wav";
+
+    let mut w = WaveReader::open(path).expect("Failure opening test file");
+
+    let mut reader = w.audio_frame_reader().unwrap();
+
+    let mut buffer = reader.create_frame_buffer();
+
+    assert_eq!(reader.read_integer_frame(&mut buffer).unwrap(), 1);
+    assert_eq!(buffer[0], -2823_i32);
+    assert_eq!(reader.read_integer_frame(&mut buffer).unwrap(), 1);
+    assert_eq!(buffer[0], 2012_i32);
+    assert_eq!(reader.read_integer_frame(&mut buffer).unwrap(), 1);
+    assert_eq!(buffer[0], 4524_i32); 
+}
+
+#[test]
+fn test_locate_multichannel_read() {
+    let path = "tests/media/ff_pink.wav";
+
+    let mut w = WaveReader::open(path).expect("Failure opening test file");
+
+    let mut reader = w.audio_frame_reader().unwrap();
+
+    let mut buffer = reader.create_frame_buffer();
+
+    assert_eq!(reader.read_integer_frame(&mut buffer).unwrap(), 1);
+    assert_eq!(buffer[0], 332702_i32);
+    assert_eq!(buffer[1], 3258791_i32);
+    assert_eq!(reader.read_integer_frame(&mut buffer).unwrap(), 1);
+    assert_eq!(buffer[0], -258742_i32); // 0x800000 = 8388608 // 8129866 - 8388608
+    assert_eq!(buffer[1], 0x0D7EF9_i32);
+
+    assert_eq!(reader.locate(100).unwrap(), 100);
+    assert_eq!(reader.read_integer_frame(&mut buffer).unwrap(), 1);
+    assert_eq!(buffer[0], 0x109422_i32);
+    assert_eq!(buffer[1], -698901_i32); // 7689707 - 8388608
+}
+
+#[test]
+fn test_channels_stereo() {
+    let path = "tests/media/ff_pink.wav";
+
+    let mut w = WaveReader::open(path).expect("Failure opening test file");
+    let channels = w.channels().unwrap();
+
+    assert_eq!(channels.len(), 2);
+    assert_eq!(channels[0].index,0);
+    assert_eq!(channels[1].index,1);
+    assert_eq!(channels[0].speaker,ChannelMask::FrontLeft);
+    assert_eq!(channels[1].speaker,ChannelMask::FrontRight);
+}
+
+#[test]
+fn test_channels_mono_no_extended() {
+    let path = "tests/media/audacity_16bit.wav";
+
+    let mut w = WaveReader::open(path).expect("Failure opening test file");
+    let channels = w.channels().unwrap();
+
+    assert_eq!(channels.len(), 1);
+    assert_eq!(channels[0].index,0);
+    assert_eq!(channels[0].speaker,ChannelMask::FrontCenter);
+}
+
+#[test]
+fn test_channels_stereo_no_fmt_extended() {
+    let path = "tests/media/pt_24bit_stereo.wav";
+
+    let mut w = WaveReader::open(path).expect("Failure opening test file");
+    let channels = w.channels().unwrap();
+
+    assert_eq!(channels.len(), 2);
+    assert_eq!(channels[0].index,0);
+    assert_eq!(channels[1].index,1);
+    assert_eq!(channels[0].speaker,ChannelMask::FrontLeft);
+    assert_eq!(channels[1].speaker,ChannelMask::FrontRight);
+}