The Audio Fool : Programming

You can't hear DC

RyanBemrose — Thu, 21 Jun 2007 20:00:58 GMT

Recently one of my team members found a bug in some old code while doing a code review. Our application was generating a sine wave to be rendered by the audio hardware. The sample format isn't important except to note that it is an unsigned value between 0 and MAX = 2*FS_AMP. The bug is in the following code.

void GenerateSineWave(float buffer[], float frequency, float amplitude) {
    // frequency in Hz, amplitude in range(0.0, 1.0)
    float w = 2 * PI * frequency / SAMPLE_RATE;
    for (int t = 0; t < NUMBER_OF_SAMPLES; t++)
        float sample = sin(w * t) * FS_AMP // full scale sine wave
        sample += FS_AMP; // Move into positive range
        sample *= amplitude; // Scale to requested amplitude
        buffer[t] = sample;
    }
}

So do you see the bug? After this code, we have a sine wave that oscillates between 0 and 2*amplitude*FS_AMP. For amplitude = 1.0, this is exactly what we want, but for any smaller amplitude, the wave is low-justified in the sample range.

What we really wanted here is a signal that is center-justified in the range, such as below. We were sending the wrong samples!

The fix is fairly simple. We want to scale (*= amplitude) before we translate (+= FS_AMP). Then we get a sine wave that oscillates between (FS_AMP *(1-amplitude)) and (FS_AMP * (1+amplitude)).

After fixing a bug in old code, the next question we have to ask ourselves is why we missed it. How come this bug wasn't found in a test pass when it was written, or any time in between? The answer is almost as subtle as the code that caused the problem. From an audio perspective, the bug had no impact at all.

The buffer generated by this buggy code was sent directly to the DAC on the hardware. The signal does not clip, and it's not distorted. All of the sine components are the same. If you got an FFT on each of the two sine waves above, they would differ only in the very first bin, the one corresponding to the DC component of the signal.

But you can't hear DC.

DC is essentially the baseline for a signal. The value from which the signal wave deviates in time. The measured level of silence. For a speaker, the DC level is the distance of the cone when unplugged. For the atmosphere, DC is about 14psi (or 1.0 atm) at sea level.

For a digital signal stored as numbers, DC can be any arbitrary value. In a computer which have a fixed minimum and maximum, we usually choose halfway between min and max because it offers the most dynamic range. This also explains why most audio formats use signed numbers for samples rather than unsigned. The center of the allowed range for a signed number is zero, and zero is a very easy number to work with. In the code snippet above, the bug would not manifest if we were using signed numbers, because the translation step for signed numbers is a no-op.

One other way of looking at DC is as a wave with frequency zero, and an infinite wavelength. Since zero is below the lowest frequency a human can hear (about 20Hz), you can't hear it. Q.E.D.

Epilogue: This bug does show up as a frequency component any time we dynamically alter the amplitude while streaming, so we fixed it.

The Rules of Code Optimization

RyanBemrose — Thu, 14 Jun 2007 20:56:00 GMT

Steve Rowe recently talks about who you're really writing for when you write code. The argument he makes is essentially that your primary audience is not the compiler, but rather your primary audience is other developers. This is something I believe strongly.

Steve also makes a point about premature optimization, and how it affects readability. This reminded me of a list of the Rules of Optimization that I try to live by:

The First Rule of Code Optimization: Don't.

Optimizing code has a negative effect on readability and maintainability. The vast majority of code doesn't need to run particularly fast, but it all needs to be maintainable. Even programs you think are one-off and temporary have a tendency to become permanent.

Most businesses want to keep costs down, but as a rule, hardware is cheap. Developer time is expensive. Don't optimize for the wrong variable.

If you believe that the First Rule doesn't apply to you, (by the way, you're probably wrong. Go read the first rule again) then it's time to consider the second rule.

The Second Rule of Code Optimization: Don't yet.

