ILMADetUserCallback Interface

This is a user callback interface that should be implemented to receive notifications of whether sound/silence is detected. You register the callback by setting the ILMADet::CallbackObj property. This interface has one method, which will be called by the filter to report sound/silence events.

DirectShow determines the duration of the audio buffer. If you use the LEADTOOLS Multimedia toolkit, you can change the size of the audio buffers using the AudioBufferSize property.

Interface Methods:

HRESULT CallbackProc (long nEvent, VARIANT *pData, long lDataCount, long lBitsPerSample, long lChannels, long lSamplesPerSec, long lAvgBytesPerSec);

Parameters

nEvent	Event notification type. It tells whether we have sound or silence. Possible values for are:
	Value	Meaning
	AUDIO_LEVEL_STARTSOUND	The filter has detected sound. The previous buffer contained silence.
	AUDIO_LEVEL_SOUND	The filter has detected sound. The previous buffer contained sound also.
	AUDIO_LEVEL_STARTSILENCE	The filter has detected silence. The previous buffer contained sound.
	AUDIO_LEVEL_SILENCE	The filter has detected silence. The previous buffer contained silence also.
pData	Pointer to the audio data. The audio data is an array of unsigned bytes (8-bit) or signed short (16-bit) values. For more information on the audio data, refer to the Comments section below.
lDataCount	The number of elements in pData. If lBitsPerSample is 8, then this also represents the size (in bytes) of the buffer pointed to by pData. If lBitsPerSample is 16, then the size of the pData buffer is lDataCount * 2.
lBitsPerSample	Number of bits per sample of mono data. This can be 8 or 16. This determines the format of the data pointed to by pData.
lChannels	Number of channels (i.e. 1=mono, 2=stereo...)
lSamplesPerSec	Sample rate, in samples per second.
lAvgBytesPerSec	Average bandwidth in bytes per second. It should be equal to lSamplesPerSec * lChannels * (lBitsPerSample / 8).

Description

The filter will call this method when sound or silence is detected. Every time the callback is received, you are also given the audio data buffer.

Returns

S_OK if successful, an HRESULT error code otherwise.

Comments

Format of audio data:

The general format of the audio data (lChannels) is as follows:

Sample 0

Channel 0

Channel 1

…

Channel lChannels – 1

In this case,

pData(0) is Sample 0, Channel 0
pData(1) is Sample 0, Channel 1

pData(lChannels - 1) is Sample 0, Channel lChannels -1
pData(lChannels) is Sample 1, Channel 0
pData(lChannels + 1) is Sample 1, Channel 1

The format for mono data is simple, because there is only one channel. In this case, every value in the array is one sample:

pData(0) is Sample 0
pData(1) is Sample 1

The format for stereo data is still simple: there are two values per sample (one for left channel and the other for right channel):

pData(0) is Sample 0, Left channel
pData(1) is Sample 0, Right channel
pData(2) is Sample 1, Left channel
pData(3) is Sample 1, Right channel

The format of the value is different depending on whether lBitsPerChannel is 8 or 16.

Format of 8-bit audio data:

The values in the array are unsigned and between 0 and 255. The real audio value will be obtained by subtracting 128 from the array value and should have a value between –128 and 127. If you want to change the value, you must remember to add 128 before putting back the data.

Here is some Visual Basic code that doubles the intensity of the sound for pData(i):

Dim val As Long ‘ use a signed data type
val = pData(i) - 128 ‘ convert pData(i) to long. val is now the audio value, in the 0..255 range
val = val * 2 ‘ double the sound intensity

' convert the value to signed 8-bit
val = pData(i) - 128

' double the audio value
val = val * 2

' clip the output to -128..127
If val > 127 Then
val = 127
ElseIf val < -128 Then
val = -128
End If

' write the data out, adding back 128
pData(i) = val + 128

Note how the real audio value was clipped to the –128 ..127 range before adding 128. This is important, otherwise distortions are introduced.

Format of 16-bit data:

The values in the array are signed and between -32768 and 32767. They contain the real audio value and it is not necessary to do the conversions like for the 8-bit data.

Here is some Visual Basic code that doubles the intensity of the sound for pData(i):

‘ use a signed data type. Use long (32-bit in VB)
‘ instead of Integer (16-bit in VB) to avoid overflows when multiplying by 2
Dim val As Long

val = pData(i)
val = val * 2

' clip the output to --32768..32767
If val > 32767 Then
val = 32767
ElseIf (val < -32768) Then
val = -32768
End If

pData(i) = val