mirror of
https://github.com/iluvcapra/bwavfile.git
synced 2025-12-31 08:50:44 +00:00
Reorganized documentation
This commit is contained in:
Jamie Hardt
@@ -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 {
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
35
src/fmt.rs
35
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 {
|
||||
|
||||
|
||||
3
src/levl.rs
Normal file
3
src/levl.rs
Normal file
@@ -0,0 +1,3 @@
|
||||
/// Resources
|
||||
///
|
||||
/// [EBU 3285 Supplement 3](https://tech.ebu.ch/docs/tech/tech3285s3.pdf) (July 2001): Peak Metadata
|
||||
77
src/lib.rs
77
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 <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
|
||||
*/
|
||||
|
||||
|
||||
2
src/sampler.rs
Normal file
2
src/sampler.rs
Normal file
@@ -0,0 +1,2 @@
|
||||
/// ## Resources
|
||||
/// - [Sampler Metadata](http://www.piclist.com/techref/io/serial/midi/wave.html)
|
||||
@@ -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<R: Read + Seek> {
|
||||
pub inner: R,
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user