Matthew van Eerde's web log : Audio

How to turn on HDCP or SCMS in an audio playback app

Maurits — Tue, 10 Nov 2009 19:07:00 GMT

There's an MSDN sample of how to turn on HDCP or SCMS in a playback app. The sample is loosely based on a test app I wrote, but there are still some rough edges. For example, the CMFAttributeImpl<T> template is not part of the SDK or the DDK. Also, there's a leak in the GetDigitalAudioEndpoint implementation. (Using the private template was my bug. The leak was someone else's.)

Exercise: find the leak.

There are also rough edges in the test app. For one thing, it doesn't play audio - the way to use the app is to

Start playing audio using your favorite audio playback application, to the digital output on which want to turn on HDCP or SCMS.
Run the trustedaudiodrivers2.exe command line to do what you want it to.

Source and binaries (x86 and amd64) attached.

>trustedaudiodrivers2
trustedaudiodrivers2 --list-devices

trustedaudiodrivers2
    --device [ communications | console | multimedia | <device-name>]
    --copy-ok [ 0 | 1 ]
    --digital-output-disable [ 0 | 1 ]
    --test-certificate-enable [ 0 | 1 ]
    --drm-level <drm-level>

--list-devices: displays a list of output devices.

Sets a Trusted Audio Drivers 2 output policy on a given audio endpoint.
--device
    communications: set policy on default communications render endpoint.
    console: set policy on default console render endpoint.
    multimedia: set policy on default multimedia render endpoint.
    <device-name>: set policy on the endpoint with this long name.
--copy-ok: 1 or 0. Set to 0 to turn on "copy protection" (SCMS or HDCP)
--digital-output-disable: 1 or 0. Set to 1 to disable output (or turn on HDCP.) --test-certificate-enable: 1 or 0. Set to 1 to allow the test certificate.
--drm-level: set to a number. 1100 is a good default.

Here's a sample command line which should disable the digital out (or enable HDCP, if the driver supports it.) This is line-wrapped for readability only.

>trustedaudiodrivers2.exe
    --device "Acer H213H (High Definition Audio Device)"
    --copy-ok 1
    --digital-output-disable 1
    --test-certificate-enable 1
    --drm-level 1300

If all goes well the output should look something like this:

Output Trust Authorities on this endpoint: 2
Processing Output Trust Authority #1 of 2
OTA action is PEACTION_PLAY (1)
GetOriginatorID() called
GetOriginatorID() called
GenerateRequiredSchemas() called
dwAttributes: MFOUTPUTATTRIBUTE_DIGITAL (0x00000001)
guidOutputSubType: MFCONNECTOR_HDMI ({57CD596D-CE47-11D9-92DB-000BDB28FF98})
cProtectionSchemasSupported: 1
MFPROTECTION_TRUSTEDAUDIODRIVERS ({65BDF3D2-0168-4816-A533-55D47B027101})
MFPROTECTION_TRUSTEDAUDIODRIVERS supported.
IMFOutputSchema::GetSchemaType called
IMFOutputSchema::GetConfigurationData called
IMFOutputTrustAuthority::SetPolicy returned 0x00000000
Processing Output Trust Authority #2 of 2
OTA action is PEACTION_EXTRACT (4)
Skipping as the OTA action is not PEACTION_PLAY
Policy successfully applied. Press any key to release IMFTrustedOutput...

At that point I pressed a key, which redacted the policy, and the music started playing again.

Common causes of failures:

No audio is playing to that device. Setting protection requires an active audio stream.
The audio device is not S/PDIF or HDMI.
The audio driver is not capable of enforcing the protection.
The audio driver is test-signed only; try --test-certificate-enable 1
Kernel debugging is enabled.
Driver verifier is enabled.

This source should compile with just publically available headers and no special voodoo on the part of the developer.

EDIT: 11/13/2009 10:05 AM

A subtle problem was called to my attention. This line triggers an ATL ASSERT:

hr = pMFOutputTrustAuthority->SetPolicy(&pMFOutputPolicy, 1, &pbTicket, &cbTicket);

The ASSERT is in CComPtr<IMFOutputPolicy>::operator& which ASSERTs if the pointer CComPtr<IMFOutputPolicy>::p is not NULL.

My first instinct was to bypass the assertion like this:

hr = pMFOutputTrustAuthority->SetPolicy(&pMFOutputPolicy.p, 1, &pbTicket, &cbTicket);

But ASSERTs are there for a reason. The fundamental problem here is that I'm trying to be too clever.

Despite its name, IMFOutputTrustAuthority::SetPolicy takes, not an IMFOutputPolicy *, but an array of IMFOutputPolicy *s. A little confusing, yes. As this is effectively a sample, I should be emphasizing this behavior, not covering it up.

So here's the fix I decided on. Updated source and binaries attached.

// we're only setting a single policy but the API allows setting multiple policies
// (like WaitForMultipleObjects)
IMFOutputPolicy *rMFOutputPolicies[1] = { pMFOutputPolicy };
hr = pMFOutputTrustAuthority->SetPolicy(
    rMFOutputPolicies,
    ARRAYSIZE(rMFOutputPolicies),
    &pbTicket,
    &cbTicket
);

How to calculate a sine sweep - the right way

Maurits — Sat, 08 Aug 2009 01:12:00 GMT

Three quarters are better than a dollar because they make noise!
-- Lilly, Lilly's Purple Plastic Purse

Last time I talked about how to calculate a sine sweep mathematically. There's a closed-form solution which is quite elegant but, alas, useless in a practical computer implementation due to the very big numbers that are being fed to the sin(...) function.

A computer implementation will care only about the discrete samples that need to be generated. The integral in the previous post turns out to be counterproductive - we're much more interested in the infinite sequence of φ_i, and more particularly in their residue mod 2π.

Here are Matlab scripts that implement a sine sweep both ways:

First, the naïve mathematical solution that just calculates the exponential:

function signal = sinesweep_nostate( ...
    start, ...
    finish, ...
    seconds, ...
    sample_rate, ...
    amplitude, ...
    initial_phase, ...
    dc ...
)
% sinesweep_nostate returns a single-channel sine logarithmic sweep
%     DO NOT USE THIS FUNCTION IN PRODUCTION
%     THIS IS A PEDAGOGICAL EXERCISE ONLY
%     THE SIGNAL THIS PRODUCES GRADUALLY DISTORTS
%     INSTEAD USE sinesweep
%
%     start: starting frequency in Hz
%     finish: ending frequency in Hz
%     seconds: duration of sweep in seconds
%     samplerate: samples per second
%     amplitude: amplitude
%     initial_phase: starting phase
%     dc: dc

% echo these interesting intermediate values to the console
R = (finish / start) ^ (1 / seconds)
B = 2 * pi * start / log(R)
A = initial_phase - B

time = 0 : 1 / sample_rate : seconds;
phase = A + B * R .^ time;
signal = amplitude * sin(phase) + dc;

end % sinesweep_nostate

Now, the iterative version that adds up the little Δφs to calculate φ_i iteratively:

function signal = sinesweep( ...
    start, ...
    finish, ...
    seconds, ...
    sample_rate, ...
    amplitude, ...
    initial_phase, ...
    dc ...
)
% sinesweep returns a single-channel sine logarithmic sweep
%     start: starting frequency in Hz
%     finish: ending frequency in Hz
%     seconds: duration of sweep in seconds
%     samplerate: samples per second
%     amplitude: amplitude
%     initial_phase: starting phase
%     dc: dc

time = 0 : 1 / sample_rate : seconds;
frequency = exp( ...
    log(start) * (1 - time / seconds) + ...
    log(finish) * (time / seconds) ...
);

phase = 0 * time;
phase(1) = initial_phase;
for i = 2:length(phase)
    phase(i) = ...
        mod(phase(i - 1) + 2 * pi * frequency(i) / sample_rate, 2 * pi);
end

signal = amplitude * sin(phase) + dc;

end % sinesweep

If anything, one would expect the first to be more accurate, since it is mathematically precise, and the second is only an approximation. But let's see how the signal produced by each of them holds up.

I calculate, and plot, the same sweep both ways, with a slight dc offset to facilitate seeing the different sweeps on the same plot. In particular this is a logarithmic sweep from 20 kHz to 21 kHz, over 30 seconds, using 44100 samples per second, an amplitude of 0.2, an initial phase of π, and a dc of 0.25 for one and 0.26 for the other:

plot(...
x, sinesweep(20000, 21000, 30, 44100, 0.2, pi, 0.25), 'd', ...
x, sinesweep_nostate(20000, 21000, 30, 44100, 0.2, pi, 0.26), 's' ...
)

(x is just 1:30*44100 - necessary to allow a single plot statement.)

Note that the approximate method is plotted in diamonds, and will be 0.01 lower on the resulting graph than the "exact" method, plotted in squares.

(This takes a while to plot because there are a heckuva lot of points...)

Ah, a nice solid mass of green and blue. I won't show it here.

OK, let's zoom in to a very early chunk of the signal - I expect these to match up closely, with only the dc offset separating the points:

Yup. Looks pretty good - give or take a pixel (quantization error in the display.)

Now let's see what happens to the signal towards the end of the 30 seconds.

Ick. Something's rotten in the state of Denmark. This distortion is so bad that it's visible - you don't even have to take an FFT to see it.

Exercise: take an FFT and look at the distortion.

Advanced Exercise: demonstrate that the distortion is, in fact, in the "exact" method and not in the iterative method... that is to say, show which clock is right.

EDIT: On second glance it looks like the second picture is just showing a horizontal shift between the two signals, which is expected. I'll need to dig deeper if I'm to prove my assertion that the iterative method produces less distortion than the "exact" method.

How to calculate a sine sweep - the wrong way

Maurits — Tue, 04 Aug 2009 00:07:00 GMT

Suppose you want to generate a continuous sine-sweep from time t_start to time t_end. You want the starting frequency to be ω_start, and the ending frequency to be ω_end; you want the sweep to be logarithmic, so that octaves are swept out in equal times. (The alternative would be to sweep linearly, but usually logarithmic sweeping is what you want.) For today we're going to have continuous time and sample values, so sample rate and bit depth will not be part of this discussion; in particular, the units of t will be seconds, and our sample values will go from -1 to 1.

Here's a picture of want we want to end up with:

Without loss of generality, set t_start = 0. This simplifies some of the math.

Let ω(t) be the "instantaneous frequency" at time t. Advanced Exercise: Define "instantaneous frequency" mathematically.

Sweeping ω(t) logarithmically means that log ω(t) is swept linearly from log ω_start to log ω_end. So

Quick check: ω(0) = ω_start, ω(t_end) = ω_end. Yup.

Let's define R (the rate of change of the frequency) as (ω_end / ω_start)^{1 / t_end}. This formula reduces to

ω(t) = ω_start R^t

Next step is to look at phase. For a sine wave of constant frequency ω, phase progresses linearly with t on the circular interval [0, 2π):
φ = k ω t
for some constant k. If the frequency of a sine wave was 1 cycle per second, the phase would go from 0 to 2π in a single second - this reveals that the correct value of k is 2π:
φ = 2π ω t

What happens with a variable frequency? A little calculus provides the answer. Consider a small change Δt, small enough so that ω(t) is almost constant over the interval:
Δφ ≈ 2π ω(t) Δt
because over that interval the sine sweep function is well approximated by a sine wave of constant frequency ω(t).

Starting from an initial phase φ_start, let Δt → 0, and:

Substitute:
u = τ log R
τ = u / log R
dτ = du / log R

Define:
B = 2π ω_start / log R
A = φ_start - B
and we have:

φ(t) = A + BR^t

Just for fun, here's the explicit solution without intermediate values:

Now, the payoff: the signal is just the sine of the phase, so our sine sweep is:

or, more explicitly:

Ah, beautiful mathematically.

But useless practically.

Why useless?

Well, note that our equation for phase is an exponential. That expression inside the sin(...) gets very big, very quickly. Any practical implementation of sin(...) is going to be utterly useless once its argument gets beyond a certain threshold - you'll get ugly chunky steps before you're halfway into the sweep.

Nonetheless, there is a practical way to generate (pretty good) sine sweeps. More on that next time.

EDIT: all logs are base e.

Bug - jack detection on Windows 7 hdaudio.sys mixed capture

Maurits — Tue, 23 Jun 2009 00:47:00 GMT

There's a bug that got away from me in Windows 7's HD Audio class driver (hdaudio.sys.)

Before I explain the bug, a few caveats:

If you're using Vista, there's no problem. This only affects Windows 7.

If you use the third-party audio driver, there's no problem. This only affects the Microsoft HD Audio class driver (hdaudio.sys.)

If your recording devices (mic and line in) are independent (can capture from both at the same time) or muxed (can capture from one or the other but not from their sum) then you're fine; this only affects mixed capture (can capture from one, from the other, or from their sum, but not from both sides of the mix independently.)

If either of your recording devices doesn't support jack presence detection then you're fine; this only affects mixed capture where both sides of the mix support jack presence detection.

Here's the bug.

There are various ways to "reset" the system and bring the OS recording device state into synchronization with the hardware state

reboot
reset the HD Audio controller
reinstall the audio driver
restart the AudioEndpointBuilder service
unplug all recording devices in the mix

The first state change (plug or unplug) after a reset works
The second and further state changes are not recognized by the OS until a reset.

Here's a sample state diagram assuming a mixed Mic and Line In (click to view full-size:)

Workarounds:

Install the third-party audio driver instead of the HD Audio class driver.

Use audio extension cables to fool the jack presence detection hardware into thinking something is always plugged in.

Why square waves have ears: Gibbs' phenomenon (Wilbraham's phenomenon)

