Audio Level: Configuration & Usage

From AVObjects Knowledge Base
(Difference between revisions)
Jump to: navigation, search
 
(19 intermediate revisions by one user not shown)
Line 1: Line 1:
Below are some usage tips for the [[Audio Level]] DirectShow filter.
+
Brief description of the [[Audio Level]] DirectShow filter capabilities.<br>
 +
Interface IMLAudioLevel can be found in file <filter installation directory>\Idl\ALevel.idl
  
==Configuration & Usage==
+
===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.<br>
  
Audio trigger is used for getting the level of amplitude in an audio stream. When the amplitude of the signal reaches the specified level, the application gets sent messages. The threshold of triggering may work at both the upper and the lower front. The upper one reacts on exceeding the given level of the signal amplitude, while the lower one reacts on the amplitude level detraction. The following example, - determining silence in a sound channel, - illustrates the usage of the audio trigger.
+
===VU-meter===
 +
The current sound level in dB for the specified channel can be get using IMLAudioLevel::GetLevel() method.<br>
 +
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.<br>
 +
If the VU-meter is not needed, then its operation can be disabled using the IMLAudioLevel::EnableProcessing() method.<br>
  
<OL>
+
===Signal amplification===
<LI>
+
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.<br>
First, we should choose the type of the messages, sent by the trigger. Currently 3 message types are supported:
+
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().<br>
* trigger notification interface (IAudioLevelNotify),
+
 
* handles to events objects,
+
===Dynamic range compression (auto gain)===
* DirectShow event notifications.
+
Auto gain reduces the audio signal level if its average amplitude from its own VU meter exceeds a specified threshold.<br>
According to the message types 3 corresponding functions are provided: AdviseNotify, AdviseEvent and AdviseDSEvent.
+
DRC parameters (threshold and gain) for an individual channel (or for all at once) are set using the IMLAudioLevel::SetAutoGain() method.
<LI>
+
Threshold and gain values are set in dB, the allowable range is [-120 db, 0 dB].<br>
Then the trigger's front has to be chosen. In case of determining silence in a channel we need the lower front.
+
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.<br>
<LI>
+
 
The trigger works in the following way. When the triggering threshold of the signal level is reached, the application is sent the OnLevelReachedBegin message. As soon as the signal level leaves the triggering threshold, the application is sent the OnLevelReachedEnd message. The triggering threshold can be specified in two units: decibels (dB) and percent (%) divided by 100. When specified in percent, the threshold value belongs to the interval from 0 up to 1. For instance, when determining silence, the threshold may have value 0.17, which is 17%.
+
===Audio trigger===
<LI>
+
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:<br>
Now is time to set the triggering delay in milliseconds (ms). When the given threshold is reached, the signal has to be at that level for the given number of ms for the trigger to switch. When the delay is passed the application will get sent the OnLevelReachedBegin message. But this message will not be sent if the signal leaves the given level before the delay expires.
+
- IMLAudioLevel::AdviseNotify(): calling IMLAudioLevelNotify::OnLevel() callback method;<br>
To determine silence in a channel, a normal value for the triggering delay is 500 ms. If the lower front chosen, and the threshold equals to 0.17, and the signal remains below the threshold for 500 ms, the application will get the OnLevelReachedBegin message, which means that silence started in the channel. As soon as the signal exceeds 0.17, the application will get the OnLevelReachedEnd message, which means that there's no silence in the channel any longer.
+
- IMLAudioLevel::AdviseEvent(): calling the function SetEvent() with handle to the event created by the user using CreateEvent() system function.<br>
<LI>
+
Other parameters are also set:<br>
The rest of parameters and the way of processing depend on the message type. When using the notification interface message type, the application has to pass a reference to the event interface. When dealing with standard Windows messages, - handles to event objects have to be passed. Use the CreateEvent function for creating handles. And when using DirectShow notifications, DirectShow interfaces are used for handling messages. The corresponding constants for the messages are EC_LEVEL_REACHED_BEGIN and EC_LEVEL_REACHED_END.
+
- the position of the audio trigger (before or after the amplifier and VU meter);<br>
<LI>
+
- channel number (or -1 for all channels at once) for collecting data and sending notifications;<br>
The Unadvise method uses to terminate the advise link established with the IAudioLevel interface. The dwAdviseCookie parameter identifies the link to terminate.
+
- threshold in dB;<br>
</OL>
+
- data accumulation interval in ms. Notifications are not called if the signal leaves the specified level before the expiration of the time interval;<br>
<br><br>
+
- threshold transition type: average absolute value of the signal above or below the threshold after the transition<br>
Auto gain control: There are 3 modes, used to avoid acoustic overfilling:
+
The method returns a cookie used to identify the notification and cancel it using IMLAudioLevel::Unadvise().<br>
* Without control (there will be crackle if the signal is amplified).
+
The trigger can be used to notify you when the silence is broken, or vice versa, when the sound stops.
* Fixed mode, which is when a maximum amplification koefficient is specified. Further, while processing the signal, the sound level is adjusted automatically to avoid overfilling.
+
It can also be used to inform about any events through the specified channel of the audio stream.<br>
* Float mode. The sound level is continuously approaching the specified amplification mark, at the same time avoiding overfilling.
+
 
When in the fixed mode, the level used is the highest possible. When in the float mode, the average level is used. Float is good when the signal is an ordinary sound.
+
===Delay correction===
<br><br><br>
+
Audio filters (Audio Renderer, for example) can have large buffers for sound accumulation and, accordingly, large delays in audio output.
You can get any extra information from the interface definition in the IDL file.
+
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.<br>
 +
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.<br>
 +
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.<br>
 +
 
 +
===Spectrum analyzer===
 +
The signal spectrum (in dB) in a given channel can be obtained using the IMLAudioLevel::GetSpectrum() method.<br>
 +
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.<br>
 +
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.<br>
 +
Spectrum analyzer parameters:<br>
 +
- number of bands per octave: 1,2,3 or 6. If 0 is selected, then spectrum analyzer is disabled.<br>
 +
- type of window function for spectrum calculation.<br>
 +
- the length of the Fourier window for calculating the spectrum.

Latest revision as of 14:03, 9 April 2021

Brief description of the Audio Level DirectShow filter capabilities.
Interface IMLAudioLevel can be found in file <filter installation directory>\Idl\ALevel.idl

Contents

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.

VU-meter

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 amplification

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.

Audio trigger

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.

Delay correction

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.

Spectrum analyzer

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.

Personal tools