

-a = Adobe Audition (CoolEdit) mode for 32-bit floats

The WAVEFORMATEXTENSIBLE structure is used (if present) to determine the format details. However, there are some programs that use their own non-standard format extensions. The most popular of these is Adobe's Audition (previously Syntrillium's CoolEdit) which created two new 32-bit floating point formats. An option has been added to WavPack (-a) to force the "adobe" interpretation of these floating point formats. If you are compressing integer files do NOT use this option.

--allow-huge-tags = allow tag data up to 16 MB (otherwise it's 1 MB)

Normally WavPack allows the APEv2 tags to contain up to 1 MB of data. This limit was implemented to allow for their use on portable devices which may have limited memory or processing resources. However, in some situations it may be desirable to place more data in the tags (for high resolution cover art scans, for example) and this option permits that. Note that these files are not fully WavPack compliant and may not work in all situations or with older versions of WavPack programs and plugins.

-bn = enable hybrid compression, n = 2.0 to 23.9 bits/sample, or
                                 n = 24-9600 kbits/second (kbps)

The default operation of WavPack is pure lossless, which means that the .wv file contains all the information that was in the original .wav file. The hybrid mode allows the user to specify a target bitrate for the output file, either in kilobits per second (kbps) or bits per sample. If the track can be losslessly compressed without exceeding the specified bitrate, then it will be and WavPack will report the compression as lossless. If lossless compression would exceed the specified bitrate, then WavPack will begin carefully discarding the least significant portion of the audio information to stay within the limit. Every effort is made to keep this inaudible, including the use of joint stereo, dynamic bit allocation and noise shaping. WavPack will report this as "lossy" compression. Although the option accepts bitrates as low as 24 kbps, the actual value that WavPack can achieve is usually much higher than that. For example, with CD-audio sampled at 44.1k the lower limit is about 196 kbps.

--blocksize=n = specify block size in samples (n = 128 - 131072)

WavPack normally determines the optimum number of samples to place into each WavPack block, however this option allows it to be directly specified. The most likely use for this option would be to improve the handling of audio files that have a variable number of redundant MSBs. For example, the output of the lossyWAV program or the output of a software HDCD decoder. This option is also often combined with the --merge-blocks option (which also reduces the minimum allowed block size to 16 samples).

-c = create correction file (.wvc) for hybrid mode (=lossless)

If the -c option is specified (in addition to the -b option), then WavPack will generate an additional file that will contain the information that was discarded to generate the lossy .wv file. This file will have the same name as the .wv file but will have the extension .wvc (the 'c' is for "correction"). When WvUnpack is used to restore the .wav file, it will attempt to find the .wvc file in the same directory as the .wv file. If it is found then the decompression will be lossless and will be reported as such, otherwise lossy decompression will be reported (assuming that any information was actually discarded during the original compression). If -c is specified but no actual information is discarded, the correction file will be deleted. The extra overhead involved with having these two files instead of a single pure lossless file is usually less than 1% of the original .WAV file and can be as low as 0.25% at high bitrates. Note that CRCs are stored for both the lossy and lossless versions, so error detection works correctly whether the .wvc file is used or not.

-cc = maximum hybrid compression (hurts lossy quality & decode speed)

Normally, when the -c option is used to create a correction file in the hybrid mode, WavPack attempts to optimize for the quality of the lossy file and lets the combined lossless compression of the two files fall where it may. This option tells WavPack to optimize for the overall compression ratio instead, even if this means some possible degradation of lossy quality (for example, dynamic noise shaping is not used in this mode). This can also have an effect on lossless decompression speed (however it does not affect lossy decoding). Keep in mind the effect of this option is not too significant either way.

--channel-order=<list> = specify non-standard channel ordering

For multichannel audio WAV files there is a Microsoft required WAVEFORMATEXTENSIBLE header to indicate which speakers are represented and those speakers must be in the standard Microsoft order (which is also specified by USB). However, some programs skip generating the WAVEFORMATEXTENSIBLE header and even write the channels in the wrong order. For files without the WAVEFORMATEXTENSIBLE header (or those with the header but with a zeroed channel mask), WavPack assumes Microsoft channel order and further assumes that all speakers (up to the number of channels) are present. If that is not the case, then this option allows the user to specify the exact channels present (and their order) from this list (which is in Microsoft order): FL,FR,FC,LFE,BL,BR,LC,FRC,BC,SL,SR,TC,TFL,TFC,TFR,TBL,TBC,TBR.

If not all of the channels in the file have speaker definitions, then it is possible to simply terminate the speaker list with "..." (e.g. FL,FR,...) to indicate that all following channels are unassigned. Specifying "..." alone indicates that all channels are unassigned.

This option may just be used to specify which channels are present, even if they are in standard Microsoft order (e.g. standard quad is FL,FR,BL,BR). In this case the option just controls the channel "mask" and performs no reordering. But if the option does result in reordering, then this is done before encoding, so if the resulting WavPack file is subsequently unpacked it will not recreate the identical WAV file (because the channels will now be in the correct order). If you want the unpacked file to be identical to the original simply do not use this option (although this means that the resulting WavPack file will not have the correct channel information and so won't play correctly in multichannel software, and also means that the compression might not be as good because the "wrong" channels will be paired in stereo).

If this option is used then it might be a good idea to add the -r option also to generate a valid WAVEFORMATEXTENSIBLE header with the correct channel information. In fact, one could even pipe the output of WavPack directly to WvUnpack for the sole purpose of reordering WAV files and adding the correct WAV headers!

-d = delete source file if successful (use with caution!)

Self explanatory.

-e = create self-extracting executable (needs wvselfx.exe)

WavPack can be used to create self-extracting archives (Windows only) with a .exe extension. In this way it is possible to distribute compressed audio without having the recipient install any other programs (or have any dlls) to unpack the archives. When the .exe file is run (directly or by double-clicking) it extracts the original .wav file into the same directory. If it can't (because the file exists or it is run on a read-only device) then it displays a standard Windows "Extract to" dialog box and allows the user to specify the destination. The self-extracting feature can be used with WavPack's hybrid modes as well as pure lossless. If a .wvc file (with the correct name) is present in the same directory as the executable, then a lossless extraction is automatically performed. It is possible to turn the .exe file back into a valid WavPack by simply changing the extension back to .wv (although the extra 33k unpacking header will still be there).

As of version 4.40, the self-extraction module will also check for a CUESHEET field in the APEv2 tag and if it is present then the text in the CUESHEET field will be extracted into an appropriately named .cue file. Note that the cuesheet is not automatically modified to point to the correct .wav file; this must be handled either when the cuesheet is embedded or (if the .exe file is renamed) by the user after extraction.

To convert an existing WavPack 4.x file into a self-extracting executable use the DOS copy command to prepend the self-extracting stub (wvselfx.exe) to the .wv file:

    C:\music_files>copy /b wvselfx.exe+music.wv music.exe 

-f = fast mode (fast, but some compromise in compression ratio)

The "fast" mode should be used when compression (or decompression) speed is more important than compression ratio (or, in lossy mode, audio quality).

-h = high quality (better compression in all modes, but slower)

The "high" mode should be used when compression ratio (or, in lossy mode, audio quality) is more important than compression (or decompression) speed. This option slows both by about a factor of about 1.5.

-hh = very high quality (best compression in all modes, but slowest)

The "very high" mode should be used when compression ratio (or, in lossy mode, audio quality) is much more important than compression (or decompression) speed. This option slows both by about a factor of about 2, and is not recommended for use on portable devices because of the high CPU load required for decoding.

--help = extended help display

Self explanatory.

-i = ignore length in wav header (no pipe output allowed)

Some programs that pipe data to encoders do not always give the correct length in the wav headers that they provide (foobar's clienc and CDex are examples). In these cases use this option to force WavPack to ignore the header and accept the actual length. Because WavPack must seek to the beginning of the file to write the correct length, this option cannot be used with piped output.

-jn = joint-stereo override (0 = left/right, 1 = mid/side)

WavPack normally defaults to joint stereo (sometimes called mid/side) in which the left and right channels are combined to form an alternate representation (essentially L+R and L-R) that compresses better in lossless mode and improves quality in lossy mode. This option allows this feature to be forced either on or off.

-l = run at low priority (for smoother multitasking)

This option can be used (in Windows only) to force WavPack to run at a low priority and is handy for doing large WavPack batch conversions in the background.

-m = compute & store MD5 signature of raw audio data

Calculate and display the MD5 checksum of the uncompressed audio data and store it in the compressed file. These sums are commonly used in file trading communities to compare versions of tracks, and as such the sums generated by WavPack match those of FLAC, OptimFROG, Shntool, and get_id3(). They can also be used by WvUnpack during decompression to verify the data integrity of lossless files.

--merge-blocks = merge consecutive blocks of equal redundancy

This option is only valid when generating lossless files and is only used with the --blocksize option. WavPack will always scan each block of audio data before compressing to determine the actual number of valid bits that need to be stored because, for various reasons, this is not always the same as the number of bits present. In some situations there can be many redundant bits, as for example in the output of the lossyWAV program or the output of software HDCD decoders. In these cases it may be advantagous to use a specific block size (or simply a small block size), but WavPack does not work very well with very small block sizes because of its relatively large block header.

The --merge-blocks option takes care of this situation by allowing WavPack to merge consecutive blocks with the same number of bits to remove. For example, if a blocksize of 512 is specified, and 10 512-sample blocks in a row all have exactly the same number of redundant bits, then these 10 blocks will be combined in to a single block of 5120 samples (which is much more efficient for WavPack). When the --merge-blocks option is specified the minimum block size that --blocksize will accept is reduced from 128 to 16 samples.

-n = calculate average and peak quantization noise (hybrid only)

This causes WavPack to calculate the average and peak quantization noise generated in the lossy version of the hybrid mode, both referenced in decibels below full scale. While it is impossible to use this as a guide to determine the audibility of the noise, it is useful for comparing the various compression options and for comparing WavPack's lossy performance to other programs. Note that this option does not currently produce meaningful results for floating point or multichannel files.

--no-utf8-convert = don't recode passed tags to UTF-8, assume they are UTF-8 already

The text fields of APEv2 tags are encoded in the UTF-8 varient of Unicode, so when tag information is passed in on the command-line (which is normally multibyte encoded in WavPack's case) they are converted to UTF-8 before being stored. If your system is already passing the strings in UTF-8, use this option to prevent double conversion.

--optimize-mono = optimization for stereo files that are really mono

Use this option on stereo files that may actually be mono (i.e. old recordings) to increase the compression ratio by up to 6%. Note that on stereo recordings that are almost mono (as many supposedly mono recordings are) this will not improve compression. This option does not significantly slow encoding, however the resulting files are not compatible with older WavPack decoders (before version 4.3).

-p = practical float storage (also 32-bit ints, not lossless)

This option reduces the storage of some floating-point data files by up to about 10% by eliminating some information that has virtually no effect on the audio data. While this does technically make the compression lossy, it retains all the advantages of floating point data (>600 dB of dynamic range, no clipping, and 25 bits of resolution). This also affects large integer compression by limiting the resolution to 24 bits.

--pair-unassigned-chans = encode unassigned channels into stereo pairs

WavPack encodes all channels of multichannel files into stereo or mono streams. So, if two channels are related (like FL and FR) then these are encoded into one stream (which improves compression performance) whereas unrelated channels (like LFE) are encoded by themselves into mono streams. Unassigned channels (those not associated with any defined speaker) are normally encoded in mono streams for safety, however this option can be used to specify that they should be paired into stereo streams. This might improve compression in cases where all of the channels were very similar, or when it is known that the channels are, in fact, stereo pairs.

-q = quiet (keep console output to a minimum)

Self explanatory.

-r = generate new RIFF wav header (removing extra chunk info)

WavPack normally saves all the RIFF header information contained in the wav file (including any chunks after the audio data). This is done so that WvUnpack.exe can restore the original wav files exactly. The -r option causes WavPack to discard the header contained in the source file (and any extra chunks) and generate a fresh wav header. Obviously the source wav header is still used to determine the format and size of the file (i.e. this is not a "raw" mode). Note that for multichannel files a WAVEFORMATEXTENSIBLE header is generated whether the source file had one or not. Also note that this option cannot be used with certain floating-point wav files generated by CoolEdit or Audition because they are not properly normalized.

--raw-pcm = input data is raw pcm (44100 Hz, 16-bit, 2-ch)

Specifies that the source file (or stdin) contains raw PCM data with no header. and conforms to standard CD quality. Note that the data must match the format of WAV file audio (i.e., little endian and signed).

Note that WavPack files created in this way will still normally decode to WAV files (with headers) when unpacked. To avoid this, use the "-r" option with the WvUnpack program to force raw unpacking.

--raw-pcm=sr,bps,ch = input data is raw pcm with specified format

Specifies that the source file (or stdin) contains raw PCM data with no header and the specified sampling rate, bit-depth, and number of channels. Parameters matching the default (44100,16,2) can be omitted. The valid range of bit-depths is from 1 to 32, with 32f specifying 32-bit floating point data. The number of channels may be from 1 to 256. Note that the data must still match the format of WAV file audio (i.e., little endian and signed, except for 8-bit data which is unsigned).

Note that WavPack files created in this way will still normally decode to WAV files (with headers) when unpacked. To avoid this, use the "-r" option with the WvUnpack program to force raw unpacking.

-sn = noise shaping override (hybrid only, n = -1.0 to 1.0, 0 = off)

WavPack uses first-order noise shaping to improve the perceived quality of lossy files and to improve the hybrid lossless compression ratio. Normally WavPack will choose the noise shaping most appropriate for the application (based on the source sampling rate and whether the -cc option is specified), but this option allows the user to override the default with a fixed value. The parameter range is +/- 1.0, where positive values shift the noise higher in frequency and negative values shift the noise lower in frequency. Values very close to -1.0 are clipped to prevent problems associated with very high gain near DC and the value zero results in no noise shaping at all (i.e., white noise). This option should not be used with the --use-dns option which enables dynamic noise shaping.

-t = copy input file's time stamp to output file(s)

Self explanatory.

--use-dns = force use of dynamic noise shaping (hybrid only)

For version 4.50, dynamic noise shaping was added to the WavPack hybrid mode. This feature causes the noise shaping to continuously adjust to the spectral characteristics of the source signal and results in significantly improved subjective quality on samples that previously caused difficulty with WavPack's lossy mode (particularly material with loud high-frequency transients). This feature is used by default except for high sampling rates (>= 64 kHz) or when the -cc option is specified (because it can adversely effect compression ratio), however the --use-dns option allows the user to force the use of dynamic noise shaping even when it would not normally be used. This option should not be specified with the -s option which overrides the default with fixed noise shaping.

-v = verify output file integrity after write

Causes WavPack to perform a separate verification pass over the output file to guarantee that the audio data is correctly encoded and stored to disk. For lossless compression this is performed with an MD5 hash even if the -m option is not specified. If an error occurs (indicating either a bug in the program or faulty hardware) then a message is displayed and the output file is deleted (and if an existing file is being overwritten, then it will be untouched). Because the output file is actually rewound and reread, this option cannot be used when writing to pipes.

--version = display program version to stdout

Self explanatory.

-w "Field=Value" = write specified metadata to APEv2 tag

Write specified information to APEv2 tag appended to WavPack file(s). May be used multiple times for multiple fields. APEv2 tags are the preferred tag format for WavPack files and are read by all the standard WavPack playback plugins. If the specified value begins with a '@', then the value is assumed to be a filename which is used to obtain the item's actual value. This is handy for including the CUESHEET field for use with images files + cuesheets and foobar2000. The filename may contain wildcards if it matches exactly one file. Also, if the file cannot be found in the current directory then the source and destination directories (if specifed) are also checked.

--write-binary-tag "Field=@file.ext" = write specified binary metadata to APEv2 tag

Write specified binary file to APEv2 tag appended to WavPack file(s). This is most commonly used to embed album cover art into WavPack files (with the field name "Cover Art (Front)"), but could be used for anything desired. A file must be specified (the data cannot come from the command-line) and it may contain wildcards if it matches exactly one file. Also, if the file cannot be found in the current directory then the source and destination directories (if specifed) are also checked.

-x[n] = extra encode processing (optional n = 1-6, 1 = default)

Like pre-4.0 versions of WavPack (and many other compressors), WavPack 4.70 normally works "symmetrically" in that encoding and decoding operate at about the same rate (regardless of the mode used). However, WavPack has an option to work "asymmetrically", so that extra processing can be done during encoding to provide better compression, but with NO corresponding cost to decoding performance!

This is enabled with the -x option and provides an average improvement in CD music compression of about 1% in "fast" mode, about 0.5% in the normal mode, and still less in the higher modes. Because the standard compression parameters are optimized for "normal" CD music audio, this option works best with "non-standard" audio (synthesized sounds, non-standard sampling rates, etc.) where it can often achieve enormous gains. The default level (n=1) provides a decent improvement with little cost in encoding speed and is recommended for all but the most time critical encoding. Higher levels provide some marginal improvement with an increasing cost of encoding speed. The highest levels (n = 4-6) are extremely slow but can provide significant improvement in special situations (i.e. synthesized sounds).

-y = yes to all warnings (use with caution!)

Self explanatory.

-z = don't write to console title bar to indicate overall progress

Self explanatory.
