ToothFairyToothFairy

ToothFairy Manual

This manual is also available as a PDF (2.2 MB) and as multi-page online help. For other languages, please see Google Translate.

1   Introduction

AirPods are great, but they don’t work quite as smoothly with Macs as they do iPhones. You can’t tell at a glance whether audio will play from the AirPods or your Mac’s built-in speaker, you have to dig into a Bluetooth submenu to connect, and then you have to go back to the menu to see when the AirPods are ready for use. ToothFairy streamlines this: just click an icon in the menu bar (or press a hotkey) to switch to the AirPods, and the icon always shows whether they’re connected.

  • Works with AirPods, as well as any Bluetooth device that you can connect to your Mac: headphones, speakers, headsets, game pad controllers, keyboards, mice, etc. (HomePod is not supported, as it is not a Bluetooth audio device.)
  • Click the hollow AirPods icon in the menu bar to switch to AirPods. It fills in to show they are connected and also displays a battery indicator. Now you know that it’s safe to start playing music; it won’t blast from your Mac’s internal speaker.
  • Supports multiple Bluetooth audio devices; you can choose a different icon and hotkey for each.
  • Get the best audio quality. macOS will normally use the SCO codec if it thinks you’re going to use the microphone. ToothFairy can ensure that it uses the higher quality AAC codec when you only care about audio output: listening to music or video or playing a game.
  • Disconnect a Bluetooth device by clicking the icon (or pressing the hotkey) again, so that you can switch back to your phone. AirPods and Beats devices with an Apple H1 or W1 chip do not need to be manually disconnected, and you can set them to avoid accidental disconnections when pressing the hotkey multiple times.
  • ToothFairy automatically launches at login, so it’s always there when you need it.
  • Optionally hide the Dock icon so it only appears in the menu bar. With the Dock icon hidden, you can right-click (or Control-click) the menu bar icon to access the settings.
  • Run a shell script when the AirPods are connected or disconnected, for example to notify you or to launch or quit another app. ToothFairy itself is also AppleScriptable, so you can control your devices from other apps (like Lacona) and automations.
  • Use with your Magic Mouse or Magic Keyboard to make sure the battery level doesn’t get too low, or to quickly reconnect them after charging or if they get disconnected.

2   Installing and Updating

ToothFairy is available from the Mac App Store and Setapp.

2.1   Requirements

ToothFairy works with macOS 10.13 and later.

ToothFairy works with devices that can be connected via the macOS Bluetooth menu. Please make sure the devices you want to connect have been paired to your Mac and work reliably before using them with ToothFairy.

Switching Bluetooth devices between multiple Macs requires that the Bluetooth device can be paired with more than one computer/phone at a time; this is not supported by the current-generation Apple Magic Keyboard/Mouse/Trackpad.

The battery indicator works with devices that can show their battery level in the Bluetooth pane in System Preferences.

3   Menus

3.1   The ToothFairy Menu

After clicking on ToothFairy’s Dock icon, you will see the ToothFairy menu at the top-left of the screen, next to the Apple menu.

4   Settings

ToothFairy’s settings window lets you add and remove devices and adjust the settings for each device. You can access the settings by clicking on ToothFairy’s Dock icon or by Control-clicking one of the device icons in the menu bar.

settings

Click the Advanced… button to see additional settings:

advanced

4.1   Adding a Device

First, make sure that your AirPods or other Bluetooth device is paired using the Bluetooth pane in System Settings or System Preferences.

To begin using a Bluetooth device with ToothFairy, click the + button in the Settings window. This will open the Bluetooth selector:

bluetooth connect

Click on the desired device and then click Select. Now your device will appear in the list at the left side of ToothFairy’s settings:

settings

Manually Adding a Device

In rare cases, macOS may incorrectly show the Select button as disabled, but you can add the device to ToothFairy by manually entering its Bluetooth address:

  1. To find the address:
    • On macOS 13 and macOS 14, go to System Settings ‣ Control Center and make sure that Bluetooth is set to Show in Menu Bar.
    • On macOS 11 and macOS 12, go to System Preferences ‣ Dock & Menu Bar ‣ Bluetooth and make sure that Show in Menu Bar is checked.
    • On earlier versions of macOS, go to System Preferences ‣ Bluetooth and make sure that Show Bluetooth in menu bar is checked.
  2. Then Option-click the macOS Bluetooth menu at the top of the screen and look for the address under the device. You may want to take a screenshot of the menu so that you can still see the address after closing it.
  3. Option-click the + button in ToothFairy and enter the device’s Bluetooth address.

Devices added in this way may have limited functionality; the device name and battery status may not be available to ToothFairy.

4.2   Menu bar icon (click to connect/disconnect)

ToothFairy adds an icon to your menu bar for each device:

easy

Click the menu bar icon to connect to the device, i.e. to begin playing audio through your AirPods or begin using your game controller. The icon will fill in to show that the device is connected. Now you know that it’s safe to start playing music; it won’t blast from your Mac’s internal speaker.

Click again to disconnect from the device. The icon will change to a hollow shape to show that the device is disconnected. This makes it possible to connect the device to a phone or other Mac. Some devices, such as Apple and Beats devices with W1 and H1 chips, don’t need to be manually disconnected. They will auto-disconnect when you try to connect them to another Mac.

Sometimes the icon will show a shape that’s filled but faded out. This means that the device is connected but not the current target for sound output (in System Settings ‣ Sound ‣ Output). In this case, clicking the icon will select the device for sound output.

You can use the pop-up menu in the settings to choose the icon that best matches you device. Choose from icons for different types of headphones, speakers, mice, tablets, trackpads, keyboards, game controllers, and phones. Hold down the Option key when opening the pop-up menu to see the filled versions of the icons.

device icons

Can I rearrange the device icons in the menu bar?

Yes, you can hold down the Command key and then click and drag on the icons to control the order of the Bluetooth devices in the menu bar. You can also control how they are ordered in relation to other menu bar items such as the Wi-Fi menu and clock.

