Sample – WASAPI exclusive-mode event-driven playback app, including the HD Audio alignment dance


Attached to this post is a sample WASAPI exclusive-mode event-driven playback app, including amd64 and x86 binaries, source, and a modification of the ac3.wav Dolby Digital test tone to include a “fact” chunk.

>play-exclusive.exe -?
play-exclusive.exe -?
play-exclusive.exe –list-devices
play-exclusive.exe [–device “Device long name”] –file “WAV file name”

    -? prints this message.
    –list-devices displays the long names of all active playback devices.

Plays the given file to the given device in WASAPI exclusive mode.
If no device is specified, plays to the default console device.

On the particular system I used to test this, these are the devices I have:

>play-exclusive.exe –list-devices
Active render endpoints found: 3
    Digital Audio (S/PDIF) (2- High Definition Audio Device)
    Speakers (2- High Definition Audio Device)
    Sceptre (High Definition Audio Device)

And this is the output I get when I play the attached ac3.wav test tones to the Sceptre HDMI output:

>play-exclusive –device “Sceptre (High Definition Audio Device)” –file ac3.wav
Opening .wav file “ac3.wav”…
The default period for this device is 30000 hundred-nanoseconds, or 144 frames.
Buffer size not aligned – doing the alignment dance.
Trying again with periodicity of 33333 hundred-nanoseconds, or 160 frames.
We ended up with a period of 33333 hns or 160 frames.

Successfully played all 460800 frames.

A word on the “alignment dance” highlighted above… first, this scene from The Pacifier.  (Vin Diesel is so coordinated.)

The Pacifier: The Peter Panda dance

Here’s the source for the dance (in play.cpp in the attached.)

// call IAudioClient::Initialize the first time
// this may very well fail
// if the device period is unaligned
hr = pAudioClient->Initialize(
    AUDCLNT_SHAREMODE_EXCLUSIVE,
    AUDCLNT_STREAMFLAGS_EVENTCALLBACK,
    hnsPeriod, hnsPeriod, pWfx, NULL
);
// if you get a compilation error on AUDCLNT_E_BUFFER_SIZE_NOT_ALIGNED,
// uncomment the #define below
//#define AUDCLNT_E_BUFFER_SIZE_NOT_ALIGNED AUDCLNT_ERR(0x019)
if (AUDCLNT_E_BUFFER_SIZE_NOT_ALIGNED == hr) {

    // if the buffer size was not aligned, need to do the alignment dance
    printf(“Buffer size not aligned – doing the alignment dance.\n”);
   
    // get the buffer size, which will be aligned
    hr = pAudioClient->GetBufferSize(&nFramesInBuffer);
    if (FAILED(hr)) {
        printf(“IAudioClient::GetBufferSize failed: hr = 0x%08x\n”, hr);
        return hr;
    }
   
    // throw away this IAudioClient
    pAudioClient->Release();

    // calculate the new aligned periodicity
    hnsPeriod = // hns =
        (REFERENCE_TIME)(
            10000.0 * // (hns / ms) *
            1000 * // (ms / s) *
            nFramesInBuffer / // frames /
            pWfx->nSamplesPerSec  // (frames / s)
            + 0.5 // rounding
        );

    // activate a new IAudioClient
    hr = pMMDevice->Activate(
        __uuidof(IAudioClient),
        CLSCTX_ALL, NULL,
        (void**)&pAudioClient
    );
    if (FAILED(hr)) {
        printf(“IMMDevice::Activate(IAudioClient) failed: hr = 0x%08x\n”, hr);
        return hr;
    }

    // try initialize again
    printf(“Trying again with periodicity of %I64u hundred-nanoseconds, or %u frames.\n”, hnsPeriod, nFramesInBuffer);
    hr = pAudioClient->Initialize(
        AUDCLNT_SHAREMODE_EXCLUSIVE,
        AUDCLNT_STREAMFLAGS_EVENTCALLBACK,
        hnsPeriod, hnsPeriod, pWfx, NULL
    );

    if (FAILED(hr)) {
        printf(“IAudioClient::Initialize failed, even with an aligned buffer: hr = 0x%08x\n”, hr);
        pAudioClient->Release();
        return hr;
    }
} else if (FAILED(hr)) {
    printf(“IAudioClient::Initialize failed: hr = 0x%08x\n”, hr);
    pAudioClient->Release();
    return hr;
}

// OK, IAudioClient::Initialize succeeded
// let’s see what buffer size we actually ended up with
hr = pAudioClient->GetBufferSize(&nFramesInBuffer);
if (FAILED(hr)) {
    printf(“IAudioClient::GetBufferSize failed: hr = 0x%08x\n”, hr);
    pAudioClient->Release();
    return hr;
}

