Added tests for Bext::default()

Nudge version

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,28 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: "[Bug] __Enter a title here__"
+labels: bug
+assignees: iluvcapra
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Example Code**:
+```rust
+// Give an example of code that is failing here.
+```
+
+**Platform**:
+ - OS
+ - `rustc` version: ____ (from `rustup -V`)
+ - Host: ____ (from `rustup show` e.g. x86_64-apple-darwin)
+ - Rust toolchain: ____ (e.g. stable-x86_64-apple-darwin)
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,25 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: "[Feature] __Name the Feature__"
+labels: enhancement
+assignees: iluvcapra
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like:**
+A clear and concise description of what you want to happen.
+
+**Code Example:**
+```rust
+// Give an example of how you would like your feature to work.
+```
+
+**Describe alternatives you've considered:**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context:**
+Add any other context or screenshots about the feature request here.

Cargo.lock

@@ -2,6 +2,21 @@
 # It is not intended for manual editing.
 version = 3
 
+[[package]]
+name = "android-tzdata"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e999941b234f3131b00bc13c22d06e8c5ff726d1b6318ac7eb276997bbb4fef0"
+
+[[package]]
+name = "android_system_properties"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "819e7219dbd41043ac279b19830f2efc897156490d7fd6ea916720117ee66311"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "ansi_term"
 version = "0.11.0"
@@ -22,17 +37,30 @@ dependencies = [
  "winapi",
 ]
 
+[[package]]
+name = "autocfg"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d468802bab17cbc0cc575e9b053f41e72aa36bfa6b7f55e3529ffa43161b97fa"
+
 [[package]]
 name = "bitflags"
 version = "1.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a"
 
+[[package]]
+name = "bumpalo"
+version = "3.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a3e2c3daef883ecc1b5d58c15adae93470a91d425f3532ba1695849656af3fc1"
+
 [[package]]
 name = "bwavfile"