See also:

4.3   Show battery status in the menu bar

With this option enabled, ToothFairy will show a battery gauge next to the device’s icon in the menu bar:

battery status

This can help you see when it’s time to charge the battery, so that it doesn’t run out at an unexpected time.

You can see the precise battery percentage (including separate levels for left and right AirPods) by hovering over the icon to show the tooltip or by Control-clicking the icon to show the menu.

Why don’t I see the battery level?

You should see the battery level for any Bluetooth device that’s fully supported by macOS. macOS can read the battery level of popular Bluetooth devices such as AirPods, Magic Mouse, Magic Keyboard, and many common third-party audio and input devices.

Some devices report the battery level in a different way that doesn’t show up even though iOS (which supports more devices than macOS) may be able to show it:

  • All devices that show the battery level in System Preferences ‣ Bluetooth on macOS 12 or earlier should also show the battery level in ToothFairy. (System Settings ‣ Bluetooth on macOS 13 and later works differently and is not as reliable an indicator of support that will work with ToothFairy.)
  • Most devices that show the battery level in the Bluetooth menu on macOS 12 and earlier will also show the battery level in ToothFairy.
  • If the macOS Bluetooth menu does not show the battery level, ToothFairy won’t, either.
  • In rare cases, macOS will show the battery level, but the Select button when trying to add the device to a third-party app such as ToothFairy may be disabled. In this case, you can add the device manually, however the device’s name and battery level may or may not be available to ToothFairy. This can happen for devices that only support Bluetooth Low Energy.

If you have an unsupported device, please contact us and let us know which device are you using. We may add direct support for popular devices in a future version of ToothFairy.

4.4   Global hotkey to connect/disconnect

You can set a hotkey for each device to quickly connect or disconnect it. Click Record Shortcut to configure the hotkey that you want. Click the × button if you no longer want to use the hotkey.

For example, you can press a hotkey when you want to begin playing audio through your AirPods. Or, since a Magic Mouse can become disconnected after charging, press the hotkey to reconnect it when you want to use it again (since you can’t click the icon using a disconnected mouse).

See also:

4.5   Launch at login

We recommend checking this box so that ToothFairy will automatically launch whenever you log into your Mac. This will ensure that your device icons and hotkeys are always available.

4.6   Hide Dock icon

Check this box if you don’t want to see ToothFairy’s icon in your Dock. You will still be able to access ToothFairy’s preferences by Control-clicking on any of the device icons in the menu bar.

Why do I see the Dock icon even after hiding it?

After you’ve checked the Hide Dock icon preference, you need to quit and relaunch ToothFairy in order for the change to take effect.

Also, macOS 10.14 and later include a section of the Dock for recent applications, and this can include the icons even of applications that have hidden their icons. To hide ToothFairy from this section, first quit ToothFairy. Then you can either:

  • Click and hold on the ToothFairy Dock icon and choose Options ‣ Remove from Dock from the menu; or

  • Drag the ToothFairy icon off the Dock; or

  • Go to System Settings ‣ Dock & Menu Bar ‣ Dock & Menu Bar and uncheck Show recent applications in Dock to hide that section entirely.

    Note: On macOS 10.15 and earlier, this is in System Preferences ‣ Dock ‣ Show recent applications in Dock.

4.7   Improve sound quality by disabling audio input from device

Devices such as AirPods have both speakers and microphones; they can be used for both audio output and audio input. With many such devices, macOS will normally use the SCO or SBC Bluetooth audio codec because this works with both output and input. It is a good choice if you are making a Skype call where you want to both listen and speak.

However, sometimes you may want to only listen, e.g. if you are playing music, watching a video, or playing a game. In this case, the SCO codec is not optimal because it has lower audio quality. A codec such AAC would provide better sounding audio, but it may not work with audio input. If you check the Improve sound quality by disabling audio input from device box, ToothFairy will tell macOS not to use the device’s microphone, which lets macOS use the higher quality codec that’s optimized for audio output.

It is still possible to do things that require audio input, e.g. starting a Skype call or talking to Siri. Depending on the app, macOS will either use the Mac’s internal microphone (e.g. Siri) or use the Bluetooth device’s microphone (e.g. FaceTime), automatically switching it to the lower quality SCO codec, overriding the change that ToothFairy made in System Settings. If this happens, when you’re done using the app, you can tell ToothFairy to disconnect and reconnect the device to switch it back to the high-quality AAC codec.

Note: Often, the audio quality can be improved by quitting the Xcode Simulator.

Note: You can download the Bluetooth Explorer app from Apple (as part of the “Additional Tools for Xcode 11”) to see and adjust codec settings for you devices.

4.8   Don’t disconnect when clicking icon or pressing hotkey

AirPods and Beats devices with an Apple H1 or W1 chip do not need to be manually disconnected, and you can set them to avoid accidental disconnections, e.g. if you didn’t mean to press the hotkey or if you press it multiple times when trying to connect. Additionally, ToothFairy will show the device menu when you click on the icon, without your having to right-click.

This is also useful to avoid accidentally disconnecting an important input device such as a mouse or keyboard.

See also:

4.9   Run shell script after connecting/disconnecting

ToothFairy itself is AppleScriptable:

applescript dictionary

ToothFairy can also trigger scripts to run automatically when you connect or disconnect a Bluetooth device. Normally, ToothFairy runs the connection script when the device becomes the audio output device, i.e. when it is ready to use. However, you can use this Terminal command to instead make it run the script when the Bluetooth connection is made:

defaults write com.robinlu.mac.Tooth-Fairy RunConnectionScriptWhenSettingAudioOutput NO

Here are some examples of what you can do with connection and disconnection scripts:

Display a Notification in Notification Center

#!/usr/bin/osascript
display notification "Connected" with title "AirPods"

Speak a Phrase Using Text-to-Speech

#!/bin/sh
/usr/bin/say "AirPods Disconnected"