Maurits — Thu, 07 May 2009 22:30:00 GMT

In a recent post I sung the praises of square waves as a way to get a heckuva lot of power (3 dB more power than a sine wave) into a sample-range-limited signal. It's time to take them down a notch now.

A problem with square waves is they're impossible to generate in the analog domain. In fact, you can't even get close.

Signals generated in the analog domain are subject to physical laws regarding continuity (no teleportation) and whatnot. A common way to model these is to express (periodic) analog signals using a basis of sine waves with integral periods. Suppose I want to generate the square wave:

f(x) = 1, -π < x < 0

-1, 0 < x < π

Graphed below are some approximations of this function using sine waves as a basis. Note that only odd values of n are used in the sums of sin(nx).

The sums converge to +/-1 quite well, but there are definite "ears" at x near 0 where there's overshoot. This doesn't appear to die down. A closeup of one of the "ears":

If anything, rather than dying down, the "ears" converge to max(f_n) → about 1.18, or about 9% of the "jump" from -1 to 1. (Dym and McKean, in their 1972 book Fourier Series and Integrals, get the 9% right but incorrectly assert that the convergence is to 1.09.)

This mathematical phenomenon - Gibbs' phenomenon - is a good illustration of the difference between convergence of a series of functions and uniform convergence.

In this case, the series of partial sums pointwise converge to the square wave... for any given point x > 0 and ε > 0, the ear will eventually move to the left, and I can choose an N such that f_n(x) is within of ε of 1 for all n > N...

