Expand description
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.
Structs§
- Chunk
Head - Chunk header that immediately precedes the body of a chunk. Composed of a 4-byte ASCII tag and the size of the body in bytes.
- Chunk
Reader - Wraps a cursor (Read + Seek) implementation that can read chunks.
- Chunk
Writer - Wraps a cursor for writing chunks to an existing WAV
- CuePoint
- A marker identifying the location of a sample in a WAV file
- Labeled
Text - Metadata associated with a cue point and succeeding samples. I have no idea why it’s called LabeledText other than the LIST chunk sub-chunk tag is “ltxt”.
Enums§
- Error
- Wave-variant errors are caused by reading invalid WAV files or chunks. Io-variant errors are caused by underlying IO operations.
Functions§
- extract_
labeled_ text_ from_ list - Treat bytes as the body of a LIST chunk, and extract all labeled-text sub- chunks.
- parse_
cue_ points - Parse bytes as an array of cue points. Leftover bytes are ignored.