Connect Another Bluetooth Device

You can attach a script like this to your mouse so that when the mouse connects it auto-connects your keyboard at the same time:

#!/usr/bin/osascript
tell application "ToothFairy"
    set connected of device "Keyboard" to true
end tell

Disconnect Another Bluetooth Device

You can attach a script like this to your AirPods so that when the headphones connect your speaker disconnects:

#!/usr/bin/osascript
tell application "ToothFairy"
    set connected of device "Speaker" to false
end tell

Run a Shortcut

You can trigger a shortcut, created in the macOS Shorcuts app, by specifying its name:

#!/bin/sh
shortcuts run "NameOfYourShortcut"

Launch Music or Another App

#!/bin/sh
open -a "Music"

Some people also like to launch a certain game when connecting their headphones.

Start Playing a Music Playlist

#!/usr/bin/osascript
tell application "Music" to play playlist "My Playlist"

For more Music script ideas, see Doug’s AppleScripts.

Quit Music

#!/usr/bin/osascript
tell app "Music" to quit

Change the Sound Input or Output Device

macOS normally sets the sound input and output automatically when connecting a device. However, in some cases it may not switch them automatically or you may wish to specify different devices. You can do this by installing switchaudio-osx and using a script like this:

#!/bin/sh
/usr/local/bin/SwitchAudioSource -t output -s "DeviceName"
/usr/local/bin/SwitchAudioSource -t input -s "DeviceName"

Adjust the Volume

macOS normally remembers the volume for each device, but you can also set it via script each time ToothFairy connects a device:

#!/usr/bin/osascript
set volume output volume 25 without output muted
set volume input volume 75

Turn Off Bluetooth When Disconnecting

Some Macs will wake from sleep to try to connect to a nearby Bluetooth device that becomes available. This can be prevented by turning off Bluetooth on your Mac when disconnecting a device. You can do this by installing blueutil and using a script like this:

#!/bin/sh
blueutil --power 0

Connect to Another Mac When Disconnecting

Say that you have Mac A and Mac B that are on the same local network (mac-a.local and mac-b.local) and you want them to share a keyboard (named Keyboard in ToothFairy):

  1. Go to System Settings ‣ General ‣ Sharing and enable Remote Application Scripting. (On macOS 12 and earlier, the setting is System Preferences ‣ Sharing ‣ Remote Apple Events.)

  2. On Mac A, set a disconnection script:

    #!/usr/bin/osascript
tell application "ToothFairy" of machine "eppc://user:password@mac-b.local"
    set device "Keyboard"'s connected to true
end tell

    You’ll need to fill in your username, password, and Bonjour name.

  3. On Mac B, set a disconnection script:

    #!/usr/bin/osascript
tell application "ToothFairy" of machine "eppc://user:password@mac-a.local"
    set device "Keyboard"'s connected to true
end tell

Now, whenever you disconnect the keyboard on one Mac, it will use AppleScript over the network to tell the other Mac to connect to it.

Prevent iTunes From Playing Automatically

Some Bluetooth headphones will make iTunes start playing automatically when you use another media player. You can prevent that by using this script when connecting to temporarily turn off the iTunes agent process:

#!/bin/sh
launchctl stop com.apple.rcd

Use this script when disconnecting to turn it back on:

#!/bin/sh
launchctl start com.apple.rcd

These scripts were contributed by a customer using macOS 10.14 and may not work on all Macs or with newer versions of macOS.

Add a Message to the System Log

#!/bin/sh
terminal-notifier -message "Connected AirPods" -title "ToothFairy"

This script requires Terminal Notifier.

Connect to iPhone’s Bluetooth Personal Hotspot

#!/usr/bin/osascript
set _deviceName to "Tom's iPhone"

tell application "System Events" to tell process "SystemUIServer"
    set _bluetoothMenu to (first menu bar item whose description is "bluetooth") of menu bar 1
    click _bluetoothMenu
    if exists menu item _deviceName of menu of _bluetoothMenu then
        tell (first menu item whose title is _deviceName) of menu of _bluetoothMenu
            click
            tell menu 1
                if exists menu item "Connect to Network" then
                    click menu item "Connect to Network"
                    return "Connecting..."
                else
                    key code 53 -- hit Escape to close BT menu
                    return "No connect button; is it already connected?"
                end if
            end tell
        end tell
    else
        key code 53 -- hit Escape to close BT menu
        return "Cannot find that device, check the name"
    end if
end tell

You’ll need to edit the script to include the proper _deviceName for your phone.

5   Frequently Asked Questions (FAQ)

5.1   What information should I include when I report a problem?

It will be faster and easier to help you if your e-mail includes the following information:

The version of macOS that you are using
Click on the Apple menu and choose About This Mac.
The version of ToothFairy that you are using
Click on the ToothFairy menu and choose About ToothFairy. (Please do not say “the latest version,” as this is ambiguous.)
Specific error information
Please see Sending in an Error Report.
If something isn’t working as you expect
Please describe what you did, what happened, and what you expected to happen instead. If possible, take a screenshot or two that illustrate the problem (see Sending in Screenshots).
If ToothFairy hangs or freezes
Please see Sending in a “Sample” Report.

5.1.1   Sending in an Error Report

If an error window appeared on your screen, please include the exact text of the error message in your e-mail. (It may help to use Copy and Paste.)

Please also send in any errors that were reported in the system log:

  1. From the ToothFairy Settings window, click on the About tab. Then click the Save Diagnostic Report button.
  2. Choose a location such as your desktop and click Save. Saving the report may take a minute or so.
  3. Create an e-mail to toothfairy@c-command.com and drag the Diagnostic Report.tbz file into the e-mail message to include it as an attachment/enclosure.

If you can’t launch ToothFairy, you can access the log directly (if you’re using macOS 10.15 or later), rather than using the automated diagnostic reporter:

  1. Click on Finder in the Dock.
  2. Open the Library folder, as described in the How can I open the Library folder? section.
  3. Open the Logs folder.
  4. Open the “ToothFairy” folder.
  5. Find the App Log.log file and attach it to your e-mail message.