-version = "1.1.0"
+version = "2.1.0"
 dependencies = [
  "byteorder",
+ "chrono",
  "clap",
  "dasp_sample",
  "encoding",
@@ -46,6 +74,33 @@ version = "1.4.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "14c189c53d098945499cdfa7ecc63567cf3886b3332b312a5b4585d8d3a6a610"
 
+[[package]]
+name = "cc"
+version = "1.0.79"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "50d30906286121d95be3d479533b458f87493b30a4b5f79a607db8f5d11aa91f"
+
+[[package]]
+name = "cfg-if"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "baf1de4339761588bc0619e3cbc0120ee582ebb74b53b4efbf79117bd2da40fd"
+
+[[package]]
+name = "chrono"
+version = "0.4.26"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ec837a71355b28f6556dbd569b37b3f363091c0bd4b2e735674521b4c5fd9bc5"
+dependencies = [
+ "android-tzdata",
+ "iana-time-zone",
+ "js-sys",
+ "num-traits",
+ "time",
+ "wasm-bindgen",
+ "winapi",
+]
+
 [[package]]
 name = "clap"
 version = "2.33.3"
@@ -61,6 +116,12 @@ dependencies = [
  "vec_map",
 ]
 
+[[package]]
+name = "core-foundation-sys"
+version = "0.8.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e496a50fda8aacccc86d7529e2c1e0892dbd0f898a6b5645b5561b89c3210efa"
+
 [[package]]
 name = "dasp_sample"
 version = "0.11.0"
@@ -140,6 +201,29 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "iana-time-zone"
+version = "0.1.56"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0722cd7114b7de04316e7ea5456a0bbb20e4adb46fd27a3697adb812cff0f37c"
+dependencies = [
+ "android_system_properties",
+ "core-foundation-sys",
+ "iana-time-zone-haiku",
+ "js-sys",
+ "wasm-bindgen",
+ "windows",
+]
+
+[[package]]
+name = "iana-time-zone-haiku"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f31827a206f56af32e590ba56d5d2d085f558508192593743f16b2306495269f"
+dependencies = [
+ "cc",
+]
+
 [[package]]
 name = "itoa"
 version = "0.4.8"
@@ -147,10 +231,58 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b71991ff56294aa922b450139ee08b3bfc70982c6b2c7562771375cf73542dd4"
 
 [[package]]
-name = "libc"
+name = "js-sys"
-version = "0.2.103"
+version = "0.3.63"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dd8f7255a17a627354f321ef0055d63b898c6fb27eff628af4d1b66b7331edf6"
+checksum = "2f37a4a5928311ac501dee68b3c7613a1037d0edb30c8e5427bd832d55d1b790"
+dependencies = [
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.144"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2b00cc1c228a6782d0f076e7b232802e0c5689d41bb5df366f2a6b6621cfdfe1"
+
+[[package]]
+name = "log"
+version = "0.4.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "518ef76f2f87365916b142844c16d8fefd85039bc5699050210a7778ee1cd1de"
+
+[[package]]
+name = "num-traits"
+version = "0.2.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "578ede34cf02f8924ab9447f50c28075b4d3e5b269972345e7e0372b38c6cdcd"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.17.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9670a07f94779e00908f3e686eab508878ebb390ba6e604d3a284c00e8d0487b"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.59"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6aeca18b86b413c660b781aa319e4e2648a3e6f9eadc9b47e9038e6fe9f3451b"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b9ab9c7eadfd8df19006f1cf1a4aed13540ed5cbc047010ece5826e10825488"
+dependencies = [
+ "proc-macro2",
+]
 
 [[package]]
 name = "ryu"
@@ -181,6 +313,17 @@ version = "0.8.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8ea5119cdb4c55b55d432abb513a0429384878c15dde60cc77b1c99de1a95a6a"
 
+[[package]]
+name = "syn"
+version = "2.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32d41677bcbe24c20c52e7c70b0d8db04134c5d1066bf98662e2871ad200ea3e"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
 [[package]]
 name = "textwrap"
 version = "0.11.0"
@@ -190,6 +333,23 @@ dependencies = [
  "unicode-width",
 ]
 
+[[package]]
+name = "time"
+version = "0.1.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b797afad3f312d1c66a56d11d0316f916356d11bd158fbc6ca6389ff6bf805a"
+dependencies = [
+ "libc",
+ "wasi",
+ "winapi",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b15811caf2415fb889178633e7724bad2509101cde276048e013b9def5e51fa0"
+
 [[package]]
 name = "unicode-width"
 version = "0.1.9"
@@ -208,6 +368,66 @@ version = "0.8.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f1bddf1187be692e79c5ffeab891132dfb0f236ed36a43c7ed39f1165ee20191"
 
+[[package]]
+name = "wasi"
+version = "0.10.0+wasi-snapshot-preview1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1a143597ca7c7793eff794def352d41792a93c481eb1042423ff7ff72ba2c31f"
+
+[[package]]
+name = "wasm-bindgen"
+version = "0.2.86"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5bba0e8cb82ba49ff4e229459ff22a191bbe9a1cb3a341610c9c33efc27ddf73"
+dependencies = [
+ "cfg-if",
+ "wasm-bindgen-macro",
+]
+
+[[package]]
+name = "wasm-bindgen-backend"
+version = "0.2.86"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "19b04bc93f9d6bdee709f6bd2118f57dd6679cf1176a1af464fca3ab0d66d8fb"
+dependencies = [
+ "bumpalo",
+ "log",
+ "once_cell",
+ "proc-macro2",
+ "quote",
+ "syn",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-macro"
+version = "0.2.86"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "14d6b024f1a526bb0234f52840389927257beb670610081360e5a03c5df9c258"
+dependencies = [
+ "quote",
+ "wasm-bindgen-macro-support",
+]
+
+[[package]]
+name = "wasm-bindgen-macro-support"
+version = "0.2.86"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e128beba882dd1eb6200e1dc92ae6c5dbaa4311aa7bb211ca035779e5efc39f8"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+ "wasm-bindgen-backend",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-shared"
+version = "0.2.86"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed9d5b4305409d1fc9482fee2d7f9bcbf24b3972bf59817ef757e23982242a93"
+
 [[package]]
 name = "winapi"
 version = "0.3.9"
@@ -229,3 +449,69 @@ name = "winapi-x86_64-pc-windows-gnu"
 version = "0.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
+
+[[package]]
+name = "windows"
+version = "0.48.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e686886bc078bc1b0b600cac0147aadb815089b6e4da64016cbd754b6342700f"
+dependencies = [
+ "windows-targets",
+]
+
+[[package]]
+name = "windows-targets"
+version = "0.48.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7b1eb6f0cd7c80c79759c929114ef071b87354ce476d9d94271031c0497adfd5"
+dependencies = [
+ "windows_aarch64_gnullvm",
+ "windows_aarch64_msvc",
+ "windows_i686_gnu",
+ "windows_i686_msvc",
+ "windows_x86_64_gnu",
+ "windows_x86_64_gnullvm",
+ "windows_x86_64_msvc",
+]
+
+[[package]]
+name = "windows_aarch64_gnullvm"
+version = "0.48.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "91ae572e1b79dba883e0d315474df7305d12f569b400fcf90581b06062f7e1bc"
+
+[[package]]
+name = "windows_aarch64_msvc"
+version = "0.48.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b2ef27e0d7bdfcfc7b868b317c1d32c641a6fe4629c171b8928c7b08d98d7cf3"
+
+[[package]]
+name = "windows_i686_gnu"
+version = "0.48.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "622a1962a7db830d6fd0a69683c80a18fda201879f0f447f065a3b7467daa241"
+
+[[package]]
+name = "windows_i686_msvc"
+version = "0.48.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4542c6e364ce21bf45d69fdd2a8e455fa38d316158cfd43b3ac1c5b1b19f8e00"
+
+[[package]]
+name = "windows_x86_64_gnu"
+version = "0.48.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ca2b8a661f7628cbd23440e50b05d705db3686f894fc9580820623656af974b1"
+
+[[package]]
+name = "windows_x86_64_gnullvm"
+version = "0.48.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7896dbc1f41e08872e9d5e8f8baa8fdd2677f29468c4e156210174edc7f7b953"
+
+[[package]]
+name = "windows_x86_64_msvc"
+version = "0.48.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1a515f5799fe4961cb532f983ce2b23082366b898e52ffbce459c86f67c8378a"

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "bwavfile"
-version = "2.0.0"
+version = "2.1.0"
 authors = ["Jamie Hardt <jamiehardt@me.com>", "Ian Hobson <ian.r.hobson@gmail.com>"]
 edition = "2018"
 license = "MIT"
@@ -19,6 +19,7 @@ dasp_sample = "0.11.0"
 encoding = "0.2.33"
 uuid = "0.8.1"
 clap = "2.33.3"
+chrono = "0.4.26"
 
 [dev-dependencies]
 serde_json = "1.0.61"

README.md

@@ -19,12 +19,12 @@ reading and creating new wave audio files.
   * 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.
+    wave data format.
 
 The library has extensive metadata support, with emphasis on film and video 
 production metadata:
-  * Broadcast-Wave metdata extension, including long description, originator 
+  * Broadcast-Wave metadata extension, including long description, originator, 
-    information, SMPTE UMID and coding history.
+		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 regions.
   * Multichannel, surround, and ambisonic audio data description including 

bwavefile.code-workspace

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

src/bext.rs

@@ -1,8 +1,10 @@
-pub type LU = f32;
 #[allow(clippy::upper_case_acronyms)]
+pub type LU = f32;
 pub type LUFS = f32;
 pub type Decibels = f32;
 
+use chrono::{Local, DateTime};
+
 ///  Broadcast-WAV metadata record.
 ///
 ///  The `bext` record contains information about the original recording of the
@@ -79,3 +81,43 @@ pub struct Bext {
     /// Coding History.
     pub coding_history: String,
 }
+
+impl Default for Bext {
+    /// Create a new version 0 `bext` with all description fields set to the empty string 
+    /// and the current local date and time filled in.
+    fn default() -> Self {
+        let now: DateTime<_> = Local::now();
+
+        Self {
+            description: "".to_string(),
+            originator: "".to_string(),
+            originator_reference: "".to_string(),
+            origination_date: now.date_naive().format("%Y-%m%-d").to_string(),
+            origination_time: now.time().format("%H:%M:%S").to_string(),
+            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: "".to_string(),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn build_default() {
+        let d = Bext::default();
+        assert_eq!(d.description, "");
+        assert_eq!(d.originator, "");
+        assert_eq!(d.originator_reference, "");
+        assert_eq!(d.version, 0);
+        assert_eq!(d.time_reference, 0);
+    }
+}

src/common_format.rs

@@ -1,8 +1,17 @@
+/// Format tags, UUIDs and utilities
+
 use uuid::Uuid;
 
+/// Format tag for integer LPCM
 pub const WAVE_TAG_PCM: u16 = 0x0001;
+
+/// Format tag for float LPCM
 pub const WAVE_TAG_FLOAT: u16 = 0x0003;
+
+/// Format tag for MPEG1
 pub const WAVE_TAG_MPEG: u16 = 0x0050;
+
+/// Format tag indicating extended format
 pub const WAVE_TAG_EXTENDED: u16 = 0xFFFE;
 
 /* RC 2361 §4:
@@ -15,34 +24,38 @@ pub const WAVE_TAG_EXTENDED: u16 = 0xFFFE;
 
 */
 
+/// Extended format UUID for integer PCM
 pub const WAVE_UUID_PCM: Uuid = Uuid::from_bytes([
     0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10, 0x00, 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71,
 ]);
 
+/// Extended format UUID for float PCM
 pub const WAVE_UUID_FLOAT: Uuid = Uuid::from_bytes([
     0x03, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10, 0x00, 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71,
 ]);
 
+/// Extended format UUID for MPEG1 data
 pub const WAVE_UUID_MPEG: Uuid = Uuid::from_bytes([
     0x50, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10, 0x00, 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71,
 ]);
 
+/// Extended format for integer Ambisonic B-Format
 pub const WAVE_UUID_BFORMAT_PCM: Uuid = Uuid::from_bytes([
     0x01, 0x00, 0x00, 0x00, 0x21, 0x07, 0xd3, 0x11, 0x86, 0x44, 0xc8, 0xc1, 0xca, 0x00, 0x00, 0x00,
 ]);
 
+/// Extended format for float Ambisonic B-Format
 pub const WAVE_UUID_BFORMAT_FLOAT: Uuid = Uuid::from_bytes([
     0x03, 0x00, 0x00, 0x00, 0x21, 0x07, 0xd3, 0x11, 0x86, 0x44, 0xc8, 0xc1, 0xca, 0x00, 0x00, 0x00,
 ]);
 
+/// Generate an extended format UUID for the given basic format tag from [WaveFmt::tag].
 fn uuid_from_basic_tag(tag: u16) -> Uuid {
     let tail: [u8; 6] = [0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71];
     Uuid::from_fields_le(tag as u32, 0x0000, 0x0010, &tail).unwrap()
 }
 
 /// Sample format of the Wave file.
-///
-///
 #[derive(Debug, Copy, Clone, PartialEq)]
 pub enum CommonFormat {
     /// Integer linear PCM

src/fmt.rs

@@ -116,7 +116,8 @@ impl ChannelMask {
 /**
  * Extended Wave Format
  *
- * https://docs.microsoft.com/en-us/windows/win32/api/mmreg/ns-mmreg-waveformatextensible
+ * Resources: 
+ * * [WAVEFORMATEXTENSIBLE structure](https://docs.microsoft.com/en-us/windows/win32/api/mmreg/ns-mmreg-waveformatextensible)
  */
 #[derive(Debug, Copy, Clone)]
 pub struct WaveFmtExtended {
@@ -151,7 +152,7 @@ pub struct WaveFmtExtended {
 /// ### 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)
+/// - [Audio File Format Specifications](http://www-mmsp.ece.mcgill.ca/Documents/AudioFormats/WAVE/WAVE.html) (September 2022) Prof. Peter Kabal, MMSP Lab, ECE, McGill University
 /// - [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
 ///
@@ -162,7 +163,7 @@ pub struct WaveFmt {
     /// A tag identifying the codec in use.
     ///
     /// If this is 0xFFFE, the codec will be identified by a GUID
-    /// in `extended_format`
+    /// in [`extended_format`](WaveFmt::extended_format).
     pub tag: u16,
 
     /// Count of audio channels in each frame
@@ -198,7 +199,7 @@ pub struct WaveFmt {
 
     /// Extended format description
     ///
-    /// Additional format metadata if `channel_count` is greater than 2,
+    /// Additional format metadata if channel_count is greater than 2,
     /// or if certain codecs are used.
     pub extended_format: Option<WaveFmtExtended>,
 }
@@ -245,11 +246,11 @@ impl WaveFmt {
         }
     }
 
-    /// Create a new integer PCM format `WaveFmt` with a custom channel bitmap.
+    /// Create a new integer PCM format [WaveFmt] with a custom channel bitmap.
     ///
-    /// The order of `channels` is not important. When reading or writing
+    /// The order of [channels](WaveFmt::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`.
+    /// files, the numerical order of the cases of [ChannelMask].
     pub fn new_pcm_multichannel(
         sample_rate: u32,
         bits_per_sample: u16,
@@ -300,7 +301,7 @@ impl WaveFmt {
 
     /// Format or codec of the file's audio data.
     ///
-    /// The `CommonFormat` unifies the format tag and the format extension GUID. Use this
+    /// 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))
@@ -377,7 +378,8 @@ impl WaveFmt {
     }
 }
 
-trait ReadWavAudioData {
+pub trait ReadWavAudioData {
+    /// Read audio data from the receiver as interleaved [i32] samples.
     fn read_i32_frames(
         &mut self,
         format: WaveFmt,
@@ -392,8 +394,11 @@ trait ReadWavAudioData {
 
 impl<T> ReadWavAudioData for T
 where
-    T: std::io::Read,
+    T: std::io::Read
 {
+    /// # Panics:
+    /// * If the format's [valid bits per sample](WaveFmt::valid_bits_per_sample) is 
+    ///   not compatible with the format's [bits per sample](WaveFmt::bits_per_sample).
     fn read_i32_frames(
         &mut self,
         format: WaveFmt,

src/lib.rs

@@ -3,22 +3,8 @@
 
 Rust Wave File Reader/Writer with Broadcast-WAV, MBWF and RF64 Support
 
-## Interfaces
+Refer to the individual modules for relevant documentation. For opening
-
+and writing files begin with [WaveReader] and [WaveWriter] respectively.
-### `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
 
@@ -64,7 +50,7 @@ pub use common_format::{
 };
 pub use cue::Cue;
 pub use errors::Error;
-pub use fmt::{ADMAudioID, ChannelDescriptor, ChannelMask, WaveFmt, WaveFmtExtended};
+pub use fmt::{ADMAudioID, ChannelDescriptor, ChannelMask, WaveFmt, WaveFmtExtended, ReadWavAudioData};
 pub use sample::{Sample, I24};
 pub use wavereader::{AudioFrameReader, WaveReader};
 pub use wavewriter::{AudioFrameWriter, WaveWriter};