Comments and documentation

src/lib.rs

@@ -1,12 +1,49 @@
-//
 /*! 
 # 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
+__(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].)
+status of this project at [Github][github].)__
+
+## Objectives and Roadmap
+
+This package aims to support read and writing any kind of WAV file you are likely 
+to encounter in a professional audio, motion picture production, broadcast, or music 
+production.
+
+Apps we test against:
+- Avid Pro Tools
+- 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
 
@@ -15,9 +52,9 @@ status of this project at [Github][github].)
 
 ### 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).
+  - 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. 
+  - No longer in force, however long-established. 
 
 
 ### Implementation of Wave format `fmt` chunk