diff --git a/src/bext.rs b/src/bext.rs index 4cc27b0..5e17a2e 100644 --- a/src/bext.rs +++ b/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 -/// check out [EBU Tech 3285](https://tech.ebu.ch/docs/tech/tech3285.pdf). +/// ## Resources +/// - [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 { diff --git a/src/cue.rs b/src/cue.rs index 02f3ba5..9d42411 100644 --- a/src/cue.rs +++ b/src/cue.rs @@ -190,7 +190,11 @@ impl AdtlMemberSearch for Vec { /// 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 diff --git a/src/fmt.rs b/src/fmt.rs index aec3bab..db1fc43 100644 --- a/src/fmt.rs +++ b/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. - * - * The `fmt` record contains essential information describing the binary - * structure of the data segment of the WAVE file, such as sample - * rate, sample binary format, channel count, etc. - * - */ +/// +/// WAV file data format record. +/// +/// The `fmt` record contains essential information describing the binary +/// structure of the data segment of the WAVE file, such as sample +/// 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 { diff --git a/src/levl.rs b/src/levl.rs new file mode 100644 index 0000000..aa511e3 --- /dev/null +++ b/src/levl.rs @@ -0,0 +1,3 @@ +/// Resources +/// +/// [EBU 3285 Supplement 3](https://tech.ebu.ch/docs/tech/tech3285s3.pdf) (July 2001): Peak Metadata \ No newline at end of file diff --git a/src/lib.rs b/src/lib.rs index b1aebf2..4a92710 100644 --- a/src/lib.rs +++ b/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 - field of the Broadcast Wave Format" -- [EBU Tech R098](https://tech.ebu.ch/docs/r/r098.pdf) (1999) "Format for the <CodingHistory> field in Broadcast Wave Format files, BWF" - -[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 */ diff --git a/src/sampler.rs b/src/sampler.rs new file mode 100644 index 0000000..044eb2c --- /dev/null +++ b/src/sampler.rs @@ -0,0 +1,2 @@ +/// ## Resources +/// - [Sampler Metadata](http://www.piclist.com/techref/io/serial/midi/wave.html) diff --git a/src/wavereader.rs b/src/wavereader.rs index 0331fc4..33464e1 100644 --- a/src/wavereader.rs +++ b/src/wavereader.rs @@ -15,27 +15,53 @@ use std::io::Cursor; use std::io::{Read, Seek}; -/** - * Wave, Broadcast-WAV and RF64/BW64 parser/reader. - * - * ``` - * 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 frame_reader = r.audio_frame_reader().unwrap(); - * let mut buffer = format.create_frame_buffer(); - * - * let read = frame_reader.read_integer_frame(&mut buffer).unwrap(); - * - * assert_eq!(buffer, [0i32]); - * assert_eq!(read, 1); - * - * ``` -*/ + +/// Wave, Broadcast-WAV and RF64/BW64 parser/reader. +/// +/// ``` +/// 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 frame_reader = r.audio_frame_reader().unwrap(); +/// let mut buffer = format.create_frame_buffer(); +/// +/// let read = frame_reader.read_integer_frame(&mut buffer).unwrap(); +/// +/// assert_eq!(buffer, [0i32]); +/// 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 { pub inner: R, diff --git a/src/wavewriter.rs b/src/wavewriter.rs index 151f9c9..dc5f89a 100644 --- a/src/wavewriter.rs +++ b/src/wavewriter.rs @@ -164,7 +164,32 @@ impl Write for WaveChunkWriter 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 where W: Write + Seek { inner : W, form_length: u64, diff --git a/tests/Untitled.txt b/tests/Untitled.txt deleted file mode 100644 index a2ea4d2..0000000 --- a/tests/Untitled.txt +++ /dev/null @@ -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