Merge branch 'master' into release

...and will push to github see if the action completes

Cargo.lock

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

Cargo.toml

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

README.md

@@ -11,19 +11,20 @@ Rust Wave File Reader/Writer with Broadcast-WAV, MBWF and RF64 Support
 This is currently a work-in-progress! However many features presently work:
 
 | Feature                               |Read |Write|
-|---------------------------------------|:-----:|:-----:|
+|---------------------------------------|:---:|:-----:|
 | Standard .wav files                   | ☑️   | ☑️   |
-| Transparent promotion to RF64/BW64    | ☑️   |    |
+| Transparent promotion to RF64/BW64    | ☑️   | ☑️   |
-| Unified interface for regular and extended Wave format | ☑️  |  |
+| Unified interface for regular and extended Wave format | ☑️   | ☑️   |
-| Channel/speaker map metadata          | ☑️    |    |
+| Channel/speaker map metadata          | ☑️   | ☑️   |
-| Ambisonic B-format metadata           | ☑️    |   |
+| Ambisonic B-format metadata           | ☑️   | ☑️   |
-| EBU Broadcast-WAVE metadata           | ☑️   |    |
+| EBU Broadcast-WAVE metadata           | ☑️   | ☑️   |
-| Basic iXML/ADM 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    | ☑️   | 🚫   |
+| Enhanced Wave file form validation    | ☑️   |     |
 
 
 ## Use Examples
@@ -69,3 +70,9 @@ All of the media for the integration tests is committed to the respository
 in zipped form. Before you can run tests, you need to `cd` into the `tests` 
 directory and run the `create_test_media.sh` script. Note that one of the 
 test files (the RF64 test case) is over four gigs in size.
+
+Likewise, [the RF64 _writing_ test case][rf64test] writes an RF64 wave file 
+to memory and is very time-intensive, so is commented-out in the code but 
+can be un-commented if you want to run it on your system. 
+
+[rf64test]: https://github.com/iluvcapra/bwavfile/blob/1f8542a7efb481da076120bf8107032c5b48889d/src/wavewriter.rs#L399

examples/blits.rs

@@ -0,0 +1,3 @@
+fn main() -> () {
+    
+}

examples/bwavefile_probe.rs

@@ -0,0 +1,3 @@
+fn main() -> () {
+    
+}

src/bext.rs

@@ -3,20 +3,23 @@ pub type LU = f32;
 pub type LUFS = f32;
 pub type Decibels = f32;
 
