Structures and Routines for Reading and Writing WAV Cue Points and Metadata

Primarily intended for manipulating Quake sound effect loops, this library can read and write WAV "cue " chunks as well as associated data stored in "LIST" chunks. This is a low-level library in the sense that it is the consumer's responsibility to ensure that WAV files created with the library are compatible with the requirements for software using the created files.

Changelog

0.1.0:

• First release for public consumption
• Made public constants crate-private (shouldn't be needed by consumers)

License

Triple-licensed under MIT / Apache 2.0 / CC0 (your choice)

lib.rs:

Structures and routines for reading and writing cue points and cue metadata from/to existing WAV files.

The general flow for reading data is to create a ChunkReader wrapping a cursor (Read + Seek implementation) pointing at the start of a WAV file, or WAV data in a larger archive file. Chunks are read as blocks of bytes; chunks tagged as "cue " can be parsed with parse_cue_points and chunks tagged with "LIST" can be processed with extract_labeled_text_from_list. Subsequent processing of the WAV's sample data can be performed by another library of your choosing after restoring the cursor from the reader.

The general flow for writing data is to create a ChunkWriter wrapping a cursor (Read + Seek + Write implementation) pointing at the start of a WAV file. For writing valid WAV files, the existing WAV file should contain "fmt " and "data" chunks in the correct order. It is not recommended for WAV files in larger archives, as data is expected to be appended to the end of the file, resulting in overwritten archive entries or a corrupted archive. Chunks are provided by creating CuePoint and LabeledText instances provided to the writer through its append methods.

Note

This library was developed based on sketchy documentation (e.g. there appears to be no consensus on whether the offset referenced in a cue point is given in samples, frames, or bytes) and was intended primarily for use with Quake and Quake sourceports for looped sound effects. There is no guarantee the files generated by this library will work with any other software, nor is there any guarantee that any file generated will work with Quake and all Quake-derived sourceports.