5.1.2   Sending in a Bluetooth Log

If the problem is related to connecting or disconnecting via Bluetooth, you can save a Bluetooth diagnostic log by entering a command in Terminal.

  • On macOS 12 Monterey or later, enter:

    sudo /System/Library/Frameworks/IOBluetooth.framework/Resources/BluetoothReporter --dumpPacketLog ~/Desktop/Bluetooth.log

    and find the Bluetooth.log file on your desktop.

  • On earlier versions of macOS, enter:

    sudo /System/Library/Frameworks/IOBluetooth.framework/Resources/BluetoothReporter

    Finder will then open a window showing the BluetoothReporter_<date>.tar.gz report file.

It’s also helpful to install a Bluetooth logging profile and then save a sysdiagnose, as described here. This requires an Apple developer account. If you don’t have a developer account, you can save a regular sysdiagnose by choosing View ‣ Run System Diagnostics… in the Activity Monitor app.

5.1.3   Sending in Screenshots

To take a screenshot, hold down the Command and Shift keys and press the number 4. Then use the mouse to select the area of the screen that you want to take a picture of. This will create a file called Screen Shot <date> at <time>.png on your desktop. Pressing the keys again will create Screen Shot <date> at <new time>.png, etc.

You can also take screenshots using the File ‣ Take Screenshot command in the Preview application.

To send in screeenshots, drag the files into your e-mail window to attach them to your message. If you’re using Apple Mail, be sure to set the Image Size pop-up menu at the bottom of the message window to Actual Size.

5.1.4   Sending in a “Sample” Report

If an app is slow, hangs (e.g. with a spinning beachball), or freezes, a “sample” report can record what your Mac was doing in order to locate the source of the problem. Depending on which app is slow or not responding, you may want to record samples from ToothFairy, Apple Mail, and/or another app.

  1. Click on Finder in the Dock.
  2. From the Go menu, choose Utilities.
  3. Double-click the Activity Monitor program.
  4. Select the app in the Activity Monitor window.
  5. Do whatever it is in the app that causes the slowness, hang, or freeze. Immediately, click on Activity Monitor in the Dock and choose Sample Process from the View menu.
  6. After Activity Monitor has finished taking the sample, click the Save… button in the “Sample of <App>” window. Save the file to your desktop and then include it in your e-mail message to toothfairy@c-command.com as an attachment. (Please do not copy and paste the text from the Activity Monitor window.)

5.1.5   Sending in Crash Log Files

Crash logs are stored in the folder:

/Users/<username>/Library/Logs/DiagnosticReports/

First click on the Finder in the Dock, then click on the Go menu, and hold down the Option key as you choose Library. Open the Logs folder, then DiagnosticReports.

Once you’ve opened the DiagnosticReports folder, find the most recent crash log file for the app that crashed and add it to your e-mail message to toothfairy@c-command.com as an attachment.

The crash log file’s name will end with either .crash or .ips. It may be in the DiagnosticReports folder or in the Retired folder inside of DiagnosticReports.

5.2   Why isn’t my device connecting?

ToothFairy works with devices that can be connected to your Mac via the macOS Bluetooth menu. If you can connect it via the system menu, you should be able to connect and disconnect it via ToothFairy. Here are some steps to try if you can’t get your device to connect or if it won’t stay connected:

  1. Make sure that Bluetooth is On in the Bluetooth pane in System Settings. It can help to turn Bluetooth off and then back on again on your Mac, or to turn it off on other nearby devices.
  2. Make sure that your device is paired with your Mac using the Bluetooth pane of System Settings. It sometimes helps to unpair the device in System Settings and then re-pair it. (Just because you can see the device and connect to it from the Bluetooth menu does not mean that it is paired. Make sure that you check System Settings.)
  3. Make sure that the device you are trying to connect is the same one that you added to ToothFairy. For example, if you got a new pair of AirPods, ToothFairy will still try to connect to the old AirPods (and report a timeout error) unless you’ve added the new ones to ToothFairy using the + button. Even if you haven’t gotten a new device, it can sometimes help to remove the device from ToothFairy using the - button and then add it back using the + button.
  4. Make sure the device’s battery is fully charged.
  5. Try restarting your Mac in Safe Mode. This will help rule out other software as the source of the problem, but it can also fix the problem (i.e. the Bluetooth device will continue working after you do a regular reboot).
  6. It can help to adjust your AirDrop settings (on your Macs and any nearby iOS devices). Bluetooth devices connect more reliably when AirDrop is off or set to Contacts Only.
  7. It can help to turn off Allow Handoff between this Mac and your iCloud devices in the General pane of System Settings.
  8. If you have USB Overdrive installed, try temporarily turning it off or uninstalling it and see whether that helps.
  9. Try disconnecting any USB hubs from your Mac or nearby Macs.
  10. Check Apple’s Potential sources of Wi-Fi and Bluetooth interference guide.
  11. Try resetting your Mac’s Bluetooth module:
    • On macOS 12, restart your Mac.
    • On earlier versions of macOS, hold down the Shift and Option keys while clicking on the Bluetooth menu. Go to the Debug submenu and choose Reset the Bluetooth Module. Then restart your Mac.
  12. Apps like Bluetooth Inspector, iStumbler, and Apple’s Bluetooth Explorer can be used to diagnose connection problems.
  13. If you still can’t get it to work, save a Bluetooth log and a diagnostic report and send them to us for further assistance.

5.3   How can I switch back to an iPhone or other Mac?

ToothFairy makes it easy to connect a Bluetooth device such as AirPods to your Mac. If you connect the AirPods with ToothFairy and then put them back in the case, they will auto-reconnect to that Mac when you take them out of the case.

AirPods will auto-disconnect from the Mac when you try to use them with another computer or phone. Some other types of headphones need to be manually disconnected, by clicking the menu bar icon or pressing the hotkey, before they can be connected to another computer or phone.