... but the series does not uniformly converge to the square wave. The following assertion is false: "for any given ε > 0, I can pick an N such that f_n(x) is within of ε of 1 for all n > N and all x > 0." This can be demonstrated by picking ε = 0.17, say. For any n, even, say, n = 10¹⁰⁰, there is an x close to 0 where f_1e100(x) > 1.17.

Why a full-scale sine wave has an intensity of -3 dB FS

Maurits — Wed, 08 Apr 2009 01:20:00 GMT

I was asked one day why this full-scale sine wave was being measured by our signal analysis tools as -3 dB FS, even though it hits the maximum and the minimum sample values:

The answer is "because it's a sine wave, not a square wave." The intensity of a signal can be calculated from the following formula:

The inner integral does not depend on t - it's just the average sample value - so it's usually precalculated:

The importance of taking dc into account during analysis can be appreciated if you try to calculate the intensity of a signal with a high dc.

Exercise: calculate the intensity of x(t) ≡ -0.5 using the formulas above; calculate the "naïve intensity" by using the last formula above and omitting dc. Note the difference.

Now that we have the necessary formulas, let's analyze our full-scale sine wave signal. Plugging in a full-scale sine wave and analyzing over a full period we get:

As expected, the average value of the signal over a single period is 0.

Evaluating the intensity requires finding the antiderivative of (sin(t))². This can be ascertained most easily by plotting a few values and realizing that (sin(t))² = (1 - cos(2t))/2:

This is a dimensionless number that ranges from 0 (signal is a flat line) to 1 (... we'll get to that later.)

We can convert this into a dB FS measurement using the formula I_{dB FS} = 20 log₁₀ I_RMS:

Et voilà - that's where the -3 dB comes from.

In contrast to a sine wave, a full-scale square wave centered at 0 has an intensity of 0 dB FS:

To finish up, a couple of advanced exercises:

Advanced Exercise: prove that, provided t₁ and t₂ are sufficiently far apart, the intensity of a general sine wave x(t) = a sin(ωt + φ) + c depends only on a and not on ω, φ, or c.

Advanced Exercise: completely characterize the set of digital signals that achieve 0 dB FS intensity. If you have, say, 1000 samples of mono 16-bit integer audio to play with, how many distinct signals achieve 0 dB FS intensity?

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

Maurits — Fri, 03 Apr 2009 18:15:00 GMT

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.

Sample - WASAPI loopback capture (record what you hear)

Maurits — Tue, 16 Dec 2008 17:28:00 GMT

In a previous post I showed how to play silence to a given audio device and hinted at a possible application.

Attached to this post is a sample WASAPI loopback capture app - amd64, x86 and source included. This allows you to record the sound that is coming out of your speakers:

>loopback-capture -?
loopback-capture -?
loopback-capture --list-devices
loopback-capture [--device "Device long name"] [--file "file name"] [--int-16]

    -? prints this message.
    --list-devices displays the long names of all active playback devices.
    --device captures from the specified device (default if omitted)
    --file saves the output to a file (loopback-capture.wav if omitted))
    --int-16 attempts to coerce data to 16-bit integer format

There are a couple of oddities for WASAPI loopback capture. One is that "event mode" doesn't work for loopback capture; you can call pAudioClient->Initialize(... AUDCLNT_STREAMFLAGS_LOOPBACK | AUDCLNT_STREAMFLAGS_EVENTCALLBACK, ... ), you can call pAudioClient->SetEventHandle(...), and everything will succeed... but the "data is ready" event will never fire. So this app creates its own waitable timer.

Another oddity is that WASAPI will only push data down to the render endpoint when there are active streams. When nothing is playing, there is nothing to capture.

For example, play a song, and then run loopback-capture. While loopback-capture is running, stop the song, and then start it again. You'll get this output when you start it back up:

>loopback-capture
Press Enter to quit...
IAudioCaptureClient::GetBuffer set flags to 0x00000001 on pass 5381 after 1088829 frames

Thread HRESULT is 0x8000ffff

The flag in question is AUDCLNT_BUFFERFLAGS_DATA_DISCONTINUITY. When the song stopped, no more data was available to capture. Eventually the song started up again, and WASAPI dutifully reported that there was a glitch detected. This app stops on glitches.

There are a couple of other possible ways to handle this. One way is to ignore glitches; then if you stop a song, wait a few seconds, and start it again, then the recorded signal will omit the wait and abut the two "audio is playing" portions.

But my particular favorite way of handling this is to run silence.exe. That way there are never any "nothing is playing" glitches, because there's always something playing.

EDIT 11/23/2009: Updated loopback-capture.exe to ignore the glitch flag on the first packet, since Windows 7 sets it. Also improved the interaction between the capture thread bailing out and the user pressing Enter to finish.

Sample - playing silence via WASAPI event-driven (pull) mode

Maurits — Wed, 10 Dec 2008 21:30:00 GMT

Be vewy vewy quiet - we'we hunting wabbits.
-- Elmer Fudd

Attached is a mini-app I've written to play silence to any given playback device using WASAPI event-driven (pull) mode. Source, x86 binary, and amd64 binary are attached.

Usage statement:

>silence -?
silence
silence -?
silence --list-devices
silence --device "Device long name"

    With no arguments, plays silence to the default audio device.
    -? prints this message.
    --list-devices displays the long names of all active playback devices.
    --device plays silence to the specified device.

>silence --list-devices
Active render endpoints found: 2
Speakers (USB Audio Device)
Headphones (High Definition Audio Device)

>silence --device "Headphones (High Definition Audio Device)"
Press Enter to quit...
Received stop event after 488 passes

While it's playing it shows up in the Volume Mixer:

Why would I write such a thing?

Well, there is the pedagogical exercise of writing a WASAPI event-driven render loop.

But there is also a practical application of an active silence stream, having to do with loopback capture. More on this in a future post...

EDIT: 7/30/2009 - fixed bug where I was treating the GetCurrentPadding value as the amount of free space in the buffer when in fact it's the amount of used space.

While I was at it, added an icon and exited immediately on errors rather than waiting for the caller to hit Enter.

