BGM.xcworkspace | ||
BGMApp | ||
BGMDriver | ||
Images | ||
pkg | ||
SharedSource | ||
.editorconfig | ||
.gitignore | ||
.travis.yml | ||
build_and_install.sh | ||
CONTRIBUTING.md | ||
DEVELOPING.md | ||
LICENSE | ||
LICENSE-Apple-Sample-Code | ||
MANUAL-INSTALL.md | ||
MANUAL-UNINSTALL.md | ||
package.sh | ||
README.md | ||
TODO.md | ||
uninstall.sh |
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 another audio source is 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:
Adding support for a new music player should only take a few minutes1 -- 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:
- Clone or download the project.
- If the project is in a zip, unzip it.
- Open Terminal and change the directory to the directory containing the project.
- 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:
-
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.) ↩