Designing code and optimizing code are two very different operations. Your maintenance programmers will thank you not to mix the two. For both optimizing and maintaining code, it is far easier to start from a good solid readable design, than to start from code that was "written optimized". (and that's assuming you can even figure out what the latter was doing). Do not optimize code as you write it, unless you like rewriting over and over.

The Third Rule of Code Optimization: Profile first.

Optimizing all of the code is almost never feasible, and is never worth it. It you're going to spend three developer days to squeeze 10 milliseconds of performance out of your code, it's probably better that you get those out of the inner loop of a column lookup, rather than the startup splash screen display code.

So which code is best to optimize? You don't know. You can generally make educated guesses, but there's your problem. They're just guesses. If you guess wrong (your first guess is almost always wrong), then you'll end up doing more harm than good by optimizing (remember the maintainability hit). So how do you know? Profile. Run tools that will tell you which code is spending most of the time. Optimize that code. Often, you'll find an answer you never expected.

Never optimize without profiling first.

Code optimization is sometimes a necessary evil, but do not forget that it is an evil. It obfuscates the true meaning of the code, and it takes developer time that could be spent on bug fixing or new features. Some applications (such as real-time audio) can't get by without optimizing, but most applications (card games, mail programs, web apps, etc) can get along just fine without unnecessarily complicating the code. And when you do need to optimize, have hard data to back up that you're optimizing the right place.

My program is the most important thing on your system, same as all the others.

RyanBemrose — Thu, 21 Dec 2006 00:22:41 GMT

Raymond had a really good post yesterday about programs that grab your attention inappropriately. I recommend reading it. The comments have some good examples of programs, mostly updaters, that take too many liberties. Of course, I completely agree that popping something up in my face completely unrelated to the task I'm performing is among the most annoying things that a computer can do.

So I was reading Raymond's post and nodding to myself over the idea that programs shouldn't be so intrusive. About halfway through, an update dialog popped up on top of the paragraph I was reading. This dialog informed me that Firefox 1.5.0.9 is available to install, and asked me if I'd like to restart Firefox in order to install it. No thanks, I'm kinda busy reading about annoying software. So I click the 'Later' button (Note that updaters in general never give the 'No and stop bothering me' option anymore - I guess too many people clicked it), and am told that I can continue and the update will be applied the next time I restart Firefox. That seems reasonable. So reasonable, in fact, that I wonder why didn't the updater just do that, instead of interrupting my task?

Ah, some coincidences are just too ironic not to write about.

Feature request for the compiler team

RyanBemrose — Sat, 09 Dec 2006 00:08:22 GMT

I want to preface this by saying that the MS compiler team have worked wonders in improving developer productivity over the years, and can't be thanked enough for turning the C++ language into an enterprise quality platform that has lasted more than a decade.

That said, "C2259: 'CFoo' : cannot instantiate abstract class" is probably one of the least useful of the compiler errors. This error occurs on a line where I am trying to instantiate a CFoo object, and the compiler has determined that CFoo is an abstract class. The problem is that most of the time CFoo isn't supposed to be an abstract class. I'm trying to instantiate it, so chances are good that, semantically, I don't intend CFoo to be an abstract class. The compiler, however, has determined that there is some pure virtual function that isn't overridden, and therefore the class is abstract and cannot be instantiated.

The reason this is a problem is that, in most cases, the bug is not that I'm trying to instantiate the class. The bug is that CFoo hasn't overridden a pure virtual function that needs to be overridden so that CFoo is not abstract. The compiler does a good job of flagging down that there's an error, but it's unhelpful because in most cases, it's flagging down the wrong error.

So what? The compiler can't be expected to discern programmer intent. That's why programmers make the big bucks, right? Lots of error codes are cryptic so why single this one out? Because it's fixable. It's not an unknowable problem. It's just an oversight is all. The answer isn't even technically difficult from a compiler's POV. The compiler has already determined that my class is abstract. It should be easy from there to tell me why the compiler thinks my class is abstract.

C2259: 'CFoo' : cannot instantiate abstract class. CFooBase::Bar(int, void*, const char*) is not overridden.

Honesty as a code metric

RyanBemrose — Fri, 03 Nov 2006 06:00:19 GMT

Of all of the programmers I've worked with over the years, I can name three who really stick out as the best. These people have earned my respect, and I will always listen to their opinions, even when I think they're completely off their rockers. I currently have the honor of working with two of those here at Microsoft. The third one I still keep contact with through his blog. Dave Brady is currently VP of tech at a small Salt Lake City firm, and has a unique insight gained by watching junior coders mature into senior programmers.

Recently, Dave posted an essay entitled Dishonest Programming. The gist of it is something that you'll find in any good coding guide - make sure your identifiers are correct, minimize side-effects, and the like. But I had never really considered "code honesty" as a metric for judging the quality of a piece of code. It's a good read if you're concerned about making sure your code is maintainable. And you should be.

If you assume your users are criminals, they will be.

RyanBemrose — Thu, 26 Oct 2006 07:32:00 GMT

A friend recently purchased for me a copy of a game, let's call it "Society III", that he knew I'd like. I had been an avid player of Society and Society II, and Amazon was having a $9.95 special. The game arrived in a standard manufacturer box, with a stamped official-looking CD. It's a legit copy.

Because the game is about two years old by now, there have been a couple of patches. Such is the way of the software lifecycle in the internet age. After installing the game and playing around for a short while, I dutifully went to the publisher's website and downloaded the latest patch. After installing the patch, however, I was no longer able to play the game. Upon launching, I would get a dialog which asked me to "Please insert the Society III CD into drive C:".

Huh?

Somehow, after the patch, the game has become confused about which drive is the CD-ROM. Obviously, I can't put the disc into drive C:. So I start poking around the config files. Maybe there's a .ini that got corrupted or a registry entry. I do find a line in society3.ini which lists the install drive, but changing that has no effect. I am unable to convince the game to let me play without inserting a CD into my C: drive.

Now, it turns out, as with most games, that the only reason for the CD at all is to verify that you actually have the original game. No other reason. For performance, the whole game has been copied to the hard drive. As with most games out there, once the game finishes the CD check, the drive goes silent, and I can even safely pop the disc out without affecting game play. So my next course of action is where things get a bit underhanded. I head out to my friendly neighborhood warez website (with my browser security set to maximum, of course), and find a crack for the game which removes the CD check entirely. Just drop in the new, patched .exe, and what do you know, I can play from my hard disk without ever inserting the CD.

So what did we learn from this exercise? Well, first of all, that copy protection software can have bugs too. But unlike innocent glitches, when your software's self-destruct button malfunctions, your UX suffers and users get alienated. My copy of Society III is legitimate, but to use my legitimate copy, I had to resort to shady methods which probably violate the EULA. This game's copy protection software starts from the implicit assumption that the user is a criminal and must be stopped. In this case, thanks to a bug in the software, it turned the user into one.

Interface Design and the Law of Leaky Abstractions

RyanBemrose — Fri, 29 Sep 2006 21:38:00 GMT

Programmers are always trying to make things simpler, usually by making them more complex. Interface too complicated? Need a bit of extra functionality? Want to work closer to the problem? Add a layer of abstraction to the code. As most programmers know, this is, ironically, usually the right solution. Abstraction is critical to breaking a problem down into managable chunks. Of course, as a friend of mine once said, in programming every problem can be solved by adding another layer of abstraction, except for the problem of too much abstraction.

Joel Spolsky once made an important observation about abstractions, which he dubbed the Law of Leaky Abstractions. As he explains, an abstraction has leaked when a user of the abstraction needs information, data, or knowledge of the underlying implementation or interface. And Spolsky's observation is an inconveniently true one.

The Law of Leaky Abstractions: Every non-trivial abstraction leaks.

So what does this mean if you're designing an interface? You've got some kind of lower-level functionality that you're exposing, so that consumers for your interface can use the functionality of your much simpler interface without regard to the ugly details of the underlying interface. Your new abstraction is so good that nobody will want to use the underlying stuff anymore. In fact, you're so confident in your new interface that you don't need to expose the old one, right? Wrong. Your abstraction will leak. No matter how careful you are in creating the abstraction, there will be a scenario where users of your interface will need knowledge of the underlying implementation or access to the underlying functionality. Your abstraction didn't fail. It just leaked. But if you've hidden the underlying functionality, then you've just disabled every scenario in which a leak occurred.

Corollary to the Law of Leaky Abstractions: An abstraction should not hide or disable that which it abstracts.

This applies to wizards, COM interfaces, API functions, communication protocols, and all other abstractions. I worked on an IRC bot a while back which could take third-party plugins. We abstracted away the IRC protocol into an object-oriented interface that would track channel state information locally and present modes and information through accessors in the interface. We implemented channel.IsModerated to wrap mode 'm', channel.IsTopicLocked to wrap mode 't', and so on with all of the standard modes. We couldn't think of any reason to need the IRC protocol directly, so we didn't expose it.

One network, however, had implemented a custom mode 'U' to block URLs in channel. Obviously we hadn't include an accessor to this mode (we weren't psychic), so our abstraction leaked, and our bot's plugins couldn't use this new mode. The solution was not to add a channel.IsBlockingURLs accessor to our class. That would lead to interface bloat (and a waste of our time) as we have to add a new accessor for each custom one-off mode or protocol extension. No, the solution was to enable plugins to program through our interface and write directly to the protocol, which we did in our next release.

