Background Music

macOS audio utility

Overview
      Auto-pause music
      Application volume
      Recording system audio
Download
Build and Install
Uninstall
Troubleshooting
Related Projects
License

Overview

Background Music gives you control over multiple sources of audio on your desktop without navigating each individual application. It provides the following functionalities:

• Automatically pause/unpause your music player when other audio sources are playing/stopped
• Per-application volume control
• Record system audio
• No restart required to install
• Runs entirely in userspace

Requires macOS 10.10+.

_{MD5: 89a74e9379041abfd6a55471f3e61b94
SHA256: 070bef360bff9e52639a4fbf23ee7052b9645004a431af6ad62997cfed99e2d7
PGP: sig, key (0595DF814E41A6F69334C5E2CAA8D9B8E39EC18C)}

We also have snapshot builds.

Background Music is still in alpha.

Auto-pause music

Background Music automatically pauses your music player when a second audio source is playing, and unpauses the player when the second source has stopped.

The auto-pause feature currently supports following music players:

• iTunes
• Spotify
• VLC
• VOX
• Decibel
• Hermes
• Swinsian
• GPMDP

Adding support for a new music player should only take a few minutes¹ -- see BGMMusicPlayer.h. If you don't know how to program, or just don't feel like it, feel free to create an issue.

Application volume

Background Music provides a volume slider for each application running your system. You can boost quiet applications above their maximum volume.

Recording system audio

You can record system audio with Background Music. With Background Music running, launch QuickTime Player and select File > New Audio Recording (or New Screen Recording, New Movie Recording). Then click the dropdown menu (⌄) next to the record button and select Background Music as the input device.

You can record system audio and a microphone together by creating an aggregate device that combines your input device (usually Built-in Input) with the Background Music device. You can create the aggregate device using the Audio MIDI Setup utility under /Applications/Utilities.

Download

Download version 0.3.1

BackgroundMusic-0.3.1.pkg (571 KB)

Or install using Homebrew

In Terminal, run the following command:

brew cask install background-music

If you want the snapshot version, run:

brew tap homebrew/cask-versions
brew cask install background-music-pre

Build and install

Building should take less than a minute. You need Xcode version 8 or higher.

Paste the following in Terminal:

(set -eo pipefail; URL='https://github.com/kyleneideck/BackgroundMusic/archive/master.tar.gz'; \
    cd $(mktemp -d); echo Downloading $URL to $(pwd); curl -qfL# $URL | gzcat - | tar x && \
    /bin/bash BackgroundMusic-master/build_and_install.sh -w && rm -rf BackgroundMusic-master)

To build and install from source:

1. Clone or download the project.
2. If the project is in a zip, unzip it.
3. Open Terminal and change the directory to the directory containing the project.
4. Run: /bin/bash build_and_install.sh.

The script restarts the system audio process (coreaudiod) at the end of the installation, so you need to pause any applications playing audio.

Manual Build and Install

• Install the virtual audio device Background Music Device.driver to /Library/Audio/Plug-Ins/HAL.

  sudo xcodebuild -project BGMDriver/BGMDriver.xcodeproj \
                  -target "PublicUtility" \
                  RUN_CLANG_STATIC_ANALYZER=0 \
                  clean build
  sudo xcodebuild -project BGMDriver/BGMDriver.xcodeproj \
                  -target "Background Music Device" \
                  RUN_CLANG_STATIC_ANALYZER=0 \
                  DSTROOT="/" \
                  clean install
  

• Install the XPC helper.

  sudo xcodebuild -project BGMApp/BGMApp.xcodeproj \
                  -target BGMXPCHelper \
                  RUN_CLANG_STATIC_ANALYZER=0 \
                  DSTROOT="/" \
                  INSTALL_PATH="$(BGMApp/BGMXPCHelper/safe_install_dir.sh)" \
                  clean install
  

• Install Background Music.app to /Applications (or wherever).

  sudo xcodebuild -project BGMApp/BGMApp.xcodeproj \
                  -target "Background Music" \
                  RUN_CLANG_STATIC_ANALYZER=0 \
                  DSTROOT="/" \
                  clean install
  

• Restart coreaudiod:
  (Audio will stop working until the next step, so you might want to pause any running audio apps.)

  sudo launchctl kill -15 system/com.apple.audio.coreaudiod
  

  or, if that fails

  sudo killall coreaudiod
  

• Run Background Music.app.

Additional detailed installation instructions can be found on the Wiki.

Uninstall

In Terminal, run uninstall.sh(found under /Applications/Background Music.app/Contents/Resources/) to remove Background Music from your system. If you cannot locate uninstall.sh, you can download the project again.

Manual Uninstall

If uninstall.sh doesn't work, try the following methods (and consider filing a bug report):

• Delete Background Music.app from /Applications.

