Audio Level: Configuration & Usage
Brief description of the Audio Level DirectShow filter capabilities.
Interface IMLAudioLevel can be found in file <filter installation directory>\Idl\ALevel.idl
Number of channels
The number of channels in the connected audio stream can be obtained using the IMLAudioLevel::GetChannels() function.
Maximum possible number of channels: 32.
The current sound level in dB for the specified channel can be get using IMLAudioLevel::GetLevel() method.
VU-meter properties (attack and release time in ms) are set using methods IMLAudioLevel::SetAttackTime() and SetReleaseTime(). The attack (rise) time is the time to reach an amplitude of 90% (-2dB) for a step signal of 0 -> 1, and the release (fall) time is an amplitude of 10% (-20dB) for a step signal of 1 -> 0.
If the VU-meter is not needed, then its operation can be disabled using the IMLAudioLevel::EnableProcessing() method.
Signal gain (in dB) for a single channel (or for all at once) is set using IMLAudioLevel::SetGain() method. Gain range: -120 to 100 dB.
A sudden change in gain can lead to distortion in the output signal. To reduce this effect, the transition time to the specified gain level is set in IMLAudioLevel::SetGain().
Dynamic range compression (auto gain)
Auto gain reduces the audio signal level if its average amplitude from its own VU meter exceeds a specified threshold.
DRC parameters (threshold and gain) for an individual channel (or for all at once) are set using the IMLAudioLevel::SetAutoGain() method. Threshold and gain values are set in dB, the allowable range is [-120 db, 0 dB].
Auto gain part uses its own VU-meter to average the amplitude, its parameters (attack, release and transition times) are set using the IMLAudioLevel::SetAutoGainTimes() method.
Trigger is used to notify the application that the averaged absolute amplitude of the signal is above or below a specified threshold for a specified time. The following notification options are available:
- IMLAudioLevel::AdviseNotify(): calling IMLAudioLevelNotify::OnLevel() callback method;
- IMLAudioLevel::AdviseEvent(): calling the function SetEvent() with handle to the event created by the user using CreateEvent() system function.
Other parameters are also set:
- the position of the audio trigger (before or after the amplifier and VU meter);
- channel number (or -1 for all channels at once) for collecting data and sending notifications;
- threshold in dB;
- data accumulation interval in ms. Notifications are not called if the signal leaves the specified level before the expiration of the time interval;
- threshold transition type: average absolute value of the signal above or below the threshold after the transition
The method returns a cookie used to identify the notification and cancel it using IMLAudioLevel::Unadvise().
The trigger can be used to notify you when the silence is broken, or vice versa, when the sound stops. It can also be used to inform about any events through the specified channel of the audio stream.
Audio filters (Audio Renderer, for example) can have large buffers for sound accumulation and, accordingly, large delays in audio output.
To reduce the delay, the IMLAudioLevel::SetDelay() method is used, with the help of which the maximum advance of the audio stream relative to the current time is set.
Data from the AudioLevel output pin will be sent to the downstream filter only after the difference between the audio output time (the output time of the first atomic audio sample from the DirectShow audio sample) and the current time from the Reference Clock becomes less than the delay time. Thus, the advance of the sound will not exceed the set delay time.
A value of -1 disables delay correction. It is not recommended to set the delay value less than 200 ms - this can lead to breaks in audio playback.
The signal spectrum (in dB) in a given channel can be obtained using the IMLAudioLevel::GetSpectrum() method.
The whole spectrum is divided into 11 octaves with centers 15.625, 31.250, 62.500, 125.000, 250.000, 500.000, 1000.000, 2000.000, 4000.000, 8000.000, 16000.000 Hz. Each octave can in turn be divided into bands.
The method returns an array of power spectrum values and the number of calculated values in the array. The number of calculated values is equal to min(total number of bands, array size). If the array size is less than the number of bands, then only the first spectrum values will be returned.
Spectrum analyzer parameters:
- number of bands per octave: 1,2,3 or 6. If 0 is selected, then spectrum analyzer is disabled.
- type of window function for spectrum calculation.
- the length of the Fourier window for calculating the spectrum.