The case of the default audio device from the future

Maurits — Sat, 08 Nov 2008 04:11:00 GMT

Hover the mouse over each picture (xkcd-style) in turn to get the text that tells the story.

An amusing behavior of Windows Vista recently came to my attention... sometimes the Sound control panel wants to go back... to the future!

So far, so good.

D'oh! Luckily, there's a way to recover...

Voilà tout.

How long can the logoff sound be?

Maurits — Tue, 28 Oct 2008 20:53:00 GMT

Windows has a customizable soundtrack - when different things happen, sounds play. You can live with the default sounds, turn all the sounds off, or substitute your own sounds. All configurable via the Sound control panel:

You can assign short or long, pleasant or annoying sounds to any event in the list. For example, you could rip a CD to .wav format and assign it to the "Maximize" event.

There are two events that are a little finicky about how long the sound is, though: the "Exit Windows" and "Windows Logoff" events. If you assign a sound that is too long to either of these events, it won't play. It plays when you click the "Test" button, but when you actually log off or shut down, the sound doesn't play.

How long is too long?

Before the answer, a quick review of .wav files.

You can have any number of frames per second. CDs use a sample rate of 44100 frames per second; DVDs use 48000 frames per second. This is usually one of (11025, 22050, 44100, 88200, 176400; 48000, 96000, 19200; 8000, 16000, 32000).

You can have any number of samples in a frame: mono (1 channel), stereo (two channels), surround (four channels), 5.1 (six channels), 7.1 (eight channels), or a different number.

Each sample is a number. This can be a floating-point number (32 bits), an unsigned integer (8 bits), or a signed integer (16 bits, 20 bits, 24 bits, 32 bits.) The 20 bit and 24 bit integers can be either in 24-bit containers or in 32-bit containers.

The fatness of the samples, and how many there are per second, determines how many bytes a second of .wav data will contain. The formula is:

bytes/second = (samples/frame, AKA channels) * (frames/second, AKA sample rate) * (bits/sample) / (bits/byte, always 8)

For performance reasons, Windows Vista limits the size of shutdown/logoff sounds to 4 MB.

So how long is 4MB? Here's the answer in tabular form for most common formats. Lengths are in seconds.

unsigned 8-bit int
sample rate	mono	stereo	surround	5.1	7.1
8000	524.29	262.14	131.07	87.38	65.54
11025	380.44	190.22	95.11	63.41	47.55
16000	262.14	131.07	65.54	43.69	32.77
22050	190.22	95.11	47.55	31.70	23.78
32000	131.07	65.54	32.77	21.85	16.38
44100	95.11	47.55	23.78	15.85	11.89
48000	87.38	43.69	21.85	14.56	10.92
88200	47.55	23.78	11.89	7.93	5.94
96000	43.69	21.85	10.92	7.28	5.46
176400	23.78	11.89	5.94	3.96	2.97
192000	21.85	10.92	5.46	3.64	2.73

signed 16-bit int
sample rate	mono	stereo	surround	5.1	7.1
8000	262.14	131.07	65.54	43.69	32.77
11025	190.22	95.11	47.55	31.70	23.78
16000	131.07	65.54	32.77	21.85	16.38
22050	95.11	47.55	23.78	15.85	11.89
32000	65.54	32.77	16.38	10.92	8.19
44100	47.55	23.78	11.89	7.93	5.94
48000	43.69	21.85	10.92	7.28	5.46
88200	23.78	11.89	5.94	3.96	2.97
96000	21.85	10.92	5.46	3.64	2.73
176400	11.89	5.94	2.97	1.98	1.49
192000	10.92	5.46	2.73	1.82	1.37

24-bit container: signed 20-bit int or signed 24-bit int
sample rate	mono	stereo	surround	5.1	7.1
8000	174.76	87.38	43.69	29.13	21.85
11025	126.81	63.41	31.70	21.14	15.85
16000	87.38	43.69	21.85	14.56	10.92
22050	63.41	31.70	15.85	10.57	7.93
32000	43.69	21.85	10.92	7.28	5.46
44100	31.70	15.85	7.93	5.28	3.96
48000	29.13	14.56	7.28	4.85	3.64
88200	15.85	7.93	3.96	2.64	1.98
96000	14.56	7.28	3.64	2.43	1.82
176400	7.93	3.96	1.98	1.32	0.99
192000	7.28	3.64	1.82	1.21	0.91

32-bit container: signed 20-bit int, signed 24-bit int, or float32
sample rate	mono	stereo	surround	5.1	7.1
8000	131.07	65.54	32.77	21.85	16.38
11025	95.11	47.55	23.78	15.85	11.89
16000	65.54	32.77	16.38	10.92	8.19
22050	47.55	23.78	11.89	7.93	5.94
32000	32.77	16.38	8.19	5.46	4.10
44100	23.78	11.89	5.94	3.96	2.97
48000	21.85	10.92	5.46	3.64	2.73
88200	11.89	5.94	2.97	1.98	1.49
96000	10.92	5.46	2.73	1.82	1.37
176400	5.94	2.97	1.49	0.99	0.74
192000	5.46	2.73	1.37	0.91	0.68

The most common audio format by far is 44.1 kHz / stereo / 16-bit; if your .wav file is of this format, you get just under 23 seconds before you hit the 4 MB limit.

If you want to go over this limit, or if you want a multichannel logoff sound, you can get away with downsampling. If you shoehorn in a longer sound, though, you may run into this:

If you just wait, the sound will play to the end and logoff will continue.

If you click "Cancel", explorer.exe will exit anyway and you'll be logged in with no shell.

A trick to get the shell back: Ctrl-Shift-Esc to bring up Task Manager, and File | New Task (Run...) | explorer.exe to reinvoke the shell. This also allows you to determine which of the notification area icons are well-behaved. :-)

Sample: find out if your default audio playback and audio capture devices are on the same hardware

Maurits — Sat, 14 Jun 2008 02:53:00 GMT

vbBretty on the audio forums asked how to tell if a given audio output and a given audio input were on the same physical audio card.

I found the exercise interesting enough to share here:

// main.cpp

#define INITGUID

#include <windows.h>
#include <tchar.h>

const GUID GUID_NULL = { 0 };

#include <atlstr.h>
#include <mmdeviceapi.h>
#include <devicetopology.h>
#include <functiondiscoverykeys.h>

#define LOG(formatstring, ...) _tprintf(formatstring _T("\n"), __VA_ARGS__)

// helper class to CoInitialize/CoUninitialize
class CCoInitialize {
private:
    HRESULT m_hr;
public:
    CCoInitialize(PVOID pReserved, HRESULT &hr)
        : m_hr(E_UNEXPECTED) { hr = m_hr = CoInitialize(pReserved); }
    ~CCoInitialize() { if (SUCCEEDED(m_hr)) { CoUninitialize(); } }
};

// helper class to CoTaskMemFree
class CCoTaskMemFreeOnExit {
private:
    PVOID m_p;
public:
    CCoTaskMemFreeOnExit(PVOID p) : m_p(p) {}
    ~CCoTaskMemFreeOnExit() { CoTaskMemFree(m_p); }
};