• Delete Background Music Device.driver from /Library/Audio/Plug-Ins/HAL.

• Pause applications that are playing audio, if you can.

• Restart coreaudiod by running the following in Terminal:
  

  sudo launchctl kill -15 system/com.apple.audio.coreaudiod
  

• Run the following in Terminal:
  

  sudo killall coreaudiod
  

• Under System Preferences > Sound, change your default output device at least once. If you only have one device:

  • Use Audio MIDI Setup to create a temporary aggregate device
  • Restart any audio applications that have stopped working
  • Restart your system

Optional

• Delete BGMXPCHelper.xpc from /usr/local/libexec or possibly /Library/Application Support/Background Music.

• Unregister BGMXPCHelper.

  • If you're using OS X 10.11:

    sudo launchctl bootout system /Library/LaunchDaemons/com.bearisdriving.BGM.XPCHelper.plist
    

  • If you're using an earlier version of OS X:

    sudo launchctl unload /Library/LaunchDaemons/com.bearisdriving.BGM.XPCHelper.plist
    

• Delete BGMXPCHelper's launchd.plist.

  sudo rm /Library/LaunchDaemons/com.bearisdriving.BGM.XPCHelper.plist
  

• Delete BGMXPCHelper's user and group.

  sudo dscl . -delete /Users/_BGMXPCHelper
  sudo dscl . -delete /Groups/_BGMXPCHelper
  

Troubleshooting

If Background Music crashes and your audio stops working, open System Preferences > Sound and change your system's default output device to something other than the Background Music device. If it already is, then change the default device and then change it back again.

If this does not work, you might have to uninstall. Consider filing a bug report if you do.

Known issues and solutions

Setting an application's volume above 50% can cause clipping

Set your volume to its maximum level and lower the volumes of other applications.

VLC pauses iTunes or Spotify when playing, and stops Background Music from unpausing your music afterwards

Under VLC's preferences, select Show All. Navigate to Interface > Main interfaces > macosx and change Control external music players to either Do nothing or Pause and resume iTunes/Spotify.

Skype pauses iTunes during calls

To disable this, uncheck Pause iTunes during calls on the General tab of Skype's preferences.

Plugging in or unplugging headphones when Background Music isn't running causes silence in the system audio

Navigate to System Preferences > Sound. Click the Output tab and change your default output device to something other than the Background Music device. Alternatively, press Option + Click on the sound icon within the menu bar to select a different output device.

This happens when macOS remembers that the Background Music device was your default audio device the last time you used (or didn't use) headphones.

A Chrome bug stops Chrome from switching to the Background Music device after you open Background Music

Chrome's audio will still play, but Background Music won't be aware of it.

Some applications play notification sounds that are only just long enough to trigger an auto-pause

Increase the kPauseDelayNSec constant in BGMAutoPauseMusic.mm. It will increase your music's overlap time over other audio, so don't increase it too much. See #5 for details.

Other issues

Some are in listed in TODO.md.

Related projects

• Core Audio User-Space Driver Examples The sample code from Apple that BGMDriver is based on.
• Soundflower - "MacOS system extension that allows applications to pass audio to other applications."
• WavTap - "globally capture whatever your mac is playing—-as simply as a screenshot"
• eqMac, GitHub - "System-wide Audio Equalizer for the Mac"
• llaudio - "An old piece of work to reverse engineer the Mac OSX user/kernel audio interface. Shows how to read audio straight out of the kernel as you would on Darwin (where most the OSX goodness is missing)"
• mute.fm, GitHub (Windows) - Auto-pause music
• Jack OS X - "A Jack audio connection kit implementation for Mac OS X"
• PulseAudio OS X - "PulseAudio for Mac OS X"
• Sound Pusher - "Virtual audio device, real-time encoder and SPDIF forwarder for Mac OS X"
• Zirkonium - "An infrastructure and application for multi-channel sound spatialization on MacOS X."

Non-free

• Audio Hijack - "Capture Audio From Anywhere on Your Mac"
• Sound Siphon, Sound Control - System/app audio recording, per-app volumes, system audio equaliser
• SoundBunny - "Control application volume independently."
• Boom 2 - "The Best Volume Booster & Equalizer For Mac"

License

Copyright © 2016-2019 Background Music contributors. Licensed under GPLv2, or any later version.

Background Music includes code from:

• Core Audio User-Space Driver Examples, original license, Copyright (C) 2013 Apple Inc. All Rights Reserved.
• Core Audio Utility Classes, original license, Copyright (C) 2014 Apple Inc. All Rights Reserved.

---

[1] However, if the music player doesn't support AppleScript, or doesn't support the events Background Music needs (isPlaying, isPaused, play and pause), it can take significantly more effort to add. (And in some cases would require changes to the music player itself.) ↩