MATTREAGAN
iOS & macOS engineer,
designer, game creator
Author: Matt Reagan
« Previous | Next »

Audible Xcode Breakpoints
Over the years I've grown to really appreciate audible Xcode breakpoints. They allow a sound effect to be played when certain code is run and then immediately continue the active executable without any pauses or interruptions.

This can be a really useful debugging tool, though I've always felt that it was somewhat limited, since by default Xcode only allows you to choose from the macOS system alert sounds.


Custom Xcode breakpoint sounds.
For this reason I've created a custom collection of sound files specifically for use with Xcode breakpoints (available on GitHub) which can be used directly from Xcode's breakpoint editor.

This post will discuss how to use the sounds themselves, but will also touch on:
  1. Why sound-based breakpoints are useful
  2. How to create them in Xcode
  3. What makes a 'good' breakpoint sound
  4. How to add custom sounds to Xcode's breakpoint editor sound menu

Typical Breakpoints

The biggest downside of typical breakpoints is that they freeze everything in its tracks and forcibly remove you from the context of the app you're debugging.

Often times this is necessary or desirable, but sometimes you'll want to gain a better understanding of how and when certain code is executing as you use the app in a fluid, natural manner. It can be difficult to achieve this with traditional breakpoints.

Logging is an option for providing feedback that doesn't require pausing, but it is typically only visible in the console, which requires that you either tab back over to Xcode or at the very least glance at some other part of your screen (or another display), which then forces you to take your eyes off of what you're doing.

Sound-based Breakpoints

Audible breakpoints have several unique advantages. They allow you to:
  • Use the app you're debugging in a natural, fluid manner, without interruptions
  • Keep your eyes completely focused on the UI or visual behaviors of that app
  • Obtain immediate feedback when reproducing timing-sensitive bugs, since the app does not need to be paused for the breakpoints to communicate the intended information
  • On macOS, avoid unwanted side effects caused by the app being deactivated when Xcode is brought forward (this is especially useful when debugging issues with popovers or utility panels, etc.)

How To Create Them

Xcode makes creating these breakpoints quick and easy:
  1. Add a breakpoint, then bring up the breakpoint editor
    Tip: hold command + option and then click the breakpoint marker in the gutter or breakpoint navigator
  2. Add a breakpoint action, and choose Sound
  3. Check the Automatically continue after evaluating actions box to avoid pausing

Default Sounds

You'll quickly notice that Xcode's default sounds are fairly limited. macOS includes a short list of system alert sounds, but most of these are not great choices for breakpoints. But, why? What actually does make a good breakpoint sound?

What Makes a 'Good' Sound?

Breakpoint sounds should ideally meet several criteria:
  1. The audio files should be small in size (fast to load, quick to initiate playback)
  2. They should be short in duration, to avoid long pauses while the breakpoint sound action is run
  3. They should be uniquely discernible from each other, in cases where multiple sounds might play close together
  4. Each playback should be distinct (so that the number of times the breakpoint sound is played is clear)
  5. They should ideally convey some kind of meaning, or improve the context of debugging in some way
That last point deserves a bit more discussion. When using this debugging technique, it makes sense to choose sounds that are contextually appropriate for the code containing the breakpoint.

For example, you may want a sound to play whenever an object is pushed onto a stack or added to a collection. The sound effect for this action, therefore, should convey some kind of 'pushing' or 'addition' effect, at least in a vague sense.

Likewise, if you wanted to pair that with a contrasting breakpoint to signal any time an object was popped or removed from a collection, the sound effect should ideally communicate a 'popping' or 'subtractive' quality (again, in a vague sense, since this is entirely subjective).

The collection below attempts to provide a well-rounded, multi-purpose set of debugging sounds which meet all of the above criteria. Some suggested use cases for each effect are shown in the list below, but the idea is to choose whatever effects make the most sense to you for the particular breakpoints you're adding.

How to Use

Option 1: Adding to Xcode

The easiest way to use these sounds is to add them to Xcode's breakpoint editor sound menu:
  1. Download the sound collection
  2. Copy the audio files into ~/Library/Sounds. (This will make them avaiable to any apps that use system alert sounds.)
  3. Quit and relaunch Xcode, if needed
After these steps, the custom sounds will be available in Xcode's breakpoint editor:

Option 2: Using AFPlay

If you don't wish to modify your ~/Library/Sounds folder, you can also easily play these sounds by using the Shell Command breakpoint action, rather than the Sound action.

Simply create a breakpoint which calls the afplay command and provide the file path to the sound effect you want to play as the argument. With this approach, you can make use of any arbitrary audio file in any location.

Speech Breakpoints

Another powerful audio breakpoint tool that should be mentioned is Apple's text-to-speech, which can be easily leveraged from Xcode breakpoints by using the Shell Command action along with the system say command.

say will audibly speak any arbitrary text and provides options for controlling the voice, accent, rate of speech, and other characteristics. The say command is surprisingly powerful: to learn more about what it can do, check out the man page.

The Sounds

While these may not be amazing audio effects from a creativity or production-value standpoint, I believe they are particularly good choices for debugging. The example context listed for each audio file is obviously just a suggestion - they can be used however you like. The idea is simply to choose an effect which has some subjective association which makes it easier to recognize each breakpoint, particularly when using multiple breakpoints together.

Download on GitHub: Xcode Breakpoint Sounds.

Xcode_CollectAdding object to a collection (sound is similar to collecting an item or increasing your score in a video game)
Xcode_PopRemoving an item from a collection (e.g. 'popping' an object from a stack), freeing memory or releasing an object
Xcode_BzztError or unexpected condition, useful for breakpoints in code that should not be hit
Xcode_SwishReleasing objects, freeing memory, exiting methods/functions, early returns
Xcode_ClickMarker or tick sound (especially short, useful for breakpoints which may occur in rapid succession)
Xcode_ErrorError or unexpected conditional
Xcode_KnockFile writes, counter increment or decrement, etc.
Xcode_PunchCostly operation or code which is performing significant work
Xcode_ZipGeneral purpose
Xcode_QuackGeneral purpose
Xcode_BirdGeneral purpose
Xcode_ChimeGeneral purpose

Licensing / Credits

These sound effects were selected from a library of royalty-free audio files, which I've amassed over the years for use with some of my game development projects. No copyrights or author credits are known to me; each audio file here is believed to be in the public domain. If you have questions on the source of any of these audio files please feel free to contact me.

"One More Thing"

If you've ever wondered where the famous Sosumi Mac alert sound got its name...