A quick run through the new Windows 7 multimedia audio SDK samples

As I mentioned yesterday, the Windows SDK is now live.  For the Windows SDK, there are 9 new samples (and one changed samples). 

 

Two of the SDK samples demonstrate the WIndows 7 “Ducking” feature – they’re actually based on the code I wrote for my PDC talk last year, but tweaked to show some new scenarios and clean up the code (the original PDC code was not ready for prime time, it was strictly demo-ware).

  • The DuckingMediaPlayer application shows both a really simple DirectShow based media player but also shows how to integrate the players volume control with the Windows per-application volume mixer.  So if you’re wondering how to integrate the volume control for your application with the built-in per-application volume controls, this sample will show you how to do it.
  • The DuckingCaptureSample application is a trivial application that uses the wave APIs to capture audio data (and throw it away).  This shows how to trigger the “ducking”  feature in WIndows 7.

The other 7 samples reproduce functionality in the old WinAudio SDK sample – instead of providing a single monolithic audio sample, we crafted  different samples each of which shows one aspect of audio rendering.  All of these samples are simple console applications which read their parameters from the command line.  They’re intentionally extremely simple to reduce the potential for confusion in the samples.

  • The EndpointVolume sample shows how to use the IAudioEndpointVolume APIs.  It demonstrates using the VolumeStepUp, VolumeStepDown, SetMute and SetMasterVolumeLevelScalar APIs.
  • The CaptureSharedEventDriven sample shows how to use WASAPI in “event driven” mode to capture data in shared mode from the microphone.
  • The CaptureSharedTimerDriven sample shows how to use WASAPI in “timer driven” mode to capture data in shared mode from the microphone.
  • The RenderSharedEventDriven sample shows how to use WASAPI in “event driven” mode to play a simple sine wave in shared mode from the speakers.
  • The RenderSharedTimerDriven sample shows how to use WASAPI in “timer driven” mode to play a simple sine wave in shared mode from the speakers.
  • The RenderExclusiveEventDriven sample shows how to use WASAPI in “event driven” mode to play a simple sine wave in exclusive mode from the speakers.  This also shows the “exclusive mode swizzle” that is required to align the buffer size with the hardware buffer size (which is required to work with many HDAudio solutions).
  • The RenderExclusiveTimerDriven sample shows how to use WASAPI in “timer driven” mode to play a simple sine wave in exclusive mode from the speakers.  This also shows the “exclusive mode swizzle” that is required to align the buffer size with the hardware buffer size (which is required to work with many HDAudio solutions).

The reason we don’t have capture exclusive samples is that we felt that users of the SDK could derive the exclusive capture samples from the render samples if it was important to them. 

All the shared mode samples also show how to implement stream switching.

 

One of the things I’m quite proud about the samples is their structure.  Each sample has the following basic file layout:

  Directory of C:\Program Files\Microsoft SDKs\Windows\v7.0\Samples\multimedia\audio\RenderExclusiveEventDriven

08/07/2009  10:08 AM    <DIR>          .
08/07/2009  10:08 AM    <DIR>          ..
07/14/2009  06:54 PM             7,079 CmdLine.cpp
07/14/2009  06:54 PM               760 CmdLine.h
07/14/2009  06:54 PM             2,084 ReadMe.txt
07/14/2009  06:54 PM               533 stdafx.cpp
07/14/2009  06:54 PM               935 stdafx.h
07/14/2009  06:54 PM             1,067 targetver.h
07/14/2009  06:54 PM             1,925 ToneGen.h
07/14/2009  06:54 PM            18,376 WASAPIRenderer.cpp
07/14/2009  06:54 PM             2,560 WASAPIRenderer.h
07/14/2009  06:54 PM            14,754 WASAPIRenderExclusiveEventDriven.cpp
07/14/2009  06:54 PM             1,283 WASAPIRenderExclusiveEventDriven.sln
07/14/2009  06:54 PM             8,403 WASAPIRenderExclusiveEventDriven.vcproj
              12 File(s)         59,759 bytes
               2 Dir(s)  62,822,105,088 bytes free

Each sample has the same set of common files:

  • CmdLine.cpp/CmdLine.h: A very simple command line parsing function
  • stdafx.cpp/stdafx.h: Common header definitions
  • targetver.h: Defines the target platform for these samples (Windows Vista in this case).
  • ToneGen.h: A very simple sine wave generating function (not present for the capture samples).
  • WASAPIRenderer.cpp/WASAPIRenderer.h (WASAPICapture for capture samples): The code which does all the WASAPI rendering and/or capturing
  • <SampleName>: Scaffolding for the sample – this defines the command line parameters and instantiates the actual render/capture object and asks it to do the rendering/capturing.

Each of these samples is essentially identical, in fact they’re sufficiently similar that you can use your favorite file comparison tool to see what code has to change to go from one mode to another.  So to see what changes are required to go from exclusive timer driven to exclusive event driven, you can windiff the RenderExclusiveEventDriven\WASAPIRenderer.cpp and RenderExclusiveTimerDriven\WASAPIRenderer.cpp files and see what changes are required to implement the different model.