search

kyleneideck / BackgroundMusic

Background Music, a macOS audio utility: automatically pause your music, set individual apps' volumes and record system audio.
GNU General Public License v2.0
15.51k stars 664 forks source link
audio audio-utility cpp macos objective-c

readme

Background Music

macOS audio utility

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

Overview

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 usually straightforward.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.

Download

Requires macOS 10.13+.

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

Option 1

Download version 0.4.3:

<img src="Images/README/pkg-icon.png" width="32" height="32" align="absmiddle" /> BackgroundMusic-0.4.3.pkg (771 KB)

MD5: 8c3bfe26c9cdf27365b9843f719ef188
SHA256: c1c48a37c83af44ce50bee68879856c96b2f6c97360ce461b1c7d653515be7fd
PGP: sig, key (0595DF814E41A6F69334C5E2CAA8D9B8E39EC18C)

Option 2

Install using Homebrew by running the following command in Terminal:

brew install --cask background-music

If you want the latest snapshot version, run:

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

Run / Configure

Just run Applications > Background Music.app! Background Music sets itself as your default output device under System Settings > Sound when it starts up (and sets it back on Quit).

Launch at Startup (Optional)

Add Background Music to System Settings > General > Login Items.

Installing from Source Code

Background Music usually takes less than a minute to build. You need Xcode version 10 or higher.

Option 1

  1. Open Terminal.
  2. Copy and paste the following command into 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)
More info... 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, `build_and_install.sh` 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 `build_and_install.sh` doesn't run.

Option 2

  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 pause any applications playing audio if you can.

To manually build and install, see MANUAL_INSTALL.md.

Uninstall

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

  1. Open Terminal.
  2. To locate uninstall.sh, run: cd /Applications/Background\ Music.app/Contents/Resources/.
  3. Run: bash uninstall.sh.

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

To manually uninstall, see MANUAL_UNINSTALL.md.

Troubleshooting

If Background Music crashes and your audio stops working, open System Settings > 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.

Make sure you allow "microphone access" when you first run Background Music. If you denied it, go to System Settings > Security & Privacy > Privacy > Microphone, find Background Music in the list and check the box next to it. Background Music doesn't actually listen to your microphone. It needs the permission because it gets your system audio from its virtual input device, which macOS counts as a microphone. (We're working on it in #177.)

If the volume slider for an app isn't working, try looking in More Apps for entries like Some App (Helper). For some meeting or video chat apps, you may need to do this to change the current meeting volume.

Known issues and solutions

Many other issues are listed in TODO.md and in GitHub Issues.

Related projects

Non-free

License

Copyright © 2016-2024 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.) ↩