// helper class to PropVariantClear
class CPropVariantClearOnExit {
private:
    PROPVARIANT *m_p;
public:
    CPropVariantClearOnExit(PROPVARIANT *p) : m_p(p) {}
    ~CPropVariantClearOnExit() { PropVariantClear(m_p); }
};

// find the default capture and render audio devices
// determine whether they are on the same audio hardware
int _tmain() {
    HRESULT hr = S_OK;

    // initialize COM
    CCoInitialize ci(NULL, hr);
    if (FAILED(hr)) {
        LOG(_T("CoInitialize failed: hr = 0x%08x"), hr);
        return __LINE__;
    }

    // get enumerator
    CComPtr<IMMDeviceEnumerator> pMMDeviceEnumerator;
    hr = pMMDeviceEnumerator.CoCreateInstance(__uuidof(MMDeviceEnumerator));
    if (FAILED(hr)) {
        LOG(_T("CoCreateInstance(IMMDeviceEnumerator) failed: hr = 0x%08x"), hr);
        return __LINE__;
    }

    // get default render/capture endpoints
    CComPtr<IMMDevice> pRenderEndpoint;
    hr = pMMDeviceEnumerator->GetDefaultAudioEndpoint(eRender, eConsole, &pRenderEndpoint);
    if (FAILED(hr)) {
        LOG(_T("GetDefaultAudioEndpoint(eRender, eConsole) failed: hr = 0x%08x"), hr);
        return __LINE__;
    }
    
    CComPtr<IMMDevice> pCaptureEndpoint;
    hr = pMMDeviceEnumerator->GetDefaultAudioEndpoint(eCapture, eConsole, &pCaptureEndpoint);
    if (FAILED(hr)) {
        LOG(_T("GetDefaultAudioEndpoint(eCapture, eConsole) failed: hr = 0x%08x"), hr);
        return __LINE__;
    }

    // get endpoint device topologies
    CComPtr<IDeviceTopology> pRenderEndpointTopology;
    hr = pRenderEndpoint->Activate(__uuidof(IDeviceTopology), CLSCTX_ALL, NULL, (void**)&pRenderEndpointTopology);
    if (FAILED(hr)) {
        LOG(_T("Render endpoint Activate(IDeviceTopology) failed: hr = 0x%08x"), hr);
        return __LINE__;
    }

    CComPtr<IDeviceTopology> pCaptureEndpointTopology;
    hr = pCaptureEndpoint->Activate(__uuidof(IDeviceTopology), CLSCTX_ALL, NULL, (void**)&pCaptureEndpointTopology);
    if (FAILED(hr)) {
        LOG(_T("Capture endpoint Activate(IDeviceTopology) failed: hr = 0x%08x"), hr);
        return __LINE__;
    }

    // get KS filter device IDs
    LPWSTR szRenderFilterId;
    CComPtr<IConnector> pConnector;
    hr = pRenderEndpointTopology->GetConnector(0, &pConnector);
    if (FAILED(hr)) {
        LOG(_T("Render endpoint topology GetConnector(0) failed: hr = 0x%08x"), hr);
        return __LINE__;
    }

    hr = pConnector->GetDeviceIdConnectedTo(&szRenderFilterId);
    if (FAILED(hr)) {
        LOG(_T("Render connector GetDeviceIdConnectedTo() failed: hr = 0x%08x"), hr);
        return __LINE__;
    }
    CCoTaskMemFreeOnExit freeRender(szRenderFilterId);
    LOG(_T("KS filter ID for render endpoint:\n\t%ls"), szRenderFilterId);

    LPWSTR szCaptureFilterId;
    pConnector = NULL;
    hr = pCaptureEndpointTopology->GetConnector(0, &pConnector);
    if (FAILED(hr)) {
        LOG(_T("Capture endpoint topology GetConnector(0) failed: hr = 0x%08x"), hr);
        return __LINE__;
    }

    hr = pConnector->GetDeviceIdConnectedTo(&szCaptureFilterId);
    if (FAILED(hr)) {
        LOG(_T("Capture connector GetDeviceIdConnectedTo() failed: hr = 0x%08x"), hr);
        return __LINE__;
    }
    CCoTaskMemFreeOnExit freeCapture(szCaptureFilterId);
    LOG(_T("KS filter ID for capture endpoint:\n\t%ls"), szCaptureFilterId);

    // get IMMDevices for each associated devnode
    CComPtr<IMMDevice> pRenderDevnode;
    hr = pMMDeviceEnumerator->GetDevice(szRenderFilterId, &pRenderDevnode);
    if (FAILED(hr)) {
        LOG(_T("Getting render devnode via IMMDeviceEnumerator::GetDevice(\"%ls\") failed: hr = 0x%08x"), szRenderFilterId, hr);
        return __LINE__;
    }
    
    CComPtr<IMMDevice> pCaptureDevnode;
    hr = pMMDeviceEnumerator->GetDevice(szCaptureFilterId, &pCaptureDevnode);
    if (FAILED(hr)) {
        LOG(_T("Getting capture devnode via IMMDeviceEnumerator::GetDevice(\"%ls\") failed: hr = 0x%08x"), szCaptureFilterId, hr);
        return __LINE__;
    }
    LOG(_T(""));

    // open property set on each devnode
    CComPtr<IPropertyStore> pRenderDevnodePropertyStore;
    hr = pRenderDevnode->OpenPropertyStore(STGM_READ, &pRenderDevnodePropertyStore);
    if (FAILED(hr)) {
        LOG(_T("Getting render devnode property store failed: hr = 0x%08x"), hr);
        return __LINE__;
    }

    CComPtr<IPropertyStore> pCaptureDevnodePropertyStore;
    hr = pCaptureDevnode->OpenPropertyStore(STGM_READ, &pCaptureDevnodePropertyStore);
    if (FAILED(hr)) {
        LOG(_T("Getting capture devnode property store failed: hr = 0x%08x"), hr);
        return __LINE__;
    }

    // get PKEY_Device_InstanceId property
    PROPVARIANT varRenderInstanceId; PropVariantInit(&varRenderInstanceId);
    CPropVariantClearOnExit clearRender(&varRenderInstanceId);
    hr = pRenderDevnodePropertyStore->GetValue(PKEY_Device_InstanceId, &varRenderInstanceId);
    if (FAILED(hr)) {
        LOG(_T("Render devnode property store GetValue(PKEY_Device_InstanceId) failed: hr = 0x%08x"), hr);
        return __LINE__;
    }
    if (VT_LPWSTR != varRenderInstanceId.vt) {
        LOG(_T("Render instance id variant type is %u - expected VT_LPWSTR"), varRenderInstanceId.vt);
        return __LINE__;
    }
    LOG(_T("Instance Id of default render device: %ls"), varRenderInstanceId.pwszVal);

    PROPVARIANT varCaptureInstanceId; PropVariantInit(&varCaptureInstanceId);
    CPropVariantClearOnExit clearCapture(&varCaptureInstanceId);
    hr = pCaptureDevnodePropertyStore->GetValue(PKEY_Device_InstanceId, &varCaptureInstanceId);
    if (FAILED(hr)) {
        LOG(_T("Capture devnode property store GetValue(PKEY_Device_InstanceId) failed: hr = 0x%08x"), hr);
        return __LINE__;
    }
    if (VT_LPWSTR != varCaptureInstanceId.vt) {
        LOG(_T("Capture instance id variant type is %u - expected VT_LPWSTR"), varCaptureInstanceId.vt);
        return __LINE__;
    }
    LOG(_T("Instance Id of default capture device: %ls"), varCaptureInstanceId.pwszVal);

    LOG(_T(""));

    // paydirt
    if (0 == _wcsicmp(varRenderInstanceId.pwszVal, varCaptureInstanceId.pwszVal)) {
        LOG(_T("Default render and capture audio endpoints ARE on the same hardware."));
    } else {
        LOG(_T("Default render and capture audio endpoints ARE NOT on the same hardware."));
    }

    return 0;
}