To a Mac

To switch to using your AirPods with another Mac, you can use ToothFairy on that Mac to quickly connect them. To prevent macOS from auto-pairing certain Bluetooth audio devices, see this page.

To an iOS Device (Manually)

To switch to using your AirPods with an iPhone, you need to tell the iPhone to connect to them. (ToothFairy on the Mac cannot make the iPhone connect.) It is usually not necessary to go to the iOS Settings to do this. Most apps, and Control Center, have a button for switching the audio output. It looks like an upward-pointing triangle with a bunch of concentric circles.

To an iOS Device (Using Siri)

You can also create a Siri shortcut in iOS to quickly switch the audio output to a particular device:

  1. Connect the AirPods to your iPhone (as described in To an iOS Device (Manually)).

  2. Open the Shortcuts app.

  3. Tap the + button at the top right to create a new shortcut.

  4. Tap the … button at the top right to name your shortcut (e.g. Play to AirPods) and set an icon.

  5. Tap Add Action and choose Set Playback Destination.

    play to airpods shortcut 1

  6. Where it says Set playback destination to iPhone, tap iPhone and change it to your device (e.g. Michael’s AirPods).

    play to airpods shortcut 2

  7. Tap Next and Done. Now you can switch the audio output to that device by running the shortcut, e.g. by telling Siri to “Play to AirPods” or by tapping the shortcut in the Shortcuts app or widget.

    play to airpods shortcut 3

To an iOS Device (Automatically)

You can also set your iPhone to automatically switch to AirPods when you open a certain app. This works even if your Mac is already using them:

  1. Connect the AirPods to your iPhone (as described in To an iOS Device (Manually)).

  2. Open the Shortcuts app.

  3. Tap Automation at the bottom of the screen.

    automation shortcut 1

  4. Tap Create Personal Automation.

    automation shortcut 2

  5. Scroll down and tap Open App.

    automation shortcut 3

  6. Tap Choose, select the app (or multiple apps), and tap Done.

  7. Tap Next.

  8. Tap Add Action and choose Set Playback Destination.

    play to airpods shortcut 1

  9. Where it says Set playback destination to iPhone, tap iPhone and change it to your device (e.g. Michael’s AirPods).

  10. Tap Next, uncheck Ask Before Running, and tap Done.

    automation shortcut 4

Keyboards

Some keyboards, such as the Apple Magic Keyboard can only be paired with one computer or iOS device at a time. Thus, to switch a Magic Keyboard between Macs you would need to pair it each time in System Settings. Other keyboards—such as the Logitech K375s, K380, K580, and K811—support multiple devices, so you can switch simply using ToothFairy.

See Also

5.4   How can I turn off Automatic Device Switching?

When using a recent model of Apple or Beats earphones with macOS 11 (or later) or iOS 14 (or later), there is a feature called Automatic Device Switching. In some cases, this works well and you automatically hear the sound from the desired Mac or iPhone without having to connect the Bluetooth device. In other cases, it can cause problems. For some customers, the AirPods seem to randomly switch back and forth between devices, even in the middle of playing audio. For others, they keep reconnecting to the same wrong Mac or iPhone, rather than staying with the one that you chose. In such cases, you may want to turn off Automatic Device Switching:

iOS 14 and Later

  1. Go to Settings ‣ Bluetooth.
  2. Tap the i button next to your device.
  3. Set Connect to This iPhone to When Last Connected to This iPhone.
  4. When you want your iPhone to connect to the device, use the audio output button, Siri, or an automatic Shortcut.

macOS 13 and Later

  1. Go to System Settings ‣ Bluetooth.
  2. Click the Options button next to your device.
  3. Set Connect to This Mac to When Last Connected to This Mac.
  4. When you want your Mac to connect to the device, press ToothFairy’s hotkey or click the icon in the menu bar.

macOS 11 and macOS 12

  1. Go to System Preferences ‣ Bluetooth.
  2. Click the Options button next to your device.
  3. Set Connect to This Mac to When Last Connected to This Mac.
  4. When you want your Mac to connect to the device, press ToothFairy’s hotkey or click the icon in the menu bar.

5.5   How can I rename a Bluetooth device?

  1. Open the Bluetooth pane of System Settings.
  2. Make sure that your device is connected.
  3. Right-click on the device and choose Rename from the contextual menu. This will change the name throughout the system and in ToothFairy.

5.6   How can I open the Library folder?

The user library folder is stored at the path /Users/<username>/Library/. The way to access it is different depending on which version of macOS you are using:

macOS 10.12.3 and Later

The Library folder is hidden by default. To open it, click on Finder in the Dock. Click on the Go menu at the top of the screen, hold down the Option and Shift keys, and then choose Library. (Only one of Option and Shift is needed, but due to an OS bug, which one you need to hold down can vary. Thus, it is easier to hold down both.)

Another way to access the Library folder is to choose Home from the Go menu, then type Command-Shift-Period to show invisible files, and then open the Library folder.

Mac OS X 10.7 Through 10.12.2

The Library folder is hidden by default. To open it, click on Finder in the Dock. Click on the Go menu at the top of the screen, hold down the Option key, and then choose Library.

Another option is to go to your home folder, choose View ‣ Show View Options and then make sure that Show Library Folder is checked.

Mac OS X 10.6

Click on Finder in the Dock, click on the Go menu, and choose Home. This will show your home folder, and you can open the Library folder directly.

6   Legal Stuff

Copyright and Trademarks

ToothFairy and this manual are copyright © 2002–2024 by C-Command Software, LLC. All rights reserved.

ToothFairy is a trademark of C-Command Software, LLC. Mac is a registered trademark of Apple Computer. All other products mentioned are trademarks of their respective owners.

End User License Agreement

