Reorganized documentation

src/bext.rs

@@ -14,8 +14,12 @@ pub type Decibels = f32;
 ///  For a Wave file to be a complaint "Broadcast-WAV" file, it must contain
 ///  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 {
 

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

@@ -24,6 +24,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,
@@ -128,14 +131,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 {
 

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

@@ -2,10 +2,6 @@
 # bwavfile
  
 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
-files works however the interfaces may change significantly. Stay up-to-date on the
-status of this project at [Github][github].)__
 
 ## Objectives and Roadmap
 
@@ -19,79 +15,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
 */
 

src/sampler.rs

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

src/wavereader.rs

@@ -15,27 +15,53 @@ 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,

src/wavewriter.rs

@@ -164,7 +164,32 @@ impl<W> Write for WaveChunkWriter<W> where W: Write + Seek {
 /// frame_writer.write_integer_frames(&[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,

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