Spot the Bug - IMFOutputSchema

Maurits — Tue, 27 May 2008 19:38:00 GMT

I found a simple but nasty bug the other day in this implementation of the IMFOutputSchema interface.

The symptoms: running this code outside of a debugger caused the app to crash. Running it under a debugger (to catch the crash) caused the app to run clean.

// outputschema.h
HRESULT CreateTrustedAudioDriversOutputSchema(
    DWORD dwConfigData,
    GUID guidOriginatorID,
    IMFOutputSchema **ppMFOutputSchema
);
 
// outputschema.cpp
// ... various include files removed ...
// CMFAttributesImpl implements the IMFAttributes interface, minus the IUnknown methods
class CTrustedAudioDriversOutputSchema : public CMFAttributesImpl<IMFOutputSchema> {

friend
    HRESULT CreateTrustedAudioDriversOutputSchema(
        DWORD dwConfigData,
        GUID guidOriginatorID,
        IMFOutputSchema **ppMFOutputSchema
    );

private:
    CTrustedAudioDriversOutputSchema(DWORD dwConfigData, GUID guidOriginatorID);
    ~CTrustedAudioDriversOutputSchema();

    ULONG m_cRefCount;
    DWORD m_dwConfigData;
    GUID m_guidOriginatorID;
    
public:
    // IUnknown methods
    HRESULT STDMETHODCALLTYPE QueryInterface(
       /* [in] */ REFIID riid,
       /* [out] */ LPVOID *ppvObject
    );
    ULONG STDMETHODCALLTYPE AddRef();
    ULONG STDMETHODCALLTYPE Release();

    // IMFOutputSchema methods
    HRESULT STDMETHODCALLTYPE GetConfigurationData(__out DWORD *pdwVal);
    HRESULT STDMETHODCALLTYPE GetOriginatorID(__out GUID *pguidOriginatorID);
    HRESULT STDMETHODCALLTYPE GetSchemaType(__out GUID *pguidSchemaType);

}; // CTrustedAudioDriversOutputSchema

HRESULT CreateTrustedAudioDriversOutputSchema(
    DWORD dwConfigData,
    GUID guidOriginatorID,
    IMFOutputSchema **ppMFOutputSchema
) {
    if (NULL == ppMFOutputSchema) {
        return E_POINTER;
    }

    *ppMFOutputSchema = NULL;

    CTrustedAudioDriversOutputSchema *pSchema =
        new CTrustedAudioDriversOutputSchema(dwConfigData, guidOriginatorID);

    if (NULL == pSchema) {
        LOG(eError, _T("new CTrustedAudioDriversOutputSchema returned a NULL pointer"));
        return E_OUTOFMEMORY;
    }

    *ppMFOutputSchema = static_cast<IMFOutputSchema *>(pSchema);

    return S_OK;
} // CreateTrustedAudioDriversOutputSchema

// constructor
CTrustedAudioDriversOutputSchema::CTrustedAudioDriversOutputSchema(
    DWORD dwConfigData, GUID guidOriginatorID
)
: m_dwConfigData(dwConfigData)
, m_guidOriginatorID(guidOriginatorID)
{}

// destructor
CTrustedAudioDriversOutputSchema::~CTrustedAudioDriversOutputSchema() {}

#define RETURN_INTERFACE(T, iid, ppOut) \
    if (IsEqualIID(__uuidof(T), (iid))) { \
        this->AddRef(); \
        *(ppOut) = static_cast<T *>(this); \
        return S_OK; \
    } else {} (void)0

// IUnknown::QueryInterface
HRESULT STDMETHODCALLTYPE
    CTrustedAudioDriversOutputSchema::QueryInterface(
        /* [in] */ REFIID riid,
        /* [out] */ LPVOID *ppvObject
) {

    if (NULL == ppvObject) {
        return E_POINTER;
    }

    *ppvObject = NULL;

    RETURN_INTERFACE(IUnknown, riid, ppvObject);
    RETURN_INTERFACE(IMFAttributes, riid, ppvObject);
    RETURN_INTERFACE(IMFOutputSchema, riid, ppvObject);

    return E_NOINTERFACE;
}

// IUnknown::AddRef
ULONG STDMETHODCALLTYPE
    CTrustedAudioDriversOutputSchema::AddRef() {

    ULONG uNewRefCount = InterlockedIncrement(&m_cRefCount);

    return uNewRefCount;
}

// IUnknown::Release
ULONG STDMETHODCALLTYPE
    CTrustedAudioDriversOutputSchema::Release() {

    ULONG uNewRefCount = InterlockedDecrement(&m_cRefCount);

    if (0 == uNewRefCount) {
        delete this;
    }

    return uNewRefCount;
}

// IMFOutputSchema::GetConfigurationData
HRESULT STDMETHODCALLTYPE
    CTrustedAudioDriversOutputSchema::GetConfigurationData(__out DWORD *pdwVal) {

    LOG(eInfo1, _T("IMFOutputSchema::GetConfigurationData called"));

    if (NULL == pdwVal) { return E_POINTER; }

    *pdwVal = m_dwConfigData;
    
    return S_OK;
}

// IMFOutputSchema::GetOriginatorID
HRESULT STDMETHODCALLTYPE
    CTrustedAudioDriversOutputSchema::GetOriginatorID(__out GUID *pguidOriginatorID) {

    LOG(eInfo1, _T("IMFOutputSchema::GetOriginatorID called"));

    if (NULL == pguidOriginatorID) { return E_POINTER; }

    *pguidOriginatorID = m_guidOriginatorID;
    
    return S_OK;
}

// IMFOutputSchema::GetSchemaType
HRESULT STDMETHODCALLTYPE
    CTrustedAudioDriversOutputSchema::GetSchemaType(__out GUID *pguidSchemaType) {

    LOG(eInfo1, _T("IMFOutputSchema::GetSchemaType called"));

    if (NULL == pguidSchemaType) { return E_POINTER; }

    *pguidSchemaType = MFPROTECTION_TRUSTEDAUDIODRIVERS;
    
    return S_OK;
}

Generating a sine wave with phase - answers

Maurits — Mon, 31 Mar 2008 23:56:00 GMT

In a previous post I posed several mathematical problems... I'd like to go back and give some answers to them.

