DOCSEARCHbyAlgolia
Submit Docs

WavPack Documentation

repository·master·Indexed 19 days ago

https://github.com/dbry/wavpack

A hybrid lossless wavefile compressor providing lossless, lossy, and hybrid audio compression modes. It includes the _libwavpack_ C library, command-line tools, and specialized 'Tiny' versions for resource-limited embedded systems. The project supports various audio formats including AIFF/AIFC, CAF, and DSDIFF (.DFF/.DSF), and provides tools for manipulating APEv2 tags and handling 32-bit float audio processing.

Tokens
17.3K
Snippets
45
Records
94
Agent score
60%

What's inside WavPack

  1. Use Tiny Versions for resource-limited CPUs

    master

    For embedded systems or portable devices with limited resources, WavPack provides specialized "Tiny" versions that do not use memory allocation functions or require floating-point arithmetic support.

    • Tiny Decoder: Designed for extremely small footprints (less than 32k of code and 4k of data). Includes assembly optimizations for ARM and Freescale ColdFire. It is the basis for the WebAssembly WavPack player.
    • Tiny Encoder: Designed for embedded use; supports pure lossless, lossy, and hybrid lossless modes.

  2. Build WavPack on Linux

    master

    To build the WavPack library and command-line programs on Linux, follow these steps:

    1. If you are using a distribution, run ./configure and then make.
    2. If you are building directly from a Git repository, run ./autogen.sh first, then ./configure and make.
    3. Optionally, run make install to install binaries into /usr/local/bin.
    4. To run a quick suite of stress tests for _libwavpack_, use make check.

    Troubleshooting & Options:

    • Assembly issues: Assembly optimizations are enabled by default. If you encounter issues, use the --disable-asm flag to use pure C.
    • Library path warnings: If command-line programs report an unexpected _libwavpack_ version, use --enable-rpath to hardcode the library location or --disable-shared to force static linking.
    • Clang requirements: For Clang-based systems (Darwin, FreeBSD, etc.), Clang version 3.5 or higher is required.
    ./configure
make
# optionally
make install

  3. Build WavPack on Windows

    master

    WavPack provides solution and project files for Visual Studio 2019. The repository includes source code for specific plugins that serve as implementation examples:

    • CoolEdit/Audition plugin: Demonstrates how to use the library to both read and write WavPack files.
    • Winamp plugin: Demonstrates extensive use of APEv2 tag reading and writing.

    Both 32-bit and 64-bit platforms are supported.

  4. Use wvtag to manipulate WavPack metadata

    master

    The wvtag command is used to apply metadata operations to WavPack source files. It operates on APEv2 tags. If a source file only contains an ID3v1 tag, wvtag will automatically import it into an APEv2 tag. If an edit is requested, the ID3v1 tag is deleted and replaced with the APEv2 tag.

    Operations are applied in this specific order:

    1. clean
    2. import
    3. delete
    4. write
    5. extract
    6. list

  5. Use WVTAG to manage WavPack metadata tags

    master

    WVTAG is a command-line utility for managing metadata tags in WavPack files. It supports text and binary tags (like cover art) and follows a specific execution order for operations applied to each file:

    1. clean: Removes existing tags.
    2. import: Imports tags from another file or ID3v2 wrappers.
    3. delete: Removes specific metadata items.
    4. write: Writes new or modified tags.
    5. extract: Pulls specific tag fields to stdout or files.
    6. list: Displays all tag items.

    Wildcard characters (*, ?) can be used in filenames.

    WVTAG [-options] file[.wv] [...]

  6. Transcoding constraints in WavPack

    master
    When using the WavPack CLI for transcoding, note that lossy to lossless transcoding is not allowed. Attempting to transcode a lossy WavPack file into a lossless format is prohibited because it can result in files that fail MD5 verification tests. The CLI will return a WAVPACK_SOFT_ERROR if this operation is attempted.

  7. CAF Channel Layout Mapping

    master

    WavPack can interpret various channel layouts defined in the CAF chan chunk. It supports two primary methods for defining channel mapping:

    1. Channel Descriptions: Uses an array of AudioChannelDescription structures to define specific labels and coordinates for each channel.
    2. Channel Bitmap: Uses a Microsoft-standard bitmask to define which channels are present.
    3. Layout Tags: Uses predefined Core Audio layout tags to automatically assign channel identities (e.g., FL, FR, FC, LFE, etc.).

    If a layout is not in the standard Microsoft order, WavPack uses a reorder string to correctly map the channels.

  8. Configure channel order and unassigned channels

    master

    WavPack can automatically determine channel masks for non-extensible WAV files. If the file does not provide channel order information, you can use the following modes:

    • Automatic: WavPack calculates a mask based on the number of channels (e.g., 0x5 for 2 channels, or a bitmask for up to 18 channels).
    • QMODE_CHANS_UNASSIGNED: Use this mode if you want to treat channels as unassigned/unordered.

  9. Configure hybrid compression modes

    master

    WavPack supports hybrid compression, which can be either lossy or lossless (2-file) depending on the flags used.

    Lossy Hybrid Mode:

    • Use -b n where n is the target bitrate (e.g., 24-9600 kbps) or bits per sample (e.g., 2.0 to 23.9 bits/sample).
    • If -c is not used, the operation is lossy.

    Lossless Hybrid Mode (2-file):

    • Use -c n where n is the target bitrate or bits per sample. This is a shortcut for -b n -c.
    • Use -cc for maximum hybrid compression (note: this may reduce lossy quality and decoding speed).
    • The -cross-decorr option uses cross-channel correlation in hybrid mode (enabled by default in lossless and -cc modes).

    Note: Hybrid mode is not applicable to DSD audio; it only works with PCM.

    # Lossy hybrid compression at 128 kbps
wavpack input.wav -b 128

# Lossless hybrid compression (2-file) at 2.0 bits/sample
wavpack input.wav -c 2.0

  10. Support for Sony Wave64 (.W64) files

    master

    The WavPack CLI tools include a helper module (wave64.c) to support Sony's Wave64 WAV file variant.

    Key characteristics of Wave64 support in WavPack:

    • It handles the .W64 format specifically.
    • Unlike the standard WAV/RF64 implementation, this module does not fall back to conventional WAV if the file size is less than 4GB.
    • It supports parsing the Wave64 header, format chunks, and data chunks to extract audio properties like sample rate, number of channels, and bits per sample.
    • It can handle various bit depths (up to 32-bit) and floating-point formats (normalized 32-bit floating point).
    • It preserves unknown RIFF chunks by copying them to the output file (unless QMODE_NO_STORE_WRAPPER is set).

  11. Verify WavPack input files

    master

    The WavPack CLI can verify the integrity of an input file.

    • Lossless Verification: If an MD5 sum is provided, the tool reformats the data to standard little-endian and performs a full MD5 verification.
    • Lossy Verification: If no MD5 is provided, the tool performs a lossy verification by checking that the exact number of samples is correct and that the decoding library did not detect any CRC errors in the WavPack blocks.

  12. Configure channel reordering

    master

    WavPack supports reordering audio channels during the packing process. This can happen in two ways:

    1. CAF Layout Reordering: If the input is a CAF file with a channel layout that is not in Microsoft order, WavPack handles the reordering automatically so that it can be unreordered during decoding.
    2. Manual Channel Order: You can specify a custom channel order via the command line. This reordering is permanent and will not be reversed during decoding. The MD5 checksum is calculated based on this new order to ensure consistency.