-/**
+
- * Broadcast-WAV metadata record.
+///  Broadcast-WAV metadata record.
- * 
+///
- * The `bext` record contains information about the original recording of the 
+///  The `bext` record contains information about the original recording of the 
- * Wave file, including a longish (256 ASCII chars) description field, 
+///  Wave file, including a longish (256 ASCII chars) description field, 
- * originator identification fields, creation calendar date and time, a 
+///  originator identification fields, creation calendar date and time, a 
- * sample-accurate recording time field, and a SMPTE UMID. 
+///  sample-accurate recording time field, and a SMPTE UMID. 
- * 
+///
- * For a Wave file to be a complaint "Broadcast-WAV" file, it must contain
+///  For a Wave file to be a complaint "Broadcast-WAV" file, it must contain
- * a `bext` metadata record.
+///  a `bext` metadata record.
- * 
+///
- * For reference on the structure and use of the BEXT record
+/// ## Resources
- * check out [EBU Tech 3285](https://tech.ebu.ch/docs/tech/tech3285.pdf).
+/// - [EBU Tech 3285](https://tech.ebu.ch/docs/tech/tech3285.pdf).
- */
+/// - [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 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"
+
 #[derive(Debug)]
 pub struct Bext {
 
@@ -47,7 +50,6 @@ pub struct Bext {
 
     /// SMPTE 330M UMID
     /// 
-    /// 
     /// This field is `None` if the version is less than 1.
     pub umid: Option<[u8; 64]>,
 

src/common_format.rs

@@ -1,12 +1,5 @@
 use uuid::Uuid;
 
-/**
- * References:
- * - http://www-mmsp.ece.mcgill.ca/Documents/AudioFormats/WAVE/Docs/multichaudP.pdf
-*/
-
-// http://dream.cs.bath.ac.uk/researchdev/wave-ex/bformat.html
-
 const BASIC_PCM: u16        = 0x0001;
 const BASIC_FLOAT: u16      = 0x0003;
 const BASIC_MPEG: u16       = 0x0050;
@@ -71,6 +64,7 @@ pub enum CommonFormat {
 }
 
 impl CommonFormat {
+    /// Resolve a tag and Uuid to a `CommonFormat`.
     pub fn make(basic: u16, uuid: Option<Uuid>) -> Self {
         match (basic, uuid) {
             (BASIC_PCM, _) => Self::IntegerPCM,
@@ -85,6 +79,10 @@ impl CommonFormat {
         }
     }
 
+    /// Get the appropriate tag and `Uuid` for the callee.
+    /// 
+    /// If there is no appropriate tag for the format of the callee, the 
+    /// returned tag will be 0xFFFE and the `Uuid` will describe the format.
     pub fn take(self) -> (u16, Uuid) {
         match self {
             Self::IntegerPCM => (BASIC_PCM, UUID_PCM),

src/cue.rs

@@ -190,7 +190,11 @@ impl AdtlMemberSearch for Vec<RawAdtlMember> {
 
 /// A cue point recorded in the `cue` and `adtl` metadata.
 /// 
+/// ## Resources
+/// - [Cue list, label and other metadata](https://sites.google.com/site/musicgapi/technical-documents/wav-file-format#smpl)
 /// 
+/// ### Not Implemented
+/// - [EBU 3285 Supplement 2](https://tech.ebu.ch/docs/tech/tech3285s2.pdf) (July 2001): Quality chunk and cuesheet
 pub struct Cue {
 
     /// Unique numeric identifier for this cue

src/fmt.rs

@@ -1,6 +1,11 @@
 use uuid::Uuid;
-use super::common_format::{CommonFormat, UUID_PCM};
+use super::common_format::{CommonFormat, UUID_PCM,UUID_BFORMAT_PCM};
+use std::io::Cursor;
 
+use byteorder::LittleEndian;
+use byteorder::WriteBytesExt;
+
+// Need more test cases for ADMAudioID
 #[allow(dead_code)]
 
 /// ADM Audio ID record.
@@ -20,6 +25,9 @@ pub struct ADMAudioID {
 }
 
 /// Describes a single channel in a WAV file.
+/// 
+/// This information is correlated from the Wave format ChannelMap field and
+/// the `chna` chunk, if present.
 pub struct ChannelDescriptor {
     /// Index, the offset of this channel's samples in one frame.
     pub index: u16,
@@ -124,14 +132,30 @@ pub struct WaveFmtExtended {
     pub type_guid : Uuid,
 }
 
-/**
+///
- * WAV file data format record.
+/// WAV file data format record.
- * 
+///
- * The `fmt` record contains essential information describing the binary
+/// The `fmt` record contains essential information describing the binary
- * structure of the data segment of the WAVE file, such as sample 
+/// structure of the data segment of the WAVE file, such as sample 
- * rate, sample binary format, channel count, etc.
+/// rate, sample binary format, channel count, etc.
- *
+///
- */
+/// 
+/// ## Resources 
+/// 
+/// ### Implementation of Wave format `fmt` chunk
+/// - [MSDN WAVEFORMATEX](https://docs.microsoft.com/en-us/windows/win32/api/mmeapi/ns-mmeapi-waveformatex)
+/// - [MSDN WAVEFORMATEXTENSIBLE](https://docs.microsoft.com/en-us/windows/win32/api/mmreg/ns-mmreg-waveformatextensible)
+///
+/// ### Other resources
+/// - [RFC 3261][rfc3261] (June 1998) "WAVE and AVI Codec Registries"
+/// - [Sampler Metadata](http://www.piclist.com/techref/io/serial/midi/wave.html)
+/// - [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
+/// 
+/// [rfc3261]: https://tools.ietf.org/html/rfc2361 
+
+
 #[derive(Debug, Copy, Clone)]
 pub struct WaveFmt {
 
@@ -182,17 +206,71 @@ pub struct WaveFmt {
 
 impl WaveFmt {
 
-    /// Create a new integer PCM format `WaveFmt` 
+    pub fn valid_bits_per_sample(&self) -> u16 {
-    pub fn new_pcm(sample_rate: u32, bits_per_sample: u16, channel_count: u16) -> Self {
+        if let Some(ext) = self.extended_format {
+            ext.valid_bits_per_sample
+        } else {
+            self.bits_per_sample
+        }
+    }
+
+    /// Create a new integer PCM format for a monoaural audio stream.
+    pub fn new_pcm_mono(sample_rate: u32, bits_per_sample: u16) -> Self {
+        Self::new_pcm_multichannel(sample_rate, bits_per_sample, 0x4)
+    }
+
+    /// Create a new integer PCM format for a standard Left-Right stereo audio 
+    /// stream.
+    pub fn new_pcm_stereo(sample_rate: u32, bits_per_sample: u16) -> Self {
+        Self::new_pcm_multichannel(sample_rate, bits_per_sample, 0x3)
+    }
+
+    /// Create a new integer PCM format for ambisonic b-format.
+    pub fn new_pcm_ambisonic(sample_rate: u32, bits_per_sample: u16, channel_count: u16) -> Self {
         let container_bits_per_sample = bits_per_sample + (bits_per_sample % 8);
         let container_bytes_per_sample= container_bits_per_sample / 8;
 
-        let tag : u16 = match channel_count {
+        WaveFmt {
-            1..=2 => 0x01,
+            tag : 0xFFFE,
-            x if x > 2 => 0xFFFE,
+            channel_count,
-            x => panic!("Invalid channel count {}", x)
+            sample_rate,
+            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: Some(WaveFmtExtended {
+                valid_bits_per_sample: bits_per_sample,
+                channel_mask: ChannelMask::DirectOut as u32,
+                type_guid: UUID_BFORMAT_PCM
+            })
+        }
+    }
+
+    /// Create a new integer PCM format `WaveFmt` with a custom channel bitmap.
+    /// 
+    /// The order of `channels` is not important. When reading or writing 
+    /// audio frames you must use the standard multichannel order for Wave 
+    /// files, the numerical order of the cases of `ChannelMask`.
+    pub fn new_pcm_multichannel(sample_rate: u32, bits_per_sample: u16, channel_bitmap: u32) -> Self {
+        let container_bits_per_sample = bits_per_sample + (bits_per_sample % 8);
+        let container_bytes_per_sample= container_bits_per_sample / 8;
+        
+        let channel_count: u16 = (0..=31).fold(0u16, |accum, n| accum + (0x1 & (channel_bitmap >> n) as u16) );
+
+        let result : (u16, Option<WaveFmtExtended>) = match channel_bitmap {
+            ch if bits_per_sample != container_bits_per_sample => (
+                (0xFFFE, Some(WaveFmtExtended { valid_bits_per_sample: bits_per_sample, channel_mask: ch, 
+                    type_guid: UUID_PCM }) )
+            ),
+            0b0100 => (0x0001, None),
+            0b0011 => (0x0001, None),
+            ch => (
+                (0xFFFE, Some( WaveFmtExtended { valid_bits_per_sample: bits_per_sample, channel_mask: ch, 
+                    type_guid: UUID_PCM}))
+            )
         };
 
+        let (tag, extformat) = result;
+
         WaveFmt {
             tag,
             channel_count,
@@ -200,17 +278,7 @@ 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: {
+            extended_format: extformat
-                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
-                }
-            }
         }
     }
 
@@ -230,6 +298,46 @@ impl WaveFmt {
         vec![0i32; self.channel_count as usize]
     }
 
+    /// 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
+    }
+
+    // Write frames into a byte vector
+    pub fn pack_frames(&self, from_frames: &[i32], into_bytes: &mut Vec<u8>) -> () {
+        let mut write_cursor = Cursor::new(into_bytes);
+
+        assert!(from_frames.len() % self.channel_count as usize == 0, 
+            "frames buffer does not contain a number of samples % channel_count == 0");
+
+            for n in 0..from_frames.len() {
+                match (self.valid_bits_per_sample(), self.bits_per_sample) {
+                    (0..=8,8) => write_cursor.write_u8((from_frames[n] + 0x80) as u8 ).unwrap(), // EBU 3285 §A2.2
+                    (9..=16,16) => write_cursor.write_i16::<LittleEndian>(from_frames[n] as i16).unwrap(),
+                    (10..=24,24) => write_cursor.write_i24::<LittleEndian>(from_frames[n]).unwrap(),
+                    (25..=32,32) => write_cursor.write_i32::<LittleEndian>(from_frames[n]).unwrap(),
+                    (b,_)=> panic!("Unrecognized integer format, bits per sample {}, channels {}, block_alignment {}", 
+                        b, self.channel_count, self.block_alignment)
+                }
+            }
+        ()
+    }
+
+    /// 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)
+    //         }
+    //     }
+    // }
+
 
     /// Channel descriptors for each channel.
     pub fn channels(&self) -> Vec<ChannelDescriptor> {

src/fourcc.rs

@@ -103,6 +103,8 @@ 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 IXML_SIG: FourCC = FourCC::make(b"iXML");
+pub const AXML_SIG: FourCC = FourCC::make(b"axml");
 
 pub const JUNK_SIG: FourCC = FourCC::make(b"JUNK");
 pub const FLLR_SIG: FourCC = FourCC::make(b"FLLR");

src/levl.rs

@@ -0,0 +1,3 @@
+/// Resources
+/// 
+/// [EBU 3285 Supplement 3](https://tech.ebu.ch/docs/tech/tech3285s3.pdf) (July 2001): Peak Metadata

src/lib.rs

@@ -3,9 +3,22 @@
  
 Rust Wave File Reader/Writer with Broadcast-WAV, MBWF and RF64 Support
 
-__(Note: This crate is still in an alpha or pre-alpha stage of development. Reading of
+## Interfaces
-files works however the interfaces may change significantly. Stay up-to-date on the
+
-status of this project at [Github][github].)__
+### `WaveReader`
+
+`WaveReader` can open and parse a Wave, Broadcast-Wave, or RF64/BW64 64-bit 
+wave file. Metadata can be accessed and parsed in arbitrary order and audio
+samples can be accessed using the `AudioFrameReader` type, created by an 
+accessor method of `WaveReader`.
+
+### `WaveWriter`
+
+`WaveWriter` can create a new Wave, Broadcast-Wave, or RF64/BW64 64-bit wave 
+file. Metadata chunks and audio samples are added sequentially, write-only, to 
+a Wave file which is automatically promoted from standard Wave to RF64 wave 
+when the total WAVE form size exceeds 0xFFFFFFFF bytes.
+
 
 ## Objectives and Roadmap
 
@@ -19,79 +32,6 @@ Apps we test against:
 - FFMpeg
 - Audacity
 
-Wave features we want to support with maximum reliability and ease of use:
-
-- Large file size, RF64 support
-- Multichannel audio formats 
-- Embedded metadata
-
-In addition to reading the audio, we want to support all of the different 
-metadata planes you are liable to need to use.
-
-- Broadcast-WAV metadata (including the SMPTE UMID and EBU v2 extensions)
-- iXML Production recorder metadata
-- ADM XML (with associated `chna` mappings)
-- Dolby metadata block
-
-Things that are _not_ necessarily in the scope of this package:
-
-- Broad codec support. There are a little more than one-hundred 
-  [registered wave codecs][rfc3261], but because this library is targeting
-  professional formats being created today, we only plan on supporting
-  two of them: tag 0x0001 (Integer Linear PCM) and tag 0x0003 (IEEE Float 
-  Linear PCM).
-- Music library metadata. There are several packages that can read ID3
-  metadata and it's not particuarly common in wave files in any case. INFO
-  metadata is more common though in professional applications it tends not
-  to be used by many applications.
-
-
-## Resources
-
-### Implementation of Broadcast Wave Files
-- [EBU Tech 3285][ebu3285] (May 2011), "Specification of the Broadcast Wave Format (BWF)"
-  - [Supplement 1](https://tech.ebu.ch/docs/tech/tech3285s1.pdf) (July 1997): MPEG Audio
-- [EBU Rec 68](https://tech.ebu.ch/docs/r/r068.pdf): Signal modulation and format constraints
-
-
-### Implementation of 64-bit Wave Files
-- [ITU-R 2088][itu2088] (October 2019), "Long-form file format for the international exchange of audio programme materials with metadata"
-  - Presently in force, adopted by the EBU in [EBU Tech 3306v2][ebu3306v2] (June 2018).
-- [EBU Tech 3306v1][ebu3306v1] (July 2009), "MBWF / RF64: An extended File Format for Audio"
-  - No longer in force, however long-established. 
-
-
-### Implementation of Wave format `fmt` chunk
-- [MSDN WAVEFORMATEX](https://docs.microsoft.com/en-us/windows/win32/api/mmeapi/ns-mmeapi-waveformatex)
-- [MSDN WAVEFORMATEXTENSIBLE](https://docs.microsoft.com/en-us/windows/win32/api/mmreg/ns-mmreg-waveformatextensible)
-
-
-### Other resources
-- [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
-
-
-### Formatting of Specific Metadatums
-- [iXML Metadata Specification](http://www.gallery.co.uk/ixml/) (April 2019) 
-- EBU 3285 Supplements:
-  - [Supplement 2](https://tech.ebu.ch/docs/tech/tech3285s2.pdf) (July 2001): Quality chunk and cuesheet
-  - [Supplement 3](https://tech.ebu.ch/docs/tech/tech3285s3.pdf) (July 2001): Peak Metadata
-  - [Supplement 4](https://tech.ebu.ch/docs/tech/tech3285s4.pdf) (April 2003): Link Metadata
-  - [Supplement 5](https://tech.ebu.ch/docs/tech/tech3285s5.pdf) (May 2018): ADM Metadata
-  - [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 &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
-[ebu3306v2]: https://tech.ebu.ch/docs/tech/tech3306.pdf
-[itu2088]: https://www.itu.int/dms_pubrec/itu-r/rec/bs/R-REC-BS.2088-1-201910-I!!PDF-E.pdf
-[rfc3261]: https://tools.ietf.org/html/rfc2361
 [github]: https://github.com/iluvcapra/bwavfile
 */
 
@@ -124,7 +64,7 @@ mod wavewriter;
 
 pub use errors::Error;
 pub use wavereader::WaveReader;
-pub use wavewriter::WaveWriter;
+pub use wavewriter::{WaveWriter, AudioFrameWriter};
 pub use bext::Bext;
 pub use fmt::{WaveFmt, WaveFmtExtended, ChannelDescriptor, ChannelMask, ADMAudioID};
 pub use common_format::CommonFormat;

src/sampler.rs

@@ -0,0 +1,2 @@
+/// ## Resources
+/// - [Sampler Metadata](http://www.piclist.com/techref/io/serial/midi/wave.html)

src/wavereader.rs

@@ -3,7 +3,8 @@ use std::io::SeekFrom;
 use std::fs::File;
 
 use super::parser::Parser;
-use super::fourcc::{FourCC, ReadFourCC, FMT__SIG,DATA_SIG, BEXT_SIG, LIST_SIG, JUNK_SIG, FLLR_SIG, CUE__SIG, ADTL_SIG};
+use super::fourcc::{FourCC, ReadFourCC, FMT__SIG,DATA_SIG, BEXT_SIG, LIST_SIG, JUNK_SIG, FLLR_SIG, CUE__SIG, 
+    ADTL_SIG, AXML_SIG, IXML_SIG};
 use super::errors::Error as ParserError;
 use super::fmt::{WaveFmt, ChannelDescriptor, ChannelMask};
 use super::bext::Bext;
@@ -15,39 +16,64 @@ use std::io::Cursor;
 use std::io::{Read, Seek};
 
 
-/**
+
- * Wave, Broadcast-WAV and RF64/BW64 parser/reader.
+/// Wave, Broadcast-WAV and RF64/BW64 parser/reader.
- * 
+///
- * ```
+/// ```
- * use bwavfile::WaveReader;
+/// use bwavfile::WaveReader; 
- * let mut r = WaveReader::open("tests/media/ff_silence.wav").unwrap();
+/// let mut r = WaveReader::open("tests/media/ff_silence.wav").unwrap();
- * 
+///
- * let format = r.format().unwrap();
+/// let format = r.format().unwrap();
- * assert_eq!(format.sample_rate, 44100);
+/// assert_eq!(format.sample_rate, 44100);
- * assert_eq!(format.channel_count, 1);
+/// assert_eq!(format.channel_count, 1);
- * 
+///
- * let mut frame_reader = r.audio_frame_reader().unwrap();
+/// let mut frame_reader = r.audio_frame_reader().unwrap();
- * let mut buffer = format.create_frame_buffer();
+/// let mut buffer = format.create_frame_buffer();
- * 
+///
- * let read = frame_reader.read_integer_frame(&mut buffer).unwrap();
+/// let read = frame_reader.read_integer_frame(&mut buffer).unwrap();
- * 
+/// 
- * assert_eq!(buffer, [0i32]);
+/// assert_eq!(buffer, [0i32]);
- * assert_eq!(read, 1);
+/// assert_eq!(read, 1);
- * 
+/// 
- * ```
+/// ```
-*/
+/// 
+/// ## Resources
+/// 
+/// ### Implementation of Wave Files
+/// - [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
+///  
+/// ### Implementation of Broadcast Wave Files
+/// - [EBU Tech 3285][ebu3285] (May 2011), "Specification of the Broadcast Wave Format (BWF)"
+///   - [Supplement 1](https://tech.ebu.ch/docs/tech/tech3285s1.pdf) (July 1997): MPEG Audio
+///   - [EBU Rec 68](https://tech.ebu.ch/docs/r/r068.pdf): Signal modulation and format constraints
+///
+/// ### Implementation of 64-bit Wave Files
+/// - [ITU-R 2088][itu2088] (October 2019), "Long-form file format for the international exchange of audio programme materials with metadata"
+///   - Presently in force, adopted by the EBU in [EBU Tech 3306v2][ebu3306v2] (June 2018).
+/// - [EBU Tech 3306v1][ebu3306v1] (July 2009), "MBWF / RF64: An extended File Format for Audio"
+///   - No longer in force, however long-established.
+/// 
+///
+/// [ebu3285]: https://tech.ebu.ch/docs/tech/tech3285.pdf
+/// [ebu3306v1]: https://tech.ebu.ch/docs/tech/tech3306v1_1.pdf
+/// [ebu3306v2]: https://tech.ebu.ch/docs/tech/tech3306.pdf
+/// [itu2088]: https://www.itu.int/dms_pubrec/itu-r/rec/bs/R-REC-BS.2088-1-201910-I!!PDF-E.pdf
+/// [rfc3261]: https://tools.ietf.org/html/rfc2361 
+
+
 #[derive(Debug)]
 pub struct WaveReader<R: Read + Seek> {
     pub inner: R,
 }
 
 impl WaveReader<File> {
-    /**
+    
-     * Open a file for reading.
+     /// Open a file for reading.
-     * 
+     ///
-     * A convenience that opens `path` and calls `Self::new()`
+     /// 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)? )
@@ -55,48 +81,45 @@ impl WaveReader<File> {
 }
 
 impl<R: Read + Seek> WaveReader<R> {
-    /**
+    
-     * Wrap a `Read` struct in a new `WaveReader`.
+    /// Wrap a `Read` struct in a new `WaveReader`.
-     * 
+    /// 
-     * This is the primary entry point into the `WaveReader` interface. The
+    /// 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
+    /// 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 
+    /// WAVE data. For a .wav file, this means it must be at the start of the 
-     * file.
+    /// file.
-     * 
+    ///
-     * This function does a minimal validation on the provided stream and
+    /// This function does a minimal validation on the provided stream and
-     * will return an `Err(errors::Error)` immediately if there is a structural 
+    /// will return an `Err(errors::Error)` immediately if there is a structural 
-     * inconsistency that makes the stream unreadable or if it's missing 
+    /// inconsistency that makes the stream unreadable or if it's missing 
-     * essential components that make interpreting the audio data impossible.
+    /// essential components that make interpreting the audio data impossible.
-     * 
+     
-     * ```rust
+    /// ```rust
-     * use std::fs::File;
+    /// use std::fs::File;
-     * use std::io::{Error,ErrorKind};
+    /// use std::io::{Error,ErrorKind};
-     * use bwavfile::{WaveReader, Error as WavError};
+    /// use bwavfile::{WaveReader, Error as WavError};
-     * 
+    ///
-     * let f = File::open("tests/media/error.wav").unwrap();
+    /// let f = File::open("tests/media/error.wav").unwrap();
-     * 
+    ///
-     * let reader = WaveReader::new(f);
+    /// let reader = WaveReader::new(f);
-     * 
+    ///
-     * match reader {
+    /// match reader {
-     *      Ok(_) => panic!("error.wav should not be openable"),
+    ///      Ok(_) => panic!("error.wav should not be openable"),
-     *      Err( WavError::IOError( e ) ) => {
+    ///      Err( WavError::IOError( e ) ) => {
-     *          assert_eq!(e.kind(), ErrorKind::UnexpectedEof)
+    ///          assert_eq!(e.kind(), ErrorKind::UnexpectedEof)
-     *      }
+    ///      }
-     *      Err(e) => panic!("Unexpected error was returned {:?}", e)
+    ///      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;
     }
@@ -110,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()?;
@@ -128,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> {
@@ -224,8 +245,7 @@ impl<R: Read + Seek> WaveReader<R> {
     /// 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_SIG, 0, buffer) 
-        self.read_chunk(ixml_fourcc, 0, buffer) 
     }
 
     /// Read AXML data.
@@ -236,8 +256,7 @@ impl<R: Read + Seek> WaveReader<R> {
     /// 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_SIG, 0, buffer)
-        self.read_chunk(axml_fourcc, 0, buffer)
     }
 
 
@@ -260,35 +279,33 @@ impl<R: Read + Seek> WaveReader<R> {
         }
     }
 
-    /** 
+    /// Validate minimal WAVE file.
-     * Validate minimal WAVE file.
+    ///
-     * 
+    /// `Ok(())` if the source is `validate_readable()` AND
-     * `Ok(())` if the source is `validate_readable()` AND
+    ///
-     * 
+    ///   - Contains _only_ a `fmt` chunk and `data` chunk, with no other chunks present
-     *   - 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
-     *   - `fmt` chunk is exactly 16 bytes long and begins _exactly_ at file offset 12
+    ///   - `data` content begins _exactly_ at file offset 36
-     *   - `data` content begins _exactly_ at file offset 36
+    ///   - is not an RF64/BW64
-     *   - is not an RF64/BW64
+    ///
-     * 
+    /// Some clients require a WAVE file to only contain format and data without any other
-     * 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.
-     * metadata and this function is provided to validate this condition.
+    ///
-     * 
+    /// ### Examples
-     * ### Examples
+    ///
-     * 
+    /// ```
-     * ```
+    /// # use bwavfile::WaveReader;
-     * # use bwavfile::WaveReader;
+    ///
-     * 
+    /// let mut w = WaveReader::open("tests/media/ff_minimal.wav").unwrap();
-     * let mut w = WaveReader::open("tests/media/ff_minimal.wav").unwrap();
+    /// w.validate_minimal().expect("Minimal wav did not validate not minimal!");
-     * w.validate_minimal().expect("Minimal wav did not validate not minimal!");
+    /// ```
-     * ```
+    ///
-     * 
+    /// ```
-     * ```
+    /// # use bwavfile::WaveReader;
-     * # use bwavfile::WaveReader;
+    ///
-     * 
+    /// let mut x = WaveReader::open("tests/media/pt_24bit_51.wav").unwrap();
-     * let mut x = WaveReader::open("tests/media/pt_24bit_51.wav").unwrap();
+    /// x.validate_minimal().expect_err("Complex WAV validated minimal!");
-     * x.validate_minimal().expect_err("Complex WAV validated minimal!");
+    /// ```
-     * ```
-    */
     pub fn validate_minimal(&mut self) -> Result<(), ParserError>  {
         self.validate_readable()?;
 
@@ -302,39 +319,37 @@ impl<R: Read + Seek> WaveReader<R> {
         }
     }
 
-    /**
+    /// Validate Broadcast-WAVE file format
-     * Validate Broadcast-WAVE file format
+    /// 
-     * 
+    /// Returns `Ok(())` if `validate_readable()` and file contains a 
-     * Returns `Ok(())` if `validate_readable()` and file contains a 
+    /// Broadcast-WAV metadata record (a `bext` chunk).
-     * Broadcast-WAV metadata record (a `bext` chunk).
+    /// 
-     * 
+    /// ### Examples
-     * ### Examples
+    /// 
-     * 
+    /// ```
-     * ```
+    /// # use bwavfile::WaveReader;
-     * # use bwavfile::WaveReader;
+    /// 
-     * 
+    /// let mut w = WaveReader::open("tests/media/ff_bwav_stereo.wav").unwrap();
-     * let mut w = WaveReader::open("tests/media/ff_bwav_stereo.wav").unwrap();
+    /// w.validate_broadcast_wave().expect("BWAVE file did not validate BWAVE");
-     * w.validate_broadcast_wave().expect("BWAVE file did not validate BWAVE");
+    /// 
-     * 
+    /// let mut x = WaveReader::open("tests/media/pt_24bit.wav").unwrap();
-     * let mut x = WaveReader::open("tests/media/pt_24bit.wav").unwrap();
+    /// x.validate_broadcast_wave().expect("BWAVE file did not validate BWAVE");
-     * x.validate_broadcast_wave().expect("BWAVE file did not validate BWAVE");
+    /// 
-     * 
+    /// let mut y = WaveReader::open("tests/media/audacity_16bit.wav").unwrap();
-     * let mut y = WaveReader::open("tests/media/audacity_16bit.wav").unwrap();
+    /// y.validate_broadcast_wave().expect_err("Plain WAV file DID validate BWAVE");
-     * 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.
+    /// Verify data is aligned to a block boundary.
-     * 
+    ///
-     * Returns `Ok(())` if `validate_readable()` and the start of the 
+    /// Returns `Ok(())` if `validate_readable()` and the start of the 
-     * `data` chunk's content begins at 0x4000.
+    /// `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)?;
@@ -345,15 +360,13 @@ impl<R: Read + Seek> WaveReader<R> {
         }
     }
 
-    /**
+    /// Verify audio data can be appended immediately to this file.
-     * Verify audio data can be appended immediately to this file.
+    /// 
-     * 
+    /// Returns `Ok(())` if:
-     * Returns `Ok(())` if:
+    ///  - `validate_readable()`
-     *  - `validate_readable()`
+    ///  - there is a `JUNK` or `FLLR` immediately at the beginning of the chunk 
-     *  - 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)
-     *    list adequately large enough to be overwritten by a `ds64` (92 bytes)
+    ///  - `data` is the final chunk
-     *  - `data` is the final chunk
-    */
     pub fn validate_prepared_for_append(&mut self) -> Result<(), ParserError> {
         self.validate_readable()?;
 

src/wavewriter.rs

@@ -1,50 +1,73 @@
 use std::fs::File;
-use std::io::{Write,Seek,SeekFrom};
+use std::io::{Write,Seek,SeekFrom,Cursor};
 
 use super::Error;
-use super::fourcc::{FourCC, WriteFourCC, RIFF_SIG, WAVE_SIG, FMT__SIG, DATA_SIG, ELM1_SIG};
+use super::fourcc::{FourCC, WriteFourCC, RIFF_SIG, RF64_SIG, DS64_SIG,
+    WAVE_SIG, FMT__SIG, DATA_SIG, ELM1_SIG, JUNK_SIG, BEXT_SIG,AXML_SIG, 
+    IXML_SIG};
 use super::fmt::WaveFmt;
 //use super::common_format::CommonFormat;
 use super::chunks::WriteBWaveChunks;
+use super::bext::Bext;
 
 use byteorder::LittleEndian;
 use byteorder::WriteBytesExt;
 
-
+/// Write audio frames to a `WaveWriter`.
+/// 
+/// 
 pub struct AudioFrameWriter<W> where W: Write + Seek {
     inner : WaveChunkWriter<W>
 }
 
 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());
 
-        let framed_bits_per_sample = format.block_alignment * 8 / format.channel_count;
+    fn new(inner: WaveChunkWriter<W>) -> Self {
-
+        AudioFrameWriter { inner }
-        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)
-            }
     }
 
-        Ok(1)
+    fn write_integer_frames_to_buffer(&self, from_frames :&[i32], to_buffer : &mut Vec<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);
+        ()
     }
 
+    /// Write interleaved samples in `buffer`
+    /// 
+    /// # Panics
+    /// 
+    /// 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];
+
+        self.write_integer_frames_to_buffer(&buffer, &mut write_buffer);
+
+        self.inner.write(&write_buffer)?;
+        self.inner.flush()?;
+        Ok(write_buffer.len() as u64 / self.inner.inner.format.channel_count as u64)
+    }
+
+    /// Finish writing audio frames and unwrap the inner `WaveWriter`.
+    /// 
+    /// This method must be called when the client has finished writing audio
+    /// data. This will finalize the audio data chunk.
     pub fn end(self) -> Result<WaveWriter<W>, Error> {
         self.inner.end()
     }
 }
 
-
+/// Write a wave data chunk.
+/// 
+/// `WaveChunkWriter` implements `Write` and as bytes are written to it,
+/// 
+/// ### Important! 
+/// 
+/// When you are done writing to a chunk you must call `end()` in order to 
+/// finalize the chunk for storage.
 pub struct WaveChunkWriter<W> where W: Write + Seek {
+    ident : FourCC,
     inner : WaveWriter<W>,
     content_start_pos : u64,
     length : u64
@@ -58,7 +81,7 @@ impl<W> WaveChunkWriter<W> where W: Write + Seek {
         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 } )
+        Ok( WaveChunkWriter { ident, inner , content_start_pos, length } )
     }
 
     fn end(mut self) -> Result<WaveWriter<W>, Error> {
@@ -72,11 +95,22 @@ impl<W> WaveChunkWriter<W> where W: Write + Seek {
 
     fn increment_chunk_length(&mut self, amount: u64) -> Result<(), std::io::Error> {
         self.length = self.length + amount;
-        if self.length < u32::MAX as u64 {
+        if !self.inner.is_rf64 {
             self.inner.inner.seek(SeekFrom::Start(self.content_start_pos - 4))?;
             self.inner.inner.write_u32::<LittleEndian>(self.length as u32)?;
         } else {
-            todo!()
+            if self.ident == DATA_SIG {
+                let data_chunk_64bit_field_offset = 8 + 4 + 8 + 8;
+                self.inner.inner.seek(SeekFrom::Start(self.content_start_pos - 4))?;
+                self.inner.inner.write_u32::<LittleEndian>(0xFFFF_FFFF)?; 
+                    // this only need to happen once, not every time we increment
+
+                self.inner.inner.seek(SeekFrom::Start(data_chunk_64bit_field_offset))?;
+                self.inner.inner.write_u64::<LittleEndian>(self.length)?;
+            } else {
+                todo!("FIXME RF64 wave writing is not yet supported for chunks other than `data`")
+            }
+            
         }
 
         Ok(())
@@ -88,8 +122,8 @@ impl<W> Write for WaveChunkWriter<W> where W: Write + Seek {
     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)?;
+        self.increment_chunk_length(written as u64)?;
 
         Ok( written )
     }
@@ -101,30 +135,80 @@ impl<W> Write for WaveChunkWriter<W> where W: Write + Seek {
 
 /// Wave, Broadcast-WAV and RF64/BW64 writer.
 /// 
+/// A `WaveWriter` creates a new wave file at the given path (with `create()`)
+/// or into the given `Write`- and `Seek`-able inner writer.
+/// 
+/// Audio is added to the wave file by starting the audio data chunk with
+/// `WaveWriter::audio_frame_writer()`. All of the functions that add chunks
+/// move the WaveWriter and return it to the host when complete.
+/// 
+/// # Structure of New Wave Files
+/// 
+/// `WaveWriter` will create a Wave file with two chunks automatically: a 96
+/// byte `JUNK` chunk and a standard `fmt ` chunk, which has the extended 
+/// length if the format your provided requires it. The first `JUNK` chunk is 
+/// a reservation for a `ds64` record which will be written over it if
+/// the file needs to be upgraded to RF64 format.
+/// 
+/// Chunks are added to the file in the order the client adds them. 
+/// `audio_file_writer()` will add a `data` chunk for the audio data, and will
+/// also add an `elm1` filler chunk prior to the data chunk to ensure that the 
+/// first byte of the data chunk's content is aligned with 0x4000.
+/// 
 /// ```
 /// 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 format = WaveFmt::new_pcm_mono(48000, 24);
 /// 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_frames(&[0i32]).unwrap();
-/// frame_writer.write_integer_frame(&[0i32]).unwrap();
+/// frame_writer.write_integer_frames(&[0i32]).unwrap();
-/// frame_writer.write_integer_frame(&[0i32]).unwrap();
+/// frame_writer.write_integer_frames(&[0i32]).unwrap();
 /// frame_writer.end().unwrap();
 /// ```
+///
+/// ## Resources
+/// 
+/// ### Implementation of Wave Files
+/// - [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
+///  
+/// ### Implementation of Broadcast Wave Files
+/// - [EBU Tech 3285][ebu3285] (May 2011), "Specification of the Broadcast Wave Format (BWF)"
+///   - [Supplement 1](https://tech.ebu.ch/docs/tech/tech3285s1.pdf) (July 1997): MPEG Audio
+///   - [EBU Rec 68](https://tech.ebu.ch/docs/r/r068.pdf): Signal modulation and format constraints
+///
+/// ### Implementation of 64-bit Wave Files
+/// - [ITU-R 2088][itu2088] (October 2019), "Long-form file format for the international exchange of audio programme materials with metadata"
+///   - Presently in force, adopted by the EBU in [EBU Tech 3306v2][ebu3306v2] (June 2018).
+/// - [EBU Tech 3306v1][ebu3306v1] (July 2009), "MBWF / RF64: An extended File Format for Audio"
+///   - No longer in force, however long-established.
+/// 
+///
+/// [ebu3285]: https://tech.ebu.ch/docs/tech/tech3285.pdf
+/// [ebu3306v1]: https://tech.ebu.ch/docs/tech/tech3306v1_1.pdf
+/// [ebu3306v2]: https://tech.ebu.ch/docs/tech/tech3306.pdf
+/// [itu2088]: https://www.itu.int/dms_pubrec/itu-r/rec/bs/R-REC-BS.2088-1-201910-I!!PDF-E.pdf
+/// [rfc3261]: https://tools.ietf.org/html/rfc2361 
 pub struct WaveWriter<W> where W: Write + Seek {
     inner : W,
     form_length: u64,
 
+    /// True if file is RF64
+    pub is_rf64: bool,
+
     /// Format of the wave file.
     pub format: WaveFmt
 }
 
+const DS64_RESERVATION_LENGTH : u32 = 96;
+
 impl WaveWriter<File> {
 
     /// Create a new Wave file at `path`.
@@ -146,25 +230,67 @@ impl<W> WaveWriter<W> where W: Write + Seek {
         inner.write_u32::<LittleEndian>(0)?;
         inner.write_fourcc(WAVE_SIG)?;
 
-        let mut retval = WaveWriter { inner, form_length: 0, format};
+        let mut retval = WaveWriter { inner, form_length: 0, is_rf64: false, format};
+
         retval.increment_form_length(4)?;
 
-        let mut chunk = retval.begin_chunk(FMT__SIG)?;
+        // write ds64_reservation
+        retval.write_junk(DS64_RESERVATION_LENGTH)?;
+
+        let mut chunk = retval.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`.
+    fn write_chunk(&mut self, ident: FourCC, data : &[u8]) -> Result<(),Error> {
-    /// 
-    /// 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)
+        self.inner.write_fourcc(ident)?;
+        assert!(data.len() < u32::MAX as usize);
+        self.inner.write_u32::<LittleEndian>(data.len() as u32)?;
+        self.inner.write(data)?;
+        if data.len() % 2 == 0 {
+            self.increment_form_length(8 + data.len() as u64)?;
+        } else {
+            self.inner.write(&[0u8])?;
+            self.increment_form_length(8 + data.len() as u64 + 1)?;
+        }
+        Ok(())
     }
 
+    /// Write Broadcast-Wave metadata to the file.
+    /// 
+    /// This function will write the metadata chunk immediately to the end of 
+    /// the file; if you have already written and closed the audio data the 
+    /// bext chunk will be positioned after it.
+    pub fn write_broadcast_metadata(&mut self, bext: &Bext) -> Result<(),Error> {
+        let mut c = Cursor::new(vec![0u8; 0]);
+        c.write_bext(&bext)?;
+        let buf = c.into_inner();
+        self.write_chunk(BEXT_SIG, &buf )?;
+        Ok(())
+    }
+
+    /// Write iXML metadata
+    pub fn write_ixml(&mut self, ixml: &[u8]) -> Result<(),Error> {
+        self.write_chunk(IXML_SIG, &ixml)
+    }
+
+    /// Write axml/ADM metadata
+    pub fn write_axml(&mut self, axml: &[u8]) -> Result<(), Error> {
+        self.write_chunk(AXML_SIG, &axml)
+    }
+
+    /// Write a `JUNK` filler chunk
+    pub fn write_junk(&mut self, length: u32) -> Result<(), Error> {
+        let filler = vec![0u8; length as usize];
+        self.write_chunk(JUNK_SIG, &filler)
+    }
+
+    /// Create an audio frame writer, which takes possession of the callee 
+    /// `WaveWriter`.
+    ///  
     pub fn audio_frame_writer(mut self) -> Result<AudioFrameWriter<W>, Error> {
         // append elm1 chunk
 
@@ -172,22 +298,51 @@ impl<W> WaveWriter<W> where W: Write + Seek {
 
         let lip = self.inner.seek(SeekFrom::End(0))?;
         let to_add = framing - (lip % framing) - 16;
-        let mut chunk = self.begin_chunk(ELM1_SIG)?;
+        let mut chunk = self.chunk(ELM1_SIG)?;
         let buf = vec![0u8; to_add as usize];
         chunk.write(&buf)?;
         let closed = chunk.end()?;
-
+        let inner = closed.chunk(DATA_SIG)?;
-        let inner = closed.begin_chunk(DATA_SIG)?;
+        Ok( AudioFrameWriter::new(inner) )
-        Ok( AudioFrameWriter { inner } )
     }
 
-    fn increment_form_length(&mut self, amount: u64) -> Result<(), std::io::Error> {
+    /// Open a wave chunk writer here
-        self.form_length = self.form_length + amount;
+    fn chunk(mut self, ident: FourCC) -> Result<WaveChunkWriter<W>,Error> {
-        self.inner.seek(SeekFrom::Start(4))?;
+        self.inner.seek(SeekFrom::End(0))?;
-        self.inner.write_u32::<LittleEndian>(self.form_length as u32)?;
+        WaveChunkWriter::begin(self, ident)
+    }
+
+    /// Upgrade this file to RF64
+    fn promote_to_rf64(&mut self) -> Result<(), std::io::Error> {
+        if !self.is_rf64 {
+            self.inner.seek(SeekFrom::Start(0))?;
+            self.inner.write_fourcc(RF64_SIG)?;
+            self.inner.write_u32::<LittleEndian>(0xFFFF_FFFF)?;
+            self.inner.seek(SeekFrom::Start(12))?;
+
+            self.inner.write_fourcc(DS64_SIG)?;
+            self.inner.seek(SeekFrom::Current(4))?;
+            self.inner.write_u64::<LittleEndian>(self.form_length)?;
+            self.is_rf64 = true;
+        }
         Ok(())
     }
 
+    /// Add `amount` to the RIFF/RF64 form length
+    fn increment_form_length(&mut self, amount: u64) -> Result<(), std::io::Error> {
+        self.form_length = self.form_length + amount;
+        if self.is_rf64 {
+            self.inner.seek(SeekFrom::Start(8 + 4 + 8))?;
+            self.inner.write_u64::<LittleEndian>(self.form_length)?;
+        } else if self.form_length < u32::MAX as u64 {
+            self.inner.seek(SeekFrom::Start(4))?;
+            self.inner.write_u32::<LittleEndian>(self.form_length as u32)?;
+        } else {
+            self.promote_to_rf64()?;
+            
+        }
+        Ok(())
+    }
 }
 
 #[test]
@@ -197,16 +352,23 @@ fn test_new() {
     use byteorder::ReadBytesExt;
 
     let mut cursor = Cursor::new(vec![0u8;0]);
-    let format = WaveFmt::new_pcm(4800, 24, 1);
+    let format = WaveFmt::new_pcm_mono(4800, 24);
     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(), JUNK_SIG);
+    let junk_size = cursor.read_u32::<LittleEndian>().unwrap();
+    assert_eq!(junk_size,96);
+    cursor.seek(SeekFrom::Current(junk_size as i64)).unwrap();
+
     assert_eq!(cursor.read_fourcc().unwrap(), FMT__SIG);
     let fmt_size = cursor.read_u32::<LittleEndian>().unwrap();
-    assert_eq!(form_size, fmt_size + 8 + 4);
+    assert_eq!(form_size, 4 + 8 + junk_size + 8 + fmt_size);
 }
 
 #[test]
@@ -216,14 +378,14 @@ fn test_write_audio() {
     use byteorder::ReadBytesExt;
 
     let mut cursor = Cursor::new(vec![0u8;0]);
-    let format = WaveFmt::new_pcm(48000, 24, 1);
+    let format = WaveFmt::new_pcm_mono(48000, 24);
     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_frames(&[0i32]).unwrap();
-    frame_writer.write_integer_frame(&[0i32]).unwrap();
+    frame_writer.write_integer_frames(&[0i32]).unwrap();
-    frame_writer.write_integer_frame(&[0i32]).unwrap();
+    frame_writer.write_integer_frames(&[0i32]).unwrap();
 
     frame_writer.end().unwrap();
 
@@ -231,22 +393,119 @@ fn test_write_audio() {
 
     cursor.seek(SeekFrom::Start(0)).unwrap();
     assert_eq!(cursor.read_fourcc().unwrap(), RIFF_SIG);
-    let _ = cursor.read_u32::<LittleEndian>().unwrap();
+    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 seek = cursor.read_u32::<LittleEndian>().unwrap();
-    cursor.seek(SeekFrom::Current(seek as i64)).unwrap();
 
-    assert_eq!(cursor.read_fourcc().unwrap(), ELM1_SIG);
+    assert_eq!(cursor.read_fourcc().unwrap(), WAVE_SIG); //4
-    let seek = cursor.read_u32::<LittleEndian>().unwrap();
-    cursor.seek(SeekFrom::Current(seek as i64)).unwrap();
 
-    assert_eq!(cursor.read_fourcc().unwrap(), DATA_SIG);
+    assert_eq!(cursor.read_fourcc().unwrap(), JUNK_SIG); //4
-    let data_size = cursor.read_u32::<LittleEndian>().unwrap();
+    let junk_size = cursor.read_u32::<LittleEndian>().unwrap(); //4
+    cursor.seek(SeekFrom::Current(junk_size as i64)).unwrap();
+
+    assert_eq!(cursor.read_fourcc().unwrap(), FMT__SIG); //4
+    let fmt_size = cursor.read_u32::<LittleEndian>().unwrap(); //4
+    cursor.seek(SeekFrom::Current(fmt_size as i64)).unwrap();
+
+    assert_eq!(cursor.read_fourcc().unwrap(), ELM1_SIG); //4
+    let elm1_size = cursor.read_u32::<LittleEndian>().unwrap(); //4
+    cursor.seek(SeekFrom::Current(elm1_size as i64)).unwrap();
+
+    assert_eq!(cursor.read_fourcc().unwrap(), DATA_SIG); //4
+    let data_size = cursor.read_u32::<LittleEndian>().unwrap(); //4
     assert_eq!(data_size, 9);
 
     let tell = cursor.seek(SeekFrom::Current(0)).unwrap();
     assert!(tell % 0x4000 == 0);
 
-
+    assert_eq!(form_size, 4 + 8 + junk_size + 8 + fmt_size + 8 + elm1_size + 8 + data_size + data_size % 2)
+}
+
+#[test]
+fn test_write_bext() {
+    use std::io::Cursor;
+
+    let mut cursor = Cursor::new(vec![0u8;0]);
+    let format = WaveFmt::new_pcm_mono(48000, 24);
+    let mut w = WaveWriter::new(&mut cursor, format).unwrap();
+
+    let bext = Bext {
+        description: String::from("Test description"),
+        originator: String::from(""),
+        originator_reference: String::from(""),
+        origination_date: String::from("2020-01-01"),
+        origination_time: String::from("12:34:56"),
+        time_reference: 0,
+        version: 0,
+        umid: None,
+        loudness_value: None,
+        loudness_range: None,
+        max_true_peak_level: None,
+        max_momentary_loudness: None,
+        max_short_term_loudness: None,
+        coding_history: String::from(""),
+    };
+
+    w.write_broadcast_metadata(&bext).unwrap();
+
+    let mut frame_writer = w.audio_frame_writer().unwrap();
+
+    frame_writer.write_integer_frames(&[0i32]).unwrap();
+    frame_writer.write_integer_frames(&[0i32]).unwrap();
+    frame_writer.write_integer_frames(&[0i32]).unwrap();
+
+    frame_writer.end().unwrap();
+}
+
+
+// NOTE! This test of RF64 writing takes several minutes to complete.
+#[test]
+fn test_create_rf64() {
+    use super::fourcc::ReadFourCC;
+    use byteorder::ReadBytesExt;
+
+    let mut cursor = Cursor::new(vec![0u8;0]);
+    let format = WaveFmt::new_pcm_stereo(48000, 24);
+    let w = WaveWriter::new(&mut cursor, format).unwrap();
+
+    let buflen = 16000 as u64;
+
+    let buf = vec![0i32; buflen as usize];
+
+    let four_and_a_half_hours_of_frames = 48000 * 16_200;
+
+    let mut af = w.audio_frame_writer().unwrap();
+
+    for _ in 0..(four_and_a_half_hours_of_frames * format.channel_count as u64 / buflen) {
+        af.write_integer_frames(&buf).unwrap();
+    }
+    af.end().unwrap();
+
+    assert!(cursor.seek(SeekFrom::End(0)).unwrap() > 0xFFFF_FFFFu64, "internal test error, Created file is not long enough to be RF64" );
+    let expected_data_length = four_and_a_half_hours_of_frames * format.block_alignment as u64;
+
+    cursor.seek(SeekFrom::Start(0)).unwrap();
+    assert_eq!(cursor.read_fourcc().unwrap(), RF64_SIG);
+    assert_eq!(cursor.read_u32::<LittleEndian>().unwrap(), 0xFFFF_FFFF);
+    assert_eq!(cursor.read_fourcc().unwrap(), WAVE_SIG);
+
+    assert_eq!(cursor.read_fourcc().unwrap(), DS64_SIG);
+    let ds64_size = cursor.read_u32::<LittleEndian>().unwrap();
+    let form_size = cursor.read_u64::<LittleEndian>().unwrap();
+    let data_size = cursor.read_u64::<LittleEndian>().unwrap();
+    assert_eq!(data_size, expected_data_length);
+    cursor.seek(SeekFrom::Current(ds64_size as i64 - 16)).unwrap();
+
+    assert_eq!(cursor.read_fourcc().unwrap(), FMT__SIG);
+    let fmt_size = cursor.read_u32::<LittleEndian>().unwrap();
+    cursor.seek(SeekFrom::Current((fmt_size + fmt_size % 2) as i64)).unwrap();
+    
+    assert_eq!(cursor.read_fourcc().unwrap(), ELM1_SIG);
+    let elm1_size = cursor.read_u32::<LittleEndian>().unwrap();
+    let data_start = cursor.seek(SeekFrom::Current((elm1_size + elm1_size % 2) as i64)).unwrap();
+    
+    assert!((data_start + 8) % 0x4000 == 0, "data content start is not aligned, starts at {}", data_start + 8);
+    assert_eq!(cursor.read_fourcc().unwrap(), DATA_SIG);
+    assert_eq!(cursor.read_u32::<LittleEndian>().unwrap(), 0xFFFF_FFFF);
+    cursor.seek(SeekFrom::Current(data_size as i64)).unwrap();
+
+    assert_eq!(4 + 8 + ds64_size as u64 + 8 + data_size + 8 + fmt_size as u64 + 8 + elm1_size as u64, form_size)
 }

tests/Untitled.txt

@@ -1,5 +0,0 @@
-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