CAREFULLY READ THE FOLLOWING LICENSE AGREEMENT. YOU ACCEPT AND AGREE TO BE BOUND BY THIS LICENSE AGREEMENT BY DOWNLOADING AND INSTALLING THE PROGRAM. IF YOU DO NOT AGREE TO THIS LICENSE, THEN DO NOT DOWNLOAD AND INSTALL THE PROGRAM, AND REMOVE THE SOFTWARE FROM YOUR COMPUTER.

License Grant

“You” means the person or company who is being licensed to use the Software or Documentation. “We,” “us” and “our” means C-Command Software, LLC.

We hereby grant you a nonexclusive license to use one copy of the Software on any single computer, or on multiple computers only used by a single person. The Software is “in use” on a computer when it is loaded into temporary memory (RAM) or installed into the permanent memory of a computer—for example, a hard disk or other storage device.

Title

We remain the owner of all right, title and interest in the Software and related explanatory written materials (“Documentation”).

Archival or Backup Copies

You may copy the Software for backup and archival purposes, provided that the original and each copy is kept in your possession and that your installation and use of the Software does not exceed that allowed in the “License Grant” section above.

Things You May Not Do

The Software and Documentation are protected by United States copyright laws and international treaties. You must treat the Software and Documentation like any other copyrighted material—for example, a book. You may not:

  • copy the Documentation,
  • copy the Software except to make archival or backup copies as provided above,
  • sublicense, rent, lease or lend any portion of the Software or Documentation.

Transfers

You may transfer all your rights to use the Software and Documentation to another person or legal entity provided you transfer this Agreement, the Software and Documentation, including all copies, updates and prior versions to such person or entity and that you retain no copies, including copies stored on computer.

Limited Warranty

The software is provided “as is,” without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software. No employee, agent, dealer or distributor of ours is authorized to modify this limited warranty, nor to make any additional warranties.

Term and Termination

This license agreement takes effect upon your use of the software and remains effective until terminated. You may terminate it at any time by destroying all copies of the Software and Documentation in your possession. It will also automatically terminate if you fail to comply with any term or condition of this license agreement. You agree on termination of this license to destroy all copies of the Software and Documentation in your possession.

General Provisions

  1. This written license agreement is the exclusive agreement between you and us concerning the Software and Documentation and supersedes any prior purchase order, communication, advertising or representation concerning the Software.
  2. This license agreement may be modified only by a writing signed by you and us.
  3. This license agreement is governed by the laws of the State of New Hampshire.
  4. You agree that the Software will not be shipped, transferred or exported into any country or used in any manner prohibited by the United States Export Administration Act or any other export laws, restrictions or regulations.

Components

The following open-source components are used in ToothFairy:

  • Regular expression support is provided by the PCRE library package, which is open source software, written by Philip Hazel, and copyright by the University of Cambridge, England.
  • CwlDemangle.swift is Copyright © 2017 Matt Gallagher and is available under the Apache License v2.0 with Runtime Library Exception.
  • Thanks to Allan Odgaard for some code snippets that are used in the Software Update installer.

7   Version History

2.8.5—October 17, 2024
2.8.4—March 6, 2024
  • The battery info updates more quickly after connecting a device.
  • The Run shell script after connecting/disconnecting help page now explains how to trigger a shortcut.
  • ToothFairy is better at remembering the current sound input device so that the Improve sound quality by disabling audio input from device feature will restore the proper one after connecting a new device.
  • You can now pull down a device’s menu while the connection progress indicator is spinning.
  • ToothFairy no longer shows arrow icons while it’s in the process of fixing the sound output, as this was confusing. Instead, it will continue showing the device as half-connected until it’s done. You can still see what’s happening with the fixing via the tooltip and the menu item text.
  • If the feature to fix the sound output is disabled, clicking the half-connected device icon now disconnects the device instead of doing nothing.
  • Each help page now has a link to a Google translation so you can view it in a different language.
  • Updated the French localization.
  • Fixed a bug where the progress indicator wouldn’t stop if you clicked the menu bar icon when using the Don’t disconnect when clicking icon or pressing hotkey option.
  • Made various fixes and updates to prevent Cocoa from logging warnings.
  • Made various threading improvements.
  • The build number is now displayed in a tooltip in the About tab.
  • Mac App Store receipt validation works better on Macs with damaged Ethernet ports.
  • The Setapp version of ToothFairy now requires macOS 12 or later, due to updating to version 4.1.0 of their framework.
2.8.3—January 11, 2023
  • Made various improvements to the workaround for the macOS issue that could prevent the sound output from being set when connecting a device. The workaround is successful more often, avoids unnecessary disconnections when the sound output spontaneously fixes itself, and it better handles devices that have been put away or manually disconnected.
  • The menu bar icon now shows when ToothFairy is fixing the sound output. An arrow in a solid circle indicates that the device is currently connected but in the process of disconnecting. An arrow with no circle indicates that the device is waiting to reconnect.
  • ToothFairy no longer reports that the sound output is not set when the device isn’t connected, anyway.
  • Fixed a problem where the progress spinner could stay visible forever, even after the device disconnected.
  • Fixed a problem where ToothFairy could show a Bluetooth connection failure error message for connections that the user did not initiate.
2.8.2—October 12, 2022
  • Added new device icons for AirPods 3, AirPods Pro 2, Beats Fit Pro, Beats Studio Buds, Galaxy Buds Live, AfterShokz Aeropex, Sony WF-1000XM4, and Sony WH-1000XM4.
  • Organized the device icons in the pop-up menu into groups and added tooltips.
  • Worked around some macOS issues that could prevent a Bluetooth device from being set as the current sound output device in various circumstances, such as if it was already connected to an iPhone.
  • Updated the menu titles from Preferences… to Settings….
  • Made various code modernizations, including the way keyboard shortcuts are saved to the preferences file.
  • ToothFairy now requires macOS 10.13 or later.
  • There is now a RunConnectionScriptWhenSettingAudioOutput esoteric preference for the Run shell script after connecting/disconnecting option.
