Performs an amplitude normalization of the input WAV file and saves the results in the output WAV file. Multichannel WAV files can be normalized across all channels or on a "per channel" basis. The computations are performed chunk-by-chunk to avoid the need for large RAM allocations when converting large files.

Supports both WAVE_FORMAT_PCM and WAVE_FORMAT_EXTENSIBLE multichannel uncompressed formats and any bit resolution between 2 and 32 inclusive. As an option, bit-depth conversion (re-quantization) can be applied between the input and output. Likewise, dither may be optionally applied before re-quantisation, with a choice from a variety of standard dithering methods including noise-shaping with a user-specified custom FIR shaping filter.

wavnormalize(InputWavFile,OutputWavFile,NormalizeFactor);

name of the input WAV file.

name of the output WAV file. Cannot be the same as the input filename if both reside in the same directory.

if a scalar, represents the factor by which the amplitude should be normalized. All channels are multiplied by the same factor. The normalization is based on the maximum (absolute) signal value across all channels.

if a vector with number of elements equal to the number of channels, then each channel is multiplied by a separate factor corresponding to the respective element of the vector. The normalization is performed "per channel", i.e. each channel is normalized based on the maximum (absolute) signal for that channel.

Possible values (for scalar or each element of vector) between 0 and 1 inclusive, where 0 implies silence, and 1 implies maximum amplitude before digital clipping occurs. To be on the safe side with respect to rounding errors in any post-normalization manipulations, a value slightly below 1, say 0.98, should be used. If the given value exceeds unity, it will be automatically reset to unity in order to avoid clipping.

Note: this function assumes that the input WAV file is correctly scaled such that it can be read using the "full" scale option in the wavin function. Likewise, the output WAV file is written using the "full" scale option.

Optional argument. Must be a structure with fields described as follows (see also wavout):

• Format field (i.e. wavformat.Format) should be a string with value 'pcm' (for WAVE_FORMAT_PCM) or 'ext' (for WAVE_FORMAT_EXTENSIBLE).
• ChannelMask field (i.e. wavformat.ChannelMask) should contain the "ChannelMask" variable (in decimal format) which prescribes the multichannel speaker allocation for WAVE_FORMAT_EXTENSIBLE. (See chnmsk2spkrlist to read more about the ChannelMask property.)
• ValidBits field (i.e. bits.ValidBits): as described in Notes below
• ContainerBits field (i.e. bits.ContainerBits): as described in Notes below
• DitherMethod field (i.e. bits.DitherMethod): numerical value indicating which type of dithering method is applied before quantisation. Possible values are:
  • 0: no dither [default]
  • 1: rectangular PDF dither, with a peak-to-peak amplitude of 1*LSB
  • 2: triangular PDF dither, with a peak-to-peak amplitude of 2*LSB
  • 3: triangular PDF with first-order high-pass noise shaping
  • 4: triangular PDF with custom FIR noise shaping filter
• DitherGain field (i.e. bits.DitherGain): gain applied to amplitude of dither [default value of 1] i.e. rectangular PDF dither has amplitude of LSB*DitherGain, and triangular PDF dither has amplitude of 2*LSB*DitherGain.
• NoiseShapeGain field: (i.e. bits.NoiseShapeGain): gain applied to the feedback path in the case where where noise shaping is activated (i.e. for DitherMethod values greater than 2) [default value of 1]
• NoiseShapeFIR field: (i.e. bits.NoiseShapeFIR): vector of coefficients for custom noise shaping filter (only valid for DitherMethod = 4). An arbitrary filter of any order may be specified. Default value is the following fifth order filter: [2.033 -2.165 1.959 -1.590 0.6149] taken from ref [2] p 851 (note: designed for 44.1 kHz).

Notes: ValidBits refers to the number of bits used in the quantisation of each sample, and ContainerBits refers to number of bits used to store each sample. ValidBits can have any value from 2 up to and including ContainerBits. Usually the value of ContainerBits is the nearest integer multiple of 8 above the value of ValidBits, but this does not need to be the case (e.g. a 2-bit quantised signal can be stored in a 32-bit container, though this would be highly wasteful in terms of disk space!)

If omitted, output format retains attributes of the input.

Optional argument. Must be a structure with fields described as follows:

• Input field: (i.e. Scaling.Input): [default 'full']. Describes the scaling law applied when reading the input WAV file. Identical to the scale argument in wavin. See wavin for full range of
  options.
• Output field: (i.e. Scaling.Output): [default 'full']. Describes the scaling law applied when writing the output WAV file. Identical to the scale argument in wavout. See wavout for full range of
  options.

Optional argument [default value 65536]. Represents the length (in samples per channel) of each successive chunk to be processed. Can have an arbitrary value, but if too small, computational efficiency will be compromised since the file I/O operations are relatively slow. If too large, memory requirements may be excessive. (Note: the value is overridden if the file length happens to be smaller!)

Optional argument. If the argument is present (even if empty), the progress is displayed via a waitbar which can be customized via the following optional fields:

• Handle field (i.e. WaitbarActivate.Handle) the handle of an externally-generated waitbar figure. If omitted a new locally-generated waitbar is created (then deleted at the end of the function)
  
• Label field (i.e. WaitbarActivate.Label) string containing the label of the waitbar
  

If this input argument is omitted, no waitbar will be used.

Inspect the source code of this function for a demonstration of how to use the wavin and wavout functions in chunk-by-chunk mode for creating a disk-based WAV processor.

See the M-Pack 1 overview for a detailed discussion of the WAV format, quantization, dithering, and noise-shaping techniques used in this m-function.

Note that wavnormalize uses wavin and wavout for the WAV file I/O and thereby does not preserve any peripheral header information (e.g. in the '.info' field) beyond the basic '.fmt' (audio format information).

Ref[1]: "Enhanced Audio Formats For Multi-Channel Configurations And High Bit Resolution" Windows Multimedia Group Microsoft Corporation, 1999.

Ref[2]: "Minimally Audible Noise Shaping", Stanley P. Lipshitz, John Vanderkooy, and Robert A. Wannamaker, J. Audio Eng. Soc., Vol. 39, No. 11, November 1991.

The following examples are contained in the m-script file entitled xmplwavnormalize.m

ExternalWaitbar.Label='Custom label...';

[y,fs]=wavin('mywav.wav');