2016-02-19 05:25:34 +00:00
|
|
|
<!-- vim: set tw=120: -->
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
# Background Music
|
2016-11-12 09:54:04 +00:00
|
|
|
##### macOS audio utility
|
2016-02-19 05:25:34 +00:00
|
|
|
|
2016-02-24 08:14:12 +00:00
|
|
|
|
2016-02-19 05:25:34 +00:00
|
|
|
|
|
|
|
|
- Automatically pauses your music player when other audio starts playing and unpauses it afterwards
|
|
|
|
|
- Per-application volume, boost quiet apps
|
2017-04-09 08:25:27 +00:00
|
|
|
- Record system audio <br><br>
|
2016-02-19 05:25:34 +00:00
|
|
|
- No restart required to install
|
|
|
|
|
- Runs entirely in userspace
|
|
|
|
|
|
2017-06-18 11:07:42 +00:00
|
|
|
## Download
|
2016-02-19 05:25:34 +00:00
|
|
|
|
2017-06-18 12:03:39 +00:00
|
|
|
### Version 0.1.1
|
2017-06-18 11:07:42 +00:00
|
|
|
|
2017-06-18 12:03:39 +00:00
|
|
|
<a href="https://github.com/kyleneideck/BackgroundMusic/releases/download/v0.1.1/BackgroundMusic-0.1.1.pkg"><img
|
|
|
|
|
src="Images/README/pkg-icon.png" width="32" height="32" align="absmiddle" />
|
|
|
|
|
BackgroundMusic-0.1.1.pkg</a> (473 KB)
|
|
|
|
|
|
|
|
|
|
Still very much in alpha. Not code signed, so you'll have to **right-click it and choose "Open"**.
|
2017-06-18 11:07:42 +00:00
|
|
|
|
2017-06-18 12:16:09 +00:00
|
|
|
**Requires OS X 10.10+**. Should work on 10.9, but I haven't tried it.
|
2017-06-18 11:07:42 +00:00
|
|
|
|
2017-06-18 12:03:39 +00:00
|
|
|
> <sub>MD5: e02988e6b32eafa88b99c4da33e7fe56</sub><br/>
|
|
|
|
|
> <sub>SHA256: 7ce875bb00fdeb2b5b363aa92367b3fa096d18cb02a02c461d5df66307ab1088</sub><br/>
|
|
|
|
|
> <sub>PGP:
|
|
|
|
|
> [sig](https://github.com/kyleneideck/BackgroundMusic/releases/download/v0.1.1/BackgroundMusic-0.1.1.pkg.asc),
|
|
|
|
|
> [key (0595DF814E41A6F69334C5E2CAA8D9B8E39EC18C)](https://bearisdriving.com/kyle-neideck.gpg)</sub>
|
2016-02-19 05:25:34 +00:00
|
|
|
|
2018-02-24 00:47:27 +00:00
|
|
|
We also have [snapshot builds](https://github.com/kyleneideck/BackgroundMusic/releases).
|
|
|
|
|
|
2016-02-19 05:25:34 +00:00
|
|
|
## Auto-pause music
|
|
|
|
|
|
|
|
|
|
Background Music can pause your music player app when other audio starts playing and unpause it afterwards. The idea is
|
|
|
|
|
that when I'm listening to music and pause it to watch a video or something I always forget to unpause it afterwards. So
|
|
|
|
|
this keeps me from wearing headphones for hours listening to nothing.
|
|
|
|
|
|
2016-11-12 09:54:04 +00:00
|
|
|
So far iTunes, [Spotify](https://www.spotify.com), [VLC](https://www.videolan.org/vlc/),
|
|
|
|
|
[VOX](https://coppertino.com/vox/mac), [Decibel](https://sbooth.org/Decibel/) and [Hermes](http://hermesapp.org/) are
|
|
|
|
|
supported. Adding support for a new music player should only take a few minutes<sup id="a1">[1](#f1)</sup> -- see
|
2017-04-09 08:25:27 +00:00
|
|
|
[BGMMusicPlayer.h](BGMApp/BGMApp/Music%20Players/BGMMusicPlayer.h). If you don't know how to program, or just don't feel
|
2016-11-12 09:54:04 +00:00
|
|
|
like it, create an issue and I'll try to add it for you.
|
2016-02-19 05:25:34 +00:00
|
|
|
|
|
|
|
|
## App volumes
|
|
|
|
|
|
|
|
|
|
Background Music has a volume slider for each app running on the system. I mostly use this to boost quiet apps above
|
|
|
|
|
their normal maximum volume.
|
|
|
|
|
|
|
|
|
|
## Recording system audio
|
|
|
|
|
|
|
|
|
|
With Background Music running, open QuickTime Player and go `File > New Audio Recording...` (or movie/screen). Then
|
2017-06-25 02:39:34 +00:00
|
|
|
click the arrow next to the record button that looks like `⌄` and select `Background Music` as the input device.
|
2016-02-19 05:25:34 +00:00
|
|
|
|
2016-02-23 08:34:56 +00:00
|
|
|
You should be able to record system audio and a microphone together by creating an [aggregate
|
|
|
|
|
device](https://support.apple.com/en-us/HT202000) that combines your input device (usually Built-in Input) with
|
2017-06-25 02:39:34 +00:00
|
|
|
the Background Music device. You can create the aggregate device using the Audio MIDI Setup utility from
|
2016-02-23 08:34:56 +00:00
|
|
|
`/Applications/Utilities`.
|
|
|
|
|
|
2017-06-18 11:07:42 +00:00
|
|
|
## Install from source
|
2016-04-29 03:18:52 +00:00
|
|
|
|
2017-06-18 12:16:09 +00:00
|
|
|
Building should take less than a minute, but you'll need [Xcode](https://developer.apple.com/xcode/download/) version
|
2017-12-26 12:04:20 +00:00
|
|
|
8 or higher.
|
2016-04-29 03:18:52 +00:00
|
|
|
|
|
|
|
|
If you're comfortable with it, you can just paste the following at a Terminal prompt.
|
|
|
|
|
|
2017-04-09 08:25:27 +00:00
|
|
|
<!--
|
|
|
|
|
Uses /bin/bash instead of just bash on the off chance that someone has a non standard Bash in their $PATH, but
|
|
|
|
|
it doesn't do that for Tar or cURL because I'm fairly sure any versions of them should work here. That said,
|
|
|
|
|
build_and_install.sh doesn't call most things by absolute paths yet anyway.
|
|
|
|
|
|
|
|
|
|
Uses "gzcat - | tar x" instead of "tar xz" because gzcat will also check the file's integrity (gzip files
|
|
|
|
|
include a checksum), which makes sure we can't run a half-downloaded copy of build_and_install.sh.
|
|
|
|
|
-->
|
2016-04-29 03:18:52 +00:00
|
|
|
```shell
|
|
|
|
|
(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 && \
|
2017-02-16 11:46:57 +00:00
|
|
|
/bin/bash BackgroundMusic-master/build_and_install.sh -w && rm -rf BackgroundMusic-master)
|
2016-04-29 03:18:52 +00:00
|
|
|
```
|
|
|
|
|
|
2017-06-18 12:16:09 +00:00
|
|
|
Otherwise, to build and install from source:
|
2016-02-19 05:25:34 +00:00
|
|
|
|
2016-12-27 18:00:52 +00:00
|
|
|
- Clone or [download](https://github.com/kyleneideck/BackgroundMusic/archive/master.zip) the project.
|
|
|
|
|
- If the project is in a zip, unzip it.
|
2016-12-27 18:04:54 +00:00
|
|
|
- Open `Terminal.app` and [change directory](https://github.com/0nn0/terminal-mac-cheatsheet#core-commands) to the
|
|
|
|
|
directory containing the project.
|
2016-04-29 03:18:52 +00:00
|
|
|
- Run the following the command: `/bin/bash build_and_install.sh`.
|
2016-04-19 13:00:14 +00:00
|
|
|
|
2016-12-27 18:00:52 +00:00
|
|
|
The script restarts the system audio process (coreaudiod) at the end of the installation, so you might want to pause any
|
|
|
|
|
apps playing audio.
|
2016-02-19 05:25:34 +00:00
|
|
|
|
2016-12-27 18:00:52 +00:00
|
|
|
Additional detailed installation instructions can be found on [the
|
|
|
|
|
Wiki](https://github.com/kyleneideck/BackgroundMusic/wiki/Installation).
|
2016-04-28 17:22:38 +00:00
|
|
|
|
2016-02-19 05:25:34 +00:00
|
|
|
## Uninstall
|
|
|
|
|
|
2017-06-18 11:07:42 +00:00
|
|
|
- Run the `uninstall.sh` script (using `Terminal.app`) to remove Background Music from your system. You should be able
|
|
|
|
|
to find it in `/Applications/Background Music.app/Contents/Resources/uninstall.sh`, but if not you can [download the
|
|
|
|
|
project](https://github.com/kyleneideck/BackgroundMusic/archive/master.zip) again.
|
2016-02-19 05:25:34 +00:00
|
|
|
- Go to the Sound section in System Preferences and change your default output device at least once. (If you only have
|
|
|
|
|
one device now, either use `Audio MIDI Setup.app` to create a temporary aggregate device, restart any audio apps that
|
|
|
|
|
have stopped working or just restart your system.)
|
|
|
|
|
|
2016-04-19 15:51:03 +00:00
|
|
|
### Manual Uninstall
|
|
|
|
|
|
2016-04-23 04:21:02 +00:00
|
|
|
Try following the instructions in [`MANUAL-UNINSTALL.md`](MANUAL-UNINSTALL.md) if `uninstall.sh` fails. (You might
|
|
|
|
|
consider submitting a bug report, too.)
|
2016-04-19 15:51:03 +00:00
|
|
|
|
2016-02-19 05:25:34 +00:00
|
|
|
## Troubleshooting
|
|
|
|
|
|
2017-06-25 02:39:34 +00:00
|
|
|
If Background Music crashes and your audio stops working, open the Sound panel in System Preferences and change your
|
|
|
|
|
system's default output device to something other than the Background Music device. If it already is, it might help to
|
|
|
|
|
change the default device and then change it back again.
|
|
|
|
|
|
|
|
|
|
Failing that, you might have to uninstall. Consider filing a bug report if you do.
|
2016-02-19 05:25:34 +00:00
|
|
|
|
|
|
|
|
## Known issues
|
|
|
|
|
|
|
|
|
|
- VLC automatically pauses iTunes/Spotify when it starts playing something, but that stops Background Music from
|
|
|
|
|
unpausing your music afterwards. To workaround it, open VLC's preferences, click `Show All`, go `Interface` > `Main
|
|
|
|
|
interfaces` > `macosx` and change `Control external music players` to either `Do nothing` or `Pause and resume
|
|
|
|
|
iTunes/Spotify`.
|
|
|
|
|
|
|
|
|
|
Similarly, Skype pauses iTunes during calls. If you want to disable that, uncheck `Pause iTunes during calls` on the
|
|
|
|
|
General tab of Skype's preferences.
|
|
|
|
|
- Plugging in or unplugging headphones when Background Music isn't running can silence system audio. To fix it, go to
|
|
|
|
|
the Sound section in System Preferences, click the Output tab and change your default output device to something other
|
2017-06-25 02:39:34 +00:00
|
|
|
than the Background Music device. Alternatively, you may Option+Click on the Sound icon in the menu bar to select a
|
2016-12-28 15:25:44 +00:00
|
|
|
different output device.
|
2016-02-19 05:25:34 +00:00
|
|
|
|
2017-06-25 02:39:34 +00:00
|
|
|
This happens when macOS remembers that the Background Music device was your default audio device the last time you
|
|
|
|
|
last used (or didn't use) headphones.
|
|
|
|
|
- [A Chrome bug](https://bugs.chromium.org/p/chromium/issues/detail?id=557620) can stop 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
|
2016-02-19 05:25:34 +00:00
|
|
|
aware of it.
|
2016-04-23 04:21:02 +00:00
|
|
|
- Some apps play notification sounds that are only just long enough to trigger an auto-pause. The only workaround right
|
2016-12-28 15:25:44 +00:00
|
|
|
now is to increase the `kPauseDelayNSec` constant in [BGMAutoPauseMusic.mm](/BGMApp/BGMApp/BGMAutoPauseMusic.mm).
|
|
|
|
|
That will make your music overlap the other audio for longer, though, so you don't want to increase it too much. See
|
2016-04-23 04:21:02 +00:00
|
|
|
[#5](https://github.com/kyleneideck/BackgroundMusic/issues/5) for details.
|
2016-12-28 15:25:44 +00:00
|
|
|
- Plenty more. Some are in listed in [TODO.md](/TODO.md).
|
2016-02-19 05:25:34 +00:00
|
|
|
|
|
|
|
|
## Related projects
|
|
|
|
|
|
|
|
|
|
- [Core Audio User-Space Driver
|
|
|
|
|
Examples](https://developer.apple.com/library/mac/samplecode/AudioDriverExamples/Introduction/Intro.html)
|
2016-04-23 04:21:02 +00:00
|
|
|
The sample code from Apple that BGMDriver is based on.
|
2016-02-19 05:25:34 +00:00
|
|
|
- [Soundflower](https://github.com/mattingalls/Soundflower) - "MacOS system extension that allows applications to pass
|
|
|
|
|
audio to other applications."
|
|
|
|
|
- [WavTap](https://github.com/pje/WavTap) - "globally capture whatever your mac is playing—-as simply as a screenshot"
|
2017-12-10 21:49:33 +00:00
|
|
|
- [eqMac](http://www.bitgapp.com/eqmac/), [GitHub](https://github.com/nodeful/eqMac2) - "System-wide Audio Equalizer for the Mac"
|
2016-02-19 05:25:34 +00:00
|
|
|
- [llaudio](https://github.com/mountainstorm/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](http://www.mute.fm), [GitHub](https://github.com/jaredsohn/mutefm) (Windows) - Auto-pause music
|
|
|
|
|
- [Jack OS X](http://www.jackosx.com) - "A Jack audio connection kit implementation for Mac OS X"
|
|
|
|
|
- [PulseAudio OS X](https://github.com/zonque/PulseAudioOSX) - "PulseAudio for Mac OS X"
|
2016-04-23 04:21:02 +00:00
|
|
|
- [Sound Pusher](https://github.com/q-p/SoundPusher) - "Virtual audio device, real-time encoder and SPDIF forwarder for
|
|
|
|
|
Mac OS X"
|
2016-04-18 15:40:40 +00:00
|
|
|
- [Zirkonium](https://code.google.com/archive/p/zirkonium) - "An infrastructure and application for multi-channel sound
|
2016-02-19 05:25:34 +00:00
|
|
|
spatialization on MacOS X."
|
|
|
|
|
|
2016-04-23 04:21:02 +00:00
|
|
|
### Non-free
|
|
|
|
|
|
2016-04-26 11:04:13 +00:00
|
|
|
- [Audio Hijack](https://rogueamoeba.com/audiohijack/) - "Capture Audio From Anywhere on Your Mac"
|
2017-05-07 05:17:48 +00:00
|
|
|
- [Sound Siphon](https://staticz.com/soundsiphon/), [Sound Control](https://staticz.com/soundcontrol/) - System/app audio recording, per-app volumes, system audio equaliser
|
2016-04-23 04:21:02 +00:00
|
|
|
- [SoundBunny](https://www.prosofteng.com/soundbunny-mac-volume-control/) - "Control application volume independently."
|
|
|
|
|
- [Boom 2](http://www.globaldelight.com/boom/index.php) - "The Best Volume Booster & Equalizer For Mac"
|
|
|
|
|
|
2016-02-19 05:25:34 +00:00
|
|
|
## License
|
|
|
|
|
|
2018-06-04 15:13:14 +00:00
|
|
|
Copyright © 2016-2018 [Background Music contributors](https://github.com/kyleneideck/BackgroundMusic/graphs/contributors).
|
2016-11-12 13:06:58 +00:00
|
|
|
Licensed under [GPLv2](https://www.gnu.org/licenses/gpl-2.0.html), or any later version.
|
2016-11-12 09:54:04 +00:00
|
|
|
|
2016-12-28 15:25:44 +00:00
|
|
|
Background Music includes code from:
|
|
|
|
|
|
|
|
|
|
- [Core Audio User-Space Driver
|
|
|
|
|
Examples](https://developer.apple.com/library/mac/samplecode/AudioDriverExamples/Introduction/Intro.html), [original
|
|
|
|
|
license](LICENSE-Apple-Sample-Code), Copyright (C) 2013 Apple Inc. All Rights Reserved.
|
|
|
|
|
- [Core Audio Utility
|
|
|
|
|
Classes](https://developer.apple.com/library/content/samplecode/CoreAudioUtilityClasses/Introduction/Intro.html),
|
|
|
|
|
[original license](LICENSE-Apple-Sample-Code), Copyright (C) 2014 Apple Inc. All Rights Reserved.
|
|
|
|
|
|
2016-11-12 09:54:04 +00:00
|
|
|
----
|
|
|
|
|
|
|
|
|
|
<b id="f1">[1]</b> 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.) [↩](#a1)
|
|
|
|
|
|
|
|
|
|
|