The Law of Leaky Abstractions says that you can never completely abstract away the whole protocol/interface/function/etc. So don't try. Abstractions are still very useful. They make things easier for the 80% case and improve efficiency. But when designing your abstraction, be careful that you don't also disable the 20% case in the process.

The Dancing Bunnies problem and the need for application-level security

RyanBemrose — Sat, 19 Aug 2006 01:59:52 GMT

Raymond today has a discussion up about the folly of trying to set security with a granularity of per-DLL. As he explains, the moment you let something untrusted run in your process space, you cannot trust anything in the process. You cannot wall off a DLL or a section of code from the rest of the process. "That's why code is not a security principal," he concludes.

But you can wall off a process. There is an ACL associated with each running process (via its user context), so you can restrict what code can do depending on its process. More on that in a moment.

The other point Raymond drives home is that, to the system, there is no difference between the application and the user. Put another way, When an application has the credentials of a user and attempts to perform an operation, there is no good way for the system to know whether the app asked the user before performing it. Therefore, the only effective way to limit what an application can do is reduce its process ACL when the application is launched, and then limit what it can do based on that.

So consider this in the context of the Dancing Bunnies problem. There is a website which will let me download an executable to watch dancing bunnies. Conventional security wisdom says that the only way to be secure is to not download the executable. This is obviously the most secure choice, from a technical standpoint, but the technical standpoint goes on its ear when you add a user to the equation. Conventional security wisdom doesn't let me see my dancing bunnies, so I'm going to download it anyway. When I run the executable, it takes on my user token, and suddenly the website's code has the full ability to do anything to my system that I can do -- and if I'm on a pre-Vista OS, that means admin access. What's worse, it probably won't even bother to ask whether I want my system owned. The nerve!

So somehow we lost the most secure option (not downloading the exe) because it wasn't acceptible to the user -- I couldn't see my dancing bunnies. Without that most secure option, the only one left is the least secure (system owned). What I think we need is another status for the app. I want an execution option that says "I want to see my dancing bunnies, but I don't want my system owned". UAC on Vista does a very good job of preventing the system owned result, but a malicious program can still do a lot of damage. Even better is the "low" security context that IE7 runs in by default on Vista, which can only access certain directories and APIs. This mode is effectively the application-level security that I spoke of earlier.

What I'd like to see, as a partial answer to the Dancing Bunnies problem, is the ability to download and save an app from the internet, and have that app marked as "untrusted". When I launch the app, it launches in some sort of sandbox similar to the "low" security mode with restricted process permissions. If it's coded correctly then it shows me my dancing bunnies. If it's malicious, then I haven't lost anything. This is something that users will buy into.

Of course, we still have the social engineering problem of exes that tell the user they can only see dancing bunnies after they click away that nagging UAC prompt. The way to fix that is to convince them that Microsoft is more trustworthy than Ye Olde Maliciouse Website. When I come up with the solution to that one, I'll let you know.