Merge branch 'candidate-v1' into HEAD

Cargo.lock

@@ -28,7 +28,7 @@ checksum = "cf1de2fe8c75bc145a2f577add951f8134889b4795d47466a54a5c846d691693"
 
 [[package]]
 name = "bwavfile"
-version = "0.9.3"
+version = "1.0.0"
 dependencies = [
  "byteorder",
  "clap",
@@ -39,9 +39,9 @@ dependencies = [
 
 [[package]]
 name = "byteorder"
-version = "1.3.4"
+version = "1.4.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "08c48aae112d48ed9f069b33538ea9e3e90aa263cfa3d1c24309612b1f7472de"
+checksum = "14c189c53d098945499cdfa7ecc63567cf3886b3332b312a5b4585d8d3a6a610"
 
 [[package]]
 name = "clap"
@@ -124,9 +124,9 @@ checksum = "a246d82be1c9d791c5dfde9a2bd045fc3cbba3fa2b11ad558f27d01712f00569"
 
 [[package]]
 name = "hermit-abi"
-version = "0.1.17"
+version = "0.1.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5aca5565f760fb5b220e499d72710ed156fdb74e631659e99377d9ebfbd13ae8"
+checksum = "322f4de77956e22ed0e5032c359a0f1273f1f7f0d79bfa3b8ffbc730d7fbcc5c"
 dependencies = [
  "libc",
 ]
@@ -139,9 +139,9 @@ checksum = "dd25036021b0de88a0aff6b850051563c6516d0bf53f8638938edbb9de732736"
 
 [[package]]
 name = "libc"
-version = "0.2.81"
+version = "0.2.97"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1482821306169ec4d07f6aca392a4681f66c75c9918aa49641a2595db64053cb"
+checksum = "12b8adadd720df158f4d70dfe7ccc6adb0472d7c55ca83445f6a5ab3e36f8fb6"
 
 [[package]]
 name = "ryu"
@@ -151,15 +151,15 @@ checksum = "71d301d4193d031abdd79ff7e3dd721168a9572ef3fe51a1517aba235bd8f86e"
 
 [[package]]
 name = "serde"
-version = "1.0.118"
+version = "1.0.126"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "06c64263859d87aa2eb554587e2d23183398d617427327cf2b3d0ed8c69e4800"
+checksum = "ec7505abeacaec74ae4778d9d9328fe5a5d04253220a85c4ee022239fc996d03"
 
 [[package]]
 name = "serde_json"
-version = "1.0.61"
+version = "1.0.64"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4fceb2595057b6891a4ee808f70054bd2d12f0e97f1cbb78689b59f676df325a"
+checksum = "799e97dc9fdae36a5c8b8f2cae9ce2ee9fdce2058c57a93e6099d919fd982f79"
 dependencies = [
  "itoa",
  "ryu",
@@ -189,9 +189,9 @@ checksum = "9337591893a19b88d8d87f2cec1e73fad5cdfd10e5a6f349f498ad6ea2ffb1e3"
 
 [[package]]
 name = "uuid"
-version = "0.8.1"
+version = "0.8.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9fde2f6a4bea1d6e007c4ad38c6839fa71cbb63b6dbf5b595aa38dc9b1093c11"
+checksum = "bc5cf98d8186244414c848017f0e2676b3fcb46807f6668a97dfe67359a3c4b7"
 
 [[package]]
 name = "vec_map"

Cargo.toml

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

README.md

@@ -4,72 +4,44 @@
 [![GitHub Workflow Status](https://img.shields.io/github/workflow/status/iluvcapra/bwavfile/Rust)](https://github.com/iluvcapra/bwavfile/actions?query=workflow%3ARust)
 
 # bwavfile
-Rust Wave File Reader/Writer with Broadcast-WAV, MBWF and RF64 Support
+Wave File Reader/Writer library in Rust, with Broadcast-WAV, MBWF and RF64 Support
 
-### Features
+## Features
 
-This is currently a work-in-progress! However many features presently work:
+__bwavfile__ provides a reader `WaveReader` and writer type `WaveWriter` for 
+reading and creating new audio files respectively.
 
-| 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        |     |     |
-| ADM `chna` channel metadata           |     |     |
-| Broadcast-WAVE Level overview `levl` metadata     |    |    |
-| Cue list metadata                     | ☑️   |     |
-| Sampler and instrument metadata       |     |     |
-| Enhanced Wave file form validation    | ☑️   |     |
+`WaveReader` and `WaveWriter` support:
+  * A unified interface for standard RIFF and RF64/BW64 64-bit Wave files.
+  * When using `WaveWriter`, wave files are transparently upgraded from RIFF
+    to RF64 when required.
+  * Unpacked reading and writing of Integer PCM and IEEE float audio data 
+    formats.
+  * A unified interface for standard `WaveFormat` and extended `WaveFormatEx`
+    wave data format specification.
+  * Multichannel, surround, and ambisonic audio data description including 
+    surround channel maps, ADM `AudioTrackFormat`, `AudioChannelFormatRef` and 
+    `AudioPackRef` data structures.
+  * Broadcast-Wave metdata extension, including long description, originator 
+    information, SMPTE UMID and coding history.
+  * Reading and writing of embedded iXML and axml/ADM metadata.
+  * Reading and writing of timed cues and and timed cue region.
+
+### Feature Roadmap
+
+Some features that may be included in the future include:
+  * Broadcast-Wave `levl` waveform overview data reading and writing.
+  * Sampler and Instrument mentadata.
 
 
 ## Use Examples
 
-### Examples Directory
-
-Check out the [examples](examples) directory for some practical use cases:
-
   * [blits](examples/blits.rs) shows how to use `WaveWriter` to create a new
     file with BLITS alignment tones.
-
-### Reading Audio Frames From a File
-
-```rust
-
- 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 buffer = format.create_frame_buffer();
- let mut frame_reader = r.audio_frame_reader().unwrap();
- 
- let read = frame_reader.read_integer_frame(&mut buffer).unwrap();
- 
- assert_eq!(buffer, [0i32]);
- 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);
-```
+  * [wave-inter](examples/wave-inter.rs) uses `WaveReader` and `WaveWriter` to
+    interleave several input Wave files into a single polyphonic Wave file.
+  * [wave-deinter](examples/wave-deinter.rs) uses `WaveReader` and `WaveWriter`
+    to de-interleave an input Wave file into several monoarual Wave files.
 
 ## Note on Testing
 

examples/wave-deinter.rs

@@ -8,7 +8,7 @@ use std::io;
 use std::path::Path;
 
 extern crate bwavfile;
-use bwavfile::{Error,WaveReader, WaveWriter, ChannelDescriptor, ChannelMask, WaveFmt, AudioFrameWriter};
+use bwavfile::{Error,WaveReader, WaveWriter, ChannelDescriptor, ChannelMask, WaveFmt};
 
 #[macro_use]
 extern crate clap;
@@ -70,7 +70,7 @@ fn process_file(infile: &str, delim : &str, numeric_channel_names : bool) -> Res
         let output_file = WaveWriter::create(&outfile_name, ouptut_format).expect("Failed to create new file");
         
         let mut output_wave_writer = output_file.audio_frame_writer()?;
-        let mut buffer = input_format.create_frame_buffer();
+        let mut buffer = input_format.create_frame_buffer(1);
 
         while input_wave_reader.read_integer_frame(&mut buffer)? > 0 {
             output_wave_writer.write_integer_frames(&buffer[n..=n])?;

src/fmt.rs

@@ -3,7 +3,7 @@ use super::common_format::{CommonFormat, UUID_PCM,UUID_BFORMAT_PCM};
 use std::io::Cursor;
 
 use byteorder::LittleEndian;
-use byteorder::WriteBytesExt;
+use byteorder::{WriteBytesExt, ReadBytesExt};
 
 // Need more test cases for ADMAudioID
 #[allow(dead_code)]
@@ -290,22 +290,23 @@ impl WaveFmt {
         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
+    /// Create a frame buffer sized to hold `length` 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]
+    pub fn create_frame_buffer(&self, length : usize) -> Vec<i32> {
+        vec![0i32; self.channel_count as usize * length]
     }
 
-    /// Calculate the size of a byte buffer needed to hold audio data of this 
-    /// format for a given number of frames
-    pub fn buffer_length(&self, frame_count: u64) -> usize {
-        (self.block_alignment as u64 * frame_count) as usize
+    /// Create a raw byte buffer to hold `length` blocks from a reader or 
+    /// writer
+    pub fn create_raw_buffer(&self, length : usize) -> Vec<u8> {
+        vec![0u8; self.block_alignment as usize * length]
     }
 
-    // Write frames into a byte vector
-    pub fn pack_frames(&self, from_frames: &[i32], into_bytes: &mut Vec<u8>) -> () {
+    /// Write frames into a byte vector
+    pub fn pack_frames(&self, from_frames: &[i32], into_bytes: &mut [u8]) -> () {
         let mut write_cursor = Cursor::new(into_bytes);
 
         assert!(from_frames.len() % self.channel_count as usize == 0, 
@@ -325,18 +326,19 @@ impl WaveFmt {
     }
 
     /// Read bytes into frames
-    // pub fn unpack_frames(&self, from_bytes: &[u8], into_frames: &mut Vec<i32>) -> () {
-    //     for n in 0..(from_bytes.len()) {
-    //         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)
-    //         }
-    //     }
-    // }
+    pub fn unpack_frames(&self, from_bytes: &[u8], into_frames: &mut [i32]) -> () {
+        let mut rdr = Cursor::new(from_bytes);
+        for n in 0..(into_frames.len()) {
+            into_frames[n] = match (self.valid_bits_per_sample(), self.bits_per_sample) {
+                (0..=8,8) => rdr.read_u8().unwrap() as i32 - 0x80_i32, // EBU 3285 §A2.2
+                (9..=16,16) => rdr.read_i16::<LittleEndian>().unwrap() as i32,
+                (10..=24,24) => rdr.read_i24::<LittleEndian>().unwrap(),
+                (25..=32,32) => rdr.read_i32::<LittleEndian>().unwrap(),
+                (b,_)=> panic!("Unrecognized integer format, bits per sample {}, channels {}, block_alignment {}", 
+                    b, self.channel_count, self.block_alignment)
+            }
+        }
+    }
 
 
     /// Channel descriptors for each channel.
@@ -379,3 +381,47 @@ impl WaveFmt {
     }
 }
 
+trait ReadWavAudioData {
+    fn read_i32_frames(&mut self, format: WaveFmt, into: &mut [i32]) -> Result<usize,std::io::Error>;
+    fn read_f32_frames(&mut self, format: WaveFmt, into: &mut [f32]) -> Result<usize,std::io::Error>;
+}
+
+impl<T> ReadWavAudioData for T where T: std::io::Read {
+
+    fn read_i32_frames(&mut self, format: WaveFmt, into: &mut [i32]) -> Result<usize, std::io::Error> { 
+        assert!(into.len() % format.channel_count as usize == 0);
+
+        for n in 0..(into.len()) {
+            into[n] = match (format.valid_bits_per_sample(), format.bits_per_sample) {
+                (0..=8,8) => self.read_u8().unwrap() as i32 - 0x80_i32, // EBU 3285 §A2.2
+                (9..=16,16) => self.read_i16::<LittleEndian>().unwrap() as i32,
+                (10..=24,24) => self.read_i24::<LittleEndian>().unwrap(),
+                (25..=32,32) => self.read_i32::<LittleEndian>().unwrap(),
+                (b,_)=> panic!("Unrecognized integer format, bits per sample {}, channels {}, block_alignment {}", 
+                    b, format.channel_count, format.block_alignment)
+            }
+        }
+
+        todo!()
+    }
+    fn read_f32_frames(&mut self, format: WaveFmt, into: &mut [f32]) -> Result<usize, std::io::Error> { 
+        assert!(into.len() % format.channel_count as usize == 0);
+        todo!()
+    }
+
+}
+
+trait WriteWavAudioData {
+    fn write_i32_frames(&mut self, format: WaveFmt, from: &[i32]) -> Result<usize, std::io::Error>;
+    fn write_f32_frames(&mut self, format: WaveFmt, from: &[f32]) -> Result<usize, std::io::Error>;
+}
+
+impl<T> WriteWavAudioData for T where T: std::io::Write {
+
+    fn write_i32_frames(&mut self, format: WaveFmt, _: &[i32]) -> Result<usize, std::io::Error> { 
+        todo!() 
+    }
+    fn write_f32_frames(&mut self, format: WaveFmt, _: &[f32]) -> Result<usize, std::io::Error> { 
+        todo!() 
+    }
+}

src/lib.rs

@@ -35,12 +35,6 @@ Apps we test against:
 [github]: https://github.com/iluvcapra/bwavfile
 */
 
-// #![feature(external_doc)]
-
-// #[doc(include="../README.md")]
-// #[cfg(doctest)]
-// pub struct ReadmeDoctests;
-
 extern crate encoding;
 extern crate byteorder;
 extern crate uuid;

src/wavereader.rs

@@ -120,6 +120,10 @@ impl<R: Read + Seek> AudioFrameReader<R> {
             Ok( 0 )
         }
     }
+
+    pub fn read_float_frame(&mut self, buffer:&mut [f32]) -> Result<u64, Error> {
+        todo!()
+    }
 }
 
 /// Wave, Broadcast-WAV and RF64/BW64 parser/reader.
@@ -133,7 +137,7 @@ impl<R: Read + Seek> AudioFrameReader<R> {
 /// assert_eq!(format.channel_count, 1);
 ///
 /// let mut frame_reader = r.audio_frame_reader().unwrap();
-/// let mut buffer = format.create_frame_buffer();
+/// let mut buffer = format.create_frame_buffer(1);
 ///
 /// let read = frame_reader.read_integer_frame(&mut buffer).unwrap();
 /// 

src/wavewriter.rs

@@ -26,7 +26,7 @@ impl<W> AudioFrameWriter<W> where W: Write + Seek {
         AudioFrameWriter { inner }
     }
 
-    fn write_integer_frames_to_buffer(&self, from_frames :&[i32], to_buffer : &mut Vec<u8>) -> () {
+    fn write_integer_frames_to_buffer(&self, from_frames :&[i32], to_buffer : &mut [u8]) -> () {
         assert!(from_frames.len() % self.inner.inner.format.channel_count as usize == 0, 
             "frames buffer does not contain a number of samples % channel_count == 0");
         self.inner.inner.format.pack_frames(&from_frames, to_buffer);
@@ -40,7 +40,8 @@ impl<W> AudioFrameWriter<W> where W: Write + Seek {
     /// This function will panic if `buffer.len()` modulo the Wave file's channel count
     /// is not zero.
     pub fn write_integer_frames(&mut self, buffer: &[i32]) -> Result<u64,Error> {
-        let mut write_buffer = vec![0u8; 0];
+        let mut write_buffer = self.inner.inner.format
+            .create_raw_buffer(buffer.len() / self.inner.inner.format.channel_count as usize);
 
         self.write_integer_frames_to_buffer(&buffer, &mut write_buffer);
 

tests/integration_test.rs

@@ -82,7 +82,7 @@ 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 buffer = w.format().unwrap().create_frame_buffer(1);
 
     let mut reader = w.audio_frame_reader().unwrap();
 
@@ -101,7 +101,7 @@ 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 buffer = w.format().unwrap().create_frame_buffer(1);
 
     let mut reader = w.audio_frame_reader().unwrap();