To reiterate, we take a sine wave period and wrap it around a cylinder, giving us this:

The problems are to:

Prove that the curve is planar.
Prove that the curve is an ellipse.
Make a Keplerian observation. Johannes Kepler was a mathematician/astronomer who made several observations relating to planetary orbits.

Let's define the curve. Since we're going to be making analogies to planetary orbit, let's define the curve parametrically. The parametric point is the analog of a planet.

Peter piper picked a peck of pickled peppers. -- Mother Goose

Penny Pingleton, you know you are punished. From now on you're wearing a giant P on your blouse EVERY DAY to school so that the whole world knows that Penny Pingleton is permanently, positively, punished.
-- Prudence Pingleton, Hairspray

OK, now that we have that out of the way... I want the parametric point to sweep its way around the unit cylinder with constant angular velocity, as viewed from above. So if we project the path of the point into the unit cylinder with z = 0, then r(t) = 1 for all t and θ(t) is linear in t. In fact let's have θ(t) be t, so at time t = 2π our parametric point has made a complete cycle.

Now we'll add the z component in. The curve is a wrapping of sin(t), so z = sin(t); we aren't affecting the vertical component of the paper by wrapping it horizontally around a cylinder.

We're actually, in a sense, done. We have the formalized equations:

r(t) = 1
θ(t) = t
z(t) = sin(t)

But let's convert to Cartesian coordinates, since we'll be dealing with planes. The relevant formulae are:

x² + y² = r²
tan(θ) = y/x

A little intuition, checked by back-substitution, gives us these for x and y:

x(t) = cos(t)
y(t) = sin(t)

Putting these together with our formula for z, we have:

x(t) = cos(t)
y(t) = sin(t)
z(t) = sin(t)

Note that, no matter what t is, y(t) = z(t)... that is, the parametric point travels entirely in the plane given by the equation y = z. This proves that the parametric path is planar. QED #1.

To tackle #2 we have to prove that this planar curve is, in fact, an ellipse. One way to do that would be to come up with x' and y' coordinates in the plane of the curve, transform the parametric equations into the new coordinate system, and verify that a(x')² + b(y')² = c² for some a, b, and c... but when I came up with the problem I had a much simpler proof in mind. There's also a third way of doing this, where you note that the curve is the result of an affine transformation of the unit circle... and an affine transformation of a circle is demonstratably an ellipse... but I hadn't thought of that.

Another astronomer/mathematician, Appollonius of Perga, made a study of "conic sections"... that is, the intersection of a plane with a double-headed cone. He came up with an exhaustive list of the kinds of curves that resulted.

Basic conic sections:

An ellipse, if the angle that the plane makes is shallower than the edge of the cone;
A hyperbola, if the angle that the plane makes is steeper than the edge of the cone;
And a parabola, if the plane is parallel to the edge of the cone.

For complicated reasons (to wit, that gravity diminishes as the square of the distance between two objects,) all heavenly bodies trace either an ellipse or a hyperbola as they go around (or past) another heavenly body.
Parabolae are theoretically possible but would smack heavily of "design"; as yet none have been observed.

For completeness, there are other "designed" ways to intersect a double-headed cone with a plane in a coincidental fashion:

Degenerate conic sections:

A circle - early astronomers were convinced that the heavenly bodies moved only in circles. It took a long time for us to believe our measurements (which showed uncircular orbits) and acknowledge that the orbits are in fact elliptical. Instead, great efforts were made to show that the deviation could be made up of other, smaller, circular sub-orbits. Eventually we admitted that the orbits were elliptical (ellipses are more complicated than circles, but much simpler than the proposed circles-within-circles) and not until Newton did we understand why planets move in ellipses.
A straight line - this is a degenerate hyperbola. This is one solution to the "one body" problem.
Two intersecting straight lines - a hyperbola, as seen from infinitely far off.
A single point - the other solution to the "one body" problem.

Since our curve is the intersection of a plane and a cylinder, we're done! ~~QED #2~~. Well, not quite.

Appolonius' results hold for cones. We have a cylinder. Those aren't quite the same thing. Right?

They aren't, quite... but a cylinder can be viewed as a degenerate form of cone. To wit, a cylinder is a cone whose apex is infinitely far off. I'll get back to a "proof" of this in a minute, but if you allow this, then we really are done.

Instead of the seven intersections of a double-headed cone and a plane, there are only four ways a cylinder and a plane can intersect. Two of these are new.

Cylindrical conics:

An ellipse - though it remains to be proven that this really is an ellipse. A circle is a special form of this... I won't show it again.
A straight line - the single body problem again.
Two straight lines - parallel this time. This is something new.
No intersection at all. The kōan of conics. This is new, but whether it is something is a question I will not attempt to address.

Now for the proof that cylindrical intersection #1 really is an ellipse. Place two double-headed cones coaxially with the cylinder. Arrange them so that:

The apexes of both cones are in the "up" direction, from anywhere on the curve in question.
The "top" cone intersects the highest point on the curve in question.
The "bottom" cone intersects the lowest point on the curve in question.

Diagram:

Notice that the entire curve lies in between the two cones. Consider the intersection of the plane that determines the curve with each of the cones. We know both of these are ellipses; we know that the intersection of the plane with the "upper" cone lies wholly outside our unknown curve; and we know that the intersection of the plane with the "inner" cone lies wholly inside our unknown curve.

Diagram:

The final stage of the proof lies in pushing the apexes of both cones to infinity, which "squeezes" our unknown curve in between two known ellipses. Since the horizontal distance between the cones goes to zero as 2^3/2 / tan(θ), our unknown curve cannot help but be elliptical-ish... to any degree of precision... and it is, thus, an ellipse. QED #2.

For the final problem, we must make a "Keplerian observation." The observation in question is that our parametric point, like the planets, sweeps out equal areas in equal times. What makes this interesting is that the parametric point does not move in the same way that a planet does... so it's a little odd that such a similar result should hold... but it does.

Let's talk a little about Kepler's second law. A planet moves around the sun in an elliptical orbit. Fine. The sun lies at one of the foci of the ellipse. An imaginary line between the planet and the sun will sweep out area at a constant rate. That is to say, when the planet is far from the sun, that line will be long... and it will move correspondingly slowly. When the planet is near to the sun, that line will be short... and it will move correspondingly quickly.

Conversely, our parametric point sweeps around the origin at constant angular velocity. So this is trivially "equal areas in equal times". Right?

Not quite. It's true that our parametric point appears to have constant angular velocity, if you project its path into the x-y plane... that is, if you view it from directly above, from a point on the z-axis.

But that's a silly way to look at things. To get an idea of the point's actual motion, it's far more natural to view it from an axis orthogonal to the plane of motion. So let's put an observer (Aranea) directly above the point, and another observer (Nellie) in the more natural location.

From Aranea's point of view, the motion is a simple constant-speed trip around a circle. But Nellie sees the parametric point's true velocity. The parametric point's velocity has two components... a constant "clockwise" component in the x-y plane, and a variable orthogonal component going "up" or "down". This is maximized when the curve crosses the x-y plane, and minimized when the curve is topping or bottoming out. So Nellie sees this:

