Peak Meters
To support Windows applications that display peak meters, the EndpointVolume API includes an IAudioMeterInformation interface. This interface represents a peak meter on an audio endpoint device. For a rendering device, the value retrieved from the peak meter represents the maximum sample value encountered in the output stream to the device during the preceding metering period. For a capture device, the value retrieved from the peak meter represents the maximum sample value encountered in the input stream from the device.
The peak-meter values obtained from the methods in the IAudioMeterInformation interface are floating-point numbers in the normalized range from 0.0 to 1.0. For example, if a PCM stream contains 16-bit samples, and the peak sample value during a particular metering period is —8914, then the absolute value recorded by the peak meter is 8914, and the normalized peak value reported by the IAudioMeterInformation interface is 8914/32768 = 0.272.
If the audio endpoint device implements the peak meter in hardware, the IAudioMeterInformation interface uses the hardware peak meter. Otherwise, the interface implements the peak meter in software.
If a device has a hardware peak meter, the peak meter is active both in shared mode and in exclusive mode. If a device lacks hardware peak meter, the peak meter is active in shared mode, but not in exclusive mode. In exclusive mode, the application and the audio hardware exchange audio data directly, bypassing the software peak meter (which always reports a peak value of 0.0).
The following C++ code example is a Windows application that displays a peak meter for the default rendering device:
// Peakmeter.cpp -- WinMain and dialog box functions
#include <windows.h>
#include <mmdeviceapi.h>
#include <endpointvolume.h>
#include "resource.h"
static BOOL CALLBACK DlgProc(HWND, UINT, WPARAM, LPARAM);
static void DrawPeakMeter(HWND, float);
// Timer ID and period (in milliseconds)
#define ID_TIMER 1
#define TIMER_PERIOD 125
#define EXIT_ON_ERROR(hr) \
if (FAILED(hr)) { goto Exit; }
#define SAFE_RELEASE(punk) \
if ((punk) != NULL) \
{ (punk)->Release(); (punk) = NULL; }
//-----------------------------------------------------------
// WinMain -- Opens a dialog box that contains a peak meter.
// The peak meter displays the peak sample value that plays
// through the default rendering device.
//-----------------------------------------------------------
int APIENTRY WinMain(HINSTANCE hInstance,
HINSTANCE hPrevInstance,
LPSTR lpCmdLine,
int nCmdShow)
{
HRESULT hr;
IMMDeviceEnumerator *pEnumerator = NULL;
IMMDevice *pDevice = NULL;
IAudioMeterInformation *pMeterInfo = NULL;
if (hPrevInstance)
{
return 0;
}
CoInitialize(NULL);
// Get enumerator for audio endpoint devices.
hr = CoCreateInstance(__uuidof(MMDeviceEnumerator),
NULL, CLSCTX_INPROC_SERVER,
__uuidof(IMMDeviceEnumerator),
(void**)&pEnumerator);
EXIT_ON_ERROR(hr)
// Get peak meter for default audio-rendering device.
hr = pEnumerator->GetDefaultAudioEndpoint(eRender, eConsole, &pDevice);
EXIT_ON_ERROR(hr)
hr = pDevice->Activate(__uuidof(IAudioMeterInformation),
CLSCTX_ALL, NULL, (void**)&pMeterInfo);
EXIT_ON_ERROR(hr)
DialogBoxParam(hInstance, L"PEAKMETER", NULL, (DLGPROC)DlgProc, (LPARAM)pMeterInfo);
Exit:
if (FAILED(hr))
{
MessageBox(NULL, TEXT("This program requires Windows Vista."),
TEXT("Error termination"), MB_OK);
}
SAFE_RELEASE(pEnumerator)
SAFE_RELEASE(pDevice)
SAFE_RELEASE(pMeterInfo)
CoUninitialize();
return 0;
}
//-----------------------------------------------------------
// DlgProc -- Dialog box procedure
//-----------------------------------------------------------
BOOL CALLBACK DlgProc(HWND hDlg, UINT message, WPARAM wParam, LPARAM lParam)
{
static IAudioMeterInformation *pMeterInfo = NULL;
static HWND hPeakMeter = NULL;
static float peak = 0;
HRESULT hr;
switch (message)
{
case WM_INITDIALOG:
pMeterInfo = (IAudioMeterInformation*)lParam;
SetTimer(hDlg, ID_TIMER, TIMER_PERIOD, NULL);
hPeakMeter = GetDlgItem(hDlg, IDC_PEAK_METER);
return TRUE;
case WM_COMMAND:
switch ((int)LOWORD(wParam))
{
case IDCANCEL:
KillTimer(hDlg, ID_TIMER);
EndDialog(hDlg, TRUE);
return TRUE;
}
break;
case WM_TIMER:
switch ((int)wParam)
{
case ID_TIMER:
// Update the peak meter in the dialog box.
hr = pMeterInfo->GetPeakValue(&peak);
if (FAILED(hr))
{
MessageBox(hDlg, TEXT("The program will exit."),
TEXT("Fatal error"), MB_OK);
KillTimer(hDlg, ID_TIMER);
EndDialog(hDlg, TRUE);
return TRUE;
}
DrawPeakMeter(hPeakMeter, peak);
return TRUE;
}
break;
case WM_PAINT:
// Redraw the peak meter in the dialog box.
ValidateRect(hPeakMeter, NULL);
DrawPeakMeter(hPeakMeter, peak);
break;
}
return FALSE;
}
//-----------------------------------------------------------
// DrawPeakMeter -- Draws the peak meter in the dialog box.
//-----------------------------------------------------------
void DrawPeakMeter(HWND hPeakMeter, float peak)
{
HDC hdc;
RECT rect;
GetClientRect(hPeakMeter, &rect);
hdc = GetDC(hPeakMeter);
FillRect(hdc, &rect, (HBRUSH)(COLOR_3DSHADOW+1));
rect.left++;
rect.top++;
rect.right = rect.left +
max(0, (LONG)(peak*(rect.right-rect.left)-1.5));
rect.bottom--;
FillRect(hdc, &rect, (HBRUSH)(COLOR_3DHIGHLIGHT+1));
ReleaseDC(hPeakMeter, hdc);
}
In the preceding code example, the WinMain function calls the CoCreateInstance function to create an instance of the IMMDeviceEnumerator interface, and it calls the IMMDeviceEnumerator::GetDefaultAudioEndpoint method to obtain the IMMDevice interface of the default rendering device. WinMain calls the IMMDevice::Activate method to obtain the device's IAudioMeterInformation interface, and it opens a dialog box to display a peak meter for the device. For more information about WinMain and CoCreateInstance, see the Windows SDK documentation. For more information about IMMDeviceEnumerator and IMMDevice, see Enumerating Audio Devices.
In the preceding code example, the DlgProc function displays the peak meter in the dialog box. During processing of the WM_INITDIALOG message, DlgProc calls the SetTimer function to set up a timer that will generate WM_TIMER messages at regular time intervals. When DlgProc receives a WM_TIMER message, it calls IAudioMeterInformation::GetPeakValue to obtain the latest peak-meter reading for the stream. DlgProc then calls the DrawPeakMeter function to draw the updated peak meter in the dialog box. For more information about SetTimer and the WM_INITDIALOG and WM_TIMER messages, see the Windows SDK documentation.
You can easily modify the preceding code example to display a peak meter for the default capture device. In the WinMain function, change the value of the first parameter in the call to the IMMDeviceEnumerator::GetDefaultAudioEndpoint from eRender to eCapture.
The following code example is the resource script that defines the controls that appear in the preceding code example:
// Peakmeter.rc -- Resource script
#include "resource.h"
#include "windows.h"
//
// Dialog
//
PEAKMETER DIALOGEX 0, 0, 150, 34
STYLE DS_MODALFRAME | WS_CAPTION | WS_SYSMENU | DS_SETFONT
CAPTION "Peak Meter"
FONT 8, "Arial Rounded MT Bold", 400, 0, 0x0
BEGIN
CTEXT "",IDC_PEAK_METER,34,14,82,5
LTEXT "Min",IDC_STATIC_MINVOL,10,12,20,12
RTEXT "Max",IDC_STATIC_MAXVOL,120,12,20,12
END
The following code example is the resource header file that defines the control identifiers that appear in the preceding code examples:
// Resource.h -- Control identifiers
#define IDC_STATIC_MINVOL 1001
#define IDC_STATIC_MAXVOL 1002
#define IDC_PEAK_METER 1003
Related topics