Update to v0.9.0

To reflect changes in create_frame_buffer()

Cargo.lock

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

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "bwavfile"
-version = "0.1.4"
+version = "0.9.0"
 authors = ["Jamie Hardt <jamiehardt@me.com>"]
 edition = "2018"
 license = "MIT"
@@ -16,5 +16,9 @@ keywords = ["audio", "broadcast", "multimedia","smpte"]
 [dependencies]
 byteorder = "1.3.4"
 encoding = "0.2.33"
+serde_json = "1.0.59"
 uuid = "0.8.1"
-serde_json = "1.0.59"
+
+[profile.release]
+debug = true
+

README.md

@@ -6,11 +6,29 @@
 # bwavfile
 Rust Wave File Reader/Writer with Broadcast-WAV, MBWF and RF64 Support
 
-This is currently a work-in-progress!
+### Features
+
+This is currently a work-in-progress! However many features presently work:
+
+| Feature                               | Read  | Write |
+|---------------------------------------|:-----:|:-----:|
+| Standard .wav files                   | ☑️   | ☑️ |
+| Transparent promotion to RF64/BW64    | ☑️   |    |
+| Unified interface for regular and extended Wave format | ☑️  |  |
+| Channel/speaker map metadata          | ☑️    |    |
+| Ambisonic B-format metadata           | ☑️    |   |
+| EBU Broadcast-WAVE metadata           | ☑️   |    |
+| Basic iXML/ADM metadata               | ☑️    |    |
+| Enhanced iXML metadata support        |        |    |
+| Broadcast-WAVE Level overview `levl` metadata         |    |    |
+| Cue list metadata                     | ☑️   |    |
+| Sampler and instrument metadata       |    |    |
+| Enhanced Wave file form validation    | ☑️   | 🚫   |
+
 
 ## Use Examples
 
-### Reading a File
+### Reading Audio Frames From a File
 
 ```rust
 
@@ -21,8 +39,8 @@ This is currently a work-in-progress!
  assert_eq!(format.sample_rate, 44100);
  assert_eq!(format.channel_count, 1);
  
+ let mut buffer = format.create_frame_buffer();
  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();
  
@@ -30,6 +48,21 @@ This is currently a work-in-progress!
  assert_eq!(read, 1);
 ```
 
+### Accessing Channel Descriptions
+
+```rust
+ use bwavfile::{WaveReader, 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);
+```
+
 ## Note on Testing
 
 All of the media for the integration tests is committed to the respository

bwavefile.code-workspace

@@ -0,0 +1,8 @@
+{
+	"folders": [
+		{
+			"path": "."
+		}
+	],
+	"settings": {}
+}

src/audio_frame_reader.rs

@@ -1,11 +1,12 @@
 use std::io::{Read, Seek};
-use std::io::SeekFrom::{Start,};
+use std::io::SeekFrom::{Start,Current,};
 
 use byteorder::LittleEndian;
 use byteorder::ReadBytesExt;
 
 use super::fmt::{WaveFmt};
 use super::errors::Error;
+use super::CommonFormat;
 
 /// Read audio frames
 /// 
@@ -15,7 +16,9 @@ use super::errors::Error;
 #[derive(Debug)]
 pub struct AudioFrameReader<R: Read + Seek> {
     inner : R,
-    format: WaveFmt
+    format: WaveFmt,
+    start: u64,
+    length: u64
 }
 
 impl<R: Read + Seek> AudioFrameReader<R> {
@@ -28,40 +31,52 @@ impl<R: Read + Seek> AudioFrameReader<R> {
     /// parameter to confirm the `block_alignment` law is fulfilled
     /// and the format tag is readable by this implementation (only
     /// format 0x01 is supported at this time.) 
-    pub fn new(inner: R, format: WaveFmt) -> Self {
+    pub fn new(mut inner: R, format: WaveFmt, start: u64, length: u64) -> Result<Self, Error> {
         assert!(format.block_alignment * 8 == format.bits_per_sample * format.channel_count, 
             "Unable to read audio frames from packed formats: block alignment is {}, should be {}",
             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 }
+        
+        inner.seek(Start(start))?;
+        Ok( AudioFrameReader { inner , format , start, length} )
+    }
+
+    /// Unwrap the inner reader.
+    pub fn into_inner(self) -> R {
+        self.inner
     }
 
     /// Locate the read position to a different frame
     /// 
     /// Seeks within the audio stream.
+    /// 
+    /// Returns the new location of the read position.
+    /// 
+    /// locate() behaves similarly to Read methods in that
+    /// seeking after the end of the audio data is not an error.
     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))?;
-        Ok( seek_result / self.format.block_alignment as u64 )
+        let seek_result = self.inner.seek(Start(self.start + position))?;
+        Ok( (seek_result - self.start) / self.format.block_alignment as u64 )
     }
 
-    /// Create a frame buffer sized to hold frames of the reader
-    /// 
-    /// This is a conveneince method that creates a `Vec<i32>` with
-    /// as many elements as there are channels in the underlying stream. 
-    pub fn create_frame_buffer(&self) -> Vec<i32> {
-        vec![0i32; self.format.channel_count as usize]
-    }
 
     /// Read a frame
     /// 
     /// 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 "right-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 
@@ -73,17 +88,22 @@ impl<R: Read + Seek> AudioFrameReader<R> {
 
         let framed_bits_per_sample = self.format.block_alignment * 8 / self.format.channel_count;
 
-        for n in 0..(self.format.channel_count as usize) {
-            buffer[n] = match (self.format.bits_per_sample, framed_bits_per_sample) {
-                (0..=8,8) => self.inner.read_u8()? as i32 - 0x80_i32, // EBU 3285 §A2.2
-                (9..=16,16) => self.inner.read_i16::<LittleEndian>()? as i32,
-                (10..=24,24) => self.inner.read_i24::<LittleEndian>()?,
-                (25..=32,32) => self.inner.read_i32::<LittleEndian>()?,
-                (b,_)=> panic!("Unrecognized integer format, bits per sample {}, channels {}, block_alignment {}", 
-                    b, self.format.channel_count, self.format.block_alignment)
-            }
-        }
+        let tell = self.inner.seek(Current(0))?;
 
-        Ok( 1 )
+        if (tell - self.start) < self.length {
+            for n in 0..(self.format.channel_count as usize) {
+                buffer[n] = match (self.format.bits_per_sample, framed_bits_per_sample) {
+                    (0..=8,8) => self.inner.read_u8()? as i32 - 0x80_i32, // EBU 3285 §A2.2
+                    (9..=16,16) => self.inner.read_i16::<LittleEndian>()? as i32,
+                    (10..=24,24) => self.inner.read_i24::<LittleEndian>()?,
+                    (25..=32,32) => self.inner.read_i32::<LittleEndian>()?,
+                    (b,_)=> panic!("Unrecognized integer format, bits per sample {}, channels {}, block_alignment {}", 
+                        b, self.format.channel_count, self.format.block_alignment)
+                }
+            }
+            Ok( 1 )
+        } else {
+            Ok( 0 )
+        }
     }
 }

src/common_format.rs

@@ -22,19 +22,19 @@ const BASIC_EXTENDED: u16   = 0xFFFE;
 
 */
 