2.8.1—June 27, 2022
2.8—May 11, 2022
  • If a Bluetooth audio device is connected but is not selected as the sound output device—as can happen if you are using Automatic Device Switching—ToothFairy now shows its menu bar icon as solid but faded out.
  • Telling ToothFairy to connect to a Bluetooth device that’s connected but not the current sound output device will now set it as the sound output device instead of disconnecting.
  • ToothFairy is better at detecting when a Bluetooth device has connected or disconnected in cases where macOS did not notify it.
  • ToothFairy now converts carriage returns to line breaks when saving a script, as improper line breaks can prevent scripts from running.
  • Updated the How can I turn off Automatic Device Switching? section of the manual.
  • Worked around a macOS issue where sometimes a Bluetooth audio device would connect without being set as the sound output target.
  • Worked around a macOS issue where an incorrect Bluetooth device name could be shown after disconnecting and reconnecting.
  • Worked around some macOS issues that could cause crashes when reading battery information or adding a new Bluetooth device.
  • Fixed a bug where the spinning progress indicator would be drawn for Light Mode when the Mac was running in Light Mode but the transparent menu bar was showing a dark desktop picture underneath. ToothFairy now treats this as de facto Dark Mode to make the progress indicator easier to see and match the rest of the menu bar content.
  • Fixed a bug where the progress indicator for a device icon could be drawn on top of it.
  • Fixed a bug where a connection or disconnection script could be run multiple times for the same event.
  • Fixed a bug where device names were prematurely truncated in the preferences table view.
2.7.8—January 4, 2022
  • Worked around an issue with macOS 12 where it was sometimes impossible to add a Bluetooth device to ToothFairy because the Select button was disabled. In such cases, you can now enter the device’s address to add it.
  • Improved the accuracy of the battery status indicator on macOS 12.
  • Made some enhancements to make Bluetooth troubleshooting easier.
  • Improved the Why isn’t my device connecting? section of the manual.
  • Improved the diagnostic report.
2.7.7—November 18, 2021
  • Worked around an issue that could cause ToothFairy to crash on macOS 12 Monterey.
2.7.6—November 16, 2021
  • Worked around an issue that could cause ToothFairy to hang on macOS 12 Monterey.
2.7.5—November 12, 2021
  • Improved the battery status indicator on macOS 12 Monterey.
  • Improved the How can I turn off Automatic Device Switching? section of the manual.
  • Added French localization.
  • ToothFairy now declares notch compatibility for the new MacBook Pros.
2.7.4—July 28, 2021
2.7.3—April 12, 2021
2.7.2—January 15, 2021
  • Fixed a bug that could cause ToothFairy to crash at launch on some Macs.
2.7.1—January 14, 2021
  • ToothFairy now runs natively on Apple Silicon Macs.
  • Added icon for AirPods Max.
  • The Run shell script after connecting/disconnecting section of the manual now has a sample script to connect the device to another Mac when disconnecting from the current one.
  • The Run shell script after connecting/disconnecting section of the manual now has a sample script that shows how to change the volume.
  • Worked around an issue that could prevent ToothFairy from launching on Macs with certain network configurations.
  • Fixed an issue adding new Bluetooth devices on macOS 11.
2.7—November 3, 2020
  • Redesigned the application icon for macOS 11 Big Sur.
  • Added new icons for AirPods Pro, Beats Studio 3, controller, headphones, Playstation, Powerbeats 2020, Siri Remote, and Xbox.
  • Added AppleScript support for listing devices, getting their properties, and toggling connections.
  • If the Don’t disconnect when clicking icon or pressing hotkey option is enabled for a device, you can now access that device’s menu with a regular click, rather than having to right-click or Control-click.
  • The Improve sound quality by disabling audio input from device option now works better when a Bluetooth device auto-connects rather than being connected via ToothFairy. It’s also more reliable in cases where macOS reports that it has set the audio input device but actually hasn’t.
  • Improved resizing the Advanced… preferences sheet.
  • The Advanced… preferences sheet now has a help button that explains the options and shows sample shell scripts and AppleScripts.
  • Updated the sample scripts in the Run shell script after connecting/disconnecting section of the manual.
  • Worked around an issue with macOS 11 where text in the device list would be vertically clipped.
  • Worked around some security changes in macOS 11 that made it impossible to save script changes.
  • Fixed a bug where ToothFairy could stuck in an error reporting loop if there was an error saving the scripts.
2.6.2—June 2, 2020
  • The How can I switch back to an iPhone or other Mac? section of the manual now describes how you can make your iPhone automatically switch back to AirPods (or another chosen Bluetooth device) when you open certain apps.
  • Added the How can I rename a Bluetooth device? section of the manual.
  • If macOS forgot that ToothFairy was set as a login item, it will now repair this at launch without your having to click the preferences checkbox.
  • Improved the Improve sound quality by disabling audio input from device and Why isn’t my device connecting? sections of the manual.
  • Adjusted the icons so that if you have a keyboard next to a trackpad, they line up.
  • The offset disconnected AirPods icon no longer looks uncentered.
  • Added Czech and Dutch localizations.
  • Fixed a bug where the Preferences window could be inappropriately shown at launch due to an interaction between macOS state restoration and the login item.
  • Tried to fix a crash due to a macOS bug after adding a new Bluetooth device.
2.6.1—December 30, 2019
  • Improved the details in the AirPods Pro icon.
  • Added another variant of the AirPods icon that’s slightly smaller, because some people prefer that size and also to help differentiate for those who have multiple pairs of AirPods.
  • The game controller icon no longer shows a wire.
  • You can now hold down the Option key when opening the icon pop-up menu to see the filled versions of the icons.
  • ToothFairy is faster at detecting when a device’s connection has been dropped without macOS noticing.
  • The How can I switch back to an iPhone or other Mac? section of the manual now tells how you can make a Siri shortcut to quickly switch an iOS device to a given audio device.
  • Updated the Adding a Device and Why isn’t my device connecting? sections of the manual.
  • When the Preferences window is already open, choosing the Preferences… menu command for a device will now select that device.
  • Closing the Advanced sheet now preserves the selected device.
