“Volume control” is a single bullet point in the feature list for the upcoming Boxer 1.2.3, but I thought it would be interesting (read “validating”) to give a behind-the-scenes tour of what actually goes into a simple feature like this.
First things first is deciding the scope of the feature. I chose early on to make the volume control apply application-wide to every game, rather than tracking it for each individual game, so that its behaviour would be consistent and predictable. The use case I targeted was one I faced daily: muting Boxer to listen to other music or videos in the background.
I chose not to target a more sophisticated use case: tweaking the volume of a specific game, such as one with annoying beeper-speaker effects or really loud MIDI music. I felt this was too complex for a single volume control.
Instead I made plans to add a separate mixer panel later, which would let you tweak the volume of each individual “channel”: PC speaker, digital audio, MIDI and CD audio and so on. The volumes you’ve set for individual channels would be remembered for each game, and scaled by the application’s master volume. But that will have to wait for a future release.
Now I'm ready to start on the physical volume control UI that the user manipulates.
I decided to add a slider to the DOS window's status bar, so it would be obvious and immediately accessible. I made the speaker icons at either end of the slider minimize/maximize the volume when clicked, like they do in iTunes. (And because the volume control is sharing space with the “Click to lock the mouse” help text, I also had to make sure the latter is hidden at small window sizes so they won’t overlap.)
But wait: OS X’s standard slider widget was designed for pale backgrounds, and looks dumb against the darker status bar area. We need a custom slider widget that’s restyled to fit. Good thing I had some custom widget code already for the Inspector panel sliders; unfortunately it needed a lot of rework before it was suitable.
Wait, what if the user is in fullscreen or has the status bar hidden? They won’t be able to access the control. So I added a “Sound” menu containing its own slider, which can be accessed from anywhere. The menu also lets me expose keyboard shortcuts with which the user can nudge the volume up or down.
Because the user can nudge the volume with those shortcuts while no volume slider is visible, we need some way to give them feedback that something has happened. Time for a new notification bezel! (Though we should only show the bezel if the volume slider isn't already visible, otherwise it’s redundant: so check for that too.)
I wanted the bezel to show a speaker that changes according to the current volume, so I snapped screenshots of OS X's menubar volume icon in each of its states and recreated them as vector versions in Photoshop.
So now the UI for our volume control is pretty much ready, but it doesn't actually do anything yet. Time to hit the emulation layer.
First, we need to control the volume of the DOSBox mixer: this component mixes together all of the audio produced by the emulated PC speaker, Sound Blaster etc. This means injecting some more code into DOSBox so that Boxer can dictate the master volume.
But General MIDI output doesn’t pass through the DOSBox mixer: it goes straight to OS X’s CoreAudio MIDI synth. Time to dust off my CoreAudio documentation and figure out how to manipulate the volume on audio units.
If we’re sending MIDI music to a real MIDI device, like an MT-32 plugged into your Mac, this uses a different system again: we need to send actual MIDI commands to the device to change its own master volume. Time to dust off the General MIDI spec. (Of course MT-32s don’t respond to General MIDI volume commands, so we need to send a different message to those instead: time to dust off the MT-32 spec too!)
Because MIDI is a low-bandwidth realtime medium, we need to take care not to spam a real MIDI device with tiny volume changes that would crowd out other MIDI messages. This means coalescing volume updates and sending them at certain intervals, once the device isn’t otherwise busy.
Another wrinkle: many MT-32-compatible DOS games send their own MIDI commands to set the master volume. If we let those go through to the external MIDI device they’ll override our own volume: so we need to detect and intercept those commands, and scale them by our own volume before sending them on their way.
And one final snag: Audio tracks from physical CDs are played back through yet another system, a decrepit and awful SDL API, whose playback volume is beyond the reach of Boxer altogether. I decided this was a bridge too far for this release, since Boxer usually rips CD audio anyway to play back in a manner it can control.
Instead, I swore a dark and solemn oath to rewrite the DOSBox audio architecture for Boxer 1.3: to remove the lingering dependencies on SDL and to unify the disparate outputs under my own roof.
So that’s what goes into a simple application volume control. This is something of an extreme case: some simple features really are trivial to implement, and most don’t have to cover quite so many bases. But they do usually involve a lot of unexpected edge-cases and layers of complexity hidden beneath the surface.
Design by 40watt.