-const UUID_PCM: Uuid =           Uuid::from_bytes([0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10, 0x00, 
+pub const UUID_PCM: Uuid =           Uuid::from_bytes([0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10, 0x00, 
     0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71]);
 
-const UUID_FLOAT: Uuid =         Uuid::from_bytes([0x03, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10, 0x00,
+pub const UUID_FLOAT: Uuid =         Uuid::from_bytes([0x03, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10, 0x00,
     0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71]);
 
-const UUID_MPEG: Uuid =          Uuid::from_bytes([0x50, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10, 0x00,
+pub const UUID_MPEG: Uuid =          Uuid::from_bytes([0x50, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10, 0x00,
     0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71]);
 
-const UUID_BFORMAT_PCM: Uuid =   Uuid::from_bytes([0x01, 0x00, 0x00, 0x00, 0x21, 0x07, 0xd3, 0x11, 
+pub const UUID_BFORMAT_PCM: Uuid =   Uuid::from_bytes([0x01, 0x00, 0x00, 0x00, 0x21, 0x07, 0xd3, 0x11, 
     0x86, 0x44, 0xc8, 0xc1, 0xca, 0x00, 0x00, 0x00]);
 
-const UUID_BFORMAT_FLOAT: Uuid = Uuid::from_bytes([0x03, 0x00, 0x00, 0x00, 0x21, 0x07, 0xd3, 0x11,
+pub const UUID_BFORMAT_FLOAT: Uuid = Uuid::from_bytes([0x03, 0x00, 0x00, 0x00, 0x21, 0x07, 0xd3, 0x11,
     0x86, 0x44, 0xc8, 0xc1, 0xca, 0x00, 0x00, 0x00]);
 
 
@@ -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),
 }
 
@@ -83,4 +96,4 @@ impl CommonFormat {
             Self::UnknownExtended(x) => ( BASIC_EXTENDED, x)
         }
     }
-}
+}

src/cue.rs

@@ -0,0 +1,258 @@
+use super::fourcc::{FourCC,ReadFourCC, LABL_SIG, NOTE_SIG, LTXT_SIG};
+use super::list_form::collect_list_form;
+
+use byteorder::{ReadBytesExt, LittleEndian};
+
+use encoding::{DecoderTrap};
+use encoding::{Encoding};
+use encoding::all::ASCII;
+
+use std::io::{Cursor, Error, Read};
+
+#[derive(Copy,Clone, Debug)]
+struct RawCue {
+    cue_point_id : u32,
+    frame : u32,
+    chunk_id : FourCC,
+    chunk_start : u32,
+    block_start : u32,
+    frame_offset : u32
+}
+
+impl RawCue {
+    fn read_from(data : &[u8]) -> Result<Vec<Self>,Error> {
+        let mut rdr = Cursor::new(data);
+        let count = rdr.read_u32::<LittleEndian>()?;
+        let mut retval : Vec<Self> = vec![];
+
+        for _ in 0..count {
+            retval.push( Self {
+                cue_point_id : rdr.read_u32::<LittleEndian>()?,
+                frame : rdr.read_u32::<LittleEndian>()?,
+                chunk_id : rdr.read_fourcc()?,
+                chunk_start : rdr.read_u32::<LittleEndian>()?,
+                block_start : rdr.read_u32::<LittleEndian>()?,
+                frame_offset : rdr.read_u32::<LittleEndian>()?
+            })
+        }
+
+        Ok( retval )
+    }
+}
+
+#[derive(Clone, Debug)]
+struct RawLabel {
+    cue_point_id : u32,
+    text : Vec<u8>
+}
+
+impl RawLabel {
+    fn read_from(data : &[u8]) -> Result<Self, Error> {
+        let mut rdr = Cursor::new(data);
+        let length = data.len();
+
+        Ok( Self {
+            cue_point_id : rdr.read_u32::<LittleEndian>()?,
+            text : {
+                let mut buf = vec![0u8; (length - 4) as usize ];
+                rdr.read_exact(&mut buf)?;
+                buf
+            }
+        })
+    }
+}
+
+#[derive(Clone, Debug)]
+struct RawNote {
+    cue_point_id : u32,
+    text : Vec<u8>
+}
+
+impl RawNote {
+    fn read_from(data : &[u8]) -> Result<Self, Error> {
+        let mut rdr = Cursor::new(data);
+        let length = data.len();
+
+        Ok( Self {
+            cue_point_id : rdr.read_u32::<LittleEndian>()?,
+            text : {
+                let mut buf = vec![0u8; (length - 4) as usize ];
+                rdr.read_exact(&mut buf)?;
+                buf
+            }
+        })
+    }
+}
+
+#[derive(Clone, Debug)]
+struct RawLtxt { 
+    cue_point_id : u32,
+    frame_length : u32,
+    purpose : FourCC,
+    country : u16,
+    language : u16,
+    dialect : u16,
+    code_page : u16,
+    text: Option<Vec<u8>>
+}
+
+impl RawLtxt {
+    fn read_from(data : &[u8]) -> Result<Self, Error> {
+        let mut rdr = Cursor::new(data);
+        let length = data.len();
+
+        Ok( Self {
+            cue_point_id : rdr.read_u32::<LittleEndian>()?,
+            frame_length : rdr.read_u32::<LittleEndian>()?,
+            purpose : rdr.read_fourcc()?,
+            country : rdr.read_u16::<LittleEndian>()?,
+            language : rdr.read_u16::<LittleEndian>()?,
+            dialect : rdr.read_u16::<LittleEndian>()?,
+            code_page : rdr.read_u16::<LittleEndian>()?,
+            text : {
+                if length - 20 > 0 {
+                    let mut buf = vec![0u8; (length - 20) as usize];
+                    rdr.read_exact(&mut buf)?;
+                    Some( buf )
+                } else {
+                    None
+                }
+            }
+        })
+    }
+}
+
+#[derive(Clone, Debug)]
+enum RawAdtlMember {
+    Label(RawLabel),
+    Note(RawNote),
+    LabeledText(RawLtxt),
+    Unrecognized(FourCC)
+}
+
+impl RawAdtlMember {
+    fn collect_from(chunk : &[u8]) -> Result<Vec<RawAdtlMember>,Error> {
+        let chunks = collect_list_form(chunk)?;
+        let mut retval : Vec<RawAdtlMember> = vec![];
+
+        for chunk in chunks.iter() {
+            retval.push( 
+                match chunk.signature {
+                    LABL_SIG => RawAdtlMember::Label( RawLabel::read_from(&chunk.contents)? ),
+                    NOTE_SIG => RawAdtlMember::Note( RawNote::read_from(&chunk.contents)? ),
+                    LTXT_SIG => RawAdtlMember::LabeledText( RawLtxt::read_from(&chunk.contents)? ),
+                    x => RawAdtlMember::Unrecognized(x)
+                }
+            )
+        }
+        Ok( retval )
+    }
+}
+
+trait AdtlMemberSearch {
+    fn labels_for_cue_point(&self, id: u32) -> Vec<&RawLabel>;
+    fn notes_for_cue_point(&self, id : u32) -> Vec<&RawNote>;
+    fn ltxt_for_cue_point(&self, id: u32) -> Vec<&RawLtxt>;
+}
+
+impl AdtlMemberSearch for Vec<RawAdtlMember> {
+
+    fn labels_for_cue_point(&self, id: u32) -> Vec<&RawLabel> {
+        self.iter().filter_map(|item| {
+            match item {
+                RawAdtlMember::Label(x) if x.cue_point_id == id => Some(x),
+                _ => None
+            }
+        })
+        .collect()
+    }
+    
+    fn notes_for_cue_point(&self, id: u32) -> Vec<&RawNote> { 
+        self.iter().filter_map(|item| {
+            match item {
+                RawAdtlMember::Note(x) if x.cue_point_id == id => Some(x),
+                _ => None
+            }
+        })
+        .collect()  
+    }
+
+    fn ltxt_for_cue_point(&self, id: u32) -> Vec<&RawLtxt> {
+        self.iter().filter_map(|item| {
+            match item {
+                RawAdtlMember::LabeledText(x) if x.cue_point_id == id => Some(x),
+                _ => None
+            }
+        })
+        .collect()
+    }
+}
+
+/// A cue point recorded in the `cue` and `adtl` metadata.
+/// 
+/// 
+pub struct Cue {
+
+    /// Unique numeric identifier for this cue
+    pub ident : u32,
+
+    /// The time of this marker
+    pub frame : u32,
+
+    /// The length of this marker, if it is a range
+    pub length : Option<u32>,
+
+    /// The text "label"/name of this marker if provided
+    pub label : Option<String>,
+
+    /// The text "note"/comment of this marker if provided
+    pub note : Option<String>
+}
+
+
+fn convert_to_cue_string(buffer : &[u8]) -> String {
+    let trimmed : Vec<u8> = buffer.iter().take_while(|c| **c != 0 as u8).cloned().collect();
+    ASCII.decode(&trimmed, DecoderTrap::Ignore).expect("Error decoding text")
+}
+
+impl Cue {
+
+    pub fn collect_from(cue_chunk : &[u8], adtl_chunk : Option<&[u8]>) -> Result<Vec<Cue>, Error> {
+        let raw_cues = RawCue::read_from(cue_chunk)?;
+        let raw_adtl : Vec<RawAdtlMember>;
+
+        if let Some(adtl) = adtl_chunk {
+            raw_adtl = RawAdtlMember::collect_from(adtl)?;
+        } else {
+            raw_adtl = vec![];
+        }
+        
+
+        Ok( 
+            raw_cues.iter()
+            .map(|i| {
+                Cue {
+                    ident : i.cue_point_id,
+                    frame : i.frame,
+                    length: {
+                        raw_adtl.ltxt_for_cue_point(i.cue_point_id).first()
+                        .filter(|x| x.purpose == FourCC::make(b"rgn "))
+                        .map(|x| x.frame_length)
+                    },
+                    label: {
+                        raw_adtl.labels_for_cue_point(i.cue_point_id).iter()
+                            .map(|s| convert_to_cue_string(&s.text))
+                            .next()
+                    },
+                    note : {
+                        raw_adtl.notes_for_cue_point(i.cue_point_id).iter()
+                            //.filter_map(|x| str::from_utf8(&x.text).ok())
+                            .map(|s| convert_to_cue_string(&s.text))
+                            .next()
+                    }
+                }
+            }).collect() 
+        )
+    }
+
+}

src/fmt.rs

@@ -1,48 +1,43 @@
-use std::convert::TryFrom;
 use uuid::Uuid;
-use super::errors::Error;
-use super::common_format::CommonFormat;
+use super::common_format::{CommonFormat, UUID_PCM};
 
+#[allow(dead_code)]
 
-/// ADM Audio ID record
+/// ADM Audio ID record.
 /// 
 /// This structure relates a channel in the wave file to either a common ADM
 /// channel definition or further definition in the WAV file's ADM metadata 
 /// chunk.
 /// 
 /// An individual channel in a WAV file can have multiple Audio IDs in an ADM 
-/// AudioProgramme.
+/// `AudioProgramme`.
 /// 
 /// See BS.2088-1 § 8, also BS.2094, also blahblahblah...
 pub struct ADMAudioID {
-    track_uid: [char; 12],
-    channel_format_ref: [char; 14],
-    pack_ref: [char; 11]
+    pub track_uid: [char; 12],
+    pub channel_format_ref: [char; 14],
+    pub pack_ref: [char; 11]
 }
 
 /// 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>,
 }
 
 
-
-/*
-https://docs.microsoft.com/en-us/windows-hardware/drivers/audio/subformat-guids-for-compressed-audio-formats
-
-These are from http://dream.cs.bath.ac.uk/researchdev/wave-ex/mulchaud.rtf
-*/
-
+/// A bitmask indicating which channels are present in 
+/// the file.
+/// 
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub enum ChannelMask {
     DirectOut        = 0x0,
@@ -149,7 +144,9 @@ pub struct WaveFmt {
     /// Count of audio channels in each frame
     pub channel_count: u16,
 
-    /// Sample rate of the audio data
+    /// Playback rate of the audio data
+    ///
+    /// In frames per second.
     pub sample_rate: u32,
 
     /// Count of bytes per second
@@ -163,6 +160,16 @@ pub struct WaveFmt {
     pub block_alignment: u16,
 
     /// Count of bits stored in the file per sample
+    ///
+    /// By rule, `bits_per_sample % 8 == 0` for Broadcast-Wave files.
+    ///
+    /// Modern clients will encode
+    /// unusual sample sizes in normal byte sizes but will set the valid_bits
+    /// flag in extended format record.
+    ///
+    /// Generally speaking this will be true for all modern wave files, though
+    /// there was an historical "packed" stereo format of 20 bits per sample,
+    /// 5 bytes per frame, 5 bytes block alignment.
     pub bits_per_sample: u16,
 
     /// Extended format description
@@ -193,14 +200,38 @@ impl WaveFmt {
             bytes_per_second: container_bytes_per_sample as u32 * sample_rate * channel_count as u32,
             block_alignment: container_bytes_per_sample * channel_count,
             bits_per_sample: container_bits_per_sample,
-            extended_format: None
+            extended_format: {
+                if channel_count > 2 {
+                    Some( WaveFmtExtended {
+                        channel_mask : !(0xFFFF_FFFF << channel_count),
+                        type_guid: UUID_PCM,
+                        valid_bits_per_sample: bits_per_sample
+                    })
+                } else {
+                    None
+                }
+            }
         }
     }
 
+    /// 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))
     }
 
+    /// Create a frame buffer sized to hold frames for a reader or writer
+    /// 
+    /// This is a conveneince method that creates a `Vec<i32>` with
+    /// as many elements as there are channels in the underlying stream. 
+    pub fn create_frame_buffer(&self) -> Vec<i32> {
+        vec![0i32; self.channel_count as usize]
+    }
+
+
+    /// Channel descriptors for each channel.
     pub fn channels(&self) -> Vec<ChannelDescriptor> {
         match self.channel_count {
             1 => vec![

src/fourcc.rs

@@ -102,9 +102,18 @@ pub const DATA_SIG: FourCC = FourCC::make(b"data");
 pub const FMT__SIG: FourCC = FourCC::make(b"fmt ");
 
 pub const BEXT_SIG: FourCC = FourCC::make(b"bext");
+//pub const FACT_SIG: FourCC = FourCC::make(b"fact");
 
 pub const JUNK_SIG: FourCC = FourCC::make(b"JUNK");
 pub const FLLR_SIG: FourCC = FourCC::make(b"FLLR");
+pub const ELM1_SIG: FourCC = FourCC::make(b"elm1");
+pub const LIST_SIG: FourCC = FourCC::make(b"LIST");
+
+pub const CUE__SIG: FourCC = FourCC::make(b"cue ");
+pub const ADTL_SIG: FourCC = FourCC::make(b"adtl");
+pub const LABL_SIG: FourCC = FourCC::make(b"labl");
+pub const NOTE_SIG: FourCC = FourCC::make(b"note");
+pub const LTXT_SIG: FourCC = FourCC::make(b"ltxt");
 
 
 #[cfg(test)]

src/lib.rs

@@ -15,6 +15,7 @@ production.
 
 Apps we test against:
 - Avid Pro Tools
+- iZotope RX Audio Editor
 - FFMpeg
 - Audacity
 
@@ -66,7 +67,9 @@ Things that are _not_ necessarily in the scope of this package:
 
 
 ### Other resources
-- [RFC 3261][rfc3261] (June 1998) "WAVE and AVI Codec Registries" 
+- [RFC 3261][rfc3261] (June 1998) "WAVE and AVI Codec Registries"
+- [Sampler Metadata](http://www.piclist.com/techref/io/serial/midi/wave.html)
+- [Cue list, label and other metadata](https://sites.google.com/site/musicgapi/technical-documents/wav-file-format#smpl)
 - [Peter Kabal, McGill University](http://www-mmsp.ece.mcgill.ca/Documents/AudioFormats/WAVE/WAVE.html)
  - [Multimedia Programming Interface and Data Specifications 1.0](http://www-mmsp.ece.mcgill.ca/Documents/AudioFormats/WAVE/Docs/riffmci.pdf) 
     (August 1991), IBM Corporation and Microsoft Corporation
@@ -82,7 +85,7 @@ Things that are _not_ necessarily in the scope of this package:
   - [Supplement 6](https://tech.ebu.ch/docs/tech/tech3285s6.pdf) (October 2009): Dolby Metadata 
 - [EBU Tech R099](https://tech.ebu.ch/docs/r/r099.pdf) (October 2011) "‘Unique’ Source Identifier (USID) for use in the 
   <OriginatorReference> field of the Broadcast Wave Format"
-- [EBU Tech R098](https://tech.ebu.ch/docs/r/r098.pdf) (1999) "Format for the <CodingHistory> field in Broadcast Wave Format files, BWF"
+- [EBU Tech R098](https://tech.ebu.ch/docs/r/r098.pdf) (1999) "Format for the &lt;CodingHistory&gt; field in Broadcast Wave Format files, BWF"
 
 [ebu3285]: https://tech.ebu.ch/docs/tech/tech3285.pdf
 [ebu3306v1]: https://tech.ebu.ch/docs/tech/tech3306v1_1.pdf
@@ -108,10 +111,11 @@ mod common_format;
 
 mod parser;
 
-
-mod raw_chunk_reader;
 mod audio_frame_reader;
+mod list_form;
+
 mod chunks;
+mod cue;
 mod bext;
 mod fmt;
 
@@ -119,8 +123,10 @@ mod wavereader;
 mod wavewriter;
 
 pub use errors::Error;
-pub use wavereader::{WaveReader};
+pub use wavereader::WaveReader;
+pub use wavewriter::WaveWriter;
 pub use bext::Bext;
-pub use fmt::{WaveFmt, WaveFmtExtended, ChannelDescriptor};
+pub use fmt::{WaveFmt, WaveFmtExtended, ChannelDescriptor, ChannelMask, ADMAudioID};
 pub use common_format::CommonFormat;
-pub use audio_frame_reader::AudioFrameReader;
+pub use audio_frame_reader::AudioFrameReader;
+pub use cue::Cue;

src/list_form.rs

@@ -0,0 +1,40 @@
+use super::fourcc::{FourCC, ReadFourCC};
+use byteorder::{ReadBytesExt, LittleEndian};
+use std::io::{Cursor, Error, Read};
+
+pub struct ListFormItem {
+    pub signature : FourCC,
+    pub contents : Vec<u8>
+}
+
+/// A helper that will accept a LIST chunk as a [u8]
+/// and give you back each segment
+/// 
+pub fn collect_list_form(list_contents :& [u8]) -> Result<Vec<ListFormItem>, Error> {
+    let mut cursor = Cursor::new(list_contents);
+    let mut remain = list_contents.len();
+    let _ = cursor.read_fourcc()?; // skip signature
+
+    remain -= 4;
+    let mut retval : Vec<ListFormItem> = vec![];
+
+    while remain > 0 {
+        let this_sig = cursor.read_fourcc()?;
+        let this_size = cursor.read_u32::<LittleEndian>()? as usize;
+        remain -= 8;
+        let mut content_buf = vec![0u8; this_size];
+        cursor.read_exact(&mut content_buf)?;
+        remain -= this_size;
+        
+        retval.push( ListFormItem { signature : this_sig, contents : content_buf } );
+        
+        if this_size % 2 == 1 {
+            cursor.read_u8()?;
+            //panic!("Got this far!");
+            remain -= 1;
+        }
+    }
+    
+
+    Ok( retval )
+}

src/parser.rs

@@ -45,6 +45,7 @@ pub struct Parser<R: Read + Seek> {
     ds64state: HashMap<FourCC,u64>
 }
 
+#[derive(Debug, PartialEq, Eq)]
 pub struct ChunkIteratorItem {
     pub signature: FourCC,
     pub start: u64,

src/raw_chunk_reader.rs

@@ -1,73 +0,0 @@
-use std::cmp::min;
-
-use std::io::SeekFrom;
-use std::io::SeekFrom::{Start, Current, End};
-use std::io::{Seek,Read,Error,ErrorKind};
-
-// I'm not sure this hasn't already been written somewhere in
-// std but I'm just doing this here as an exercise.
-#[derive(Debug)]
-pub struct RawChunkReader<'a, R: Read + Seek> {
-    reader: &'a mut R,
-    start: u64,
-    length: u64,
-    position: u64
-}
-
-impl<'a,R: Read + Seek> RawChunkReader<'a, R> {
-    pub fn new(reader: &'a mut R, start: u64, length: u64) -> Self {
-        return Self {
-            reader: reader, 
-            start: start, 
-            length: length, 
-            position: 0
-        }
-    }
-
-    pub fn length(&self) -> u64 {
-        self.length
-    } 
-}
-
-impl<'a, R:Read + Seek> Read for RawChunkReader<'_, R> {
-    fn read(&mut self, buf: &mut [u8]) -> Result<usize, Error> { 
-        if self.position >= self.length {
-            Err(Error::new(ErrorKind::UnexpectedEof, "RawChunkReader encountered end-of-file"))
-        } else {
-            self.reader.seek(Start(self.start + self.position))?;
-            let to_read = min(self.length - self.position, buf.len() as u64);
-            self.reader.take(to_read).read(buf)?;
-            self.position += to_read;
-            Ok(to_read as usize)
-        }
-    }
-}
-
-impl<'a, R:Read + Seek> Seek for RawChunkReader<'_, R> {
-    fn seek(&mut self, seek: SeekFrom) -> Result<u64, std::io::Error> { 
-        match seek {
-            Start(s) => {
-                self.position = s;
-                Ok(self.position)
-            },
-            Current(s) => {
-                let new_position = s + self.position as i64;
-                if new_position < 0 {
-                    Err( Error::new(ErrorKind::Other, "Attempted seek before beginning of chunk") )
-                } else {
-                    self.position = new_position as u64;
-                    Ok(self.position)
-                }
-            },
-            End(s) => {
-                let new_position = s + self.length as i64;
-                if new_position < 0 {
-                    Err( Error::new(ErrorKind::Other, "Attempted seek before beginning of chunk") )
-                } else {
-                    self.position = new_position as u64;
-                    Ok(self.position)
-                }
-            }
-        }
-    }
-}

src/wavereader.rs

@@ -1,16 +1,17 @@
 
+use std::io::SeekFrom;
 use std::fs::File;
 
 use super::parser::Parser;
-use super::fourcc::{FourCC, FMT__SIG,DATA_SIG, BEXT_SIG, JUNK_SIG, FLLR_SIG};
+use super::fourcc::{FourCC, ReadFourCC, FMT__SIG,DATA_SIG, BEXT_SIG, LIST_SIG, JUNK_SIG, FLLR_SIG, CUE__SIG, ADTL_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;
+use super::cue::Cue;
 
-
+use std::io::Cursor;
 use std::io::{Read, Seek};
 
 
@@ -26,7 +27,7 @@ use std::io::{Read, Seek};
  * assert_eq!(format.channel_count, 1);
  * 
  * let mut frame_reader = r.audio_frame_reader().unwrap();
- * let mut buffer = frame_reader.create_frame_buffer();
+ * let mut buffer = format.create_frame_buffer();
  * 
  * let read = frame_reader.read_integer_frame(&mut buffer).unwrap();
  * 
@@ -65,7 +66,7 @@ impl<R: Read + Seek> WaveReader<R> {
      * 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 impoossible.
+     * essential components that make interpreting the audio data impossible.
      * 
      * ```rust
      * use std::fs::File;
@@ -100,13 +101,13 @@ impl<R: Read + Seek> WaveReader<R> {
         return self.inner;
     }
 
-    /**
-     * Create an `AudioFrameReader` for reading each audio frame.
-    */
-    pub fn audio_frame_reader(&mut self) -> Result<AudioFrameReader<RawChunkReader<R>>, ParserError> {
+    ///
+    /// Create an `AudioFrameReader` for reading each audio frame and consume the `WaveReader`.
+    ///
+    pub fn audio_frame_reader(mut self) -> Result<AudioFrameReader<R>, ParserError> {
         let format = self.format()?;
-        let audio_chunk_reader = self.chunk_reader(DATA_SIG, 0)?;
-        Ok(AudioFrameReader::new(audio_chunk_reader, format))
+        let audio_chunk_reader = self.get_chunk_extent_at_index(DATA_SIG, 0)?;
+        Ok(AudioFrameReader::new(self.inner, format, audio_chunk_reader.0, audio_chunk_reader.1)?)
     }
 
     /**
@@ -118,20 +119,128 @@ impl<R: Read + Seek> WaveReader<R> {
         Ok( data_length / (format.block_alignment as u64) )
     } 
 
-    /**
-     * Sample and frame format of this wave file.
-     */
+    
+    /// Sample and frame format of this wave file.
+    ///
     pub fn format(&mut self) -> Result<WaveFmt, ParserError> {
-        self.chunk_reader(FMT__SIG, 0)?.read_wave_fmt()
+        let (start, _) = self.get_chunk_extent_at_index(FMT__SIG, 0)?;
+        self.inner.seek(SeekFrom::Start(start))?;
+        self.inner.read_wave_fmt()
     }
 
-    /**
-     * The Broadcast-WAV metadata record for this file.
-     */
-    pub fn broadcast_extension(&mut self) -> Result<Bext, ParserError> {
-        self.chunk_reader(BEXT_SIG, 0)?.read_bext()
+    ///
+    /// The Broadcast-WAV metadata record for this file, if present.
+    /// 
+    pub fn broadcast_extension(&mut self) -> Result<Option<Bext>, ParserError> {
+        let mut bext_buff : Vec<u8> = vec![ ];
+        let result = self.read_chunk(BEXT_SIG, 0, &mut bext_buff)?;
+        if result > 0 {
+            let mut bext_cursor = Cursor::new(bext_buff);
+            Ok( Some( bext_cursor.read_bext()? ) )
+        } else {
+            Ok( None)
+        }
+
     }
 
+    /// 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() )
+    }
+
+    /// Read cue points.
+    /// 
+    /// ```rust
+    /// use bwavfile::WaveReader;
+    /// use bwavfile::Cue;
+    /// 
+    /// let mut f = WaveReader::open("tests/media/izotope_test.wav").unwrap();
+    /// let cue_points = f.cue_points().unwrap();
+    /// 
+    /// assert_eq!(cue_points.len(), 3);
+    /// assert_eq!(cue_points[0].ident, 1);
+    /// assert_eq!(cue_points[0].frame, 12532);
+    /// assert_eq!(cue_points[0].length, None);
+    /// assert_eq!(cue_points[0].label, Some(String::from("Marker 1")));
+    /// assert_eq!(cue_points[0].note, Some(String::from("Marker 1 Comment")));
+    /// 
+    /// assert_eq!(cue_points[1].ident, 2);
+    /// assert_eq!(cue_points[1].frame, 20997);
+    /// assert_eq!(cue_points[1].length, None);
+    /// assert_eq!(cue_points[1].label, Some(String::from("Marker 2")));
+    /// assert_eq!(cue_points[1].note, Some(String::from("Marker 2 Comment"))); 
+    /// 
+    /// assert_eq!(cue_points[2].ident, 3);
+    /// assert_eq!(cue_points[2].frame, 26711);
+    /// assert_eq!(cue_points[2].length, Some(6465));
+    /// assert_eq!(cue_points[2].label, Some(String::from("Timed Region")));
+    /// assert_eq!(cue_points[2].note, Some(String::from("Region Comment"))); 
+    /// 
+    /// ```
+    pub fn cue_points(&mut self) -> Result<Vec<Cue>,ParserError> {
+        let mut cue_buffer : Vec<u8> = vec![];
+        let mut adtl_buffer : Vec<u8> = vec![];
+
+        let cue_read = self.read_chunk(CUE__SIG, 0, &mut cue_buffer)?;
+        let adtl_read = self.read_list(ADTL_SIG, &mut adtl_buffer)?;
+
+        match (cue_read, adtl_read) {
+            (0,_) => Ok( vec![] ),
+            (_,0) => Ok( Cue::collect_from(&cue_buffer, None)? ),
+            (_,_) => Ok( Cue::collect_from(&cue_buffer, Some(&adtl_buffer) )? )
+        }
+    }
+
+    /// Read iXML data.
+    /// 
+    /// The iXML data will be appended to `buffer`.
+    /// If there are no iXML metadata present in the file, 
+    /// Ok(0) will be returned.
+    pub fn read_ixml(&mut self, buffer: &mut Vec<u8>) -> Result<usize, ParserError> {
+        let ixml_fourcc = FourCC::make(b"iXML");
+        self.read_chunk(ixml_fourcc, 0, buffer) 
+    }
+
+    /// Read AXML data.
+    /// 
+    /// The axml data will be appended to `buffer`. By convention this will 
+    /// generally be ADM metadata.
+    /// 
+    /// If there are no axml metadata present in the file, 
+    /// Ok(0) will be returned
+    pub fn read_axml(&mut self, buffer: &mut Vec<u8>) -> Result<usize, ParserError> {
+        let axml_fourcc = FourCC::make(b"axml");
+        self.read_chunk(axml_fourcc, 0, buffer)
+    }
+
+
     /**
     * Validate file is readable.
     * 
@@ -157,6 +266,8 @@ impl<R: Read + Seek> WaveReader<R> {
      * `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
@@ -185,7 +296,7 @@ impl<R: Read + Seek> WaveReader<R> {
             .into_chunk_list()?.iter().map(|c| c.signature ).collect();
 
         if chunk_fourccs == vec![FMT__SIG, DATA_SIG] {
-            Ok(())
+            Ok(()) /* FIXME: finish implementation */
         } else {
             Err( ParserError::NotMinimalWaveFile )
         }
@@ -269,20 +380,77 @@ impl<R: Read + Seek> WaveReader<R> {
     }
 }
 
-impl<R:Read+Seek> WaveReader<R> { /* Private Implementation */
+impl<R:Read+Seek> WaveReader<R> {
 
-    fn chunk_reader(&mut self, signature: FourCC, at_index: u32) -> Result<RawChunkReader<R>, ParserError> {
-        let (start, length) = self.get_chunk_extent_at_index(signature, at_index)?;
-        Ok( RawChunkReader::new(&mut self.inner, start, length) )
-    } 
+    // Private implementation
+    //
+    // As time passes thi get smore obnoxious because I haven't implemented recursive chunk 
+    // parsing in the raw parser and I'm working around it
 
-    fn get_chunk_extent_at_index(&mut self, fourcc: FourCC, index: u32) -> Result<(u64,u64), ParserError> {
+    // fn chunk_reader(&mut self, signature: FourCC, at_index: u32) -> Result<RawChunkReader<R>, ParserError> {
+    //     let (start, length) = self.get_chunk_extent_at_index(signature, at_index)?;
+    //     Ok( RawChunkReader::new(&mut self.inner, start, length) )
+    // } 
+
+    fn read_list(&mut self, ident: FourCC, buffer: &mut Vec<u8>) -> Result<usize, ParserError> {
+        if let Some(index) = self.get_list_form(ident)? {
+            self.read_chunk(LIST_SIG, index, buffer)
+        } else {
+            Ok( 0 )
+        }
+    }
+
+
+    fn read_chunk(&mut self, ident: FourCC, at: u32, mut buffer: &mut Vec<u8>) -> Result<usize, ParserError> {
+
+        match self.get_chunk_extent_at_index(ident, at) {
+            Ok((start, length)) => {
+                buffer.resize(length as usize, 0x0);
+                self.inner.seek(SeekFrom::Start(start))?;
+                self.inner.read(&mut buffer).map_err(|e| ParserError::IOError(e))
+            },
+            Err(ParserError::ChunkMissing { signature : _} ) => Ok(0),
+            Err( any ) => Err(any.into())
+        }
+    }
+
+    /// Extent of every chunk with the given fourcc
+    fn get_chunks_extents(&mut self, fourcc: FourCC) -> Result<Vec<(u64,u64)>, ParserError> {
         let p = Parser::make(&mut self.inner)?.into_chunk_list()?;
 
-        if let Some(chunk) = p.iter().filter(|item| item.signature == fourcc).nth(index as usize) {
-            Ok ((chunk.start, chunk.length))
+        Ok( p.iter().filter(|item| item.signature == fourcc)
+            .map(|item| (item.start, item.length)).collect() )
+    }
+
+    /// Index of first LIST for with the given FORM fourcc
+    fn get_list_form(&mut self, fourcc: FourCC) -> Result<Option<u32>, ParserError> {
+        for (n, (start, _)) in self.get_chunks_extents(LIST_SIG)?.iter().enumerate() {
+            self.inner.seek(SeekFrom::Start(*start as u64))?;
+            let this_fourcc = self.inner.read_fourcc()?;
+            if this_fourcc == fourcc {
+                return Ok( Some( n as u32 ) );
+            }
+        }
+
+        Ok( None )
+    }
+
+    fn get_chunk_extent_at_index(&mut self, fourcc: FourCC, index: u32) -> Result<(u64,u64), ParserError> {
+        if let Some((start, length)) = self.get_chunks_extents(fourcc)?.iter().nth(index as usize) {
+            Ok ((*start, *length))
         } else {
-            Err( ParserError::ChunkMissing { signature : fourcc })
+            Err( ParserError::ChunkMissing { signature : fourcc } )
         }
     }
 }
+
+#[test]
+fn test_list_form() {
+    let mut f = WaveReader::open("tests/media/izotope_test.wav").unwrap();
+    let mut buf : Vec<u8> = vec![];
+    
+    f.read_list(ADTL_SIG, &mut buf).unwrap();
+
+    assert_ne!(buf.len(),  0);
+
+}

src/wavewriter.rs

@@ -1,104 +1,252 @@
-use std::io::{Write, Seek, SeekFrom};
 use std::fs::File;
-use std::io::Cursor;
+use std::io::{Write,Seek,SeekFrom};
 
-use super::errors::Error;
-use super::chunks::{WriteBWaveChunks};
-use super::bext::Bext;
-use super::fmt::{WaveFmt};
-use super::fourcc::{FourCC, RIFF_SIG, WAVE_SIG, FMT__SIG, JUNK_SIG, BEXT_SIG, DATA_SIG, WriteFourCC};
+use super::Error;
+use super::fourcc::{FourCC, WriteFourCC, RIFF_SIG, WAVE_SIG, FMT__SIG, DATA_SIG, ELM1_SIG};
+use super::fmt::WaveFmt;
+//use super::common_format::CommonFormat;
+use super::chunks::WriteBWaveChunks;
 
 use byteorder::LittleEndian;
 use byteorder::WriteBytesExt;
 
-struct WaveWriter<W> where W: Write + Seek {
-    inner : W
+
+pub struct AudioFrameWriter<W> where W: Write + Seek {
+    inner : WaveChunkWriter<W>
 }
 
-impl WaveWriter<File> {
-    pub fn create(path : &str, format:WaveFmt, broadcast_extension: Option<Bext>) -> Result<Self,Error> {
-        let inner = File::create(path)?;
-        Self::make(inner, format, broadcast_extension)
-    }
-}
+impl<W> AudioFrameWriter<W> where W: Write + Seek {
+    pub fn write_integer_frame(&mut self, buffer: &[i32]) -> Result<u64,Error> {
+        let format = self.inner.inner.format;
+        assert!(buffer.len() as u16 == format.channel_count, 
+            "read_integer_frame was called with a mis-sized buffer, expected {}, was {}", 
+            format.channel_count, buffer.len());
 
-impl<W:Write + Seek> WaveWriter<W> {
+        let framed_bits_per_sample = format.block_alignment * 8 / format.channel_count;
 
-    pub fn make(inner : W, format: WaveFmt, broadcast_extension: Option<Bext>) -> Result<Self, Error> {
-        let mut retval = Self { inner };
-        retval.prepare_created(format, broadcast_extension)?;
-        Ok(retval) 
-    }
-
-    fn prepare_created(&mut self, format : WaveFmt, broadcast_extension: Option<Bext>) -> Result<(),Error> {
-        self.inner.write_fourcc(RIFF_SIG)?;
-        self.inner.write_u32::<LittleEndian>(4)?;
-        self.inner.write_fourcc(WAVE_SIG)?;
-        let mut written : u64 = 4;
-
-        let ds64_reservation = [0u8; 92];
-
-        written += self.primitive_append_chunk(JUNK_SIG, &ds64_reservation)?;
-
-        let fmt_data : Vec<u8> = {
-            let mut c = Cursor::new(vec![]);
-            c.write_wave_fmt(&format)?;
-            c.into_inner()
-        };
-
-        written += self.primitive_append_chunk(FMT__SIG, &fmt_data)?;
-
-        if let Some(bext) = broadcast_extension {
-            let mut b = Cursor::new(vec![]);
-            b.write_bext(&bext)?;
-            let data = b.into_inner();
-            written += self.primitive_append_chunk(BEXT_SIG, &data)?;
+        for n in 0..(format.channel_count as usize) {
+            match (format.bits_per_sample, framed_bits_per_sample) {
+                (0..=8,8) => self.inner.write_u8((buffer[n] + 0x80) as u8 )?, // EBU 3285 §A2.2
+                (9..=16,16) => self.inner.write_i16::<LittleEndian>(buffer[n] as i16)?,
+                (10..=24,24) => self.inner.write_i24::<LittleEndian>(buffer[n])?,
+                (25..=32,32) => self.inner.write_i32::<LittleEndian>(buffer[n])?,
+                (b,_)=> panic!("Unrecognized integer format, bits per sample {}, channels {}, block_alignment {}", 
+                    b, format.channel_count, format.block_alignment)
+            }
         }
-        
-        // show our work
-        let desired_data_alignment = 0x4000;
-        let data_fourcc_start = desired_data_alignment - 8;
-        let current_position_from_start = written + 8;
-        let data_pad_length = data_fourcc_start - current_position_from_start;
 
-        let data_padding = vec![0u8; data_pad_length as usize];
+        Ok(1)
+    }
 
-        written += self.primitive_append_chunk(JUNK_SIG, &data_padding)?;
+    pub fn end(self) -> Result<WaveWriter<W>, Error> {
+        self.inner.end()
+    }
+}
 
-        self.inner.write_fourcc(DATA_SIG)?;
-        self.inner.write_u32::<LittleEndian>(0)?;
 
-        written += 8;
-        self.inner.seek(SeekFrom::Start(4))?;
-        self.inner.write_u32::<LittleEndian>(written as u32)?;
+pub struct WaveChunkWriter<W> where W: Write + Seek {
+    inner : WaveWriter<W>,
+    content_start_pos : u64,
+    length : u64
+}
+
+impl<W> WaveChunkWriter<W> where W: Write + Seek {
+
+    fn begin(mut inner : WaveWriter<W>, ident : FourCC) -> Result<Self,Error> {
+        let length : u64 = 0;
+        inner.inner.write_fourcc(ident)?;
+        inner.inner.write_u32::<LittleEndian>(length as u32)?;
+        inner.increment_form_length(8)?;
+        let content_start_pos = inner.inner.seek(SeekFrom::End(0))?;
+        Ok( WaveChunkWriter { inner , content_start_pos, length } )
+    }
+
+    fn end(mut self) -> Result<WaveWriter<W>, Error> {
+        if self.length % 2 == 1 {
+            self.inner.inner.seek(SeekFrom::End(0))?;
+            self.inner.inner.write(&[0u8])?;
+            self.inner.increment_form_length(1)?;
+        }
+        Ok( self.inner )
+    }
+
+    fn increment_chunk_length(&mut self, amount: u64) -> Result<(), std::io::Error> {
+        self.length = self.length + amount;
+        if self.length < u32::MAX as u64 {
+            self.inner.inner.seek(SeekFrom::Start(self.content_start_pos - 4))?;
+            self.inner.inner.write_u32::<LittleEndian>(self.length as u32)?;
+        } else {
+            todo!()
+        }
 
         Ok(())
     }
+}
 
-    fn primitive_append_chunk(&mut self, signature: FourCC, data: &[u8]) -> Result<u64,Error> {
-        assert!((data.len() as u32) < u32::MAX, 
-            "primitive_append_chunk called with a long data buffer");
+impl<W> Write for WaveChunkWriter<W> where W: Write + Seek {
 
-        self.inner.write_fourcc(signature)?;
-        self.inner.write_u32::<LittleEndian>(data.len() as u32)?;
-        self.inner.write_all(&data)?;
-        let padding : u64 = data.len() as u64 % 2;
-        if padding == 1 {
-            self.inner.write_u8(0)?;
-        }
+    fn write(&mut self, buffer: &[u8]) -> Result<usize, std::io::Error> { 
+        self.inner.inner.seek(SeekFrom::End(0))?;
+        let written = self.inner.inner.write(buffer)?;
+        self.increment_chunk_length(written as u64)?;
+        self.inner.increment_form_length(written as u64)?;
 
-        Ok(8 + data.len() as u64 + padding)
+        Ok( written )
+    }
+
+    fn flush(&mut self) -> Result<(), std::io::Error> { 
+        self.inner.inner.flush()
     }
 }
 
-#[test]
-fn test_chunk_append() -> Result<(), Error> {
-    let mut test :Vec<u8> = vec![];
-    let mut cursor = Cursor::new(test);
-    let f = WaveFmt::new_pcm(48000, 16, 1);
-    let mut w = WaveWriter::make(cursor, f, None)?;
+/// Wave, Broadcast-WAV and RF64/BW64 writer.
+/// 
+/// ```
+/// use bwavfile::{WaveWriter,WaveFmt};
+/// # use std::io::Cursor;
+/// 
+/// // Write a three-sample wave file to a cursor
+/// let mut cursor = Cursor::new(vec![0u8;0]);
+/// let format = WaveFmt::new_pcm(48000, 24, 1);
+/// let w = WaveWriter::new(&mut cursor, format).unwrap();
+///
+/// let mut frame_writer = w.audio_frame_writer().unwrap();
+///
+/// frame_writer.write_integer_frame(&[0i32]).unwrap();
+/// frame_writer.write_integer_frame(&[0i32]).unwrap();
+/// frame_writer.write_integer_frame(&[0i32]).unwrap();
+/// frame_writer.end().unwrap();
+/// ``` 
+pub struct WaveWriter<W> where W: Write + Seek {
+    inner : W,
+    form_length: u64,
 
+    /// Format of the wave file.
+    pub format: WaveFmt
+}
+
+impl WaveWriter<File> {
+
+    /// Create a new Wave file at `path`.
+    pub fn create(path : &str, format : WaveFmt) -> Result<Self, Error> {
+        let f = File::create(path)?;
+        Ok( Self::new(f, format)? )
+    }
+}
+
+impl<W> WaveWriter<W> where W: Write + Seek {
+
+    /// Wrap a writer in a Wave writer.
+    /// 
+    /// The inner writer will immediately have a RIFF WAVE file header 
+    /// written to it along with the format descriptor (and possibly a `fact`
+    /// chunk if appropriate).
+    pub fn new(mut inner : W, format: WaveFmt) -> Result<Self, Error> {
+        inner.write_fourcc(RIFF_SIG)?;
+        inner.write_u32::<LittleEndian>(0)?;
+        inner.write_fourcc(WAVE_SIG)?;
+
+        let mut retval = WaveWriter { inner, form_length: 0, format};
+        retval.increment_form_length(4)?;
+
+        let mut chunk = retval.begin_chunk(FMT__SIG)?;
+        chunk.write_wave_fmt(&format)?;
+        let retval = chunk.end()?;
+
+        Ok( retval )
+    }
+
+    /// Create a new chunk writer, which takes posession of the `WaveWriter`.
+    /// 
+    /// Begin writing a chunk segment. To close the chunk (and perhaps write 
+    /// another), call `end()` on the chunk writer.
+    pub fn begin_chunk(mut self, ident: FourCC) -> Result<WaveChunkWriter<W>,Error> {
+        self.inner.seek(SeekFrom::End(0))?;
+        WaveChunkWriter::begin(self, ident)
+    }
+
+    pub fn audio_frame_writer(mut self) -> Result<AudioFrameWriter<W>, Error> {
+        // append elm1 chunk
+
+        let framing = 0x4000;
+
+        let lip = self.inner.seek(SeekFrom::End(0))?;
+        let to_add = framing - (lip % framing) - 16;
+        let mut chunk = self.begin_chunk(ELM1_SIG)?;
+        let buf = vec![0u8; to_add as usize];
+        chunk.write(&buf)?;
+        let closed = chunk.end()?;
+
+        let inner = closed.begin_chunk(DATA_SIG)?;
+        Ok( AudioFrameWriter { inner } )
+    }
+
+    fn increment_form_length(&mut self, amount: u64) -> Result<(), std::io::Error> {
+        self.form_length = self.form_length + amount;
+        self.inner.seek(SeekFrom::Start(4))?;
+        self.inner.write_u32::<LittleEndian>(self.form_length as u32)?;
+        Ok(())
+    }
+
+}
+
+#[test]
+fn test_new() {
+    use std::io::Cursor;
+    use super::fourcc::ReadFourCC;
+    use byteorder::ReadBytesExt;
+
+    let mut cursor = Cursor::new(vec![0u8;0]);
+    let format = WaveFmt::new_pcm(4800, 24, 1);
+    WaveWriter::new(&mut cursor, format).unwrap();
+
+    cursor.seek(SeekFrom::Start(0)).unwrap();
+    assert_eq!(cursor.read_fourcc().unwrap(), RIFF_SIG);
+    let form_size = cursor.read_u32::<LittleEndian>().unwrap();
+    assert_eq!(cursor.read_fourcc().unwrap(), WAVE_SIG);
+    assert_eq!(cursor.read_fourcc().unwrap(), FMT__SIG);
+    let fmt_size = cursor.read_u32::<LittleEndian>().unwrap();
+    assert_eq!(form_size, fmt_size + 8 + 4);
+}
+
+#[test]
+fn test_write_audio() {
+    use std::io::Cursor;
+    use super::fourcc::ReadFourCC;
+    use byteorder::ReadBytesExt;
+
+    let mut cursor = Cursor::new(vec![0u8;0]);
+    let format = WaveFmt::new_pcm(48000, 24, 1);
+    let w = WaveWriter::new(&mut cursor, format).unwrap();
+    
+    let mut frame_writer = w.audio_frame_writer().unwrap();
+
+    frame_writer.write_integer_frame(&[0i32]).unwrap();
+    frame_writer.write_integer_frame(&[0i32]).unwrap();
+    frame_writer.write_integer_frame(&[0i32]).unwrap();
+
+    frame_writer.end().unwrap();
+
+    cursor.seek(SeekFrom::Start(0)).unwrap();
+
+    cursor.seek(SeekFrom::Start(0)).unwrap();
+    assert_eq!(cursor.read_fourcc().unwrap(), RIFF_SIG);
+    let _ = cursor.read_u32::<LittleEndian>().unwrap();
+    assert_eq!(cursor.read_fourcc().unwrap(), WAVE_SIG);
+    assert_eq!(cursor.read_fourcc().unwrap(), FMT__SIG);
+    let seek = cursor.read_u32::<LittleEndian>().unwrap();
+    cursor.seek(SeekFrom::Current(seek as i64)).unwrap();
+
+    assert_eq!(cursor.read_fourcc().unwrap(), ELM1_SIG);
+    let seek = cursor.read_u32::<LittleEndian>().unwrap();
+    cursor.seek(SeekFrom::Current(seek as i64)).unwrap();
+
+    assert_eq!(cursor.read_fourcc().unwrap(), DATA_SIG);
+    let data_size = cursor.read_u32::<LittleEndian>().unwrap();
+    assert_eq!(data_size, 9);
+
+    let tell = cursor.seek(SeekFrom::Current(0)).unwrap();
+    assert!(tell % 0x4000 == 0);
     
 
-    Ok(())
-}
+}

tests/Untitled.txt

@@ -0,0 +1,5 @@
+Marker file version: 1
+Time format: Time
+Marker 1	00:00:00.28417234		Marker 1 Comment
+Marker 2	00:00:00.47612245		Marker 2 Comment
+Timed Region	00:00:00.60569161	00:00:00.75226757	Region Comment

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() {
@@ -74,4 +75,105 @@ fn test_minimal_wave()  {
     } else {
         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 buffer = w.format().unwrap().create_frame_buffer();
+
+    let mut reader = w.audio_frame_reader().unwrap();
+
+    
+
+    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 buffer = w.format().unwrap().create_frame_buffer();
+
+    let mut reader = w.audio_frame_reader().unwrap();
+
+    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);
+}
+
+//See issue 6 and 7
+#[test]
+fn test_frame_reader_consumes_reader() {
+    // Issue #6
+    use bwavfile::WaveFmt;
+    use bwavfile::AudioFrameReader;
+    use std::fs::File;
+    fn from_wav_filename(wav_filename: &str) -> Result<(WaveFmt, AudioFrameReader<File>), ()> {
+        if let Ok(mut r) = WaveReader::open(&wav_filename) {
+            let format = r.format().unwrap();
+            let frame_reader = r.audio_frame_reader().unwrap();
+            Ok((format, frame_reader))
+        } else {
+            Err(())
+        }
+    }
+
+    let _result = from_wav_filename("tests/media/pt_24bit_stereo.wav").unwrap();
 }