Skip to content


Switch branches/tags
This branch is 123 commits behind kyleneideck:master.

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Background Music

macOS audio utility

      Auto-pause music
      Application volume
      Recording system audio
Build and Install
Related Projects


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
Note: 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:

Adding support for a new music player is straight-forward.1 If you don't know how to program, or just don't feel like it, feel free to create an issue. Otherwise, see BGMMusicPlayer.h.

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.


Requires macOS 10.10+.

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

You can download the current prebuilt version of Background Music using the following options. We also have snapshot builds.

Option 1

Download version 0.3.1:

BackgroundMusic-0.3.1.pkg (571 KB)

Option 2

Install using Homebrew by running the following command in Terminal:

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

If you need the latest version of Background Music, you can download from the source on github using the following options. Building should take less than a minute. You need Xcode version 8 or higher.

Option 1

  1. Open Terminal.
  2. Copy and paste the following command into Terminal:
(set -eo pipefail; URL=''; \
    cd $(mktemp -d); echo Downloading $URL to $(pwd); curl -qfL# $URL | gzcat - | tar x && \
    /bin/bash BackgroundMusic-master/ -w && rm -rf BackgroundMusic-master)

This command uses /bin/bash instead of bash in case someone has a nonstandard Bash in their $PATH. However, it doesn't do this for tar or curl. In addition, doesn't call programs by absolute paths. This command also uses gzcat - | tar x instead of tar xz because gzcat will also check the file's integrity (gzip files include a checksum), and will ensure that a half-downloaded copy of doesn't run.

Option 2

If you are not comfortable using the single-line command above, you can manually build and install from the source on github using the following steps:

  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

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

To manually build and install, see


To uninstall Background Music from your system, follow these steps:

  1. Open Terminal.
  2. To locate, run:cd /Applications/Background\
  3. Run: sh

If you cannot locate, you can download the project again.

To manually uninstall, see


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 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

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)"
  •, 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."


  • 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"


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

Background Music includes code from:

[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.)


Background Music, a macOS audio utility: automatically pause your music, set individual apps' volumes and record system audio.



Unknown, Unknown licenses found

Licenses found






No packages published


  • C++ 55.8%
  • Objective-C 15.1%
  • C 13.7%
  • Objective-C++ 10.7%
  • Shell 4.0%
  • JavaScript 0.4%
  • Other 0.3%