It seems hard to believe, given that the parametric point is speeding up and slowing down according to different rules... and the notion of "center" is different... but the fact is, the parametric point also sweeps out equal areas in equal times!

To see this most easily, look at Aranea's point of view again. Have Aranea draw a grid on her picture of the system. She can count the area swept out in any given time by counting the number of squares.

Now consider what those squares look like to Nellie. They're rectangles. But they're all of equal area. Aranea and Nellie can label the squares according to some naming scheme, and will agree that the same set of squares/rectangles were swept out... but this means, since the rectangles are of equal area, that even in Nellie's point of view, equal areas are swept out in equal times! QED #3.

Generating a sine wave with phase

Maurits — Fri, 18 Jan 2008 22:18:00 GMT

I alluded to a bug in my last post but didn't explicitly say what it was. Hint: it's all about phase.

So let's talk about phase for a minute. Sine waves are periodic... although they are frequently plotted over very large intervals, their natural domain is a single period.

(original)

Exercise - The original version, when printed, makes a nice armband.

Advanced Exercise - generate a one-and-a-half period sine wave, print it on both sides of a piece of paper, and make a Möbius strip.

Well, that's a step, but it's not really getting at the nature of the sine wave. Yes, we notice that the beginning value (0) is the same as the ending value... and the beginning slope (+1) is the same as the ending slope... and there is, perhaps, a certain smoothness beyond even slope (in fact, all derivatives agree at the crossover point...)

If you see a fact, try to see it as intuitively as possible.

Do the first exercise above - print out the original image, cut it out along the lines, and make a cylinder by connecting the short ends together. Rotate the cylinder through various orientations, paying particular attention to the location of the sine wave at all times.

What you get is hard to render in a two-dimensional blog post, but here's a stab at it (Matlab script below:)

(original)

Notice that this representation of the sine wave is an ellipse.

Exercise - Prove that the red line in the above graph is planar (Hint: you can type the equation of the plane in three keystrokes.)

Advanced Exercise - Prove that it's an ellipse.

Advanced Exercise - Make a Keplerian observation. (Hint: note the angles at which the red line crosses the dotted black lines.)

So what does this have to do with phase?

Everything.

There's another hint in the documentation of double sin(double), which I also linked in my last post:

sin returns the sine of x [phase]. If x [phase] is greater than or equal to 263, or less than or equal to –263, a loss of significance in the result occurs. (my emphasis)

A final hint: again from my last post, "as a side effect, we get a kinda-sorta implementation of ϕ [phase]."

When you find yourself with a kinda-sorta implementation of something, that is occasionally a hint from above that your life will be easier if you do some self-examination... perhaps a full-blown implementation of that thing will be (a) easier and (b) more what you actually want.

No more hints. If you want to figure it out for yourself, stop reading now.

OK, here's the scoop. The thing you feed to sin(...) is a radian measurement. This is naturally between 0 and 2π (or, perhaps, -π to π if you prefer.) You can feed it things that are out of this range... say, sin(100.0)... but this is a little out of the natural and there are consequences.

double-type numbers, and floating point numbers in general, can represent very small numbers to a very high degree of precision... and they can represent very large numbers with the same relative degree of precision. See IEEE754 for gory details.

An illustration is in order. Richard Feynman, celebrity physicist, tells a story of his youth. He claimed to be able to solve, in one minute, to within 10% accuracy, any problem that can be stated in ten seconds.

He did pretty well until someone came up with "tan(10¹⁰⁰)".

If you feed bigger and bigger numbers to sin(...), eventually it starts giving you sloppy answers. It has to. It's not getting enough information to give you a good answer.

I was able to test the tone generation function and measure the signal-to-noise ratio of the tones it was producing after varying lengths of sample time. It started off very well, but after very long times (days, weeks, years) the SNR would get slowly compromised until, after millions of years, the signal disappeared.

That is not the bug.

But it is a serious clue to the bug.

If the worst-case scenario for an implementation is that the signal will depreciate over a million years, ship it.

Take your cylinder that you made above. Place it in front of you so that the taped-together part is directly in front of your nose, and the part to the right has the red line going up. This is a sine wave.

Rotate it clockwise 90 degrees, so the part in front of your nose has the red line brushing the top. Now it is a cosine wave.

Rotate it counter-clockwise 60 degrees, so the part in front of your nose has the red line crossing the dotted line. Now it is a sine wave with a known phase (30 degrees.)

In fact, rotate it any angle (say, ϕ) and it's a sine wave with known phase ϕ.

We can't do that with our tone generator.

That is the bug. We're implementing a tweaked version of phase which has a forgivable side effect, but which is not a full implementation of phase.

Why do we care about implementing phase?

Well, for example, one problem I sometimes have when testing audio fidelity is I connect the stereo cables to the Audio Precision equipment the wrong way (left-to-right and right-to-left.) If I could generate the test tones out of phase by 90 degrees, with the left channel in front of the right channel, I could take a phase measurement and log a "you have the cables backwards" error. I send different frequencies over the cables, so the ifFrameOffset parameter is of little use here.

So what's the improved implementation?

Instead of

// given a buffer, fills it with sine wave data
HRESULT FillBufferWithSine(
    LPCWAVEFORMATEX pWfx, // includes sample rate
    double lfAmplitude,
    double lfFrequency,
    UINT64 ifFrameOffset,
    PBYTE pBuffer,
    UINT32 cbBytes
);

// given a buffer, fills it with sine wave data
HRESULT 
FillBufferWithSine(
    LPCWAVEFORMATEX pWfx, // includes sample rate
    double lfAmplitude,
    double lfFrequency,

    // in/out
    //     On input, initial phase (0 to 2pi).
    //     On output, phase of next sample.

    double *plfPhase,

    PBYTE pBuffer, // out - byte count is cbBytes
    UINT32 cbBytes
);

Now, if you want to generate a lot of contiguous sine tone buffers, you do something like this:

double lfPhase = 0.0; // start at 0... or somewhere else
while (...) {
    // ... 
    // FillBufferWithSine takes care of updating lfPhase as necessary 
    hr = FillBufferWithSine(pWfx, lfAmp, lfFreq, &lfPhase, pBuffer, cbBytes);
    // ... 
}

As a side effect of this new phase feature, the quality degradation non-issue goes away. So the generated tones will sound good forever... which is kind of neat... but not the motivation for this fix.

Why did this happen?

Because there are many ways to measure time. You can count samples... you can count milliseconds... you can count hundred-nanosecond intervals... you can count CPU flops... you can do so many different things. Some are more natural than others in different contexts.

The reason this happened is because a time measure that was very natural in one context (counting frames: playing an audio stream) was somewhat artificially shoved into another context (generating a sine wave) where there was another, more natural context (changing phase.) Alas, context switching is a frequent source of bugs.

Matlab script to generate the three-dimensional rendering of a sine wave:

t = 0:pi/50:2*pi;
h = -1:0.5:1;
z = ones(size(t))' * h;

sinx = cos(t);
siny = sin(t);
sinz = sin(t);

plot3( ...
    sinx, siny, z, 'k:', ...
    sinx, siny, sinz, 'r' ...
);