2.6—October 29, 2019
  • Added icons for AirPods Pro, Beats X, Microsoft Surface Earbuds, and an alternate icon for a pair of regular AirPods that are positioned symmetrically rather than offset.
  • Adjusted the way battery levels map to gradations in the menu bar gauge.
  • Added a button to the About tab to open the ToothFairy manual.
  • Worked around a macOS bug that could prevent launching the app after using AirPlay.
  • Fixed a regression where the battery level wasn’t shown if it was exactly 100%.
  • Modernized the localizations.
  • Reduced the size of the app.
2.5.1—October 1, 2019
  • The battery gauge uses twice as many gradations as before to show the battery level more precisely.
  • The Control-click menu now shows the battery percentage on a separate line, to avoid having such a wide menu item.
  • If you rename a Bluetooth device, the name now updates in ToothFairy without having to relaunch the app.
  • The Bluetooth devices are now sorted by name in the Preferences window.
  • Adjusted the battery level tooltip text so that it doesn’t look funny if only one of the AirPods is connected.
  • Worked around a crash on macOS 10.15 that could occur if the system asked you for permission to allow ToothFairy to control your Bluetooth device and you declined.
  • Worked around a potential crash that could occur if a Bluetooth device’s name couldn’t be loaded.
  • All the settings are now documented in the manual.
2.5—April 17, 2019
  • Added menu bar icons for more devices: pair of AirPods, Powerbeats3, Powerbeats Pro, Beats Solo, headset, speakers (boombox, conference, cylinder, desktop, vertical), graphics tablet, game controller, Magic Mouse, 2-button mouse, Magic Trackpad 2 (top and side views), Magic Trackpad 1 (side view), iPhone, and tablet.
  • Clicking on a device in the menu bar now shows a menu with its name, connection status, and battery level, so you can see the information immediately instead of waiting for the tooltip to appear.
  • The Preferences window now explains that you can right-click (or Control-click) the menu bar icon to access the preferences when the Dock icon is hidden.
  • The Preferences window now explains that showing the battery status requires a device whose battery level appears in the Bluetooth pane in System Preferences.
  • Tweaked various Preferences window text to clarify the icon and audio input settings and how the new Apple H1 chip fits in.
  • Improved the Why don’t I see the battery level? and Why isn’t my device connecting? sections of the manual.
  • When reporting a Bluetooth error, ToothFairy now includes the hex code and error name to help look up the exact cause of the problem.
  • Fixed a regression where changing the icon didn’t work on macOS 10.11.
  • Updated code for Xcode 10.2 and Swift 5.
2.4.9—January 29, 2019
  • ToothFairy no longer shows an error window when you try to connect to a device that’s already connected.
  • ToothFairy now automatically retries connecting via Bluetooth to make it more likely that it will succeed without user intervention.
  • Improved the Why isn’t my device connecting? section of the manual.
  • Added the Why don’t I see the battery level? section of the manual.
  • Added accessibility labels for the device icon menu and menu bar status icon.
  • ToothFairy is more judicious about changing the audio input device, to avoid excessive Micro Snitch notifications.
  • Fixed a bug where some script text could be displayed with the wrong color in Dark Mode.
2.4.8—November 7, 2018
  • If there’s an error connecting to your Bluetooth device, ToothFairy now recommends to you how you can fix it.
  • Improved the wording in various user interface text.
  • Fixed a bug where the menu bar background color when clicking on the menu didn’t match the accent color on macOS 10.14 or the Graphite appearance on earlier versions.
  • Added the Why isn’t my device connecting? and Why do I see the Dock icon even after hiding it? sections of the manual.
  • The Credits sheet now links to the privacy policy.
  • Added accessibility descriptions in the Preferences window.
  • Improved the diagnostic report.
  • Error logging now includes more information about the error and the device it’s related to.
2.4.7—August 14, 2018
  • Added support for Dark Mode on macOS 10.14.
  • Revised various preferences text to improve clarity. For example:
    • Global hotkey to switch connection is now Global hotkey to connect/disconnect.
    • Hide dock icon (effect after next launch) is now Hide Dock icon (takes effect at next launch).
    • Audio output only is now Improve sound quality by disabling audio input.
    • Connection only mode is now Don’t disconnect when clicking icon or pressing hotkey.
  • Fixed a bug where the Audio output only option didn’t work, causing AirPods to be inappropriately set as the system audio input device.
  • Added the Save Diagnostic Report button.
  • Reduced the size of the application by having ToothFairy and its login item helper share the same copy of the Swift libraries.
  • Fixed the minimum widths of the OK buttons.
  • Reformatted the text in the credits sheet with fonts, styles, and clickable links.
2.4.6—July 11, 2018
  • The shell script text views now use a monospaced font for better readability of punctuation characters.
  • The shell script text views now disable automatic quote and dash substitution so that you don’t accidentally get smart punctuation in your scripts.
  • Fixed a bug where opening the Preferences window didn’t always bring it to the front.
  • Fixed a bug where the disconnection script was not run.
  • Fixed a bug where there was extra space at the end of the tooltip when hovering over the menu bar icon.
  • Fixed a bug where some of the menu bar icons were not centered when the battery indicator was visible.
  • Updated the German localization.
2.4.5—June 14, 2018
  • C-Command Software has acquired ToothFairy from the original developer, Yibin (Robin) Lu, who was no longer able to work on the app. We thank Robin for his work and look forward to continuing development of the app.
  • Restored compatibility with macOS 10.11.
  • The right-click menu now appears on mouse down instead of mouse up, for consistency with other menus.
  • Updated the copyright and credits.
  • Renamed the app from Tooth Fairy to ToothFairy.
  • Fixed a bug where the credits sheet didn’t have a minimum width.
  • Removed an .sdef file that’s not actually used.