// calculate the new period
hnsPeriod = // hns =
    (REFERENCE_TIME)(
        10000.0 * // (hns / ms) *
        1000 * // (ms / s) *
        nFramesInBuffer / // frames /
        pWfx->nSamplesPerSec  // (frames / s)
        + 0.5 // rounding
    );

 

 

Note the new HRESULT. 

HD Audio works on a 128-byte aligned buffer size.  This dance ensures that the HD Audio driver is being fed data in chunks of 128 bytes.  It is somewhat complicated by the fact that IAudioClient::Initialize takes a parameter of hundred-nano-seconds, but IAudioClient::GetBufferSize sets a parameter of frames.

EDIT September 28 2015: moved source to https://github.com/mvaneerde/blog/tree/master/play-exclusive

play-exclusive.zip

Comments (24)

  1. Tanveer Badar says:

    Your comment on Raymond’s blog is rather odd.

    http://blogs.msdn.com/oldnewthing/archive/2009/04/03/9529929.aspx#9530732

    How do you expect computers to work without virtual memory?

  2. > How do you expect computers to work without virtual memory?

    Quickly* or not at all**.

    *If everything fits in physical memory

    **If it doesn’t

  3. Preben Friis says:

    I do not get it: You initialize it at 3 ms. It returns a buffer size of 160 bytes. You tear it down and re-initialize it with a time that corresponds to 160 bytes buffer. Woudn’t ignoring "AUDCLNT_E_BUFFER_SIZE_NOT_ALIGNED" give the same end-result, or did I miss something?

  4. If you ignore the AUDCLNT_E_BUFFER_SIZE_NOT_ALIGNED error, then further calls you make on that IAudioClient object will fail (well, calls other than IAudioClient::GetBufferSize.)

    In particular, there’s no way to get an IAudioRenderClient or an IAudioCaptureClient on a needs-alignment endpoint without doing the dance (or guessing right the first time) because IAudioClient::GetService(…) will fail.

  5. Preben Friis says:

    Thaks for your reply. My current implementation does guess right the first time (as long as the rule is to stick with 128 byte alignment).

  6. roger says:

    So I assume the purpose of this was just an example demo to show how to us exclusive mode "right" or "well"?

  7. Andy says:

    be careful !!!

    hnsPeriod = // hns =

           (REFERENCE_TIME)(

               10000.0 * // (hns / ms) *

               1000 * // (ms / s) *

               nFramesInBuffer / // frames /

               pWfx->nSamplesPerSec  // (frames / s)

               + 0.5 // rounding

           );

    doesn't work as expected.

    (10000.0 * 1000 / 44100 * 160) = 36281.179138321997

    (10000.0 * 1000 / 44100 * 160) + 0.5 = 36281.679138321997

    when assigning to hnsPeriod which is supposedly "int" or smth

    we get

    hnsPeriod = 36281

    then doing reverse calculations of nFramesInBuffer

    nFramesInBuffer=36281*44100/(1000*10000)=159

    Not 160 as expected. another one from MS :(

  8. The going-back-to-frames code looks like this:

       // need to know how many frames that is

       UINT32 nFramesInBuffer = (UINT32)( // frames =

           1.0 * hnsPeriod * // hns *

           pWfx->nSamplesPerSec / // (frames / s) /

           1000 / // (ms / s) /

           10000 // (hns / s) /

           + 0.5 // rounding

       );

    Notice the 1.0 to force a conversion to double, and then the +0.5 at the end.

    36281*44100/1000/10000 is 159.9992…; adding 0.5 and then converting to int snaps this to the nearest frame, 160.

  9. Andy says:

    where does code snippet coming from? Is it really code that works in the OS or you think it should be like this?

  10. Andy says:

    And what is priority in your calculations duration or number of frames? Why is it so confusing?

  11. Code snippets come from the attached play-exclusive.zip, play.cpp.  This code is not in the OS; this is an example WASAPI client.

  12. On this forum post:

    social.msdn.microsoft.com/…/f4ec50d0-01cc-4217-8647-a2d7ec693c6d

    you mention that capture would look similar.  I tried to create a simple exclusive capture program, but the program hangs when I unplug the microphone.  Forum post:

    social.msdn.microsoft.com/…/83f5978d-e809-46ab-95bd-e41502901cdd

    Have you tried creating an exclusive capture example program?  Have you ever run into this problem before?  I saw that there's a problem calling Release from a different thread than the one that called GetService(), but that does not appear to be my problem.

    Thanks!  Great post, BTW.

    Bill

  13. You're probably hanging on this line:

           // in a production app there would be a timeout here

           WaitForSingleObject(hNeedDataEvent, INFINITE);

    Add a timeout value of, let's say, five times the buffer duration in milliseconds.  If WaitForSingleObject returns anything but WAIT_OBJECT_0, log a failure and bubble it up.

  14. Cubra says:

    what codes do I need to add in order to play files other than 16bit 44.1KHz format? Sorry, maybe off topic!

  15. If the audio driver supports the wave format in the .wav file, this will play it.

    If the audio driver does not support the wave format in the .wav file, then you will need a format converter.  WASAPI does not provide a format converter, so you will need to use a higher-level API like Media Foundation to play the content.

  16. Cubra says:

    I can play 24bit 192KHz wav file with Foobar player. Does it mean my audio driver is OK? I'm using on board Realtek High Definition Audio which supports up to 24bit 192Khz. I got AUDCLNT_E_UNSUPPORTED_FORMAT even after using WAVEFORMATEXTENSIBLE. Any further pointer would be appreciated!

  17. Jeyminee says:

    When i compile your code, i obtain this error :s

    prefs.cpp(366): error C2664: 'mmioOpenA' : cannot convert parameter 1 from 'LPWSTR' to 'LPSTR'

    1>          Types pointed to are unrelated; conversion requires reinterpret_cast, C-style cast or function-style cast

  18. @Cubra: there are two ways a driver can support 24 bit.  It can support 24 bit in 24-bit containers, where each sample is three bytes long.  Or it can support 24 bit in 32-bit containers.  Each sample is a signed four-byte integer, but the least significant byte is considered garbage and should be ignored.

    Heuristically, HD Audio drivers tend to favor 24-bit-in-32-bit-containers, and USB Audio drivers tend to favor 24-bit-in-24-bit-containers.  But the app should query format support for both separately.  For 24-in-24, specify wBitsPerSample and wValidBitsPerSample of 24; for 24-in-32, specify wBitsPerSample = 32 and wValidBitsPerSample of 24.

    If you're playing 24-in-24 audio to a 24-in-32-capable driver you'll need to do some processing in your app to add the extra byte of padding.  Similarly, if you're playing 24-in-32 audio to a 24-in-24-capable driver you'll need to remove the padding.

  19. @Jeyminee: edit your project properties to include these flags to pass to the C++ compiler:

    -DUNICODE -D_UNICODE

  20. sudha says:

    I tried to run the executable that comes with the zip file, and getting errors(Audio device does not support the requested format).

    Ran the executable on Win 7 system.

    I tried playing it through HDMI to speakers on the display, as well as directly on my laptop speaker, same error for both cases. Any clues.

    play-exclusive.exe –list-devices

    Active render endpoints found: 2

       VX2453 Series (Intel(R) Display Audio)

       Speakers / HP (IDT High Definition Audio CODEC)

    play-exclusive.exe –device "VX2453 Series (Intel(R) Display Audio)"

    –file ac3.wav

    Opening .wav file "ac3.wav"…

    Audio device does not support the requested format.

    Thread returned failing HRESULT 0x88890008

    play-exclusive.exe –list-devices

    Active render endpoints found: 1

       Speakers / HP (IDT High Definition Audio CODEC)

    play-exclusive.exe –device "Speakers / HP (IDT High Definition Audi

    o CODEC)" –file ac3.wav

    Opening .wav file "ac3.wav"…

    Audio device does not support the requested format.

    Thread returned failing HRESULT 0x88890008

  21. 0x88890008 is AUDCLNT_E_UNSUPPORTED_FORMAT, which is normal if the device does not support the WAVEFORMATEX format in the .wav file.

    ac3.wav has Dolby Digital audio in it. I would only expect a hardware receiver with the Dolby logo to be able to decode Dolby Digital in hardware, so I am not surprised your HDMI TV and built-in speakers reject it.

  22. Emek says:

    Thanks for the sample code. I was going to ask about this to you; but decided to do a web search first and found my answer :)

  23. Robert Bielik says:

    Hi Matthew, I'm trying to get a WASAPI shared client working with capture + rendering, but have artefact problems (render part) when I use a non-buffer-size. It works fine when ONLY rendering, but not when doing both. I know it's hard to have answers from this brief, informationless, description :) But do you have any general pointers to handling events etc. i.e. is it better to WaitForMultipleObjects with the capture/play handles, or WaitForSingleObject on each ? That kind of stuff.. :)

  24. @Robert a good place to ask your question is here:

    social.msdn.microsoft.com/…/home

    If you're capturing and rendering on the same thread you might have to worry about clock skew; you can use IAudioClockAdjustment to compensate.