Merge pull request #785 from khipp/update-homebrew

Update Homebrew installation instructions

.editorconfig

@@ -0,0 +1,15 @@
+# This file was added to get GitHub to display our source code correctly when
+# it has mixed tabs and spaces. (I didn't realise the sample code BGMDriver is
+# based on used tabs and it's too late to fix it now.)
+#
+# See http://editorconfig.org.
+
+# This is the top-most .editorconfig file.
+root = true
+
+# Set tabs to the width of 4 spaces in C, C++, Objective-C and Objective-C++
+# source files.
+[*.{h,c,cpp,m,mm}]
+tab_width = 4
+
+

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,49 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+## Example bug report template
+
+> Don't worry if you have trouble getting some of this info. Just leave it out.
+
+**Description of the bug**
+> Please don't just say it's "not working".
+
+**Steps to reproduce**
+> Steps to reproduce the bug. This usually doesn't need to be super detailed.
+1. Go to '...'
+2. Click on '...'
+3. See error message '...'
+
+**Versions**
+> Please complete the following information.
+ - Background Music: [e.g. "0.4.3" or "0.4.0-SNAPSHOT-c0ab98b". `Preferences > About Background Music`]
+ - macOS: [e.g. "11.3 Beta (20E5172i)" or "Big Sur". ` > About This Mac`]
+
+**Hardware**
+> Delete this part if you think it's probably not necessary.
+ - Computer: [e.g. "MacBook Pro (13-inch, 2016, Four Thunderbolt 3 Ports)". ` > About This Mac`]
+ - Audio Device: [e.g. "Built-in Output. Manufacturer: Apple Inc. Output Channels: 2 [...]". `System Information app > Hardware > Audio`]
+
+**Debug logs**
+> If you think the developers might not be able to reproduce the bug on their computers, e.g. because an important feature is completely broken and they would have noticed, it can help to include [debug logs](https://github.com/kyleneideck/BackgroundMusic/wiki/Getting-Debug-Logs). This takes a little effort, so feel free to leave it out at first.
+
+[Debug logs attached here](https://github.com/example/background-music-debug-logs.txt)
+
+**Other info**
+> Anything else you want to add?
+
+---
+
+> Tips
+> (Delete this section before posting.)
+>  - https://github.com/kyleneideck/BackgroundMusic#troubleshooting
+>  - Try the latest SNAPSHOT version from https://github.com/kyleneideck/BackgroundMusic/releases (if it's newer than the latest non-SNAPSHOT release).
+>  - If your bug is one of these common issues, consider leaving a comment or a +1 (👍) on an existing issue:
+>     - Background Music currently only supports audio devices with two channels. Bluetooth devices often only have one.
+>     - Volumes having no effect for certain apps: Microsoft Teams ([workaround](https://github.com/kyleneideck/BackgroundMusic/issues/268#issuecomment-604977210)), Zoom ([workaround](https://github.com/kyleneideck/BackgroundMusic/issues/396#issuecomment-741992157)), Discord ([workaround](https://github.com/kyleneideck/BackgroundMusic/issues/210#issuecomment-507048957), [see also](https://github.com/kyleneideck/BackgroundMusic/issues/267#issuecomment-617327850)), Chrome (sometimes)

.github/ISSUE_TEMPLATE/other.md

@@ -0,0 +1,10 @@
+---
+name: Other
+about: Feature request, question, support request or anything else
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+> There's no template for this issue type. I just wanted to make it clear that it's OK to submit other types of issues.

.github/workflows/build-test-release.yml

@@ -0,0 +1,216 @@
+# TODO: Split this into multiple .yml files? Multiple jobs?
+name: Build, Test and Release
+
+on:
+  push:
+    branches:
+      - '*'
+    tags:
+      - '*'
+  pull_request:
+    branches:
+      - '*'
+
+jobs:
+  # Build and test in the same job because the UI tests expect BGMDriver to be installed.
+  build-and-test:
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      matrix:
+        # TODO: Add older macOS versions.
+        os:
+          - macos-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Work in a case-sensitive disk image.
+        # This lets us catch failures that only happen on case-sensitive filesystems.
+        run: |
+          hdiutil create \
+            -type SPARSEBUNDLE \
+            -fs 'Case-sensitive Journaled HFS+' \
+            -volname bgmbuild \
+            -nospotlight \
+            -verbose \
+            -attach \
+            -size 100m \
+            bgmbuild.dmg
+          sudo cp -r . /Volumes/bgmbuild
+          cd /Volumes/bgmbuild
+      - name: Install coreutils for actions/runner/issues/884 workaround.
+        # See https://github.com/actions/runner/issues/884#issuecomment-1018851327
+        run: brew install coreutils
+      - name: Build and install Background Music.
+        run: |
+          # `sudo` and `tput` expect this to be set.
+          export TERM=xterm-256color
+          genv --default-signal=PIPE yes | sudo ./build_and_install.sh
+      - name: Print the log file.
+        if: always()
+        run: cat build_and_install.log
+      - name: Log some checksums.
+        run: 'find */build/Release/*/ -type f -exec md5 {} \;'
+      - name: Log the installed audio devices and their IDs.
+        run: |
+          system_profiler SPAudioDataType
+          say -a '?'
+      - name: Check the BGM dirs and files were installed.
+        run: |
+          # These commands fail if the dir/file isn't found.
+          ls -la "/Applications/Background Music.app"
+          ls -la "/Library/Audio/Plug-Ins/HAL/Background Music Device.driver"
+          ls -la "/usr/local/libexec/BGMXPCHelper.xpc" \
+            || ls -la "/Library/Application Support/Background Music/BGMXPCHelper.xpc"
+          ls -la "/Library/LaunchDaemons/com.bearisdriving.BGM.XPCHelper.plist"
+      - name: Close BGMApp (which the install script opened).
+        run: >-
+          osascript -e 'tell application "Background Music" to quit'
+          || killall "Background Music"
+      - name: Skip the UI tests. (They don't work on GitHub Actions yet.)
+        run: BGMApp/BGMAppTests/UITests/skip-ui-tests.py
+      - name: Run the tests.
+        run: |
+          echo '::group::BGMDriver Tests'
+          xcodebuild \
+            -quiet \
+            -workspace BGM.xcworkspace \
+            -scheme 'Background Music Device' \
+            test
+          echo '::endgroup::'
+
+          echo '::group::BGMXPCHelper Tests'
+          xcodebuild \
+            -quiet \
+            -workspace BGM.xcworkspace \
+            -scheme 'BGMXPCHelper' \
+            test
+          echo '::endgroup::'
+
+          # Grant BGMApp authorization to use input devices.
+          # This is necessary for the UI tests because accepting the "Background Music would like to
+          # use the microphone" dialog programmatically isn't reliable.
+          # TODO: Commented out because we would need to generate the csreq (codesign signature)
+          #       value to match the BGMApp bundle the tests will run against.
+          # dbPath="$HOME/Library/Application Support/com.apple.TCC/TCC.db"
+          # values="'kTCCServiceMicrophone','com.bearisdriving.BGM.App',0,2,2,1,X'FADE0C000000004800000001000000070000000800000014545ABE68FAF437700B14984BB24117EDDA1BBF2C0000000800000014386FB63B9CD6BA6E83CEDEAF4EDEE177C1FAEA92',NULL,NULL,'UNUSED',NULL,0,1652845317"
+          # sqlQuery="INSERT OR IGNORE INTO access VALUES($values);"
+          # sqlite3 "$dbPath" "$sqlQuery" || (echo "Failed to modify $dbPath"; exit 1)
+          # # Log the added TCC.db entry.
+          # sqlite3 "$dbPath" "select * from access where client like '%BGM%';"
+
+          echo '::group::BGMApp Tests'
+          # TODO: Commented out in case it uses too much CPU.
+          # log stream --info \
+          #   --predicate 'process == "coreaudiod" or
+          #                process == "Background Music" or
+          #                process == "BGMXPCHelper" or
+          #                composedMessage contains[cd] "Background Music" or
+          #                composedMessage contains "BGM"' > app.log &
+          xcodebuild \
+            -quiet \
+            -workspace BGM.xcworkspace \
+            -scheme 'Background Music' \
+            test
+          echo '::endgroup::'
+      - name: Upload the test results.
+        if: always()
+        uses: actions/upload-artifact@v3
+        with:
+          name: bgm-test-results
+          path: |
+            /Users/runner/Library/Developer/Xcode/DerivedData/*/Logs/Test/*.xcresult
+            app.log
+            /Users/runner/Library/Logs/CrashReporter/*
+            /Users/runner/Library/Logs/DiagnosticReports/*
+      - name: Uninstall Background Music.
+        run: |
+          # `tput` expects this to be set.
+          export TERM=xterm-256color
+          genv --default-signal=PIPE yes | sudo ./uninstall.sh
+      - name: Check the BGM dirs and files were removed.
+        run: |
+          if ls -la "/Applications/Background Music.app"; then exit 1; fi
+          if ls -la "/Library/Audio/Plug-Ins/HAL/Background Music Device.driver"; then exit 1; fi
+          if ls -la "/usr/local/libexec/BGMXPCHelper.xpc"; then exit 1; fi
+          if ls -la "/Library/Application Support/Background Music/BGMXPCHelper.xpc"; then
+            exit 1
+          fi
+          if ls -la "/Library/LaunchDaemons/com.bearisdriving.BGM.XPCHelper.plist"; then exit 1; fi
+  release:
+    runs-on: macos-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Build the .pkg installer.
+        run: |
+          # `sudo` and `tput` expect this to be set.
+          export TERM=xterm-256color
+          # If this build is for a tag with "DEBUG" in its name, build a debug package. (More
+          # detailed logging, no optimization, etc.)
+          if [[ "$GITHUB_REF" =~ .*DEBUG.* ]]; then
+            sudo ./package.sh -d
+          else
+            sudo ./package.sh
+          fi
+      - name: Install the .pkg.
+        # Delete archives/ first because it contains a copy of Background Music.app.
+        # Background Music.app is "relocatable", which means that if the user moves it and then
+        # installs a new version, macOS will put the new version in the same place. This makes sure
+        # the installer puts Background Music.app in /Applications so the build won't fail when we
+        # check that later.
+        #
+        # package.sh puts the archives in a zipfile next to the .pkg, so we can still upload them
+        # after deleting the directory here.
+        #
+        # TODO: On TravisCI, this was failing for debug builds. We couldn't figure out why, so we
+        #       might have to ignore that with
+        #       || [[ "$GITHUB_REF" =~ .*DEBUG.* ]]
+        run: |
+          sudo rm -rf archives
+          sudo installer \
+            -pkg Background-Music-*/BackgroundMusic-*.pkg \
+            -target / \
+            -verbose \
+            -dumplog
+      - name: Print the installer logs.
+        if: always()
+        # This trims the start of the log to save space.
+        run: grep -E -A 9999 -B 20 'Background.?Music' /var/log/install.log
+      - name: Check the BGM dirs and files were installed.
+        if: always()
+        run: |
+          ls -la "/Applications/Background Music.app"
+          ls -la "/Library/Audio/Plug-Ins/HAL/Background Music Device.driver"
+          ls -la "/usr/local/libexec/BGMXPCHelper.xpc" \
+            || ls -la "/Library/Application Support/Background Music/BGMXPCHelper.xpc"
+          ls -la "/Library/LaunchDaemons/com.bearisdriving.BGM.XPCHelper.plist"
+      - name: Upload the .pkg installer and archives.
+        if: always()
+        uses: actions/upload-artifact@v3
+        with:
+          name: pkg-installer
+          path: Background-Music-*
+      - name: Upload the log file from the package.sh build.
+        if: always()
+        uses: actions/upload-artifact@v3
+        with:
+          name: build-and-install-log-for-pkg
+          path: build_and_install.log
+# TODO: Create a GitHub release. This is the Travis YAML that was handling it:
+# deploy:
+#  provider: releases
+#  api_key:
+#    secure: j5Gd[...]
+#  file_glob: true
+#  file: Background-Music-*/*
+#  skip_cleanup: true
+#  name: $TRAVIS_TAG
+#  prerelease: true
+#  draft: true
+#  on:
+#    repo: kyleneideck/BackgroundMusic
+#    tags: true
+#    # TODO: Use "condition" to build master and tags?
+#    condition: $DEPLOY = true

.gitignore

@@ -2,6 +2,14 @@
 .*.swp
 /BGMDriver/BGMDriver/quick_install.conf
 /build_and_install.log
+.idea/
+tags
+cmake-build-debug/
+/Background-Music-*/
+BGM.xcworkspace/xcshareddata/IDEWorkspaceChecks.plist
+Images/*.aux
+Images/*.log
+/archives/
 
 # Everything below is from https://github.com/github/gitignore/blob/master/Objective-C.gitignore
 

.travis.yml

@@ -1,42 +0,0 @@
-language: objective-c
-matrix:
-  include:
-    - os: osx
-      osx_image: xcode8
-      xcode_sdk: macosx10.11
-      sudo: required
-    - os: osx
-      osx_image: xcode7.3
-      xcode_sdk: macosx10.11
-      sudo: required
-    - os: osx
-      osx_image: xcode7.1
-      xcode_sdk: macosx10.10
-      sudo: required
-branches:
-  only:
-    - master
-install:
-# Install Apple's NullAudio device. Travis' VMs don't have any audio devices installed.
-  - sudo xcodebuild -project BGMApp/BGMAppTests/NullAudio/AudioDriverExamples.xcodeproj -target NullAudio DSTROOT="/" install
-  - sudo launchctl kickstart -kp system/com.apple.audio.coreaudiod || sudo killall coreaudiod
-script:
-# Build in a case-sensitive disk image to catch failures that only happen on case-sensitive filesystems.
-  - hdiutil create -type SPARSEBUNDLE -fs 'Case-sensitive Journaled HFS+' -volname bgmbuild -nospotlight -verbose -attach -size 50m bgmbuild.dmg
-  - sudo cp -r . /Volumes/bgmbuild
-  - cd /Volumes/bgmbuild
-# Install Background Music
-  - yes | ./build_and_install.sh
-  - cat build_and_install.log
-  - find */build/Release/*/ -type f -exec md5 {} \;
-# Log the installed audio devices...
-  - system_profiler SPAudioDataType
-# ...and their IDs.
-  - say -a '?'
-# Close BGMApp (which the install script opened).
-  - osascript -e 'tell application "Background Music" to quit'
-  - xcodebuild -workspace BGM.xcworkspace -scheme 'Background Music Device' test
-  - xcodebuild -workspace BGM.xcworkspace -scheme 'Background Music' test
-  - xcodebuild -workspace BGM.xcworkspace -scheme 'BGMXPCHelper' test
-  - yes | ./uninstall.sh
-  - ls /Applications /Library/Audio/Plug-Ins/HAL /usr/local/libexec /Library/Application\ Support/Background\ Music

BGM.xcworkspace/contents.xcworkspacedata

@@ -10,15 +10,39 @@
    <FileRef
       location = "group:README.md">
    </FileRef>
+   <FileRef
+      location = "group:MANUAL-INSTALL.md">
+   </FileRef>
+   <FileRef
+      location = "group:MANUAL-UNINSTALL.md">
+   </FileRef>
    <FileRef
       location = "group:TODO.md">
    </FileRef>
+   <FileRef
+      location = "group:DEVELOPING.md">
+   </FileRef>
    <FileRef
       location = "group:CONTRIBUTING.md">
    </FileRef>
    <FileRef
       location = "group:LICENSE">
    </FileRef>
+   <FileRef
+      location = "group:LICENSE-Apple-Sample-Code">
+   </FileRef>
+   <FileRef
+      location = "group:build_and_install.sh">
+   </FileRef>
+   <FileRef
+      location = "group:uninstall.sh">
+   </FileRef>
+   <FileRef
+      location = "group:package.sh">
+   </FileRef>
+   <FileRef
+      location = "group:pkg">
+   </FileRef>
    <FileRef
       location = "group:Images">
    </FileRef>

BGMApp/BGMApp.xcodeproj/xcshareddata/xcschemes/BGMXPCHelper.xcscheme

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <Scheme
-   LastUpgradeVersion = "0810"
+   LastUpgradeVersion = "0900"
    version = "1.3">
    <BuildAction
       parallelizeBuildables = "YES"
@@ -26,7 +26,42 @@
       buildConfiguration = "Debug"
       selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
       selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
-      shouldUseLaunchSchemeArgsEnv = "YES">
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      enableAddressSanitizer = "YES"
+      enableASanStackUseAfterReturn = "YES"
+      enableUBSanitizer = "YES"
+      codeCoverageEnabled = "YES"
+      onlyGenerateCoverageForSpecifiedTargets = "YES">
+      <MacroExpansion>
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "27379B8E1C7F57DA0084A24C"
+            BuildableName = "BGMXPCHelper.xpc"
+            BlueprintName = "BGMXPCHelper"
+            ReferencedContainer = "container:BGMApp.xcodeproj">
+         </BuildableReference>
+      </MacroExpansion>
+      <AdditionalOptions>
+         <AdditionalOption
+            key = "NSZombieEnabled"
+            value = "YES"
+            isEnabled = "YES">
+         </AdditionalOption>
+         <AdditionalOption
+            key = "MallocScribble"
+            value = ""
+            isEnabled = "YES">
+         </AdditionalOption>
+      </AdditionalOptions>
+      <CodeCoverageTargets>
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "27379B8E1C7F57DA0084A24C"
+            BuildableName = "BGMXPCHelper.xpc"
+            BlueprintName = "BGMXPCHelper"
+            ReferencedContainer = "container:BGMApp.xcodeproj">
+         </BuildableReference>
+      </CodeCoverageTargets>
       <Testables>
          <TestableReference
             skipped = "NO">
@@ -39,22 +74,14 @@
             </BuildableReference>
          </TestableReference>
       </Testables>
-      <MacroExpansion>
-         <BuildableReference
-            BuildableIdentifier = "primary"
-            BlueprintIdentifier = "27379B8E1C7F57DA0084A24C"
-            BuildableName = "BGMXPCHelper.xpc"
-            BlueprintName = "BGMXPCHelper"
-            ReferencedContainer = "container:BGMApp.xcodeproj">
-         </BuildableReference>
-      </MacroExpansion>
-      <AdditionalOptions>
-      </AdditionalOptions>
    </TestAction>
    <LaunchAction
       buildConfiguration = "Debug"
       selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
       selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      enableAddressSanitizer = "YES"
+      enableASanStackUseAfterReturn = "YES"
+      enableUBSanitizer = "YES"
       launchStyle = "0"
       useCustomWorkingDirectory = "NO"
       ignoresPersistentStateOnLaunch = "NO"
@@ -70,7 +97,24 @@
             ReferencedContainer = "container:BGMApp.xcodeproj">
          </BuildableReference>
       </MacroExpansion>
+      <EnvironmentVariables>
+         <EnvironmentVariable
+            key = "ASAN_OPTIONS"
+            value = "detect_odr_violation=1:use_odr_indicator=1:detect_stack_use_after_return=1:detect_invalid_pointer_pairs=2:check_initialization_order=1"
+            isEnabled = "YES">
+         </EnvironmentVariable>
+      </EnvironmentVariables>
       <AdditionalOptions>
+         <AdditionalOption
+            key = "NSZombieEnabled"
+            value = "YES"
+            isEnabled = "YES">
+         </AdditionalOption>
+         <AdditionalOption
+            key = "MallocScribble"
+            value = ""
+            isEnabled = "YES">
+         </AdditionalOption>
       </AdditionalOptions>
    </LaunchAction>
    <ProfileAction

BGMApp/BGMApp.xcodeproj/xcshareddata/xcschemes/Background Music.xcscheme

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <Scheme
-   LastUpgradeVersion = "0810"
+   LastUpgradeVersion = "0900"
    version = "1.3">
    <BuildAction
       parallelizeBuildables = "YES"
@@ -27,29 +27,11 @@
       selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
       selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
       shouldUseLaunchSchemeArgsEnv = "YES"
-      enableAddressSanitizer = "YES">
-      <Testables>
-         <TestableReference
-            skipped = "NO">
-            <BuildableReference
-               BuildableIdentifier = "primary"
-               BlueprintIdentifier = "1CB8B3481BBA75F0000E2DD1"
-               BuildableName = "BGMAppTests.xctest"
-               BlueprintName = "BGMAppTests"
-               ReferencedContainer = "container:BGMApp.xcodeproj">
-            </BuildableReference>
-         </TestableReference>
-         <TestableReference
-            skipped = "NO">
-            <BuildableReference
-               BuildableIdentifier = "primary"
-               BlueprintIdentifier = "2743C9F51D86CFF90089613B"
-               BuildableName = "BGMAppUnitTests.xctest"
-               BlueprintName = "BGMAppUnitTests"
-               ReferencedContainer = "container:BGMApp.xcodeproj">
-            </BuildableReference>
-         </TestableReference>
-      </Testables>
+      enableAddressSanitizer = "YES"
+      enableASanStackUseAfterReturn = "YES"
+      enableUBSanitizer = "YES"
+      codeCoverageEnabled = "YES"
+      onlyGenerateCoverageForSpecifiedTargets = "YES">
       <MacroExpansion>
          <BuildableReference
             BuildableIdentifier = "primary"
@@ -60,12 +42,58 @@
          </BuildableReference>
       </MacroExpansion>
       <AdditionalOptions>
+         <AdditionalOption
+            key = "NSZombieEnabled"
+            value = "YES"
+            isEnabled = "YES">
+         </AdditionalOption>
+         <AdditionalOption
+            key = "MallocScribble"
+            value = ""
+            isEnabled = "YES">
+         </AdditionalOption>
       </AdditionalOptions>
+      <CodeCoverageTargets>
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "1CB8B3351BBA75EF000E2DD1"
+            BuildableName = "Background Music.app"
+            BlueprintName = "Background Music"
+            ReferencedContainer = "container:BGMApp.xcodeproj">
+         </BuildableReference>
+      </CodeCoverageTargets>
+      <Testables>
+         <TestableReference
+            skipped = "NO"
+            parallelizable = "YES"
+            testExecutionOrdering = "random">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "2743C9F51D86CFF90089613B"
+               BuildableName = "BGMAppUnitTests.xctest"
+               BlueprintName = "BGMAppUnitTests"
+               ReferencedContainer = "container:BGMApp.xcodeproj">
+            </BuildableReference>
+         </TestableReference>
+         <TestableReference
+            skipped = "NO">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "1CCC4F531E584081008053E4"
+               BuildableName = "BGMAppUITests.xctest"
+               BlueprintName = "BGMAppUITests"
+               ReferencedContainer = "container:BGMApp.xcodeproj">
+            </BuildableReference>
+         </TestableReference>
+      </Testables>
    </TestAction>
    <LaunchAction
       buildConfiguration = "Debug"
       selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
       selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      enableAddressSanitizer = "YES"
+      enableASanStackUseAfterReturn = "YES"
+      enableUBSanitizer = "YES"
       launchStyle = "0"
       useCustomWorkingDirectory = "NO"
       ignoresPersistentStateOnLaunch = "NO"
@@ -82,14 +110,34 @@
             ReferencedContainer = "container:BGMApp.xcodeproj">
          </BuildableReference>
       </BuildableProductRunnable>
+      <CommandLineArguments>
+         <CommandLineArgument
+            argument = "--show-dock-icon"
+            isEnabled = "NO">
+         </CommandLineArgument>
+         <CommandLineArgument
+            argument = "--no-persistent-data"
+            isEnabled = "NO">
+         </CommandLineArgument>
+      </CommandLineArguments>
       <EnvironmentVariables>
          <EnvironmentVariable
             key = "ASAN_OPTIONS"
-            value = "detect_odr_violation=0"
+            value = "detect_odr_violation=1:use_odr_indicator=1:detect_stack_use_after_return=1:detect_invalid_pointer_pairs=2:check_initialization_order=1"
             isEnabled = "YES">
          </EnvironmentVariable>
       </EnvironmentVariables>
       <AdditionalOptions>
+         <AdditionalOption
+            key = "NSZombieEnabled"
+            value = "YES"
+            isEnabled = "YES">
+         </AdditionalOption>
+         <AdditionalOption
+            key = "MallocScribble"
+            value = ""
+            isEnabled = "YES">
+         </AdditionalOption>
       </AdditionalOptions>
    </LaunchAction>
    <ProfileAction

BGMApp/BGMApp/AppDelegate.mm

@@ -1,288 +0,0 @@
-// This file is part of Background Music.
-//
-// Background Music is free software: you can redistribute it and/or
-// modify it under the terms of the GNU General Public License as
-// published by the Free Software Foundation, either version 2 of the
-// License, or (at your option) any later version.
-//
-// Background Music is distributed in the hope that it will be useful,
-// but WITHOUT ANY WARRANTY; without even the implied warranty of
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-// GNU General Public License for more details.
-//
-// You should have received a copy of the GNU General Public License
-// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
-
-//
-//  AppDelegate.mm
-//  BGMApp
-//
-//  Copyright © 2016 Kyle Neideck
-//
-
-// Self Includes
-#import "AppDelegate.h"
-
-// Local Includes
-#import "BGM_Types.h"
-#import "BGMUserDefaults.h"
-#import "BGMAudioDeviceManager.h"
-#import "BGMMusicPlayers.h"
-#import "BGMAutoPauseMusic.h"
-#import "BGMAutoPauseMenuItem.h"
-#import "BGMAppVolumes.h"
-#import "BGMPreferencesMenu.h"
-#import "BGMXPCListener.h"
-#import "SystemPreferences.h"
-
-
-#pragma clang assume_nonnull begin
-
-static float const kStatusBarIconPadding = 0.25;
-
-@implementation AppDelegate {
-    // The button in the system status bar (the bar with volume, battery, clock, etc.) to show the main menu
-    // for the app. These are called "menu bar extras" in the Human Interface Guidelines.
-    NSStatusItem* statusBarItem;
-    
-    // Only show the 'BGMXPCHelper is missing' error dialog once.
-    BOOL haveShownXPCHelperErrorMessage;
-    
-    BGMAutoPauseMusic* autoPauseMusic;
-    BGMAutoPauseMenuItem* autoPauseMenuItem;
-    BGMMusicPlayers* musicPlayers;
-    BGMAppVolumes* appVolumes;
-    BGMAudioDeviceManager* audioDevices;
-    BGMPreferencesMenu* prefsMenu;
-    BGMXPCListener* xpcListener;
-}
-
-- (void) awakeFromNib {
-    haveShownXPCHelperErrorMessage = NO;
-    
-    // Set up the status bar item
-    statusBarItem = [[NSStatusBar systemStatusBar] statusItemWithLength:NSSquareStatusItemLength];
-    
-    // Set the icon
-    NSImage* icon = [NSImage imageNamed:@"FermataIcon"];
-    if (icon != nil) {
-        CGFloat lengthMinusPadding = [[statusBarItem button] frame].size.height * (1 - kStatusBarIconPadding);
-        [icon setSize:NSMakeSize(lengthMinusPadding, lengthMinusPadding)];
-        // Make the icon a "template image" so it gets drawn colour-inverted when it's highlighted or the status
-        // bar's in dark mode
-        [icon setTemplate:YES];
-        statusBarItem.button.image = icon;
-    } else {
-        // If our icon is missing for some reason, fallback to a fermata character (1D110)
-        statusBarItem.button.title = @"𝄐";
-    }
-    
-    // Set the main menu
-    statusBarItem.menu = self.bgmMenu;
-}
-
-- (void) applicationDidFinishLaunching:(NSNotification*)aNotification {
-    #pragma unused (aNotification)
-    
-    // Log the version/build number.
-    //
-    // TODO: NSLog should only be used for logging errors.
-    // TODO: Automatically add the commit ID to the end of the build number for unreleased builds. (In the
-    //       Info.plist or something -- not here.)
-    NSLog(@"BGMApp version: %@, BGMApp build number: %@",
-          NSBundle.mainBundle.infoDictionary[@"CFBundleShortVersionString"],
-          NSBundle.mainBundle.infoDictionary[@"CFBundleVersion"]);
-
-    // Set up the rest of the UI and other external interfaces.
-    
-    BGMUserDefaults* userDefaults = [BGMUserDefaults new];
-    [userDefaults registerDefaults];
-
-    // audioDevices coordinates BGMDevice and the output device. It manages playthrough, volume/mute controls, etc.
-    {
-        NSError* error;
-        audioDevices = [[BGMAudioDeviceManager alloc] initWithError:&error];
-        if (audioDevices == nil) {
-            [self showDeviceNotFoundErrorMessageAndExit:error.code];
-        }
-    }
-
-    {
-        NSError* error = [audioDevices setBGMDeviceAsOSDefault];
-        if (error) {
-            [self showSetDeviceAsDefaultError:error
-                                      message:@"Could not set Background Music Device as your default audio device."
-                              informativeText:@"You might be able to set it yourself."];
-        }
-    }
-    
-    musicPlayers = [[BGMMusicPlayers alloc] initWithAudioDevices:audioDevices
-                                                    userDefaults:userDefaults];
-    
-    autoPauseMusic = [[BGMAutoPauseMusic alloc] initWithAudioDevices:audioDevices
-                                                        musicPlayers:musicPlayers];
-    
-    autoPauseMenuItem = [[BGMAutoPauseMenuItem alloc] initWithMenuItem:self.autoPauseMenuItemUnwrapped
-                                                        autoPauseMusic:autoPauseMusic
-                                                          musicPlayers:musicPlayers
-                                                          userDefaults:userDefaults];
-    
-    xpcListener = [[BGMXPCListener alloc] initWithAudioDevices:audioDevices
-                                  helperConnectionErrorHandler:^(NSError* error) {
-                                      NSLog(@"AppDelegate::applicationDidFinishLaunching: (helperConnectionErrorHandler) "
-                                             "BGMXPCHelper connection error: %@",
-                                            error);
-                                      
-                                      [self showXPCHelperErrorMessage:error];
-                                  }];
-    
-    appVolumes = [[BGMAppVolumes alloc] initWithMenu:self.bgmMenu
-                                       appVolumeView:self.appVolumeView
-                                        audioDevices:audioDevices];
-    
-    prefsMenu = [[BGMPreferencesMenu alloc] initWithBGMMenu:self.bgmMenu
-                                               audioDevices:audioDevices
-                                               musicPlayers:musicPlayers
-                                                 aboutPanel:self.aboutPanel
-                                      aboutPanelLicenseView:self.aboutPanelLicenseView];
-    
-    // Handle events about the main menu. (See the NSMenuDelegate methods below.)
-    self.bgmMenu.delegate = self;
-}
-
-- (void) applicationWillTerminate:(NSNotification*)aNotification {
-    #pragma unused (aNotification)
-    
-    DebugMsg("AppDelegate::applicationWillTerminate");
-
-    NSError* error = [audioDevices unsetBGMDeviceAsOSDefault];
-    
-    if (error) {
-        [self showSetDeviceAsDefaultError:error
-                                  message:@"Failed to reset your system's audio output device."
-                          informativeText:@"You'll have to change it yourself to get audio working again."];
-    }
-}
-
-#pragma mark Error messages
-
-- (void) showDeviceNotFoundErrorMessageAndExit:(NSInteger)code {
-    // Show an error dialog and exit if either BGMDevice wasn't found on the system or we couldn't find any output devices
-    
-    // NSAlert should only be used on the main thread.
-    dispatch_async(dispatch_get_main_queue(), ^{
-        NSAlert* alert = [NSAlert new];
-        
-        if (code == kBGMErrorCode_BGMDeviceNotFound) {
-            // TODO: Check whether the driver files are in /Library/Audio/Plug-Ins/HAL and offer to install them if not. Also,
-            //       it would be nice if we could restart coreaudiod automatically (using launchd).
-            [alert setMessageText:@"Could not find the Background Music virtual audio device."];
-            [alert setInformativeText:@"Make sure you've installed Background Music.driver to /Library/Audio/Plug-Ins/HAL and restarted coreaudiod (e.g. \"sudo killall coreaudiod\")."];
-        } else if (code == kBGMErrorCode_OutputDeviceNotFound) {
-            [alert setMessageText:@"Could not find an audio output device."];
-            [alert setInformativeText:@"If you do have one installed, this is probably a bug. Sorry about that. Feel free to file an issue on GitHub."];
-        }
-        
-        [alert runModal];
-        [NSApp terminate:self];
-    });
-}
-
-- (void) showXPCHelperErrorMessage:(NSError*)error {
-    if (!haveShownXPCHelperErrorMessage) {
-        haveShownXPCHelperErrorMessage = YES;
-        
-        // NSAlert should only be used on the main thread.
-        dispatch_async(dispatch_get_main_queue(), ^{
-            NSAlert* alert = [NSAlert new];
-            
-            // TODO: Offer to install BGMXPCHelper if it's missing.
-            // TODO: Show suppression button?
-            [alert setMessageText:@"Error connecting to BGMXPCHelper."];
-            [alert setInformativeText:[NSString stringWithFormat:@"%s%s%@ (%lu)",
-                                       "Make sure you have BGMXPCHelper installed. There are instructions in the "
-                                       "README.md file.\n\n"
-                                       "Background Music might still work, but it won't work as well as it could.",
-                                       "\n\nDetails:\n",
-                                       [error localizedDescription],
-                                       [error code]]];
-            [alert runModal];
-        });
-    }
-}
-
-- (void) showSetDeviceAsDefaultError:(NSError*)error
-                             message:(NSString*)msg
-                     informativeText:(NSString*)info {
-    dispatch_async(dispatch_get_main_queue(), ^{
-        NSLog(@"%@ %@ Error: %@", msg, info, error);
-        
-        NSAlert* alert = [NSAlert alertWithError:error];
-        alert.messageText = msg;
-        alert.informativeText = info;
-        
-        [alert addButtonWithTitle:@"OK"];
-        [alert addButtonWithTitle:@"Open Sound in System Preferences"];
-        
-        NSModalResponse buttonClicked = [alert runModal];
-        
-        if (buttonClicked != NSAlertFirstButtonReturn) {  // 'OK' is the first button.
-            [self openSysPrefsSoundOutput];
-        }
-    });
-}
-
-- (void) openSysPrefsSoundOutput {
-    SystemPreferencesApplication* __nullable sysPrefs =
-        [SBApplication applicationWithBundleIdentifier:@"com.apple.systempreferences"];
-    
-    if (!sysPrefs) {
-        NSLog(@"Could not open System Preferences");
-        return;
-    }
-    
-    // In System Preferences, go to the "Output" tab on the "Sound" pane.
-    for (SystemPreferencesPane* pane : [sysPrefs panes]) {
-        DebugMsg("AppDelegate::openSysPrefsSoundOutput: pane = %s", [pane.name UTF8String]);
-        
-        if ([pane.id isEqualToString:@"com.apple.preference.sound"]) {
-            sysPrefs.currentPane = pane;
-            
-            for (SystemPreferencesAnchor* anchor : [pane anchors]) {
-                DebugMsg("AppDelegate::openSysPrefsSoundOutput: anchor = %s", [anchor.name UTF8String]);
-                
-                if ([[anchor.name lowercaseString] isEqualToString:@"output"]) {
-                    DebugMsg("AppDelegate::openSysPrefsSoundOutput: Showing Output in Sound pane.");
-                    
-                    [anchor reveal];
-                }
-            }
-        }
-    }
-    
-    // Bring System Preferences to the foreground.
-    [sysPrefs activate];
-}
-
-#pragma mark NSMenuDelegate
-
-- (void) menuNeedsUpdate:(NSMenu*)menu {
-    if ([menu isEqual:self.bgmMenu]) {
-        [autoPauseMenuItem parentMenuNeedsUpdate];
-    } else {
-        DebugMsg("AppDelegate::menuNeedsUpdate: Warning: unexpected menu. menu=%s", menu.description.UTF8String);
-    }
-}
-
-- (void) menu:(NSMenu*)menu willHighlightItem:(NSMenuItem* __nullable)item {
-    if ([menu isEqual:self.bgmMenu]) {
-        [autoPauseMenuItem parentMenuItemWillHighlight:item];
-    } else {
-        DebugMsg("AppDelegate::menu: Warning: unexpected menu. menu=%s", menu.description.UTF8String);
-    }
-}
-
-@end
-
-#pragma clang assume_nonnull end
-

BGMApp/BGMApp/BGMApp-Debug.entitlements

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>com.apple.security.automation.apple-events</key>
+	<true/>
+	<key>com.apple.security.device.audio-input</key>
+	<true/>
+    <!--
+    Without this key, AddressSanitizer and the UI tests would only work when BGMApp is code signed.
+    -->
+	<key>com.apple.security.cs.disable-library-validation</key>
+	<true/>
+</dict>
+</plist>

BGMApp/BGMApp/BGMApp.entitlements

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>com.apple.security.automation.apple-events</key>
+	<true/>
+	<key>com.apple.security.device.audio-input</key>
+	<true/>
+</dict>
+</plist>

BGMApp/BGMApp/BGMAppDelegate.h

@@ -0,0 +1,59 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMAppDelegate.h
+//  BGMApp
+//
+//  Copyright © 2016, 2017, 2020 Kyle Neideck
+//  Copyright © 2021 Marcus Wu
+//
+//  Sets up and tears down the app.
+//
+
+// System Includes
+#import <Cocoa/Cocoa.h>
+
+@class BGMAudioDeviceManager;
+@class BGMAppVolumesController;
+
+// Tags for UI elements in MainMenu.xib
+static NSInteger const kVolumesHeadingMenuItemTag = 3;
+static NSInteger const kSeparatorBelowVolumesMenuItemTag = 4;
+
+@interface BGMAppDelegate : NSObject <NSApplicationDelegate, NSMenuDelegate>
+
+@property (weak) IBOutlet NSMenu* bgmMenu;
+
+@property (weak) IBOutlet NSView* outputVolumeView;
+@property (weak) IBOutlet NSTextField* outputVolumeLabel;
+@property (weak) IBOutlet NSSlider* outputVolumeSlider;
+
+@property (weak) IBOutlet NSView* systemSoundsView;
+@property (weak) IBOutlet NSSlider* systemSoundsSlider;
+
+@property (weak) IBOutlet NSView* appVolumeView;
+
+@property (weak) IBOutlet NSPanel* aboutPanel;
+@property (unsafe_unretained) IBOutlet NSTextView* aboutPanelLicenseView;
+
+@property (weak) IBOutlet NSMenuItem* autoPauseMenuItemUnwrapped;
+@property (weak) IBOutlet NSMenuItem* debugLoggingMenuItemUnwrapped;
+
+@property (readonly) BGMAudioDeviceManager* audioDevices;
+@property BGMAppVolumesController* appVolumes;
+
+@end
+

BGMApp/BGMApp/BGMAppDelegate.mm

@@ -0,0 +1,542 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMAppDelegate.mm
+//  BGMApp
+//
+//  Copyright © 2016-2022 Kyle Neideck
+//  Copyright © 2021 Marcus Wu
+//
+
+// Self Include
+#import "BGMAppDelegate.h"
+
+// Local Includes
+#import "BGM_Utils.h"
+#import "BGMAppVolumes.h"
+#import "BGMAppVolumesController.h"
+#import "BGMAutoPauseMusic.h"
+#import "BGMAutoPauseMenuItem.h"
+#import "BGMDebugLoggingMenuItem.h"
+#import "BGMMusicPlayers.h"
+#import "BGMOutputDeviceMenuSection.h"
+#import "BGMOutputVolumeMenuItem.h"
+#import "BGMPreferencesMenu.h"
+#import "BGMPreferredOutputDevices.h"
+#import "BGMStatusBarItem.h"
+#import "BGMSystemSoundsVolume.h"
+#import "BGMTermination.h"
+#import "BGMUserDefaults.h"
+#import "BGMXPCListener.h"
+#import "SystemPreferences.h"
+
+// System Includes
+#import <AVFoundation/AVCaptureDevice.h>
+
+
+#pragma clang assume_nonnull begin
+
+static NSString* const kOptNoPersistentData  = @"--no-persistent-data";
+static NSString* const kOptShowDockIcon      = @"--show-dock-icon";
+
+@implementation BGMAppDelegate {
+    // The button in the system status bar that shows the main menu.
+    BGMStatusBarItem* statusBarItem;
+    
+    // Only show the 'BGMXPCHelper is missing' error dialog once.
+    BOOL haveShownXPCHelperErrorMessage;
+
+    // Persistently stores user settings and data.
+    BGMUserDefaults* userDefaults;
+
+    BGMAutoPauseMusic* autoPauseMusic;
+    BGMAutoPauseMenuItem* autoPauseMenuItem;
+    BGMMusicPlayers* musicPlayers;
+    BGMSystemSoundsVolume* systemSoundsVolume;
+    BGMOutputDeviceMenuSection* outputDeviceMenuSection;
+    BGMPreferencesMenu* prefsMenu;
+    BGMDebugLoggingMenuItem* debugLoggingMenuItem;
+    BGMXPCListener* xpcListener;
+    BGMPreferredOutputDevices* preferredOutputDevices;
+}
+
+@synthesize audioDevices = audioDevices;
+@synthesize appVolumes = appVolumes;
+
+- (void) awakeFromNib {
+    [super awakeFromNib];
+    
+    // Show BGMApp in the dock, if the command-line option for that was passed. This is used by the
+    // UI tests.
+    if ([NSProcessInfo.processInfo.arguments indexOfObject:kOptShowDockIcon] != NSNotFound) {
+        [NSApp setActivationPolicy:NSApplicationActivationPolicyRegular];
+    }
+    
+    haveShownXPCHelperErrorMessage = NO;
+
+    // Set up audioDevices, which coordinates BGMDevice and the output device. It manages
+    // playthrough, volume/mute controls, etc.
+    if (![self initAudioDeviceManager]) {
+        return;
+    }
+
+    // Stored user settings
+    userDefaults = [self createUserDefaults];
+
+    // Add the status bar item. (The thing you click to show BGMApp's main menu.)
+    statusBarItem = [[BGMStatusBarItem alloc] initWithMenu:self.bgmMenu
+                                              audioDevices:audioDevices
+                                              userDefaults:userDefaults];
+}
+
+- (void) applicationDidFinishLaunching:(NSNotification*)aNotification {
+    #pragma unused (aNotification)
+    
+    // Log the version/build number.
+    //
+    // TODO: NSLog should only be used for logging errors.
+    // TODO: Automatically add the commit ID to the end of the build number for unreleased builds. (In the
+    //       Info.plist or something -- not here.)
+    NSLog(@"BGMApp version: %@, BGMApp build number: %@",
+          NSBundle.mainBundle.infoDictionary[@"CFBundleShortVersionString"],
+          NSBundle.mainBundle.infoDictionary[@"CFBundleVersion"]);
+
+    // Handles changing (or not changing) the output device when devices are added or removed. Must
+    // be initialised before calling setBGMDeviceAsDefault.
+    preferredOutputDevices =
+        [[BGMPreferredOutputDevices alloc] initWithDevices:audioDevices userDefaults:userDefaults];
+
+    // Skip this if we're compiling on a version of macOS before 10.14 as won't compile and it
+    // isn't needed.
+#if MAC_OS_X_VERSION_MAX_ALLOWED >= 101400  // MAC_OS_X_VERSION_10_14
+    if (@available(macOS 10.14, *)) {
+        // On macOS 10.14+ we need to get the user's permission to use input devices before we can
+        // use BGMDevice for playthrough (see BGMPlayThrough), so we wait until they've given it
+        // before making BGMDevice the default device. This way, if the user is playing audio when
+        // they open Background Music, we won't interrupt it while we're waiting for them to click
+        // OK.
+        [AVCaptureDevice requestAccessForMediaType:AVMediaTypeAudio
+                                 completionHandler:^(BOOL granted) {
+            dispatch_async(dispatch_get_main_queue(), ^{
+                if (granted) {
+                    DebugMsg("BGMAppDelegate::applicationDidFinishLaunching: Permission granted");
+                    [self continueLaunchAfterInputDevicePermissionGranted];
+                } else {
+                    NSLog(@"BGMAppDelegate::applicationDidFinishLaunching: Permission denied");
+                    // If they don't accept, Background Music won't work at all and the only way to
+                    // fix it is in System Preferences, so show an error dialog with instructions.
+                    //
+                    // TODO: It would be nice if this dialog had a shortcut to open the System
+                    //       Preferences panel. See showSetDeviceAsDefaultError.
+                    [self showErrorMessage:@"Background Music needs permission to use microphones."
+                           informativeText:@"It uses a virtual microphone to access your system's "
+                                            "audio.\n\nYou can grant the permission by going to "
+                                            "System Preferences > Security and Privacy > "
+                                            "Microphone and checking the box for Background Music."
+                 exitAfterMessageDismissed:YES];
+                }
+            });
+        }];
+    }
+    else
+#endif
+    {
+        // We can change the device immediately on older versions of macOS because they don't
+        // require user permission for input devices.
+        [self continueLaunchAfterInputDevicePermissionGranted];
+    }
+}
+
+- (void) continueLaunchAfterInputDevicePermissionGranted {
+    // Choose an output device for BGMApp to use to play audio.
+    if (![self setInitialOutputDevice]) {
+        return;
+    }
+
+    // Make BGMDevice the default device.
+    [self setBGMDeviceAsDefault];
+
+    // Handle some of the unusual reasons BGMApp might have to exit, mostly crashes.
+    BGMTermination::SetUpTerminationCleanUp(audioDevices);
+
+    // Set up the rest of the UI and other external interfaces.
+    musicPlayers = [[BGMMusicPlayers alloc] initWithAudioDevices:audioDevices
+                                                    userDefaults:userDefaults];
+
+    autoPauseMusic = [[BGMAutoPauseMusic alloc] initWithAudioDevices:audioDevices
+                                                        musicPlayers:musicPlayers];
+
+    [self setUpMainMenu];
+
+    xpcListener = [[BGMXPCListener alloc] initWithAudioDevices:audioDevices
+                                  helperConnectionErrorHandler:^(NSError* error) {
+        NSLog(@"BGMAppDelegate::continueLaunchAfterInputDevicePermissionGranted: "
+              "(helperConnectionErrorHandler) BGMXPCHelper connection error: %@",
+              error);
+        [self showXPCHelperErrorMessage:error];
+    }];
+}
+
+// Returns NO if (and only if) BGMApp is about to terminate because of a fatal error.
+- (BOOL) initAudioDeviceManager {
+    audioDevices = [BGMAudioDeviceManager new];
+
+    if (!audioDevices) {
+        [self showBGMDeviceNotFoundErrorMessageAndExit];
+        return NO;
+    }
+
+    return YES;
+}
+
+// Returns NO if (and only if) BGMApp is about to terminate because of a fatal error.
+- (BOOL) setInitialOutputDevice {
+    AudioObjectID preferredDevice = [preferredOutputDevices findPreferredDevice];
+
+    if (preferredDevice != kAudioObjectUnknown) {
+        NSError* __nullable error = [audioDevices setOutputDeviceWithID:preferredDevice
+                                                        revertOnFailure:NO];
+        if (error) {
+            // Show the error message.
+            [self showFailedToSetOutputDeviceErrorMessage:BGMNN(error)
+                                          preferredDevice:preferredDevice];
+        }
+    } else {
+        // We couldn't find a device to use, so show an error message and quit.
+        [self showOutputDeviceNotFoundErrorMessageAndExit];
+        return NO;
+    }
+
+    return YES;
+}
+
+// Sets the "Background Music" virtual audio device (BGMDevice) as the user's default audio device.
+- (void) setBGMDeviceAsDefault {
+    NSError* error = [audioDevices setBGMDeviceAsOSDefault];
+
+    if (error) {
+        [self showSetDeviceAsDefaultError:error
+                                  message:@"Could not set the Background Music device as your"
+                                           "default audio device."
+                          informativeText:@"You might be able to change it yourself."];
+    }
+}
+
+- (void) menuWillOpen:(NSMenu*)menu {
+    if (@available(macOS 10.16, *)) {
+        // Set menu offset and check for any active menu items
+        float menuOffset = 12.0;
+        for (NSMenuItem* menuItem in self.bgmMenu.itemArray) {
+            if (menuItem.state == NSControlStateValueOn && menuItem.indentationLevel == 0) {
+                menuOffset += 10;
+                break;
+            }
+        }
+        
+        // Align volume output device and slider
+        for (NSView* subview in self.outputVolumeView.subviews) {
+            CGRect newSubview = subview.frame;
+            newSubview.origin.x = menuOffset;
+            subview.frame = newSubview;
+        }
+
+        // Align system sounds and app volumes
+        double appIconTitleOffset = 0;
+        for (NSMenuItem* menuItem in self.bgmMenu.itemArray) {
+            if (menuItem.view.subviews.count == 7 || menuItem.view.subviews.count == 3) {
+                NSTextField* appTitle;
+                NSImageView* appIcon;
+                
+                for (NSView* subview in menuItem.view.subviews) {
+                    if (menuItem.view.subviews.count == 3) {
+                        // System sounds
+                        if ([subview isKindOfClass:[NSTextField class]]) {
+                            appTitle = (NSTextField*)subview;
+                        }
+                        if ([subview isKindOfClass:[NSImageView class]]) {
+                            appIcon = (NSImageView*)subview;
+                        }
+                    } else if (menuItem.view.subviews.count == 7) {
+                        // App volumes
+                        if ([subview isKindOfClass:[BGMAVM_AppNameLabel class]]) {
+                            appTitle = (NSTextField*)subview;
+                        }
+                        if ([subview isKindOfClass:[BGMAVM_AppIcon class]]) {
+                            appIcon = (NSImageView*)subview;
+                        }
+                    }
+                }
+ 
+                if (appIconTitleOffset == 0) {
+                    appIconTitleOffset = appTitle.frame.origin.x - appIcon.frame.origin.x;
+                }
+                
+                CGRect newAppIcon = appIcon.frame;
+                newAppIcon.origin.x = menuOffset;
+                appIcon.frame = newAppIcon;
+                CGRect newAppTitle = appTitle.frame;
+                newAppTitle.origin.x = menuOffset + appIconTitleOffset;
+                appTitle.frame = newAppTitle;
+            }
+        }
+    }
+}
+
+- (void) setUpMainMenu {
+    autoPauseMenuItem =
+        [[BGMAutoPauseMenuItem alloc] initWithMenuItem:self.autoPauseMenuItemUnwrapped
+                                        autoPauseMusic:autoPauseMusic
+                                          musicPlayers:musicPlayers
+                                          userDefaults:userDefaults];
+
+    [self initVolumesMenuSection];
+
+    // Output device selection.
+    outputDeviceMenuSection =
+            [[BGMOutputDeviceMenuSection alloc] initWithBGMMenu:self.bgmMenu
+                                                   audioDevices:audioDevices
+                                               preferredDevices:preferredOutputDevices];
+    [audioDevices setOutputDeviceMenuSection:outputDeviceMenuSection];
+
+    // Preferences submenu.
+    prefsMenu = [[BGMPreferencesMenu alloc] initWithBGMMenu:self.bgmMenu
+                                               audioDevices:audioDevices
+                                               musicPlayers:musicPlayers
+                                              statusBarItem:statusBarItem
+                                                 aboutPanel:self.aboutPanel
+                                      aboutPanelLicenseView:self.aboutPanelLicenseView];
+
+    // Enable/disable debug logging. Hidden unless you option-click the status bar icon.
+    debugLoggingMenuItem =
+        [[BGMDebugLoggingMenuItem alloc] initWithMenuItem:self.debugLoggingMenuItemUnwrapped];
+    [statusBarItem setDebugLoggingMenuItem:debugLoggingMenuItem];
+
+    // Handle events about the main menu. (See the NSMenuDelegate methods below.)
+    self.bgmMenu.delegate = self;
+}
+
+- (BGMUserDefaults*) createUserDefaults {
+    BOOL persistentDefaults =
+        [NSProcessInfo.processInfo.arguments indexOfObject:kOptNoPersistentData] == NSNotFound;
+    NSUserDefaults* wrappedDefaults = persistentDefaults ? [NSUserDefaults standardUserDefaults] : nil;
+    return [[BGMUserDefaults alloc] initWithDefaults:wrappedDefaults];
+}
+
+- (void) initVolumesMenuSection {
+    // Create the menu item with the (main) output volume slider.
+    BGMOutputVolumeMenuItem* outputVolume =
+            [[BGMOutputVolumeMenuItem alloc] initWithAudioDevices:audioDevices
+                                                             view:self.outputVolumeView
+                                                           slider:self.outputVolumeSlider
+                                                      deviceLabel:self.outputVolumeLabel];
+    [audioDevices setOutputVolumeMenuItem:outputVolume];
+
+    NSInteger headingIdx = [self.bgmMenu indexOfItemWithTag:kVolumesHeadingMenuItemTag];
+
+    // Add it to the main menu below the "Volumes" heading.
+    [self.bgmMenu insertItem:outputVolume atIndex:(headingIdx + 1)];
+
+    // Add the volume control for system (UI) sounds to the menu.
+    BGMAudioDevice uiSoundsDevice = [audioDevices bgmDevice].GetUISoundsBGMDeviceInstance();
+
+    systemSoundsVolume =
+        [[BGMSystemSoundsVolume alloc] initWithUISoundsDevice:uiSoundsDevice
+                                                         view:self.systemSoundsView
+                                                       slider:self.systemSoundsSlider];
+
+    [self.bgmMenu insertItem:systemSoundsVolume.menuItem atIndex:(headingIdx + 2)];
+
+    // Add the app volumes to the menu.
+    appVolumes = [[BGMAppVolumesController alloc] initWithMenu:self.bgmMenu
+                                                 appVolumeView:self.appVolumeView
+                                                  audioDevices:audioDevices];
+}
+
+- (void) applicationWillTerminate:(NSNotification*)aNotification {
+    #pragma unused (aNotification)
+    
+    DebugMsg("BGMAppDelegate::applicationWillTerminate");
+
+    // Change the user's default output device back.
+    NSError* error = [audioDevices unsetBGMDeviceAsOSDefault];
+    
+    if (error) {
+        [self showSetDeviceAsDefaultError:error
+                                  message:@"Failed to reset your system's audio output device."
+                          informativeText:@"You'll have to change it yourself to get audio working again."];
+    }
+}
+
+#pragma mark Error messages
+
+- (void) showBGMDeviceNotFoundErrorMessageAndExit {
+    // BGMDevice wasn't found on the system. Most likely, BGMDriver isn't installed. Show an error
+    // dialog and exit.
+    //
+    // TODO: Check whether the driver files are in /Library/Audio/Plug-Ins/HAL? Might even want to
+    //       offer to install them if not.
+    [self showErrorMessage:@"Could not find the Background Music virtual audio device."
+           informativeText:@"Make sure you've installed Background Music Device.driver to "
+                            "/Library/Audio/Plug-Ins/HAL and restarted coreaudiod (e.g. \"sudo "
+                            "killall coreaudiod\")."
+ exitAfterMessageDismissed:YES];
+}
+
+- (void) showFailedToSetOutputDeviceErrorMessage:(NSError*)error
+                                 preferredDevice:(BGMAudioDevice)device {
+    NSLog(@"Failed to set initial output device. Error: %@", error);
+
+    dispatch_async(dispatch_get_main_queue(), ^{
+        NSAlert* alert = [NSAlert alertWithError:BGMNN(error)];
+        alert.messageText = @"Failed to set the output device.";
+
+        NSString* __nullable name = nil;
+        BGM_Utils::LogAndSwallowExceptions(BGMDbgArgs, [&] {
+            name = (__bridge NSString* __nullable)device.CopyName();
+        });
+
+        alert.informativeText =
+                [NSString stringWithFormat:@"Could not start the device '%@'. (Error: %ld)",
+                        name, error.code];
+
+        [alert runModal];
+    });
+}
+
+- (void) showOutputDeviceNotFoundErrorMessageAndExit {
+    // We couldn't find any output devices. Show an error dialog and exit.
+    [self showErrorMessage:@"Could not find an audio output device."
+           informativeText:@"If you do have one installed, this is probably a bug. Sorry about "
+                            "that. Feel free to file an issue on GitHub."
+ exitAfterMessageDismissed:YES];
+}
+
+- (void) showXPCHelperErrorMessage:(NSError*)error {
+    if (!haveShownXPCHelperErrorMessage) {
+        haveShownXPCHelperErrorMessage = YES;
+        
+        // NSAlert should only be used on the main thread.
+        dispatch_async(dispatch_get_main_queue(), ^{
+            NSAlert* alert = [NSAlert new];
+            
+            // TODO: Offer to install BGMXPCHelper if it's missing.
+            // TODO: Show suppression button?
+            [alert setMessageText:@"Error connecting to BGMXPCHelper."];
+            [alert setInformativeText:[NSString stringWithFormat:@"%s%s%@ (%lu)",
+                                       "Make sure you have BGMXPCHelper installed. There are instructions in the "
+                                       "README.md file.\n\n"
+                                       "Background Music might still work, but it won't work as well as it could.",
+                                       "\n\nDetails:\n",
+                                       [error localizedDescription],
+                                       [error code]]];
+            [alert runModal];
+        });
+    }
+}
+
+- (void) showErrorMessage:(NSString*)message
+          informativeText:(NSString*)informativeText
+exitAfterMessageDismissed:(BOOL)fatal {
+    // NSAlert should only be used on the main thread.
+    dispatch_async(dispatch_get_main_queue(), ^{
+        NSAlert* alert = [NSAlert new];
+        [alert setMessageText:message];
+        [alert setInformativeText:informativeText];
+
+        // This crashes if built with Xcode 9.0.1, but works with versions of Xcode before 9 and
+        // with 9.1.
+        [alert runModal];
+
+        if (fatal) {
+            [NSApp terminate:self];
+        }
+    });
+}
+
+- (void) showSetDeviceAsDefaultError:(NSError*)error
+                             message:(NSString*)msg
+                     informativeText:(NSString*)info {
+    dispatch_async(dispatch_get_main_queue(), ^{
+        NSLog(@"%@ %@ Error: %@", msg, info, error);
+        
+        NSAlert* alert = [NSAlert alertWithError:error];
+        alert.messageText = msg;
+        alert.informativeText = info;
+        
+        [alert addButtonWithTitle:@"OK"];
+        [alert addButtonWithTitle:@"Open Sound in System Preferences"];
+        
+        NSModalResponse buttonClicked = [alert runModal];
+        
+        if (buttonClicked != NSAlertFirstButtonReturn) {  // 'OK' is the first button.
+            [self openSysPrefsSoundOutput];
+        }
+    });
+}
+
+- (void) openSysPrefsSoundOutput {
+    SystemPreferencesApplication* __nullable sysPrefs =
+        [SBApplication applicationWithBundleIdentifier:@"com.apple.systempreferences"];
+    
+    if (!sysPrefs) {
+        NSLog(@"Could not open System Preferences");
+        return;
+    }
+    
+    // In System Preferences, go to the "Output" tab on the "Sound" pane.
+    for (SystemPreferencesPane* pane : [sysPrefs panes]) {
+        DebugMsg("BGMAppDelegate::openSysPrefsSoundOutput: pane = %s", [pane.name UTF8String]);
+        
+        if ([pane.id isEqualToString:@"com.apple.preference.sound"]) {
+            sysPrefs.currentPane = pane;
+            
+            for (SystemPreferencesAnchor* anchor : [pane anchors]) {
+                DebugMsg("BGMAppDelegate::openSysPrefsSoundOutput: anchor = %s", [anchor.name UTF8String]);
+                
+                if ([[anchor.name lowercaseString] isEqualToString:@"output"]) {
+                    DebugMsg("BGMAppDelegate::openSysPrefsSoundOutput: Showing Output in Sound pane.");
+                    
+                    [anchor reveal];
+                }
+            }
+        }
+    }
+    
+    // Bring System Preferences to the foreground.
+    [sysPrefs activate];
+}
+
+#pragma mark NSMenuDelegate
+
+- (void) menuNeedsUpdate:(NSMenu*)menu {
+    if ([menu isEqual:self.bgmMenu]) {
+        [autoPauseMenuItem parentMenuNeedsUpdate];
+    } else {
+        DebugMsg("BGMAppDelegate::menuNeedsUpdate: Warning: unexpected menu. menu=%s", menu.description.UTF8String);
+    }
+}
+
+- (void) menu:(NSMenu*)menu willHighlightItem:(NSMenuItem* __nullable)item {
+    if ([menu isEqual:self.bgmMenu]) {
+        [autoPauseMenuItem parentMenuItemWillHighlight:item];
+    } else {
+        DebugMsg("BGMAppDelegate::menu: Warning: unexpected menu. menu=%s", menu.description.UTF8String);
+    }
+}
+@end
+
+#pragma clang assume_nonnull end
+

BGMApp/BGMApp/BGMAppVolumes.h

@@ -17,19 +17,36 @@
 //  BGMAppVolumes.h
 //  BGMApp
 //
-//  Copyright © 2016 Kyle Neideck
+//  Copyright © 2016, 2017 Kyle Neideck
+//  Copyright © 2021 Marcus Wu
 //
 
 // Local Includes
-#import "BGMAudioDeviceManager.h"
+#import "BGMAppVolumesController.h"
 
 // System Includes
 #import <Cocoa/Cocoa.h>
 
 
+#pragma clang assume_nonnull begin
+
 @interface BGMAppVolumes : NSObject
 
-- (id) initWithMenu:(NSMenu*)menu appVolumeView:(NSView*)view audioDevices:(BGMAudioDeviceManager*)audioDevices;
+- (id) initWithController:(BGMAppVolumesController*)inController
+                  bgmMenu:(NSMenu*)inMenu
+            appVolumeView:(NSView*)inView;
+
+// Pass -1 for initialVolume or kAppPanNoValue for initialPan to leave the volume/pan at its default level.
+- (void) insertMenuItemForApp:(NSRunningApplication*)app
+                initialVolume:(int)volume
+                   initialPan:(int)pan;
+
+- (void) removeMenuItemForApp:(NSRunningApplication*)app;
+
+- (void) removeAllAppVolumeMenuItems;
+
+- (BGMAppVolumeAndPan) getVolumeAndPanForApp:(NSRunningApplication*)app;
+- (void) setVolumeAndPan:(BGMAppVolumeAndPan)volumeAndPan forApp:(NSRunningApplication*)app;
 
 @end
 
@@ -37,7 +54,10 @@
 
 @protocol BGMAppVolumeMenuItemSubview <NSObject>
 
-- (void) setUpWithApp:(NSRunningApplication*)app context:(BGMAppVolumes*)ctx menuItem:(NSMenuItem*)item;
+- (void) setUpWithApp:(NSRunningApplication*)app
+              context:(BGMAppVolumes*)ctx
+           controller:(BGMAppVolumesController*)ctrl
+             menuItem:(NSMenuItem*)item;
 
 @end
 
@@ -54,13 +74,16 @@
 
 @interface BGMAVM_VolumeSlider : NSSlider <BGMAppVolumeMenuItemSubview>
 
-- (void) setRelativeVolume:(NSNumber*)relativeVolume;
+- (void) setRelativeVolume:(int)relativeVolume;
 
 @end
 
 @interface BGMAVM_PanSlider : NSSlider <BGMAppVolumeMenuItemSubview>
 
-- (void) setPanPosition:(NSNumber*)panPosition;
+- (void) setPanPosition:(int)panPosition;
 
 @end
 
+#pragma clang assume_nonnull end
+
+

BGMApp/BGMApp/BGMAppVolumes.m

@@ -0,0 +1,535 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMAppVolumes.m
+//  BGMApp
+//
+//  Copyright © 2016-2020 Kyle Neideck
+//  Copyright © 2017 Andrew Tonner
+//  Copyright © 2021 Marcus Wu
+//  Copyright © 2022 Jon Egan
+//
+
+// Self Include
+#import "BGMAppVolumes.h"
+
+// Local Includes
+#import "BGM_Types.h"
+#import "BGM_Utils.h"
+#import "BGMAppDelegate.h"
+
+// PublicUtility Includes
+#import "CADebugMacros.h"
+
+
+static float const     kSlidersSnapWithin          = 5;
+static CGFloat const   kAppVolumeViewInitialHeight = 20;
+static NSString* const kMoreAppsMenuTitle          = @"More Apps";
+
+@implementation BGMAppVolumes {
+    BGMAppVolumesController* controller;
+
+    NSMenu* bgmMenu;
+    NSMenu* moreAppsMenu;
+    
+    NSView* appVolumeView;
+    CGFloat appVolumeViewFullHeight;
+
+    // The number of menu items this class has added to bgmMenu. Doesn't include the More Apps menu.
+    NSInteger numMenuItems;
+}
+
+- (id) initWithController:(BGMAppVolumesController*)inController
+                  bgmMenu:(NSMenu*)inMenu
+            appVolumeView:(NSView*)inView {
+    if ((self = [super init])) {
+        controller = inController;
+        bgmMenu = inMenu;
+        moreAppsMenu = [[NSMenu alloc] initWithTitle:kMoreAppsMenuTitle];
+        appVolumeView = inView;
+        appVolumeViewFullHeight = appVolumeView.frame.size.height;
+        numMenuItems = 0;
+
+        // Add the More Apps menu to the main menu.
+        NSMenuItem* moreAppsMenuItem =
+            [[NSMenuItem alloc] initWithTitle:kMoreAppsMenuTitle action:nil keyEquivalent:@""];
+        moreAppsMenuItem.submenu = moreAppsMenu;
+
+        [bgmMenu insertItem:moreAppsMenuItem atIndex:([self lastMenuItemIndex] + 1)];
+        numMenuItems++;
+
+        // Put an empty menu item above the More Apps menu item to fix its top margin.
+        NSMenuItem* spacer = [[NSMenuItem alloc] initWithTitle:@"" action:nil keyEquivalent:@""];
+        spacer.view = [[NSView alloc] initWithFrame:NSMakeRect(0, 0, 0, 4)];
+        spacer.hidden = YES;  // Tells accessibility clients to ignore this menu item.
+
+        [bgmMenu insertItem:spacer atIndex:[self lastMenuItemIndex]];
+        numMenuItems++;
+    }
+    
+    return self;
+}
+
+#pragma mark UI Modifications
+
+- (void) insertMenuItemForApp:(NSRunningApplication*)app
+                initialVolume:(int)volume
+                   initialPan:(int)pan {
+    NSMenuItem* appVolItem = [self createBlankAppVolumeMenuItem];
+
+    // Look through the menu item's subviews for the ones we want to set up
+    for (NSView* subview in appVolItem.view.subviews) {
+        if ([subview conformsToProtocol:@protocol(BGMAppVolumeMenuItemSubview)]) {
+            [(NSView<BGMAppVolumeMenuItemSubview>*)subview setUpWithApp:app
+                                                                context:self
+                                                             controller:controller
+                                                               menuItem:appVolItem];
+        }
+    }
+
+    // Store the NSRunningApplication object with the menu item so when the app closes we can find the item to remove it
+    appVolItem.representedObject = app;
+
+    // Set the slider to the volume for this app if we got one from the driver
+    [self setVolumeOfMenuItem:appVolItem relativeVolume:volume panPosition:pan];
+
+    // NSMenuItem didn't implement NSAccessibility before OS X SDK 10.12.
+#if MAC_OS_X_VERSION_MAX_ALLOWED >= 101200  // MAC_OS_X_VERSION_10_12
+    if ([appVolItem respondsToSelector:@selector(setAccessibilityTitle:)]) {
+        // TODO: This doesn't show up in Accessibility Inspector for me. Not sure why.
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wpartial-availability"
+        appVolItem.accessibilityTitle = [NSString stringWithFormat:@"%@", [app localizedName]];
+#pragma clang diagnostic pop
+    }
+#endif
+
+    // Add the menu item to its menu.
+    if (app.activationPolicy == NSApplicationActivationPolicyRegular) {
+        [bgmMenu insertItem:appVolItem atIndex:[self firstMenuItemIndex]];
+        numMenuItems++;
+    } else if (app.activationPolicy == NSApplicationActivationPolicyAccessory) {
+        [moreAppsMenu insertItem:appVolItem atIndex:0];
+    }
+}
+
+- (NSMenuItem*) getMenuItemForApp:(NSRunningApplication*)app {
+    NSInteger lastAppVolumeMenuItemIndex = [self lastMenuItemIndex] - 2;
+
+    for (NSInteger i = [self firstMenuItemIndex]; i <= lastAppVolumeMenuItemIndex; i++) {
+        NSMenuItem* item = [bgmMenu itemAtIndex:i];
+        NSRunningApplication* itemApp = item.representedObject;
+        BGMAssert(itemApp, "!itemApp for %s", item.title.UTF8String);
+
+        if ([itemApp isEqual:app]) {
+            return item;
+        }
+    }
+    for (NSInteger i = 0; i < [moreAppsMenu numberOfItems]; i++) {
+        NSMenuItem* item = [moreAppsMenu itemAtIndex:i];
+        NSRunningApplication* itemApp = item.representedObject;
+        BGMAssert(itemApp, "!itemApp for %s", item.title.UTF8String);
+
+        if ([itemApp isEqual:app]) {
+            return item;
+        }
+    }
+
+    return nil;
+}
+
+- (BGMAppVolumeAndPan) getVolumeAndPanForApp:(NSRunningApplication*)app {
+    BGMAppVolumeAndPan result = {
+        .volume = -1,
+        .pan = kAppPanNoValue
+    };
+
+    NSMenuItem *item = [self getMenuItemForApp:app];
+
+    if (item == nil) {
+        return result;
+    }
+
+    for (NSView* subview in item.view.subviews) {
+        // Get the volume.
+        if ([subview isKindOfClass:[BGMAVM_VolumeSlider class]]) {
+            result.volume = [(BGMAVM_VolumeSlider*)subview intValue];
+        }
+
+        // Get the pan position.
+        if ([subview isKindOfClass:[BGMAVM_PanSlider class]]) {
+            result.pan = [(BGMAVM_PanSlider*)subview intValue];
+        }
+    }
+
+    return result;
+}
+
+- (void) setVolumeAndPan:(BGMAppVolumeAndPan)volumeAndPan forApp:(NSRunningApplication*)app {
+    NSMenuItem *item = [self getMenuItemForApp:app];
+
+    if (item == nil) {
+        return;
+    }
+
+    for (NSView* subview in item.view.subviews) {
+        // Set the volume.
+        if (volumeAndPan.volume != -1 && [subview isKindOfClass:[BGMAVM_VolumeSlider class]]) {
+            [(BGMAVM_VolumeSlider*)subview setRelativeVolume:volumeAndPan.volume];
+        }
+
+        // Set the pan position.
+        if (volumeAndPan.pan != kAppPanNoValue && [subview isKindOfClass:[BGMAVM_PanSlider class]]) {
+            [(BGMAVM_PanSlider*)subview setPanPosition:volumeAndPan.pan];
+        }
+    }
+
+}
+
+// Create a blank menu item to copy as a template.
+- (NSMenuItem*) createBlankAppVolumeMenuItem {
+    NSMenuItem* menuItem = [[NSMenuItem alloc] initWithTitle:@"" action:nil keyEquivalent:@""];
+    
+    menuItem.view = appVolumeView;
+    menuItem = [menuItem copy];  // So we can modify a copy of the view, rather than the template itself.
+    
+    return menuItem;
+}
+
+- (void) setVolumeOfMenuItem:(NSMenuItem*)menuItem relativeVolume:(int)volume panPosition:(int)pan {
+    // Update the sliders.
+    for (NSView* subview in menuItem.view.subviews) {
+        // Set the volume.
+        if (volume != -1 && [subview isKindOfClass:[BGMAVM_VolumeSlider class]]) {
+            [(BGMAVM_VolumeSlider*)subview setRelativeVolume:volume];
+        }
+
+        // Set the pan position.
+        if (pan != kAppPanNoValue && [subview isKindOfClass:[BGMAVM_PanSlider class]]) {
+            [(BGMAVM_PanSlider*)subview setPanPosition:pan];
+        }
+    }
+}
+
+- (NSInteger) firstMenuItemIndex {
+    return [self lastMenuItemIndex] - numMenuItems + 1;
+}
+
+- (NSInteger) lastMenuItemIndex {
+    return [bgmMenu indexOfItemWithTag:kSeparatorBelowVolumesMenuItemTag] - 1;
+}
+
+- (void) removeMenuItemForApp:(NSRunningApplication*)app {
+    // Subtract two extra positions to skip the More Apps menu and the spacer menu item above it.
+    NSInteger lastAppVolumeMenuItemIndex = [self lastMenuItemIndex] - 2;
+
+    // Check each app volume menu item and remove the item that controls the given app.
+
+    // Look through the main menu.
+    for (NSInteger i = [self firstMenuItemIndex]; i <= lastAppVolumeMenuItemIndex; i++) {
+        NSMenuItem* item = [bgmMenu itemAtIndex:i];
+        NSRunningApplication* itemApp = item.representedObject;
+        BGMAssert(itemApp, "!itemApp for %s", item.title.UTF8String);
+
+        if ([itemApp isEqual:app]) {
+            [bgmMenu removeItem:item];
+            numMenuItems--;
+            return;
+        }
+    }
+
+    // Look through the More Apps menu.
+    for (NSInteger i = 0; i < [moreAppsMenu numberOfItems]; i++) {
+        NSMenuItem* item = [moreAppsMenu itemAtIndex:i];
+        NSRunningApplication* itemApp = item.representedObject;
+        BGMAssert(itemApp, "!itemApp for %s", item.title.UTF8String);
+
+        if ([itemApp isEqual:app]) {
+            [moreAppsMenu removeItem:item];
+            return;
+        }
+    }
+}
+
+- (void) showHideExtraControls:(BGMAVM_ShowMoreControlsButton*)button {
+    // Show or hide an app's extra controls, currently only pan, in its App Volumes menu item.
+    
+    NSMenuItem* menuItem = button.cell.representedObject;
+    
+    BGMAssert(button, "!button");
+    BGMAssert(menuItem, "!menuItem");
+
+    CGFloat width = menuItem.view.frame.size.width;
+#if DEBUG
+    CGFloat height = menuItem.view.frame.size.height;
+#endif
+
+    const char* appName =
+        [((NSRunningApplication*)menuItem.representedObject).localizedName UTF8String];
+
+    // Using this function (instead of just ==) shouldn't be necessary, but just in case.
+#if DEBUG
+    BOOL(^nearEnough)(CGFloat x, CGFloat y) = ^BOOL(CGFloat x, CGFloat y) {
+        return fabs(x - y) < 0.01;  // We don't need much precision.
+    };
+#endif
+    
+    bool allSubviewsShowing = true;
+    for (NSView* subview in menuItem.view.subviews) {
+        if (subview.hidden) {
+            allSubviewsShowing = false;
+            break;
+        }
+        //DebugMsg("BGMAppVolumes:: subview hash / hidden: (%lu) / (%hhd)", (unsigned long)subview.hash, subview.hidden);
+    }
+
+    if (allSubviewsShowing) {
+        // Hide extra controls
+        DebugMsg("BGMAppVolumes::showHideExtraControls: Hiding extra controls (%s)", appName);
+        
+        BGMAssert(nearEnough(height, appVolumeViewFullHeight), "Extra controls were already hidden");
+        
+        // Make the menu item shorter to hide the extra controls. Keep the width unchanged.
+        menuItem.view.frameSize = NSMakeSize(width, kAppVolumeViewInitialHeight);
+        // Turn the button upside down so the arrowhead points down.
+        button.frameCenterRotation = 180.0;
+        // Move the button up slightly so it aligns with the volume slider.
+        [button setFrameOrigin:NSMakePoint(button.frame.origin.x, button.frame.origin.y - 1)];
+
+        // Set the extra controls, and anything else below the fold, to hidden so accessibility
+        // clients can skip over them.
+        for (NSView* subview in menuItem.view.subviews) {
+            CGFloat top = subview.frame.origin.y + subview.frame.size.height;
+            if (top <= 0.0) {
+                subview.hidden = YES;
+            }
+        }
+    } else {
+        // Show extra controls
+        DebugMsg("BGMAppVolumes::showHideExtraControls: Showing extra controls (%s)", appName);
+        
+        BGMAssert(nearEnough(button.frameCenterRotation, 180.0), "Unexpected button rotation");
+        BGMAssert(nearEnough(height, kAppVolumeViewInitialHeight), "Extra controls were already shown");
+        
+        // Make the menu item taller to show the extra controls. Keep the width unchanged.
+        menuItem.view.frameSize = NSMakeSize(width, appVolumeViewFullHeight);
+        // Turn the button rightside up so the arrowhead points up.
+        button.frameCenterRotation = 0.0;
+        // Move the button down slightly, back to its original position.
+        [button setFrameOrigin:NSMakePoint(button.frame.origin.x, button.frame.origin.y + 1)];
+
+        // Set all of the UI elements in the menu item to "not hidden" for accessibility clients.
+        for (NSView* subview in menuItem.view.subviews) {
+            subview.hidden = NO;
+        }
+    }
+}
+
+- (void) removeAllAppVolumeMenuItems {
+    // Remove all of the menu items this class adds to the menu except for the last two, which are
+    // the More Apps menu item and the invisible spacer above it.
+    while (numMenuItems > 2) {
+        [bgmMenu removeItemAtIndex:[self firstMenuItemIndex]];
+        numMenuItems--;
+    }
+
+    // The More Apps menu only contains app volume menu items, so we can just remove everything.
+    [moreAppsMenu removeAllItems];
+}
+
+@end
+
+#pragma mark Custom Classes (IB)
+
+// Custom classes for the UI elements in the app volume menu items
+
+@implementation BGMAVM_AppIcon
+
+- (void) setUpWithApp:(NSRunningApplication*)app
+              context:(BGMAppVolumes*)ctx
+           controller:(BGMAppVolumesController*)ctrl
+             menuItem:(NSMenuItem*)menuItem {
+    #pragma unused (ctx, ctrl, menuItem)
+    
+    self.image = app.icon;
+
+    // Remove the icon from the accessibility hierarchy.
+#if MAC_OS_X_VERSION_MAX_ALLOWED >= 101000  // MAC_OS_X_VERSION_10_10
+    if ([self.cell respondsToSelector:@selector(setAccessibilityElement:)]) {
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wpartial-availability"
+        self.cell.accessibilityElement = NO;
+#pragma clang diagnostic pop
+    }
+#endif
+}
+
+@end
+
+@implementation BGMAVM_AppNameLabel
+
+- (void) setUpWithApp:(NSRunningApplication*)app
+              context:(BGMAppVolumes*)ctx
+           controller:(BGMAppVolumesController*)ctrl
+             menuItem:(NSMenuItem*)menuItem {
+    #pragma unused (ctx, ctrl, menuItem)
+    
+    NSString* name = app.localizedName ? (NSString*)app.localizedName : @"";
+    self.stringValue = name;
+}
+
+@end
+
+@implementation BGMAVM_ShowMoreControlsButton
+
+- (void) setUpWithApp:(NSRunningApplication*)app
+              context:(BGMAppVolumes*)ctx
+           controller:(BGMAppVolumesController*)ctrl
+             menuItem:(NSMenuItem*)menuItem {
+    #pragma unused (app, ctrl)
+    
+    // Set up the button that show/hide the extra controls (currently only a pan slider) for the app.
+    self.cell.representedObject = menuItem;
+    self.target = ctx;
+    self.action = @selector(showHideExtraControls:);
+    
+    // The menu item starts out with the extra controls visible, so we hide them here.
+    //
+    // TODO: Leave them visible if any of the controls are set to non-default values. The user has no way to
+    //       tell otherwise. Maybe we should also make this button look different if the controls are hidden
+    //       when they have non-default values.
+    [ctx showHideExtraControls:self];
+
+    if ([self respondsToSelector:@selector(setAccessibilityTitle:)]) {
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wpartial-availability"
+        self.accessibilityTitle = @"More options";
+#pragma clang diagnostic pop
+    }
+}
+
+@end
+
+@implementation BGMAVM_VolumeSlider {
+    // Will be set to -1 for apps without a pid
+    pid_t appProcessID;
+    NSString* __nullable appBundleID;
+    BGMAppVolumesController* controller;
+}
+
+- (void) setUpWithApp:(NSRunningApplication*)app
+              context:(BGMAppVolumes*)ctx
+           controller:(BGMAppVolumesController*)ctrl
+             menuItem:(NSMenuItem*)menuItem {
+    #pragma unused (ctx, menuItem)
+    
+    controller = ctrl;
+    
+    self.target = self;
+    self.action = @selector(appVolumeChanged);
+    
+    appProcessID = app.processIdentifier;
+    appBundleID = app.bundleIdentifier;
+    
+    self.maxValue = kAppRelativeVolumeMaxRawValue;
+    self.minValue = kAppRelativeVolumeMinRawValue;
+
+    if ([self respondsToSelector:@selector(setAccessibilityTitle:)]) {
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wpartial-availability"
+        self.accessibilityTitle = [NSString stringWithFormat:@"Volume for %@", [app localizedName]];
+#pragma clang diagnostic pop
+    }
+}
+
+// We have to handle snapping for volume sliders ourselves because adding a tick mark (snap point) in Interface Builder
+// changes how the slider looks.
+- (void) snap {
+    // Snap to the 50% point.
+    float midPoint = (float)((self.maxValue + self.minValue) / 2);
+    if (self.floatValue > (midPoint - kSlidersSnapWithin) && self.floatValue < (midPoint + kSlidersSnapWithin)) {
+        self.floatValue = midPoint;
+    }
+}
+
+- (void) setRelativeVolume:(int)relativeVolume {
+    self.intValue = relativeVolume;
+    [self snap];
+}
+
+- (void) appVolumeChanged {
+    // TODO: This (sending updates to the driver) should probably be rate-limited. It uses a fair bit of CPU for me.
+    
+    DebugMsg("BGMAppVolumes::appVolumeChanged: App volume for %s (%d) changed to %d",
+             appBundleID.UTF8String,
+             appProcessID,
+             self.intValue);
+    
+    [self snap];
+
+    // The values from our sliders are in
+    // [kAppRelativeVolumeMinRawValue, kAppRelativeVolumeMaxRawValue] already.
+    [controller setVolume:self.intValue forAppWithProcessID:appProcessID bundleID:appBundleID];
+}
+
+@end
+
+@implementation BGMAVM_PanSlider {
+    // Will be set to -1 for apps without a pid
+    pid_t appProcessID;
+    NSString* __nullable appBundleID;
+    BGMAppVolumesController* controller;
+}
+
+- (void) setUpWithApp:(NSRunningApplication*)app
+              context:(BGMAppVolumes*)ctx
+           controller:(BGMAppVolumesController*)ctrl
+             menuItem:(NSMenuItem*)menuItem {
+    #pragma unused (ctx, menuItem)
+    
+    controller = ctrl;
+    
+    self.target = self;
+    self.action = @selector(appPanPositionChanged);
+    
+    appProcessID = app.processIdentifier;
+    appBundleID = app.bundleIdentifier;
+    
+    self.minValue = kAppPanLeftRawValue;
+    self.maxValue = kAppPanRightRawValue;
+
+    if ([self respondsToSelector:@selector(setAccessibilityTitle:)]) {
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wpartial-availability"
+        self.accessibilityTitle = [NSString stringWithFormat:@"Pan for %@", [app localizedName]];
+#pragma clang diagnostic pop
+    }
+}
+
+- (void) setPanPosition:(int)panPosition {
+    self.intValue = panPosition;
+}
+
+- (void) appPanPositionChanged {
+    // TODO: This (sending updates to the driver) should probably be rate-limited. It uses a fair bit of CPU for me.
+    
+    DebugMsg("BGMAppVolumes::appPanPositionChanged: App pan position for %s changed to %d", appBundleID.UTF8String, self.intValue);
+
+    // The values from our sliders are in [kAppPanLeftRawValue, kAppPanRightRawValue] already.
+    [controller setPanPosition:self.intValue forAppWithProcessID:appProcessID bundleID:appBundleID];
+}
+
+@end

BGMApp/BGMApp/BGMAppVolumes.mm

@@ -1,447 +0,0 @@
-// This file is part of Background Music.
-//
-// Background Music is free software: you can redistribute it and/or
-// modify it under the terms of the GNU General Public License as
-// published by the Free Software Foundation, either version 2 of the
-// License, or (at your option) any later version.
-//
-// Background Music is distributed in the hope that it will be useful,
-// but WITHOUT ANY WARRANTY; without even the implied warranty of
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-// GNU General Public License for more details.
-//
-// You should have received a copy of the GNU General Public License
-// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
-
-//
-//  BGMAppVolumes.m
-//  BGMApp
-//
-//  Copyright © 2016, 2017 Kyle Neideck
-//  Copyright © 2017 Andrew Tonner
-//
-
-// Self Include
-#import "BGMAppVolumes.h"
-
-// BGM Includes
-#include "BGM_Types.h"
-#include "BGM_Utils.h"
-
-// PublicUtility Includes
-#include "CACFDictionary.h"
-#include "CACFArray.h"
-#include "CACFString.h"
-
-
-// Tags for UI elements in MainMenu.xib
-static NSInteger const kAppVolumesHeadingMenuItemTag = 3;
-static NSInteger const kSeparatorBelowAppVolumesMenuItemTag = 4;
-
-static float const kSlidersSnapWithin = 5;
-
-static CGFloat const kAppVolumeViewInitialHeight = 20;
-
-@implementation BGMAppVolumes {
-    NSMenu* bgmMenu;
-    
-    NSView* appVolumeView;
-    CGFloat appVolumeViewFullHeight;
-    
-    BGMAudioDeviceManager* audioDevices;
-}
-
-- (id) initWithMenu:(NSMenu*)menu appVolumeView:(NSView*)view audioDevices:(BGMAudioDeviceManager*)devices {
-    if ((self = [super init])) {
-        bgmMenu = menu;
-        appVolumeView = view;
-        appVolumeViewFullHeight = appVolumeView.frame.size.height;
-        audioDevices = devices;
-        
-        // Create the menu items for controlling app volumes
-        [self insertMenuItemsForApps:[[NSWorkspace sharedWorkspace] runningApplications]];
-        
-        // Register for notifications when the user opens or closes apps, so we can update the menu
-        [[NSWorkspace sharedWorkspace] addObserver:self
-                                        forKeyPath:@"runningApplications"
-                                           options:NSKeyValueObservingOptionNew | NSKeyValueObservingOptionOld
-                                           context:nil];
-    }
-    
-    return self;
-}
-
-- (void) dealloc {
-    [[NSWorkspace sharedWorkspace] removeObserver:self forKeyPath:@"runningApplications" context:nil];
-}
-
-#pragma mark UI Modifications
-
-- (void) insertMenuItemsForApps:(NSArray<NSRunningApplication*>*)apps {
-    NSAssert([NSThread isMainThread], @"insertMenuItemsForApps is not thread safe");
-    
-#ifndef NS_BLOCK_ASSERTIONS  // If assertions are enabled
-    auto numMenuItems = [&self]() {
-        NSInteger headingIdx = [bgmMenu indexOfItemWithTag:kAppVolumesHeadingMenuItemTag];
-        NSInteger separatorIdx = [bgmMenu indexOfItemWithTag:kSeparatorBelowAppVolumesMenuItemTag];
-        return separatorIdx - headingIdx - 1;
-    };
-    
-    NSInteger numMenuItemsBeforeInsert = numMenuItems();
-    NSUInteger numApps = 0;
-#endif
-    
-    // Get the app volumes currently set on the device
-    CACFArray appVolumesOnDevice((CFArrayRef)[audioDevices bgmDevice].GetPropertyData_CFType(kBGMAppVolumesAddress), false);
-    
-    NSInteger index = [bgmMenu indexOfItemWithTag:kAppVolumesHeadingMenuItemTag] + 1;
-    
-    // Add a volume-control menu item for each app
-    for (NSRunningApplication* app in apps) {
-        // Only show apps that appear in the dock (at first)
-        // TODO: Would it be better to only show apps that are registered as HAL clients?
-        if (app.activationPolicy != NSApplicationActivationPolicyRegular) continue;
-        
-#ifndef NS_BLOCK_ASSERTIONS  // If assertions are enabled
-        // Count how many apps we should add menu items for so we can check it at the end of the method
-        numApps++;
-#endif
-        
-        NSMenuItem* appVolItem = [self createBlankAppVolumeMenuItem];
-        
-        // Look through the menu item's subviews for the ones we want to set up
-        for (NSView* subview in appVolItem.view.subviews) {
-            if ([subview conformsToProtocol:@protocol(BGMAppVolumeMenuItemSubview)]) {
-                [(NSView<BGMAppVolumeMenuItemSubview>*)subview setUpWithApp:app context:self menuItem:appVolItem];
-            }
-        }
-        
-        // Store the NSRunningApplication object with the menu item so when the app closes we can find the item to remove it
-        appVolItem.representedObject = app;
-        
-        // Set the slider to the volume for this app if we got one from the driver
-        [self setVolumeOfMenuItem:appVolItem fromAppVolumes:appVolumesOnDevice];
-        
-        [bgmMenu insertItem:appVolItem atIndex:index];
-    }
-    
-    NSAssert3(numMenuItems() == (numMenuItemsBeforeInsert + numApps),
-              @"Added more/fewer menu items than there were apps. Items before: %ld, items after: %ld, apps: %lu",
-              (long)numMenuItemsBeforeInsert,
-              (long)numMenuItems(),
-              (unsigned long)numApps);
-}
-
-// Create a blank menu item to copy as a template.
-- (NSMenuItem*) createBlankAppVolumeMenuItem {
-    NSMenuItem* menuItem = [[NSMenuItem alloc] initWithTitle:@"" action:nil keyEquivalent:@""];
-    
-    menuItem.view = appVolumeView;
-    menuItem = [menuItem copy];  // So we can modify a copy of the view, rather than the template itself.
-    
-    return menuItem;
-}
-
-- (void) removeMenuItemsForApps:(NSArray<NSRunningApplication*>*)apps {
-    NSAssert([NSThread isMainThread], @"removeMenuItemsForApps is not thread safe");
-    
-    NSInteger firstItemIndex = [bgmMenu indexOfItemWithTag:kAppVolumesHeadingMenuItemTag] + 1;
-    NSInteger lastItemIndex = [bgmMenu indexOfItemWithTag:kSeparatorBelowAppVolumesMenuItemTag] - 1;
-    
-    // Check each app volume menu item, removing the items that control one of the given apps
-    for (NSInteger i = firstItemIndex; i <= lastItemIndex; i++) {
-        NSMenuItem* item = [bgmMenu itemAtIndex:i];
-        
-        for (NSRunningApplication* appToBeRemoved in apps) {
-            NSRunningApplication* itemApp = item.representedObject;
-            
-            if ([itemApp isEqual:appToBeRemoved]) {
-                [bgmMenu removeItem:item];
-                // Correct i to account for the item we removed, since we're editing the menu in place
-                i--;
-                continue;
-            }
-        }
-    }
-}
-
-- (void) setVolumeOfMenuItem:(NSMenuItem*)menuItem fromAppVolumes:(CACFArray&)appVolumes {
-    // Set menuItem's volume slider to the volume of the app in appVolumes that menuItem represents
-    // Leaves menuItem unchanged if it doesn't match any of the apps in appVolumes
-    NSRunningApplication* representedApp = menuItem.representedObject;
-    
-    for (UInt32 i = 0; i < appVolumes.GetNumberItems(); i++) {
-        CACFDictionary appVolume(false);
-        appVolumes.GetCACFDictionary(i, appVolume);
-        
-        // Match the app to the menu item by pid or bundle id
-        CACFString bundleID;
-        bundleID.DontAllowRelease();
-        appVolume.GetCACFString(CFSTR(kBGMAppVolumesKey_BundleID), bundleID);
-        
-        pid_t pid;
-        appVolume.GetSInt32(CFSTR(kBGMAppVolumesKey_ProcessID), pid);
-        
-        if ((representedApp.processIdentifier == pid) ||
-            [representedApp.bundleIdentifier isEqualToString:(__bridge NSString*)bundleID.GetCFString()]) {
-            CFTypeRef relativeVolume;
-            appVolume.GetCFType(CFSTR(kBGMAppVolumesKey_RelativeVolume), relativeVolume);
-            
-            CFTypeRef panPosition;
-            appVolume.GetCFType(CFSTR(kBGMAppVolumesKey_PanPosition), panPosition);
-            
-            // Update the slider
-            for (NSView* subview in menuItem.view.subviews) {
-                if ([subview respondsToSelector:@selector(setRelativeVolume:)]) {
-                    [subview performSelector:@selector(setRelativeVolume:) withObject:(__bridge NSNumber*)relativeVolume];
-                }
-                if ([subview respondsToSelector:@selector(setPanPosition:)]) {
-                    [subview performSelector:@selector(setPanPosition:) withObject:(__bridge NSNumber*)panPosition];
-                }
-            }
-        }
-    }
-}
-
-- (void) showHideExtraControls:(BGMAVM_ShowMoreControlsButton*)button {
-    // Show or hide an app's extra controls, currently only pan, in its App Volumes menu item.
-    
-    NSMenuItem* menuItem = button.cell.representedObject;
-    
-    BGMAssert(button, "!button");
-    BGMAssert(menuItem, "!menuItem");
-    
-    CGFloat width = menuItem.view.frame.size.width;
-    CGFloat height = menuItem.view.frame.size.height;
-    
-#if DEBUG
-    const char* appName = [((NSRunningApplication*)menuItem.representedObject).localizedName UTF8String];
-#endif
-    
-    auto nearEnough = [](CGFloat x, CGFloat y) {  // Shouldn't be necessary, but just in case.
-        return fabs(x - y) < 0.01;  // We don't need much precision.
-    };
-    
-    if (nearEnough(button.frameCenterRotation, 0.0)) {
-        // Hide extra controls
-        DebugMsg("BGMAppVolumes::showHideExtraControls: Hiding extra controls (%s)", appName);
-        
-        BGMAssert(nearEnough(height, appVolumeViewFullHeight), "Extra controls were already hidden");
-        
-        // Make the menu item shorter to hide the extra controls. Keep the width unchanged.
-        menuItem.view.frameSize = { width, kAppVolumeViewInitialHeight };
-        // Turn the button upside down so the arrowhead points down.
-        button.frameCenterRotation = 180.0;
-        // Move the button up slightly so it aligns with the volume slider.
-        [button setFrameOrigin:NSMakePoint(button.frame.origin.x, button.frame.origin.y - 1)];
-    } else {
-        // Show extra controls
-        DebugMsg("BGMAppVolumes::showHideExtraControls: Showing extra controls (%s)", appName);
-        
-        BGMAssert(nearEnough(button.frameCenterRotation, 180.0), "Unexpected button rotation");
-        BGMAssert(nearEnough(height, kAppVolumeViewInitialHeight), "Extra controls were already shown");
-        
-        // Make the menu item taller to show the extra controls. Keep the width unchanged.
-        menuItem.view.frameSize = { width, appVolumeViewFullHeight };
-        // Turn the button rightside up so the arrowhead points up.
-        button.frameCenterRotation = 0.0;
-        // Move the button down slightly, back to it's original position.
-        [button setFrameOrigin:NSMakePoint(button.frame.origin.x, button.frame.origin.y + 1)];
-    }
-}
-
-#pragma mark KVO
-
-- (void) observeValueForKeyPath:(NSString *)keyPath ofObject:(id)object change:(NSDictionary *)change context:(void *)context
-{
-    #pragma unused (object, context)
-    
-    // KVO callback for the apps currently running on the system. Adds/removes the associated menu items.
-    if ([keyPath isEqualToString:@"runningApplications"]) {
-        NSArray<NSRunningApplication*>* newApps = [change objectForKey:NSKeyValueChangeNewKey];
-        NSArray<NSRunningApplication*>* oldApps = [change objectForKey:NSKeyValueChangeOldKey];
-        
-        int changeKind = [[change valueForKey:NSKeyValueChangeKindKey] intValue];
-        switch (changeKind) {
-            case NSKeyValueChangeInsertion:
-                [self insertMenuItemsForApps:newApps];
-                break;
-                
-            case NSKeyValueChangeRemoval:
-                [self removeMenuItemsForApps:oldApps];
-                break;
-                
-            case NSKeyValueChangeReplacement:
-                [self removeMenuItemsForApps:oldApps];
-                [self insertMenuItemsForApps:newApps];
-                break;
-                
-            case NSKeyValueChangeSetting:
-                [bgmMenu removeAllItems];
-                [self insertMenuItemsForApps:newApps];
-                break;
-        }
-    }
-}
-
-#pragma mark BGMDevice Communication
-
-- (void) sendVolumeChangeToBGMDevice:(SInt32)newVolume appProcessID:(pid_t)appProcessID appBundleID:(NSString*)appBundleID {
-    CACFDictionary appVolumeChange(true);
-    appVolumeChange.AddSInt32(CFSTR(kBGMAppVolumesKey_ProcessID), appProcessID);
-    appVolumeChange.AddString(CFSTR(kBGMAppVolumesKey_BundleID), (__bridge CFStringRef)appBundleID);
-    // The values from our sliders are in [kAppRelativeVolumeMinRawValue, kAppRelativeVolumeMaxRawValue] already
-    appVolumeChange.AddSInt32(CFSTR(kBGMAppVolumesKey_RelativeVolume), newVolume);
-    
-    CACFArray appVolumeChanges(true);
-    appVolumeChanges.AppendDictionary(appVolumeChange.GetDict());
-
-    [audioDevices bgmDevice].SetPropertyData_CFType(kBGMAppVolumesAddress, appVolumeChanges.AsPropertyList());
-}
-
-- (void) sendPanPositionChangeToBGMDevice:(SInt32)newPanPosition appProcessID:(pid_t)appProcessID appBundleID:(NSString*)appBundleID {
-    CACFDictionary appVolumeChange(true);
-    appVolumeChange.AddSInt32(CFSTR(kBGMAppVolumesKey_ProcessID), appProcessID);
-    appVolumeChange.AddString(CFSTR(kBGMAppVolumesKey_BundleID), (__bridge CFStringRef)appBundleID);
-    
-    // The values from our sliders are in [kAppPanLeftRawValue, kAppPanRightRawValue] already
-    appVolumeChange.AddSInt32(CFSTR(kBGMAppVolumesKey_PanPosition), newPanPosition);
-    
-    CACFArray appVolumeChanges(true);
-    appVolumeChanges.AppendDictionary(appVolumeChange.GetDict());
-    
-    [audioDevices bgmDevice].SetPropertyData_CFType(kBGMAppVolumesAddress, appVolumeChanges.AsPropertyList());
-}
-
-@end
-
-#pragma mark Custom Classes (IB)
-
-// Custom classes for the UI elements in the app volume menu items
-
-@implementation BGMAVM_AppIcon
-
-- (void) setUpWithApp:(NSRunningApplication*)app context:(BGMAppVolumes*)ctx menuItem:(NSMenuItem*)menuItem {
-    #pragma unused (ctx, menuItem)
-    
-    self.image = app.icon;
-}
-
-@end
-
-@implementation BGMAVM_AppNameLabel
-
-- (void) setUpWithApp:(NSRunningApplication*)app context:(BGMAppVolumes*)ctx menuItem:(NSMenuItem*)menuItem {
-    #pragma unused (ctx, menuItem)
-    
-    NSString* name = app.localizedName ? (NSString*)app.localizedName : @"";
-    self.stringValue = name;
-}
-
-@end
-
-@implementation BGMAVM_ShowMoreControlsButton
-
-- (void) setUpWithApp:(NSRunningApplication*)app context:(BGMAppVolumes*)ctx menuItem:(NSMenuItem*)menuItem {
-    #pragma unused (app)
-    
-    // Set up the button that show/hide the extra controls (currently only a pan slider) for the app.
-    self.cell.representedObject = menuItem;
-    self.target = ctx;
-    self.action = @selector(showHideExtraControls:);
-    
-    // The menu item starts out with the extra controls visible, so we hide them here.
-    //
-    // TODO: Leave them visible if any of the controls are set to non-default values. The user has no way to
-    //       tell otherwise. Maybe we should also make this button look different if the controls are hidden
-    //       when they have non-default values.
-    [ctx showHideExtraControls:self];
-}
-
-@end
-
-@implementation BGMAVM_VolumeSlider {
-    // Will be set to -1 for apps without a pid
-    pid_t appProcessID;
-    NSString* appBundleID;
-    BGMAppVolumes* context;
-}
-
-- (void) setUpWithApp:(NSRunningApplication*)app context:(BGMAppVolumes*)ctx menuItem:(NSMenuItem*)menuItem {
-    #pragma unused (menuItem)
-    
-    context = ctx;
-    
-    self.target = self;
-    self.action = @selector(appVolumeChanged);
-    
-    appProcessID = app.processIdentifier;
-    appBundleID = app.bundleIdentifier;
-    
-    self.maxValue = kAppRelativeVolumeMaxRawValue;
-    self.minValue = kAppRelativeVolumeMinRawValue;
-}
-
-// We have to handle snapping for volume sliders ourselves because adding a tick mark (snap point) in Interface Builder
-// changes how the slider looks.
-- (void) snap {
-    // Snap to the 50% point.
-    float midPoint = static_cast<float>((self.maxValue + self.minValue) / 2);
-    if (self.floatValue > (midPoint - kSlidersSnapWithin) && self.floatValue < (midPoint + kSlidersSnapWithin)) {
-        self.floatValue = midPoint;
-    }
-}
-
-- (void) setRelativeVolume:(NSNumber*)relativeVolume {
-    self.intValue = relativeVolume.intValue;
-    [self snap];
-}
-
-- (void) appVolumeChanged {
-    // TODO: This (sending updates to the driver) should probably be rate-limited. It uses a fair bit of CPU for me.
-    
-    DebugMsg("BGMAppVolumes::appVolumeChanged: App volume for %s changed to %d", appBundleID.UTF8String, self.intValue);
-    
-    [self snap];
-    
-    [context sendVolumeChangeToBGMDevice:self.intValue appProcessID:appProcessID appBundleID:appBundleID];
-}
-
-@end
-
-@implementation BGMAVM_PanSlider {
-    // Will be set to -1 for apps without a pid
-    pid_t appProcessID;
-    NSString* appBundleID;
-    BGMAppVolumes* context;
-}
-
-- (void) setUpWithApp:(NSRunningApplication*)app context:(BGMAppVolumes*)ctx menuItem:(NSMenuItem*)menuItem {
-    #pragma unused (menuItem)
-    
-    context = ctx;
-    
-    self.target = self;
-    self.action = @selector(appPanPositionChanged);
-    
-    appProcessID = app.processIdentifier;
-    appBundleID = app.bundleIdentifier;
-    
-    self.minValue = kAppPanLeftRawValue;
-    self.maxValue = kAppPanRightRawValue;
-}
-
-- (void) setPanPosition:(NSNumber *)panPosition {
-    self.intValue = panPosition.intValue;
-}
-
-- (void) appPanPositionChanged {
-    // TODO: This (sending updates to the driver) should probably be rate-limited. It uses a fair bit of CPU for me.
-    
-    DebugMsg("BGMAppVolumes::appPanPositionChanged: App pan position for %s changed to %d", appBundleID.UTF8String, self.intValue);
-    
-    [context sendPanPositionChangeToBGMDevice:self.intValue appProcessID:appProcessID appBundleID:appBundleID];
-}
-
-@end
-

BGMApp/BGMApp/BGMAppVolumesController.h

@@ -0,0 +1,60 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMAppVolumesController.h
+//  BGMApp
+//
+//  Copyright © 2017 Kyle Neideck
+//  Copyright © 2021 Marcus Wu
+//
+
+// Local Includes
+#import "BGMAudioDeviceManager.h"
+
+// System Includes
+#import <Cocoa/Cocoa.h>
+
+
+#pragma clang assume_nonnull begin
+
+typedef struct BGMAppVolumeAndPan {
+    int volume;
+    int pan;
+} BGMAppVolumeAndPan;
+
+@interface BGMAppVolumesController : NSObject
+
+- (id) initWithMenu:(NSMenu*)menu
+      appVolumeView:(NSView*)view
+       audioDevices:(BGMAudioDeviceManager*)audioDevices;
+
+// See BGMBackgroundMusicDevice::SetAppVolume.
+- (void)  setVolume:(SInt32)volume
+forAppWithProcessID:(pid_t)processID
+           bundleID:(NSString* __nullable)bundleID;
+
+// See BGMBackgroundMusicDevice::SetPanVolume.
+- (void) setPanPosition:(SInt32)pan
+    forAppWithProcessID:(pid_t)processID
+               bundleID:(NSString* __nullable)bundleID;
+
+- (BGMAppVolumeAndPan) getVolumeAndPanForApp:(NSRunningApplication *)app;
+- (void) setVolumeAndPan:(BGMAppVolumeAndPan)volumeAndPan forApp:(NSRunningApplication*)app;
+
+@end
+
+#pragma clang assume_nonnull end
+

BGMApp/BGMApp/BGMAppVolumesController.mm

@@ -0,0 +1,259 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMAppVolumesController.mm
+//  BGMApp
+//
+//  Copyright © 2017, 2018 Kyle Neideck
+//  Copyright © 2017 Andrew Tonner
+//  Copyright © 2021 Marcus Wu
+//
+
+// Self Include
+#import "BGMAppVolumesController.h"
+
+// Local Includes
+#import "BGM_Types.h"
+#import "BGM_Utils.h"
+#import "BGMAppVolumes.h"
+
+// PublicUtility Includes
+#import "CACFArray.h"
+#import "CACFDictionary.h"
+#import "CACFString.h"
+
+// System Includes
+#include <libproc.h>
+
+
+#pragma clang assume_nonnull begin
+
+@implementation BGMAppVolumesController {
+    // The App Volumes UI.
+    BGMAppVolumes* appVolumes;
+    BGMAudioDeviceManager* audioDevices;
+}
+
+#pragma mark Initialisation
+
+- (id) initWithMenu:(NSMenu*)menu
+      appVolumeView:(NSView*)view
+       audioDevices:(BGMAudioDeviceManager*)devices {
+    if ((self = [super init])) {
+        audioDevices = devices;
+        appVolumes = [[BGMAppVolumes alloc] initWithController:self
+                                                       bgmMenu:menu
+                                                 appVolumeView:view];
+
+        // Create the menu items for controlling app volumes.
+        NSArray<NSRunningApplication*>* apps = [[NSWorkspace sharedWorkspace] runningApplications];
+        [self insertMenuItemsForApps:apps];
+
+        // Register for notifications when the user opens or closes apps, so we can update the menu.
+        auto opts = NSKeyValueObservingOptionNew | NSKeyValueObservingOptionOld;
+        [[NSWorkspace sharedWorkspace] addObserver:self
+                                        forKeyPath:@"runningApplications"
+                                           options:opts
+                                           context:nil];
+    }
+
+    return self;
+}
+
+- (void) dealloc {
+    [[NSWorkspace sharedWorkspace] removeObserver:self
+                                       forKeyPath:@"runningApplications"
+                                          context:nil];
+}
+
+// Adds a volume control menu item for each given app.
+- (void) insertMenuItemsForApps:(NSArray<NSRunningApplication*>*)apps {
+    NSAssert([NSThread isMainThread], @"insertMenuItemsForApps is not thread safe");
+
+    // TODO: Handle the C++ exceptions this method can throw. They can cause crashes because this
+    //       method is called in a KVO handler.
+
+    // Get the app volumes currently set on the device
+    CACFArray volumesFromBGMDevice([audioDevices bgmDevice].GetAppVolumes(), false);
+
+    for (NSRunningApplication* app in apps) {
+        if ([self shouldBeIncludedInMenu:app]) {
+            BGMAppVolumeAndPan initial = [self getVolumeAndPanForApp:app
+                                                         fromVolumes:volumesFromBGMDevice];
+            [appVolumes insertMenuItemForApp:app
+                               initialVolume:initial.volume
+                                  initialPan:initial.pan];
+        }
+    }
+}
+
+- (BGMAppVolumeAndPan) getVolumeAndPanForApp:(NSRunningApplication *)app {
+    return [appVolumes getVolumeAndPanForApp:app];
+}
+
+- (void) setVolumeAndPan:(BGMAppVolumeAndPan)volumeAndPan forApp:(NSRunningApplication*)app {
+    [appVolumes setVolumeAndPan:volumeAndPan forApp:app];
+    if (volumeAndPan.volume != -1) {
+        [self setVolume:volumeAndPan.volume forAppWithProcessID:app.processIdentifier bundleID:app.bundleIdentifier];
+    }
+    if (volumeAndPan.pan != kAppPanNoValue) {
+        [self setPanPosition:volumeAndPan.pan forAppWithProcessID:app.processIdentifier bundleID:app.bundleIdentifier];
+    }
+}
+
+- (BGMAppVolumeAndPan) getVolumeAndPanForApp:(NSRunningApplication*)app
+                                 fromVolumes:(const CACFArray&)volumes {
+    BGMAppVolumeAndPan volumeAndPan = {
+        .volume = -1,
+        .pan = kAppPanNoValue
+    };
+
+    for (UInt32 i = 0; i < volumes.GetNumberItems(); i++) {
+        CACFDictionary appVolume(false);
+        volumes.GetCACFDictionary(i, appVolume);
+
+        // Match the app to the volume/pan by pid or bundle ID.
+        CACFString bundleID;
+        bundleID.DontAllowRelease();
+        appVolume.GetCACFString(CFSTR(kBGMAppVolumesKey_BundleID), bundleID);
+
+        pid_t pid;
+        appVolume.GetSInt32(CFSTR(kBGMAppVolumesKey_ProcessID), pid);
+
+        if ((app.processIdentifier == pid) ||
+            [app.bundleIdentifier isEqualToString:(__bridge NSString*)bundleID.GetCFString()]) {
+            // Found a match, so read the volume and pan.
+            appVolume.GetSInt32(CFSTR(kBGMAppVolumesKey_RelativeVolume), volumeAndPan.volume);
+            appVolume.GetSInt32(CFSTR(kBGMAppVolumesKey_PanPosition), volumeAndPan.pan);
+            break;
+        }
+    }
+
+    return volumeAndPan;
+}
+
+- (BOOL) shouldBeIncludedInMenu:(NSRunningApplication*)app {
+    // Ignore hidden apps and Background Music itself.
+    // TODO: Would it be better to only show apps that are registered as HAL clients?
+    BOOL isHidden = app.activationPolicy != NSApplicationActivationPolicyRegular &&
+                    app.activationPolicy != NSApplicationActivationPolicyAccessory;
+
+    NSString* bundleID = app.bundleIdentifier;
+    BOOL isBGMApp = bundleID && [@kBGMAppBundleID isEqualToString:BGMNN(bundleID)];
+
+    return !isHidden && !isBGMApp;
+}
+
+- (void) removeMenuItemsForApps:(NSArray<NSRunningApplication*>*)apps {
+    NSAssert([NSThread isMainThread], @"removeMenuItemsForApps is not thread safe");
+
+    for (NSRunningApplication* app in apps) {
+        [appVolumes removeMenuItemForApp:app];
+    }
+}
+
+#pragma mark Accessors
+
+- (void)  setVolume:(SInt32)volume
+forAppWithProcessID:(pid_t)processID
+           bundleID:(NSString* __nullable)bundleID {
+    // Update the app's volume.
+    audioDevices.bgmDevice.SetAppVolume(volume, processID, (__bridge_retained CFStringRef)bundleID);
+
+    // If this volume is for FaceTime, set the volume for the avconferenced process as well. This
+    // works around FaceTime not playing its own audio. It plays UI sounds through
+    // systemsoundserverd and call audio through avconferenced.
+    //
+    // This isn't ideal because other apps might play audio through avconferenced, but I don't see a
+    // good way we could find out which app is actually playing the audio. We could probably figure
+    // it out from reading avconferenced's logs, at least, if it turns out to be important. See
+    // https://github.com/kyleneideck/BackgroundMusic/issues/139.
+    if ([bundleID isEqual:@"com.apple.FaceTime"]) {
+        [self setAvconferencedVolume:volume];
+    }
+}
+
+- (void) setAvconferencedVolume:(SInt32)volume {
+    // TODO: This volume will be lost if avconferenced is restarted.
+    pid_t pids[1024];
+    size_t procCount = proc_listallpids(pids, 1024);
+    char path[PROC_PIDPATHINFO_MAXSIZE];
+
+    for (int i = 0; i < procCount; i++) {
+        pid_t pid = pids[i];
+
+        if (proc_pidpath(pid, path, sizeof(path)) > 0 &&
+            strncmp(path, "/usr/libexec/avconferenced", sizeof(path)) == 0) {
+            DebugMsg("Setting avconferenced volume: %d", volume);
+            audioDevices.bgmDevice.SetAppVolume(volume, pid, nullptr);
+            return;
+        }
+    }
+
+    LogWarning("Failed to set avconferenced volume.");
+}
+
+- (void) setPanPosition:(SInt32)pan
+    forAppWithProcessID:(pid_t)processID
+               bundleID:(NSString* __nullable)bundleID {
+    audioDevices.bgmDevice.SetAppPanPosition(pan,
+                                             processID,
+                                             (__bridge_retained CFStringRef)bundleID);
+}
+
+#pragma mark KVO
+
+- (void) observeValueForKeyPath:(NSString* __nullable)keyPath
+                       ofObject:(id __nullable)object
+                         change:(NSDictionary* __nullable)change
+                        context:(void* __nullable)context
+{
+    #pragma unused (object, context)
+
+    // KVO callback for the apps currently running on the system. Adds/removes the associated menu
+    // items.
+    if (keyPath && change && [keyPath isEqualToString:@"runningApplications"]) {
+        NSArray<NSRunningApplication*>* newApps = change[NSKeyValueChangeNewKey];
+        NSArray<NSRunningApplication*>* oldApps = change[NSKeyValueChangeOldKey];
+
+        int changeKind = [change[NSKeyValueChangeKindKey] intValue];
+
+        switch (changeKind) {
+            case NSKeyValueChangeInsertion:
+                [self insertMenuItemsForApps:newApps];
+                break;
+
+            case NSKeyValueChangeRemoval:
+                [self removeMenuItemsForApps:oldApps];
+                break;
+
+            case NSKeyValueChangeReplacement:
+                [self removeMenuItemsForApps:oldApps];
+                [self insertMenuItemsForApps:newApps];
+                break;
+
+            case NSKeyValueChangeSetting:
+                [appVolumes removeAllAppVolumeMenuItems];
+                [self insertMenuItemsForApps:newApps];
+                break;
+        }
+    }
+}
+
+@end
+
+#pragma clang assume_nonnull end
+

BGMApp/BGMApp/BGMAppWatcher.h

@@ -0,0 +1,49 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMAppWatcher.h
+//  BGMApp
+//
+//  Copyright © 2019 Kyle Neideck
+//
+//  Calls callback functions when a given application is launched or terminated. Starts watching
+//  after being initialised, stops after being destroyed.
+//
+
+// System Includes
+#import <Foundation/Foundation.h>
+
+
+#pragma clang assume_nonnull begin
+
+@interface BGMAppWatcher : NSObject
+
+// appLaunched will be called when the application is launched and appTerminated will be called when
+// it's terminated. Background apps, status bar apps, etc. are ignored.
+- (instancetype) initWithBundleID:(NSString*)bundleID
+                      appLaunched:(void(^)(void))appLaunched
+                    appTerminated:(void(^)(void))appTerminated;
+
+// With this constructor, when an application is launched or terminated, isMatchingBundleID will be
+// called first to decide whether or not the callback should be called.
+- (instancetype) initWithAppLaunched:(void(^)(void))appLaunched
+                       appTerminated:(void(^)(void))appTerminated
+                  isMatchingBundleID:(BOOL(^)(NSString* appBundleID))isMatchingBundleID;
+
+@end
+
+#pragma clang assume_nonnull end
+

BGMApp/BGMApp/BGMAppWatcher.m

@@ -0,0 +1,109 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMAppWatcher.m
+//  BGMApp
+//
+//  Copyright © 2019 Kyle Neideck
+//
+
+// Self Include
+#import "BGMAppWatcher.h"
+
+// System Includes
+#import <Cocoa/Cocoa.h>
+
+
+#pragma clang assume_nonnull begin
+
+@implementation BGMAppWatcher {
+    // Tokens for the notification observers so we can remove them in dealloc.
+    id<NSObject> didLaunchToken;
+    id<NSObject> didTerminateToken;
+}
+
+- (instancetype) initWithBundleID:(NSString*)bundleID
+                      appLaunched:(void(^)(void))appLaunched
+                    appTerminated:(void(^)(void))appTerminated {
+    return [self initWithAppLaunched:appLaunched
+                       appTerminated:appTerminated
+                  isMatchingBundleID:^BOOL(NSString* appBundleID) {
+                      return [bundleID isEqualToString:appBundleID];
+                  }];
+}
+
+- (instancetype) initWithAppLaunched:(void(^)(void))appLaunched
+                       appTerminated:(void(^)(void))appTerminated
+                  isMatchingBundleID:(BOOL(^)(NSString*))isMatchingBundleID
+{
+    if ((self = [super init])) {
+        NSNotificationCenter* center = [NSWorkspace sharedWorkspace].notificationCenter;
+
+        didLaunchToken =
+            [center addObserverForName:NSWorkspaceDidLaunchApplicationNotification
+                                object:nil
+                                 queue:nil
+                            usingBlock:^(NSNotification* notification) {
+                                if ([BGMAppWatcher shouldBeHandled:notification
+                                                isMatchingBundleID:isMatchingBundleID]) {
+                                    appLaunched();
+                                }
+                            }];
+
+        didTerminateToken =
+            [center addObserverForName:NSWorkspaceDidTerminateApplicationNotification
+                                object:nil
+                                 queue:nil
+                            usingBlock:^(NSNotification* notification) {
+                                if ([BGMAppWatcher shouldBeHandled:notification
+                                                isMatchingBundleID:isMatchingBundleID]) {
+                                    appTerminated();
+                                }
+                            }];
+    }
+
+    return self;
+}
+
+// Returns YES if we should call the app launch/termination callback for this NSNotification.
++ (BOOL) shouldBeHandled:(NSNotification*)notification
+      isMatchingBundleID:(BOOL(^)(NSString*))isMatchingBundleID {
+    NSString* __nullable notifiedBundleID =
+        [notification.userInfo[NSWorkspaceApplicationKey] bundleIdentifier];
+
+    // Ignore the notification if the app doesn't have a bundle ID or isMatchingBundleID returns NO.
+    return notifiedBundleID && isMatchingBundleID((NSString*)notifiedBundleID);
+}
+
+- (void) dealloc {
+    // Remove the application launch/termination observers.
+    NSNotificationCenter* center = [NSWorkspace sharedWorkspace].notificationCenter;
+
+    if (didLaunchToken) {
+        [center removeObserver:didLaunchToken];
+        didLaunchToken = nil;
+    }
+
+    if (didTerminateToken) {
+        [center removeObserver:didTerminateToken];
+        didTerminateToken = nil;
+    }
+}
+
+@end
+
+#pragma clang assume_nonnull end
+

BGMApp/BGMApp/BGMAudioDevice.cpp

@@ -0,0 +1,391 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMAudioDevice.cpp
+//  BGMApp
+//
+//  Copyright © 2017 Kyle Neideck
+//
+
+// Self Include
+#include "BGMAudioDevice.h"
+
+// Local Includes
+#include "BGM_Types.h"
+
+// System Includes
+#include <AudioToolbox/AudioServices.h>
+
+
+#pragma mark Construction/Destruction
+
+BGMAudioDevice::BGMAudioDevice(AudioObjectID inAudioDevice)
+:
+    CAHALAudioDevice(inAudioDevice)
+{
+}
+
+BGMAudioDevice::BGMAudioDevice(CFStringRef inUID)
+:
+    CAHALAudioDevice(inUID)
+{
+}
+
+BGMAudioDevice::BGMAudioDevice(const CAHALAudioDevice& inDevice)
+:
+    BGMAudioDevice(inDevice.GetObjectID())
+{
+}
+
+BGMAudioDevice::~BGMAudioDevice()
+{
+}
+
+bool    BGMAudioDevice::CanBeOutputDeviceInBGMApp() const
+{
+    CFStringRef uid = CopyDeviceUID();
+    assert(uid != nullptr);
+
+    bool isNullDevice = CFEqual(uid, CFSTR(kBGMNullDeviceUID));
+    CFRelease(uid);
+
+    bool hasOutputChannels = GetTotalNumberChannels(/* inIsInput = */ false) > 0;
+    bool canBeDefault = CanBeDefaultDevice(/* inIsInput = */ false, /* inIsSystem = */ false);
+
+    return !IsBGMDeviceInstance() &&
+            !isNullDevice &&
+            !IsHidden() &&
+            hasOutputChannels &&
+            canBeDefault;
+}
+
+#pragma mark Available Controls
+
+bool    BGMAudioDevice::HasSettableMasterVolume(AudioObjectPropertyScope inScope) const
+{
+    return HasVolumeControl(inScope, kMasterChannel) &&
+        VolumeControlIsSettable(inScope, kMasterChannel);
+}
+
+bool    BGMAudioDevice::HasSettableVirtualMasterVolume(AudioObjectPropertyScope inScope) const
+{
+    AudioObjectPropertyAddress virtualMasterVolumeAddress = {
+        kAudioHardwareServiceDeviceProperty_VirtualMainVolume,
+        inScope,
+        kAudioObjectPropertyElementMaster
+    };
+
+    // TODO: Replace these calls deprecated AudioToolbox functions. There are more below.
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdeprecated-declarations"
+    Boolean virtualMasterVolumeIsSettable;
+    OSStatus err = AudioHardwareServiceIsPropertySettable(GetObjectID(),
+                                                          &virtualMasterVolumeAddress,
+                                                          &virtualMasterVolumeIsSettable);
+    virtualMasterVolumeIsSettable &= (err == kAudioServicesNoError);
+
+    bool hasVirtualMasterVolume =
+        AudioHardwareServiceHasProperty(GetObjectID(), &virtualMasterVolumeAddress);
+#pragma clang diagnostic pop
+
+    return hasVirtualMasterVolume && virtualMasterVolumeIsSettable;
+}
+
+bool    BGMAudioDevice::HasSettableMasterMute(AudioObjectPropertyScope inScope) const
+{
+    return HasMuteControl(inScope, kMasterChannel) &&
+        MuteControlIsSettable(inScope, kMasterChannel);
+}
+
+#pragma mark Control Values Accessors
+
+void    BGMAudioDevice::CopyMuteFrom(const BGMAudioDevice inDevice,
+                                     AudioObjectPropertyScope inScope)
+{
+    // TODO: Support for devices that have per-channel mute controls but no master mute control
+    if(HasSettableMasterMute(inScope) && inDevice.HasMuteControl(inScope, kMasterChannel))
+    {
+        SetMuteControlValue(inScope,
+                            kMasterChannel,
+                            inDevice.GetMuteControlValue(inScope, kMasterChannel));
+    }
+}
+
+void    BGMAudioDevice::CopyVolumeFrom(const BGMAudioDevice inDevice,
+                                       AudioObjectPropertyScope inScope)
+{
+    // Get the volume of the other device.
+    bool didGetVolume = false;
+    Float32 volume = FLT_MIN;
+
+    if(inDevice.HasVolumeControl(inScope, kMasterChannel))
+    {
+        volume = inDevice.GetVolumeControlScalarValue(inScope, kMasterChannel);
+        didGetVolume = true;
+    }
+
+    // Use the average channel volume of the other device if it has no master volume.
+    if(!didGetVolume)
+    {
+        UInt32 numChannels =
+            inDevice.GetTotalNumberChannels(inScope == kAudioObjectPropertyScopeInput);
+        volume = 0;
+
+        for(UInt32 channel = 1; channel <= numChannels; channel++)
+        {
+            if(inDevice.HasVolumeControl(inScope, channel))
+            {
+                volume += inDevice.GetVolumeControlScalarValue(inScope, channel);
+                didGetVolume = true;
+            }
+        }
+
+        if(numChannels > 0)  // Avoid divide by zero.
+        {
+            volume /= numChannels;
+        }
+    }
+
+    // Set the volume of this device.
+    if(didGetVolume && volume != FLT_MIN)
+    {
+        bool didSetVolume = false;
+
+        try
+        {
+            didSetVolume = SetMasterVolumeScalar(inScope, volume);
+        }
+        catch(CAException e)
+        {
+            OSStatus err = e.GetError();
+            char err4CC[5] = CA4CCToCString(err);
+            CFStringRef uid = CopyDeviceUID();
+            LogWarning("BGMAudioDevice::CopyVolumeFrom: CAException '%s' trying to set master "
+                       "volume of %s",
+                       err4CC,
+                       CFStringGetCStringPtr(uid, kCFStringEncodingUTF8));
+            CFRelease(uid);
+        }
+
+        if(!didSetVolume)
+        {
+            // Couldn't find a master volume control to set, so try to find a virtual one
+            Float32 virtualMasterVolume;
+            bool success = inDevice.GetVirtualMasterVolumeScalar(inScope, virtualMasterVolume);
+            if(success)
+            {
+                didSetVolume = SetVirtualMasterVolumeScalar(inScope, virtualMasterVolume);
+            }
+        }
+
+        if(!didSetVolume)
+        {
+            // Couldn't set a master or virtual master volume, so as a fallback try to set each
+            // channel individually.
+            UInt32 numChannels = GetTotalNumberChannels(inScope == kAudioObjectPropertyScopeInput);
+            for(UInt32 channel = 1; channel <= numChannels; channel++)
+            {
+                if(HasVolumeControl(inScope, channel) && VolumeControlIsSettable(inScope, channel))
+                {
+                    SetVolumeControlScalarValue(inScope, channel, volume);
+                }
+            }
+        }
+    }
+}
+
+bool    BGMAudioDevice::SetMasterVolumeScalar(AudioObjectPropertyScope inScope, Float32 inVolume)
+{
+    if(HasSettableMasterVolume(inScope))
+    {
+        SetVolumeControlScalarValue(inScope, kMasterChannel, inVolume);
+        return true;
+    }
+
+    return false;
+}
+
+bool    BGMAudioDevice::GetVirtualMasterVolumeScalar(AudioObjectPropertyScope inScope,
+                                                     Float32& outVirtualMasterVolume) const
+{
+    AudioObjectPropertyAddress virtualMasterVolumeAddress = {
+        kAudioHardwareServiceDeviceProperty_VirtualMainVolume,
+        inScope,
+        kAudioObjectPropertyElementMaster
+    };
+
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdeprecated-declarations"
+    if(!AudioHardwareServiceHasProperty(GetObjectID(), &virtualMasterVolumeAddress))
+    {
+        return false;
+    }
+#pragma clang diagnostic pop
+
+    UInt32 virtualMasterVolumePropertySize = sizeof(Float32);
+    return kAudioServicesNoError == AHSGetPropertyData(GetObjectID(),
+                                                       &virtualMasterVolumeAddress,
+                                                       &virtualMasterVolumePropertySize,
+                                                       &outVirtualMasterVolume);
+}
+
+bool    BGMAudioDevice::SetVirtualMasterVolumeScalar(AudioObjectPropertyScope inScope,
+                                                     Float32 inVolume)
+{
+    // TODO: For me, setting the virtual master volume sets all the device's channels to the same volume, meaning you can't
+    //       keep any channels quieter than the others. The expected behaviour is to scale the channel volumes
+    //       proportionally. So to do this properly I think we'd have to store BGMDevice's previous volume and calculate
+    //       each channel's new volume from its current volume and the distance between BGMDevice's old and new volumes.
+    //
+    //       The docs kAudioHardwareServiceDeviceProperty_VirtualMasterVolume for say
+    //           "If the device has individual channel volume controls, this property will apply to those identified by the
+    //           device's preferred multi-channel layout (or preferred stereo pair if the device is stereo only). Note that
+    //           this control maintains the relative balance between all the channels it affects.
+    //       so I'm not sure why that's not working here. As a workaround we take the to device's (virtual master) balance
+    //       before changing the volume and set it back after, but of course that'll only work for stereo devices.
+
+    bool didSetVolume = false;
+
+    if(HasSettableVirtualMasterVolume(inScope))
+    {
+        // Not sure why, but setting the virtual master volume sets all channels to the same volume. As a workaround, we store
+        // the current balance here so we can reset it after setting the volume.
+        Float32 virtualMasterBalance;
+        bool didGetVirtualMasterBalance = GetVirtualMasterBalance(inScope, virtualMasterBalance);
+
+        AudioObjectPropertyAddress virtualMasterVolumeAddress = {
+            kAudioHardwareServiceDeviceProperty_VirtualMainVolume,
+            inScope,
+            kAudioObjectPropertyElementMaster
+        };
+
+        didSetVolume = (kAudioServicesNoError == AHSSetPropertyData(GetObjectID(),
+                                                                    &virtualMasterVolumeAddress,
+                                                                    sizeof(Float32),
+                                                                    &inVolume));
+
+        // Reset the balance
+        AudioObjectPropertyAddress virtualMasterBalanceAddress = {
+            kAudioHardwareServiceDeviceProperty_VirtualMainBalance,
+            inScope,
+            kAudioObjectPropertyElementMaster
+        };
+
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdeprecated-declarations"
+        if(didSetVolume &&
+           didGetVirtualMasterBalance &&
+           AudioHardwareServiceHasProperty(GetObjectID(), &virtualMasterBalanceAddress))
+        {
+            Boolean balanceIsSettable;
+            OSStatus err = AudioHardwareServiceIsPropertySettable(GetObjectID(),
+                                                                  &virtualMasterBalanceAddress,
+                                                                  &balanceIsSettable);
+            if(err == kAudioServicesNoError && balanceIsSettable)
+            {
+                AHSSetPropertyData(GetObjectID(),
+                                   &virtualMasterBalanceAddress,
+                                   sizeof(Float32),
+                                   &virtualMasterBalance);
+            }
+        }
+#pragma clang diagnostic pop
+    }
+
+    return didSetVolume;
+}
+
+bool    BGMAudioDevice::GetVirtualMasterBalance(AudioObjectPropertyScope inScope,
+                                                Float32& outVirtualMasterBalance) const
+{
+    AudioObjectPropertyAddress virtualMasterBalanceAddress = {
+        kAudioHardwareServiceDeviceProperty_VirtualMainBalance,
+        inScope,
+        kAudioObjectPropertyElementMaster
+    };
+
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdeprecated-declarations"
+    if(!AudioHardwareServiceHasProperty(GetObjectID(), &virtualMasterBalanceAddress))
+    {
+        return false;
+    }
+#pragma clang diagnostic pop
+
+    UInt32 virtualMasterVolumePropertySize = sizeof(Float32);
+    return kAudioServicesNoError == AHSGetPropertyData(GetObjectID(),
+                                                       &virtualMasterBalanceAddress,
+                                                       &virtualMasterVolumePropertySize,
+                                                       &outVirtualMasterBalance);
+}
+
+#pragma mark Implementation
+
+bool    BGMAudioDevice::IsBGMDevice(bool inIncludeUISoundsInstance) const
+{
+    bool isBGMDevice = false;
+
+    if(GetObjectID() != kAudioObjectUnknown)
+    {
+        // Check the device's UID to see whether it's BGMDevice.
+        CFStringRef uid = CopyDeviceUID();
+        if (uid == nullptr) {
+            return isBGMDevice;
+        }
+
+        isBGMDevice =
+            CFEqual(uid, CFSTR(kBGMDeviceUID)) ||
+                    (inIncludeUISoundsInstance && CFEqual(uid, CFSTR(kBGMDeviceUID_UISounds)));
+
+        CFRelease(uid);
+    }
+
+    return isBGMDevice;
+}
+
+// static
+OSStatus    BGMAudioDevice::AHSGetPropertyData(AudioObjectID inObjectID,
+                                               const AudioObjectPropertyAddress* inAddress,
+                                               UInt32* ioDataSize,
+                                               void* outData)
+{
+    // The docs for AudioHardwareServiceGetPropertyData specifically allow passing NULL for
+    // inQualifierData as we do here, but it's declared in an assume_nonnull section so we have to
+    // disable the warning here. I'm not sure why inQualifierData isn't __nullable. I'm assuming
+    // it's either a backwards compatibility thing or just a bug.
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wnonnull"
+#pragma clang diagnostic ignored "-Wdeprecated-declarations"
+    // The non-depreciated version of this (and the setter below) doesn't seem to support devices
+    // other than the default
+    return AudioHardwareServiceGetPropertyData(inObjectID, inAddress, 0, NULL, ioDataSize, outData);
+#pragma clang diagnostic pop
+}
+
+// static
+OSStatus    BGMAudioDevice::AHSSetPropertyData(AudioObjectID inObjectID,
+                                               const AudioObjectPropertyAddress* inAddress,
+                                               UInt32 inDataSize,
+                                               const void* inData)
+{
+    // See the explanation about these pragmas in AHSGetPropertyData
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wnonnull"
+#pragma clang diagnostic ignored "-Wdeprecated-declarations"
+    return AudioHardwareServiceSetPropertyData(inObjectID, inAddress, 0, NULL, inDataSize, inData);
+#pragma clang diagnostic pop
+}
+

BGMApp/BGMApp/BGMAudioDevice.h

@@ -0,0 +1,121 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//  BGMAudioDevice.h
+//  BGMApp
+//
+//  Copyright © 2017, 2020 Kyle Neideck
+//
+//  A HAL audio device. Note that this class's only state is the AudioObjectID of the device.
+//
+
+#ifndef BGMApp__BGMAudioDevice
+#define BGMApp__BGMAudioDevice
+
+// PublicUtility Includes
+#include "CAHALAudioDevice.h"
+
+
+class BGMAudioDevice
+:
+    public CAHALAudioDevice
+{
+
+#pragma mark Construction/Destruction
+
+public:
+                       BGMAudioDevice(AudioObjectID inAudioDevice);
+    /*!
+     Creates a BGMAudioDevice with the Audio Object ID of the device whose UID is inUID or, if no
+     such device is found, kAudioObjectUnknown.
+
+     @throws CAException If the HAL returns an error when queried for the device's ID.
+     @see kAudioPlugInPropertyTranslateUIDToDevice in AudioHardwareBase.h.
+     */
+                       BGMAudioDevice(CFStringRef inUID);
+                       BGMAudioDevice(const CAHALAudioDevice& inDevice);
+    virtual            ~BGMAudioDevice();
+
+#if defined(__OBJC__)
+
+    // Hack/workaround for Objective-C classes so we don't have to use pointers for instance
+    // variables.
+                       BGMAudioDevice() : BGMAudioDevice(kAudioObjectUnknown) { }
+
+#endif /* defined(__OBJC__) */
+
+                       operator AudioObjectID() const { return GetObjectID(); }
+
+    /*!
+     @return True if this device is BGMDevice. (Specifically, the main instance of BGMDevice, not
+             the instance used for UI sounds.)
+     @throws CAException If the HAL returns an error when queried.
+     */
+    bool               IsBGMDevice() const { return IsBGMDevice(false); };
+    /*!
+     @return True if this device is either the main instance of BGMDevice (the device named
+             "Background Music") or the instance used for UI sounds (the device named "Background
+             Music (UI Sounds)").
+     @throws CAException If the HAL returns an error when queried.
+     */
+    bool               IsBGMDeviceInstance() const { return IsBGMDevice(true); };
+
+    /*!
+     @return True if this device can be set as the output device in BGMApp.
+     @throws CAException If the HAL returns an error when queried.
+     */
+    bool               CanBeOutputDeviceInBGMApp() const;
+
+#pragma mark Available Controls
+
+    bool               HasSettableMasterVolume(AudioObjectPropertyScope inScope) const;
+    bool               HasSettableVirtualMasterVolume(AudioObjectPropertyScope inScope) const;
+    bool               HasSettableMasterMute(AudioObjectPropertyScope inScope) const;
+
+#pragma mark Control Values Accessors
+
+    void               CopyMuteFrom(const BGMAudioDevice inDevice,
+                                    AudioObjectPropertyScope inScope);
+    void               CopyVolumeFrom(const BGMAudioDevice inDevice,
+                                      AudioObjectPropertyScope inScope);
+
+    bool               SetMasterVolumeScalar(AudioObjectPropertyScope inScope, Float32 inVolume);
+    
+    bool               GetVirtualMasterVolumeScalar(AudioObjectPropertyScope inScope,
+                                                    Float32& outVirtualMasterVolume) const;
+    bool               SetVirtualMasterVolumeScalar(AudioObjectPropertyScope inScope,
+                                                    Float32 inVolume);
+
+    bool               GetVirtualMasterBalance(AudioObjectPropertyScope inScope,
+                                               Float32& outVirtualMasterBalance) const;
+
+#pragma mark Implementation
+
+private:
+    bool               IsBGMDevice(bool inIncludingUISoundsInstance) const;
+
+    static OSStatus    AHSGetPropertyData(AudioObjectID inObjectID,
+                                          const AudioObjectPropertyAddress* inAddress,
+                                          UInt32* ioDataSize,
+                                          void* outData);
+    static OSStatus    AHSSetPropertyData(AudioObjectID inObjectID,
+                                          const AudioObjectPropertyAddress* inAddress,
+                                          UInt32 inDataSize,
+                                          const void* inData);
+
+};
+
+#endif /* BGMApp__BGMAudioDevice */
+

BGMApp/BGMApp/BGMAudioDeviceManager.h

@@ -17,31 +17,46 @@
 //  BGMAudioDeviceManager.h
 //  BGMApp
 //
-//  Copyright © 2016 Kyle Neideck
+//  Copyright © 2016-2018 Kyle Neideck
 //
-//  Manages the BGMDevice and the output device. Sets the system's current default device as the
-//  output device on init, then starts playthrough and mirroring the devices' controls. The output
-//  device can be changed but the BGMDevice is fixed.
+//  Manages BGMDevice and the output device. Sets the system's current default device as the output
+//  device on init, then starts playthrough and mirroring the devices' controls.
 //
 
+#if defined(__cplusplus)
+
+// Local Includes
+#import "BGMBackgroundMusicDevice.h"
+
 // PublicUtility Includes
-#ifdef __cplusplus
 #import "CAHALAudioDevice.h"
-#endif
+
+#endif /* defined(__cplusplus) */
 
 // System Includes
 #import <Foundation/Foundation.h>
 #import <CoreAudio/AudioHardwareBase.h>
 
+// Forward Declarations
+@class BGMOutputVolumeMenuItem;
+@class BGMOutputDeviceMenuSection;
+
 
 #pragma clang assume_nonnull begin
 
-extern int const kBGMErrorCode_BGMDeviceNotFound;
-extern int const kBGMErrorCode_OutputDeviceNotFound;
+static const int kBGMErrorCode_OutputDeviceNotFound = 1;
+static const int kBGMErrorCode_ReturningEarly       = 2;
 
 @interface BGMAudioDeviceManager : NSObject
 
-- (instancetype) initWithError:(NSError**)error;
+// Returns nil if BGMDevice isn't installed.
+- (instancetype) init;
+
+// Set the BGMOutputVolumeMenuItem to be notified when the output device is changed.
+- (void) setOutputVolumeMenuItem:(BGMOutputVolumeMenuItem*)item;
+
+// Set the BGMOutputDeviceMenuSection to be notified when the output device is changed.
+- (void) setOutputDeviceMenuSection:(BGMOutputDeviceMenuSection*)menuSection;
 
 // Set BGMDevice as the default audio device for all processes
 - (NSError* __nullable) setBGMDeviceAsOSDefault;
@@ -49,7 +64,12 @@ extern int const kBGMErrorCode_OutputDeviceNotFound;
 - (NSError* __nullable) unsetBGMDeviceAsOSDefault;
 
 #ifdef __cplusplus
-- (CAHALAudioDevice) bgmDevice;
+// The virtual device published by BGMDriver.
+- (BGMBackgroundMusicDevice) bgmDevice;
+
+// The device BGMApp will play audio through, making it, from the user's perspective, the system's
+// default output device.
+- (CAHALAudioDevice) outputDevice;
 #endif
 
 - (BOOL) isOutputDevice:(AudioObjectID)deviceID;
@@ -74,8 +94,16 @@ extern int const kBGMErrorCode_OutputDeviceNotFound;
                                  dataSourceID:(UInt32)dataSourceID
                               revertOnFailure:(BOOL)revertOnFailure;
 
-// Blocks until IO has started running on the output device (for playthrough).
-- (OSStatus) waitForOutputDeviceToStart;
+// Start playthrough synchronously. Blocks until IO has started on the output device and playthrough
+// is running. See BGMPlayThrough.
+//
+// Returns one of the error codes defined by this class or BGMPlayThrough, or an AudioHardware error
+// code received from the HAL.
+- (OSStatus) startPlayThroughSync:(BOOL)forUISoundsDevice;
+
+// When the output device is changed, BGMAudioDeviceManager will send the ID of the new output
+// device to BGMXPCHelper through this connection.
+- (void) setBGMXPCHelperConnection:(NSXPCConnection* __nullable)connection;
 
 @end
 

BGMApp/BGMApp/BGMAudioDeviceManager.mm

@@ -17,63 +17,69 @@
 //  BGMAudioDeviceManager.mm
 //  BGMApp
 //
-//  Copyright © 2016 Kyle Neideck
+//  Copyright © 2016-2018 Kyle Neideck
 //
 
 // Self Include
 #import "BGMAudioDeviceManager.h"
 
 // Local Includes
-#include "BGM_Types.h"
-#include "BGM_Utils.h"
-#include "BGMDeviceControlSync.h"
-#include "BGMPlayThrough.h"
+#import "BGM_Types.h"
+#import "BGM_Utils.h"
+#import "BGMAudioDevice.h"
+#import "BGMDeviceControlSync.h"
+#import "BGMOutputDeviceMenuSection.h"
+#import "BGMOutputVolumeMenuItem.h"
+#import "BGMPlayThrough.h"
+#import "BGMXPCProtocols.h"
 
 // PublicUtility Includes
-#include "CAHALAudioSystemObject.h"
-#include "CAAutoDisposer.h"
+#import "CAAtomic.h"
+#import "CAAutoDisposer.h"
+#import "CAHALAudioSystemObject.h"
 
 
-int const kBGMErrorCode_BGMDeviceNotFound = 0;
-int const kBGMErrorCode_OutputDeviceNotFound = 1;
-
-// Hack/workaround that adds a default constructor to CAHALAudioDevice so we don't have to use pointers for the instance variables
-class BGMAudioDevice : public CAHALAudioDevice {
-    using CAHALAudioDevice::CAHALAudioDevice;
-public:
-    BGMAudioDevice() : CAHALAudioDevice(kAudioDeviceUnknown) { }
-};
+#pragma clang assume_nonnull begin
 
 @implementation BGMAudioDeviceManager {
-    BGMAudioDevice bgmDevice;
+    // This ivar is a pointer so that BGMBackgroundMusicDevice's constructor doesn't get called
+    // during [BGMAudioDeviceManager alloc] when the ivars are initialised. It queries the HAL for
+    // BGMDevice's AudioObject ID, which might throw a CAException, most likely because BGMDevice
+    // isn't installed.
+    //
+    // That would be the only way for [BGMAudioDeviceManager alloc] to throw a CAException, so we
+    // could wrap that call in a try/catch block instead, but it would make the code a bit
+    // confusing.
+    BGMBackgroundMusicDevice* bgmDevice;
     BGMAudioDevice outputDevice;
+    
     BGMDeviceControlSync deviceControlSync;
     BGMPlayThrough playThrough;
+    BGMPlayThrough playThrough_UISounds;
+
+    // A connection to BGMXPCHelper so we can send it the ID of the output device.
+    NSXPCConnection* __nullable bgmXPCHelperConnection;
+
+    BGMOutputVolumeMenuItem* __nullable outputVolumeMenuItem;
+    BGMOutputDeviceMenuSection* __nullable outputDeviceMenuSection;
+
+    NSRecursiveLock* stateLock;
 }
 
 #pragma mark Construction/Destruction
 
-- (id) initWithError:(NSError**)error {
+- (instancetype) init {
     if ((self = [super init])) {
-        bgmDevice = BGMAudioDevice(CFSTR(kBGMDeviceUID));
-        
-        if (bgmDevice.GetObjectID() == kAudioObjectUnknown) {
-            LogError("BGMAudioDeviceManager::initWithError: BGMDevice not found");
-            if (error) {
-                *error = [NSError errorWithDomain:@kBGMAppBundleID code:kBGMErrorCode_BGMDeviceNotFound userInfo:nil];
-            }
-            self = nil;
-            return self;
-        }
-        
-        [self initOutputDevice];
-        
-        
-        if (outputDevice.GetObjectID() == kAudioDeviceUnknown) {
-            LogError("BGMAudioDeviceManager::initWithError: output device not found");
-            if (error) {
-                *error = [NSError errorWithDomain:@kBGMAppBundleID code:kBGMErrorCode_OutputDeviceNotFound userInfo:nil];
-            }
+        stateLock = [NSRecursiveLock new];
+        bgmXPCHelperConnection = nil;
+        outputVolumeMenuItem = nil;
+        outputDeviceMenuSection = nil;
+        outputDevice = kAudioObjectUnknown;
+
+        try {
+            bgmDevice = new BGMBackgroundMusicDevice;
+        } catch (const CAException& e) {
+            LogError("BGMAudioDeviceManager::init: BGMDevice not found. (%d)", e.GetError());
             self = nil;
             return self;
         }
@@ -82,172 +88,70 @@ public:
     return self;
 }
 
-- (void) initOutputDevice {
-    CAHALAudioSystemObject audioSystem;
-    // outputDevice = BGMAudioDevice(CFSTR("AppleHDAEngineOutput:1B,0,1,1:0"));
-    AudioObjectID defaultDeviceID = audioSystem.GetDefaultAudioDevice(false, false);
-    if (defaultDeviceID == bgmDevice.GetObjectID()) {
-        // TODO: If BGMDevice is already the default (because BGMApp didn't shutdown properly or it was set manually)
-        //       we should temporarily disable BGMDevice so we can find out what the previous default was.
-        
-        // For now, just pick the device with the lowest latency
-        UInt32 numDevices = audioSystem.GetNumberAudioDevices();
-        if (numDevices > 0) {
-            SInt32 minLatencyDeviceIdx = -1;
-            UInt32 minLatency = UINT32_MAX;
-            CAAutoArrayDelete<AudioObjectID> devices(numDevices);
-            audioSystem.GetAudioDevices(numDevices, devices);
-            
-            for (UInt32 i = 0; i < numDevices; i++) {
-                BGMAudioDevice device(devices[i]);
-                
-                BOOL isBGMDevice = device.GetObjectID() == bgmDevice.GetObjectID();
-                BOOL hasOutputChannels = device.GetTotalNumberChannels(/* inIsInput = */ false) > 0;
-                
-                if (!isBGMDevice && hasOutputChannels) {
-                    if (minLatencyDeviceIdx == -1) {
-                        // First, look for any device other than BGMDevice
-                        minLatencyDeviceIdx = i;
-                    } else if (device.GetLatency(false) < minLatency) {
-                        // Then compare the devices by their latencies
-                        minLatencyDeviceIdx = i;
-                        minLatency = device.GetLatency(false);
-                    }
-                }
-            }
-            
-            BGMLogUnexpectedExceptionsMsg("BGMAudioDeviceManager::initOutputDevice",
-                                          "setOutputDeviceWithID:devices[minLatencyDeviceIdx]", [&]() {
-                // TODO: On error, try a different output device.
-                [self setOutputDeviceWithID:devices[minLatencyDeviceIdx] revertOnFailure:NO];
-            });
+- (void) dealloc {
+    @try {
+        [stateLock lock];
+
+        if (bgmDevice) {
+            delete bgmDevice;
+            bgmDevice = nullptr;
         }
-    } else {
-        BGMLogUnexpectedExceptionsMsg("BGMAudioDeviceManager::initOutputDevice",
-                                      "setOutputDeviceWithID:defaultDeviceID", [&]() {
-            // TODO: Return the error from setOutputDeviceWithID so it can be returned by initWithError.
-            [self setOutputDeviceWithID:defaultDeviceID revertOnFailure:NO];
-        });
-    }
-    
-    assert(outputDevice.GetObjectID() != bgmDevice.GetObjectID());
-    
-    // Log message
-    if (outputDevice.GetObjectID() == kAudioDeviceUnknown) {
-        CFStringRef outputDeviceUID = outputDevice.CopyDeviceUID();
-        DebugMsg("BGMAudioDeviceManager::initDevices: Set output device to %s",
-                 CFStringGetCStringPtr(outputDeviceUID, kCFStringEncodingUTF8));
-        CFRelease(outputDeviceUID);
+    } @finally {
+        [stateLock unlock];
     }
 }
 
+- (void) setOutputVolumeMenuItem:(BGMOutputVolumeMenuItem*)item {
+    outputVolumeMenuItem = item;
+}
+
+- (void) setOutputDeviceMenuSection:(BGMOutputDeviceMenuSection*)menuSection {
+    outputDeviceMenuSection = menuSection;
+}
+
 #pragma mark Systemwide Default Device
 
 // Note that there are two different "default" output devices on OS X: "output" and "system output". See
-// AudioHardwarePropertyDefaultSystemOutputDevice in AudioHardware.h.
+// kAudioHardwarePropertyDefaultSystemOutputDevice in AudioHardware.h.
 
 - (NSError* __nullable) setBGMDeviceAsOSDefault {
-    DebugMsg("BGMAudioDeviceManager::setBGMDeviceAsOSDefault: Setting the system's default audio "
-             "device to BGMDevice");
-    
-    CAHALAudioSystemObject audioSystem;
-    
-    AudioDeviceID bgmDeviceID = kAudioDeviceUnknown;
-    AudioDeviceID outputDeviceID = kAudioDeviceUnknown;
-    
-    @synchronized (self) {
-        BGMLogAndSwallowExceptions("setBGMDeviceAsOSDefault", [&]() {
-            bgmDeviceID = bgmDevice.GetObjectID();
-            outputDeviceID = outputDevice.GetObjectID();
-        });
-    }
-    
-    if (outputDeviceID == kAudioDeviceUnknown) {
-        return [NSError errorWithDomain:@kBGMAppBundleID code:kBGMErrorCode_OutputDeviceNotFound userInfo:nil];
-    }
-    if (bgmDeviceID == kAudioDeviceUnknown) {
-        return [NSError errorWithDomain:@kBGMAppBundleID code:kBGMErrorCode_BGMDeviceNotFound userInfo:nil];
+    try {
+        // Intentionally avoid taking stateLock before making calls to the HAL. See
+        // startPlayThroughSync.
+        CAMemoryBarrier();
+        bgmDevice->SetAsOSDefault();
+    } catch (const CAException& e) {
+        BGMLogExceptionIn("BGMAudioDeviceManager::setBGMDeviceAsOSDefault", e);
+        return [NSError errorWithDomain:@kBGMAppBundleID code:e.GetError() userInfo:nil];
     }
 
-    try {
-        AudioDeviceID currentDefault = audioSystem.GetDefaultAudioDevice(false, true);
-        
-        try {
-            if (currentDefault == outputDeviceID) {
-                // The default system device was the same as the default device, so change that as well
-                audioSystem.SetDefaultAudioDevice(false, true, bgmDeviceID);
-            }
-        
-            audioSystem.SetDefaultAudioDevice(false, false, bgmDeviceID);
-        } catch (CAException e) {
-            NSLog(@"SetDefaultAudioDevice threw CAException (%d)", e.GetError());
-            return [NSError errorWithDomain:@kBGMAppBundleID code:e.GetError() userInfo:nil];
-        }
-    } catch (...) {
-        NSLog(@"Unexpected exception");
-        return [NSError errorWithDomain:@kBGMAppBundleID code:-1 userInfo:nil];
-    }
-    
     return nil;
 }
 
 - (NSError* __nullable) unsetBGMDeviceAsOSDefault {
-    CAHALAudioSystemObject audioSystem;
-    
-    bool bgmDeviceIsDefault = true;
-    bool bgmDeviceIsSystemDefault = true;
-    
-    AudioDeviceID bgmDeviceID = kAudioDeviceUnknown;
-    AudioDeviceID outputDeviceID = kAudioDeviceUnknown;
-    
-    @synchronized (self) {
-        BGMLogAndSwallowExceptions("unsetBGMDeviceAsOSDefault", [&]() {
-            bgmDeviceID = bgmDevice.GetObjectID();
-            outputDeviceID = outputDevice.GetObjectID();
-            
-            bgmDeviceIsDefault =
-                (audioSystem.GetDefaultAudioDevice(false, false) == bgmDeviceID);
-            
-            bgmDeviceIsSystemDefault =
-                (audioSystem.GetDefaultAudioDevice(false, true) == bgmDeviceID);
-        });
+    // Copy the devices so we can call the HAL without holding stateLock. See startPlayThroughSync.
+    BGMBackgroundMusicDevice* bgmDeviceCopy;
+    AudioDeviceID outputDeviceID;
+
+    @try {
+        [stateLock lock];
+        bgmDeviceCopy = bgmDevice;
+        outputDeviceID = outputDevice.GetObjectID();
+    } @finally {
+        [stateLock unlock];
     }
-    
-    if (outputDeviceID == kAudioDeviceUnknown) {
-        return [NSError errorWithDomain:@kBGMAppBundleID code:kBGMErrorCode_OutputDeviceNotFound userInfo:nil];
+
+    if (outputDeviceID == kAudioObjectUnknown) {
+        return [NSError errorWithDomain:@kBGMAppBundleID
+                                   code:kBGMErrorCode_OutputDeviceNotFound
+                               userInfo:nil];
     }
-    if (bgmDeviceID == kAudioDeviceUnknown) {
-        return [NSError errorWithDomain:@kBGMAppBundleID code:kBGMErrorCode_BGMDeviceNotFound userInfo:nil];
-    }
-    
-    if (bgmDeviceIsDefault) {
-        DebugMsg("BGMAudioDeviceManager::unsetBGMDeviceAsOSDefault: Setting the system's default output "
-                 "device back to device %d", outputDeviceID);
-        
-        try {
-            audioSystem.SetDefaultAudioDevice(false, false, outputDeviceID);
-        } catch (CAException e) {
-            return [NSError errorWithDomain:@kBGMAppBundleID code:e.GetError() userInfo:nil];
-        } catch (...) {
-            BGMLogUnexpectedExceptionIn("BGMAudioDeviceManager::unsetBGMDeviceAsOSDefault "
-                                        "SetDefaultAudioDevice (output)");
-        }
-    }
-    
-    // If we changed the default system output device to BGMDevice, which we only do if it's set to
-    // the same device as the default output device, change it back to the previous device.
-    if (bgmDeviceIsSystemDefault) {
-        DebugMsg("BGMAudioDeviceManager::unsetBGMDeviceAsOSDefault: Setting the system's default system "
-                 "output device back to device %d", outputDeviceID);
-        
-        try {
-            audioSystem.SetDefaultAudioDevice(false, true, outputDeviceID);
-        } catch (CAException e) {
-            return [NSError errorWithDomain:@kBGMAppBundleID code:e.GetError() userInfo:nil];
-        } catch (...) {
-            BGMLogUnexpectedExceptionIn("BGMAudioDeviceManager::unsetBGMDeviceAsOSDefault "
-                                        "SetDefaultAudioDevice (system output)");
-        }
+
+    try {
+        bgmDeviceCopy->UnsetAsOSDefault(outputDeviceID);
+    } catch (const CAException& e) {
+        BGMLogExceptionIn("BGMAudioDeviceManager::unsetBGMDeviceAsOSDefault", e);
+        return [NSError errorWithDomain:@kBGMAppBundleID code:e.GetError() userInfo:nil];
     }
     
     return nil;
@@ -255,31 +159,47 @@ public:
 
 #pragma mark Accessors
 
-- (CAHALAudioDevice) bgmDevice {
-    return bgmDevice;
+- (BGMBackgroundMusicDevice) bgmDevice {
+    return *bgmDevice;
+}
+
+- (CAHALAudioDevice) outputDevice {
+    return outputDevice;
 }
 
 - (BOOL) isOutputDevice:(AudioObjectID)deviceID {
-    @synchronized (self) {
+    @try {
+        [stateLock lock];
         return deviceID == outputDevice.GetObjectID();
+    } @finally {
+        [stateLock unlock];
     }
 }
 
 - (BOOL) isOutputDataSource:(UInt32)dataSourceID {
-    @synchronized (self) {
+    BOOL isOutputDataSource = NO;
+
+    @try {
+        [stateLock lock];
+        
         try {
             AudioObjectPropertyScope scope = kAudioDevicePropertyScopeOutput;
             UInt32 channel = 0;
             
-            return outputDevice.HasDataSourceControl(scope, channel) &&
-                (dataSourceID == outputDevice.GetCurrentDataSourceID(scope, channel));
-        } catch (CAException e) {
+            isOutputDataSource =
+                    outputDevice.HasDataSourceControl(scope, channel) &&
+                            (dataSourceID == outputDevice.GetCurrentDataSourceID(scope, channel));
+        } catch (const CAException& e) {
             BGMLogException(e);
-            return false;
         }
+    } @finally {
+        [stateLock unlock];
     }
+
+    return isOutputDataSource;
 }
 
+#pragma mark Output Device
 
 - (NSError* __nullable) setOutputDeviceWithID:(AudioObjectID)deviceID
                               revertOnFailure:(BOOL)revertOnFailure {
@@ -299,81 +219,126 @@ public:
 - (NSError* __nullable) setOutputDeviceWithIDImpl:(AudioObjectID)newDeviceID
                                      dataSourceID:(UInt32* __nullable)dataSourceID
                                   revertOnFailure:(BOOL)revertOnFailure {
-    DebugMsg("BGMAudioDeviceManager::setOutputDeviceWithID: Setting output device. newDeviceID=%u",
+    DebugMsg("BGMAudioDeviceManager::setOutputDeviceWithIDImpl: Setting output device. newDeviceID=%u",
              newDeviceID);
     
-    AudioDeviceID currentDeviceID = outputDevice.GetObjectID();  // (GetObjectID doesn't throw.)
-    
-    // Set up playthrough and control sync
-    BGMAudioDevice newOutputDevice(newDeviceID);
-    
-    try {
-        @synchronized (self) {
-            // Re-read the device ID after entering the monitor. (The initial read is because
-            // currentDeviceID's used in the catch blocks.)
-            currentDeviceID = outputDevice.GetObjectID();
-            
-            if (newDeviceID != currentDeviceID) {
-                // Mirror changes in BGMDevice's controls to the new output device's.
-                deviceControlSync = BGMDeviceControlSync(bgmDevice, newOutputDevice);
-                
-                // Stream audio from BGMDevice to the new output device. This blocks while the old device
-                // stops IO.
-                playThrough = BGMPlayThrough(bgmDevice, newOutputDevice);
+    @try {
+        [stateLock lock];
 
-                outputDevice = newOutputDevice;
-            }
+        AudioDeviceID currentDeviceID = outputDevice.GetObjectID();  // (Doesn't throw.)
+
+        try {
+            [self setOutputDeviceWithIDImpl:newDeviceID
+                               dataSourceID:dataSourceID
+                            currentDeviceID:currentDeviceID];
+        } catch (const CAException& e) {
+            BGMAssert(e.GetError() != kAudioHardwareNoError,
+                      "CAException with kAudioHardwareNoError");
             
-            // Set the output device to use the new data source.
-            if (dataSourceID) {
-                // TODO: If this fails, ideally we'd still start playthrough and return an error, but not
-                //       revert the device. It would probably be a bit awkward, though.
-                [self setDataSource:*dataSourceID device:outputDevice];
-            }
-            
-            if (newDeviceID != currentDeviceID) {
-                // We successfully changed to the new device. Start playthrough on it, since audio might be
-                // playing. (If we only changed the data source, playthrough will already be running if it
-                // needs to be.)
-                playThrough.Start();
-                // But stop playthrough if audio isn't playing, since it uses CPU.
-                playThrough.StopIfIdle();
-            }
+            return [self failedToSetOutputDevice:newDeviceID
+                                       errorCode:e.GetError()
+                                        revertTo:(revertOnFailure ? &currentDeviceID : nullptr)];
+        } catch (...) {
+            return [self failedToSetOutputDevice:newDeviceID
+                                       errorCode:kAudioHardwareUnspecifiedError
+                                        revertTo:(revertOnFailure ? &currentDeviceID : nullptr)];
         }
-    } catch (CAException e) {
-        BGMAssert(e.GetError() != kAudioHardwareNoError,
-                  "CAException with kAudioHardwareNoError");
-        
-        return [self failedToSetOutputDevice:newDeviceID
-                                   errorCode:e.GetError()
-                                    revertTo:(revertOnFailure ? &currentDeviceID : nullptr)];
-    } catch (...) {
-        return [self failedToSetOutputDevice:newDeviceID
-                                   errorCode:kAudioHardwareUnspecifiedError
-                                    revertTo:(revertOnFailure ? &currentDeviceID : nullptr)];
+
+        // Tell other classes and BGMXPCHelper that we changed the output device.
+        [self propagateOutputDeviceChange];
+    } @finally {
+        [stateLock unlock];
     }
-    
+
     return nil;
 }
 
-- (void) setDataSource:(UInt32)dataSourceID device:(BGMAudioDevice)device {
-    BGMLogAndSwallowExceptions("BGMAudioDeviceManager::setDataSource", [&]() {
+// Throws CAException.
+- (void) setOutputDeviceWithIDImpl:(AudioObjectID)newDeviceID
+                      dataSourceID:(UInt32* __nullable)dataSourceID
+                   currentDeviceID:(AudioObjectID)currentDeviceID {
+    if (newDeviceID != currentDeviceID) {
+        BGMAudioDevice newOutputDevice(newDeviceID);
+        [self setOutputDeviceForPlaythroughAndControlSync:newOutputDevice];
+        outputDevice = newOutputDevice;
+    }
+
+    // Set the output device to use the new data source.
+    if (dataSourceID) {
+        // TODO: If this fails, ideally we'd still start playthrough and return an error, but not
+        //       revert the device. It would probably be a bit awkward, though.
+        [self setDataSource:*dataSourceID device:outputDevice];
+    }
+
+    if (newDeviceID != currentDeviceID) {
+        // We successfully changed to the new device. Start playthrough on it, since audio might be
+        // playing. (If we only changed the data source, playthrough will already be running if it
+        // needs to be.)
+        playThrough.Start();
+        playThrough_UISounds.Start();
+        // But stop playthrough if audio isn't playing, since it uses CPU.
+        playThrough.StopIfIdle();
+        playThrough_UISounds.StopIfIdle();
+    }
+
+    CFStringRef outputDeviceUID = outputDevice.CopyDeviceUID();
+    DebugMsg("BGMAudioDeviceManager::setOutputDeviceWithIDImpl: Set output device to %s (%d)",
+             CFStringGetCStringPtr(outputDeviceUID, kCFStringEncodingUTF8),
+             outputDevice.GetObjectID());
+    CFRelease(outputDeviceUID);
+}
+
+// Changes the output device that playthrough plays audio to and that BGMDevice's controls are
+// kept in sync with. Throws CAException.
+- (void) setOutputDeviceForPlaythroughAndControlSync:(const BGMAudioDevice&)newOutputDevice {
+    // Deactivate playthrough rather than stopping it so it can't be started by HAL notifications
+    // while we're updating deviceControlSync.
+    playThrough.Deactivate();
+    playThrough_UISounds.Deactivate();
+
+    deviceControlSync.SetDevices(*bgmDevice, newOutputDevice);
+    deviceControlSync.Activate();
+
+    // Stream audio from BGMDevice to the new output device. This blocks while the old device stops
+    // IO.
+    playThrough.SetDevices(bgmDevice, &newOutputDevice);
+    playThrough.Activate();
+
+    // TODO: Support setting different devices as the default output device and the default system
+    //       output device the way OS X does?
+    BGMAudioDevice uiSoundsDevice = bgmDevice->GetUISoundsBGMDeviceInstance();
+    playThrough_UISounds.SetDevices(&uiSoundsDevice, &newOutputDevice);
+    playThrough_UISounds.Activate();
+}
+
+- (void) setDataSource:(UInt32)dataSourceID device:(BGMAudioDevice&)device {
+    BGMLogAndSwallowExceptions("BGMAudioDeviceManager::setDataSource", ([&] {
         AudioObjectPropertyScope scope = kAudioObjectPropertyScopeOutput;
         UInt32 channel = 0;
-        
+
         if (device.DataSourceControlIsSettable(scope, channel)) {
             DebugMsg("BGMAudioDeviceManager::setOutputDeviceWithID: Setting dataSourceID=%u",
                      dataSourceID);
             
             device.SetCurrentDataSourceByID(scope, channel, dataSourceID);
         }
-    });
+    }));
+}
+
+- (void) propagateOutputDeviceChange {
+    // Tell BGMXPCHelper that the output device has changed.
+    [self sendOutputDeviceToBGMXPCHelper];
+
+    // Update the menu item for the volume of the output device.
+    [outputVolumeMenuItem outputDeviceDidChange];
+    [outputDeviceMenuSection outputDeviceDidChange];
 }
 
 - (NSError*) failedToSetOutputDevice:(AudioDeviceID)deviceID
                            errorCode:(OSStatus)errorCode
                             revertTo:(AudioDeviceID*)revertTo {
     // Using LogWarning from PublicUtility instead of NSLog here crashes from a bad access. Not sure why.
+    // TODO: Possibly caused by a bug in CADebugMacros.cpp. See commit ab9d4cd.
     NSLog(@"BGMAudioDeviceManager::failedToSetOutputDevice: Couldn't set device with ID %u as output device. "
           "%s%d. %@",
           deviceID,
@@ -399,11 +364,104 @@ public:
     return [NSError errorWithDomain:@kBGMAppBundleID code:errorCode userInfo:info];
 }
 
-- (OSStatus) waitForOutputDeviceToStart {
-    // Intentionally not synchronized to avoid blocking the UI thread. BGMPlayThrough::WaitForOutputDeviceToStart
-    // will be interrupted if the output device is changed.
-    return playThrough.WaitForOutputDeviceToStart();
+- (OSStatus) startPlayThroughSync:(BOOL)forUISoundsDevice {
+    // We can only try for stateLock because setOutputDeviceWithID might have already taken it, then made a
+    // HAL request to BGMDevice and be waiting for the response. Some of the requests setOutputDeviceWithID
+    // makes to BGMDevice block in the HAL if another thread is in BGM_Device::StartIO.
+    //
+    // Since BGM_Device::StartIO calls this method (via XPC), waiting for setOutputDeviceWithID to release
+    // stateLock could cause deadlocks. Instead we return early with an error code that BGMDriver knows to
+    // ignore, since the output device is (almost certainly) being changed and we can't avoid dropping frames
+    // while the output device starts up.
+    OSStatus err;
+    BOOL gotLock;
+    
+    @try {
+        gotLock = [stateLock tryLock];
+
+        BOOL isBigSur = NO;
+        if (@available(macOS 11.0, *)) {
+            isBigSur = YES;
+        }
+
+        // Always start playthrough asynchronously. Temp workaround for deadlock on Big Sur.
+        if (!isBigSur && gotLock) {
+            BGMPlayThrough& pt = (forUISoundsDevice ? playThrough_UISounds : playThrough);
+
+            // Playthrough might not have been notified that BGMDevice is starting yet, so make sure
+            // playthrough is starting. This way we won't drop any frames while waiting for the HAL to send
+            // that notification. We can't be completely sure this is safe from deadlocking, though, since
+            // CoreAudio is closed-source.
+            //
+            // TODO: Test this on older OS X versions. Differences in the CoreAudio implementations could
+            //       cause deadlocks.
+            BGMLogAndSwallowExceptionsMsg("BGMAudioDeviceManager::startPlayThroughSync",
+                                          "Starting playthrough", [&] {
+                pt.Start();
+            });
+
+            err = pt.WaitForOutputDeviceToStart();
+            BGMAssert(err != BGMPlayThrough::kDeviceNotStarting, "Playthrough didn't start");
+        } else {
+            LogWarning("BGMAudioDeviceManager::startPlayThroughSync: Didn't get state lock. Returning "
+                       "early with kBGMErrorCode_ReturningEarly.");
+            err = kBGMErrorCode_ReturningEarly;
+
+            dispatch_async(BGMGetDispatchQueue_PriorityUserInteractive(), ^{
+                @try {
+                    [stateLock lock];
+
+                    BGMPlayThrough& pt = (forUISoundsDevice ? playThrough_UISounds : playThrough);
+                    
+                    BGMLogAndSwallowExceptionsMsg("BGMAudioDeviceManager::startPlayThroughSync",
+                                                  "Starting playthrough (dispatched)", [&] {
+                        pt.Start();
+                    });
+
+                    BGMLogAndSwallowExceptions("BGMAudioDeviceManager::startPlayThroughSync", [&] {
+                        pt.StopIfIdle();
+                    });
+                } @finally {
+                    [stateLock unlock];
+                }
+            });
+        }
+    } @finally {
+        if (gotLock) {
+            [stateLock unlock];
+        }
+    }
+    
+    return err;
+}
+
+#pragma mark BGMXPCHelper Communication
+
+- (void) setBGMXPCHelperConnection:(NSXPCConnection* __nullable)connection {
+    bgmXPCHelperConnection = connection;
+
+    // Tell BGMXPCHelper which device is the output device, since it might not be up-to-date.
+    [self sendOutputDeviceToBGMXPCHelper];
+}
+
+- (void) sendOutputDeviceToBGMXPCHelper {
+    NSXPCConnection* __nullable connection = bgmXPCHelperConnection;
+
+    if (connection)
+    {
+        id<BGMXPCHelperXPCProtocol> helperProxy =
+                [connection remoteObjectProxyWithErrorHandler:^(NSError* error) {
+                    // We could wait a bit and try again, but it isn't that important.
+                    NSLog(@"BGMAudioDeviceManager::sendOutputDeviceToBGMXPCHelper: Connection"
+                           "error: %@", error);
+                }];
+
+        [helperProxy setOutputDeviceToMakeDefaultOnAbnormalTermination:outputDevice.GetObjectID()];
+    }
 }
 
 @end
 
+#pragma clang assume_nonnull end
+
+

BGMApp/BGMApp/BGMAutoPauseMenuItem.m

@@ -17,7 +17,7 @@
 //  BGMAutoPauseMenuItem.m
 //  BGMApp
 //
-//  Copyright © 2016 Kyle Neideck
+//  Copyright © 2016, 2019 Kyle Neideck
 //  Copyright © 2016 Tanner Hoke
 //
 
@@ -25,7 +25,7 @@
 #import "BGMAutoPauseMenuItem.h"
 
 // Local Includes
-#import "BGMMusicPlayer.h"
+#import "BGMAppWatcher.h"
 
 
 #pragma clang assume_nonnull begin
@@ -41,7 +41,7 @@ static SInt64 const kMenuItemUpdateWaitTime = 1;
     NSMenuItem* menuItem;
     BGMAutoPauseMusic* autoPauseMusic;
     BGMMusicPlayers* musicPlayers;
-    id<NSObject> didLaunchToken, didTerminateToken;
+    BGMAppWatcher* appWatcher;
 }
 
 - (instancetype) initWithMenuItem:(NSMenuItem*)item
@@ -66,53 +66,39 @@ static SInt64 const kMenuItemUpdateWaitTime = 1;
         // Toggle auto-pause when the menu item is clicked.
         menuItem.target = self;
         menuItem.action = @selector(toggleAutoPauseMusic);
-        
-        [self updateMenuItemTitle];
-        [self initMusicPlayerObservers];
+
+        [self initMenuItemTitle];
     }
     
     return self;
 }
 
-- (void) initMusicPlayerObservers {
-    // Add observers that enable/disable the Auto-pause Music menu item when the music player is launched/terminated.
-    NSNotificationCenter* center = [[NSWorkspace sharedWorkspace] notificationCenter];
-    
-    id<NSObject> (^addObserver)(NSString*) = ^(NSString* name) {
-        return [center addObserverForName:name
-                                   object:nil
-                                    queue:nil
-                               usingBlock:^(NSNotification* note) {
-                                   NSString* appBundleID = [note.userInfo[NSWorkspaceApplicationKey] bundleIdentifier];
-                                   BOOL isAboutThisMusicPlayer = musicPlayers.selectedMusicPlayer.bundleID &&
-                                       [appBundleID isEqualToString:(NSString*)musicPlayers.selectedMusicPlayer.bundleID];
-                                   
-                                   if (isAboutThisMusicPlayer) {
-                                       dispatch_after(dispatch_time(DISPATCH_TIME_NOW,
-                                                                    kMenuItemUpdateWaitTime * NSEC_PER_SEC),
-                                                      dispatch_get_main_queue(),
-                                                      ^{
-                                                          [self updateMenuItemTitle];
-                                                      });
-                                   }
-                               }];
-    };
-    
-    didLaunchToken = addObserver(NSWorkspaceDidLaunchApplicationNotification);
-    didTerminateToken = addObserver(NSWorkspaceDidTerminateApplicationNotification);
-}
+- (void) initMenuItemTitle {
+    // Set the initial text, tool-tip, state, etc.
+    [self updateMenuItemTitle];
 
-- (void) dealloc {
-    // Remove the application launch/termination observers.
-    NSNotificationCenter* center = [[NSWorkspace sharedWorkspace] notificationCenter];
-    
-    if (didLaunchToken) {
-        [center removeObserver:didLaunchToken];
-    }
-    
-    if (didTerminateToken) {
-        [center removeObserver:didTerminateToken];
-    }
+    // Avoid retain cycles in case we ever want to destroy instances of this class.
+    BGMAutoPauseMenuItem* __weak weakSelf = self;
+
+    // Add a callback that enables/disables the Auto-pause Music menu item when the music player
+    // is launched/terminated.
+    void (^callback)(void) = ^{
+        dispatch_after(dispatch_time(DISPATCH_TIME_NOW, kMenuItemUpdateWaitTime * NSEC_PER_SEC),
+                       dispatch_get_main_queue(),
+                       ^{
+                           BGMAutoPauseMenuItem* strongSelf = weakSelf;
+                           [strongSelf updateMenuItemTitle];
+                       });
+    };
+
+    appWatcher = [[BGMAppWatcher alloc] initWithAppLaunched:callback
+                                              appTerminated:callback
+                                         isMatchingBundleID:^BOOL(NSString* appBundleID) {
+        BGMAutoPauseMenuItem* strongSelf = weakSelf;
+        NSString* __nullable playerBundleID =
+                strongSelf->musicPlayers.selectedMusicPlayer.bundleID;
+        return playerBundleID && [appBundleID isEqualToString:(NSString*)playerBundleID];
+    }];
 }
 
 - (void) toggleAutoPauseMusic {
@@ -143,7 +129,7 @@ static SInt64 const kMenuItemUpdateWaitTime = 1;
     //
     // We don't actually disable it just in case the user decides to disable auto-pause and their music player isn't
     // running. E.g. someone who only recently installed Background Music and doesn't want to use auto-pause at all.
-    if (musicPlayers.selectedMusicPlayer.isRunning) {
+    if (musicPlayers.selectedMusicPlayer.running) {
         menuItem.attributedTitle = nil;
         menuItem.toolTip = nil;
     } else {
@@ -190,7 +176,7 @@ static SInt64 const kMenuItemUpdateWaitTime = 1;
     
     // Only update the menu item if it's changing (from highlighted to unhighlighted or vice versa) to save a little
     // CPU.
-    if (willHighlightMenuItem ^ menuItem.highlighted) {
+    if (willHighlightMenuItem != menuItem.highlighted) {
         [self updateMenuItemTitleWithHighlight:willHighlightMenuItem];
     }
 }

BGMApp/BGMApp/BGMAutoPauseMusic.mm

@@ -17,7 +17,7 @@
 //  BGMAutoPauseMusic.m
 //  BGMApp
 //
-//  Copyright © 2016 Kyle Neideck
+//  Copyright © 2016, 2017 Kyle Neideck
 //
 
 // Self Include
@@ -50,10 +50,10 @@ static UInt64 const kPauseDelayNSec = 1500 * NSEC_PER_MSEC;
 //       immediately if we haven't been paused for long and the non-music-player client stops IO? That would usually indicate that
 //       it doesn't intend to start playing audio again soon. We'd also have to deal with music players that don't stop IO when
 //       they're paused.
-static UInt64 const kMaxUnpauseDelayNSec = 3000 * NSEC_PER_MSEC;
+static UInt64 const kMaxUnpauseDelayNSec = 3500 * NSEC_PER_MSEC;
 static UInt64 const kMinUnpauseDelayNSec = kMaxUnpauseDelayNSec / 10;
 // We multiply the time spent paused by this factor to calculate the delay before we consider unpausing.
-static Float32 const kUnpauseDelayWeightingFactor = 0.25f;
+static Float32 const kUnpauseDelayWeightingFactor = 0.1f;
 
 @implementation BGMAutoPauseMusic {
     BOOL enabled;
@@ -84,7 +84,18 @@ static Float32 const kUnpauseDelayWeightingFactor = 0.25f;
         enabled = NO;
         wePaused = NO;
         
-        dispatch_queue_attr_t attr = dispatch_queue_attr_make_with_qos_class(DISPATCH_QUEUE_SERIAL, QOS_CLASS_DEFAULT, 0);
+        dispatch_queue_attr_t attr;
+
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wpartial-availability"
+        if (&dispatch_queue_attr_make_with_qos_class) {
+            attr = dispatch_queue_attr_make_with_qos_class(DISPATCH_QUEUE_SERIAL, QOS_CLASS_DEFAULT, 0);
+        } else {
+            // OS X 10.9 fallback
+            attr = DISPATCH_QUEUE_SERIAL;
+        }
+#pragma clang diagnostic pop
+
         listenerQueue = dispatch_queue_create("com.bearisdriving.BGM.AutoPauseMusic.Listener", attr);
         pauseUnpauseMusicQueue = dispatch_queue_create("com.bearisdriving.BGM.AutoPauseMusic.PauseUnpauseMusic", attr);
         
@@ -107,7 +118,7 @@ static Float32 const kUnpauseDelayWeightingFactor = 0.25f;
         // so we have to check them all
         for (int i = 0; i < inNumberAddresses; i++) {
             if (inAddresses[i].mSelector == kAudioDeviceCustomPropertyDeviceAudibleState) {
-                SInt32 audibleState = [weakSelf deviceAudibleState];
+                BGMDeviceAudibleState audibleState = [weakSelf deviceAudibleState];
                 
 #if DEBUG
                 const char audibleStateStr[5] = CA4CCToCString(audibleState);
@@ -133,15 +144,8 @@ static Float32 const kUnpauseDelayWeightingFactor = 0.25f;
     };
 }
 
-- (SInt32) deviceAudibleState {
-    SInt32 audibleState;
-    CFNumberRef audibleStateRef =
-        static_cast<CFNumberRef>([audioDevices bgmDevice].GetPropertyData_CFType(kBGMAudibleStateAddress));
-    
-    CFNumberGetValue(audibleStateRef, kCFNumberSInt32Type, &audibleState);
-    CFRelease(audibleStateRef);
-    
-    return audibleState;
+- (BGMDeviceAudibleState) deviceAudibleState {
+    return [audioDevices bgmDevice].GetAudibleState();
 }
 
 - (void) queuePauseBlock {
@@ -177,8 +181,8 @@ static Float32 const kUnpauseDelayWeightingFactor = 0.25f;
     // Unpause sooner if we've only been paused for a short time. This is so a notification sound causing an auto-pause is
     // less of an interruption.
     //
-    // TODO: Would it help much if we ignored all audio played on the "system default" device rather than the "default"
-    //       device? IIRC apps are supposed to use the former for UI sounds.
+    // TODO: Fading in and out would make short pauses a lot less jarring because, if they were short enough, we wouldn't
+    //       actually pause the music player. So you'd hear a dip in the music's volume rather than a gap.
     UInt64 unpauseDelayNsec =
         static_cast<UInt64>((wentSilent - wentAudible) * kUnpauseDelayWeightingFactor);
     

BGMApp/BGMApp/BGMBackgroundMusicDevice.cpp

@@ -0,0 +1,327 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMBackgroundMusicDevice.cpp
+//  BGMApp
+//
+//  Copyright © 2016-2019 Kyle Neideck
+//  Copyright © 2017 Andrew Tonner
+//
+
+// Self Include
+#include "BGMBackgroundMusicDevice.h"
+
+// Local Includes
+#include "BGM_Types.h"
+#include "BGM_Utils.h"
+
+// PublicUtility Includes
+#include "CADebugMacros.h"
+#include "CAHALAudioSystemObject.h"
+#include "CACFArray.h"
+#include "CACFDictionary.h"
+
+// STL Includes
+#include <map>
+
+
+#pragma clang assume_nonnull begin
+
+#pragma mark Construction/Destruction
+
+BGMBackgroundMusicDevice::BGMBackgroundMusicDevice()
+:
+    BGMAudioDevice(CFSTR(kBGMDeviceUID)),
+    mUISoundsBGMDevice(CFSTR(kBGMDeviceUID_UISounds))
+{
+    if((GetObjectID() == kAudioObjectUnknown) || (mUISoundsBGMDevice == kAudioObjectUnknown))
+    {
+        LogError("BGMBackgroundMusicDevice::BGMBackgroundMusicDevice: Error getting BGMDevice ID");
+        Throw(CAException(kAudioHardwareIllegalOperationError));
+    }
+};
+
+BGMBackgroundMusicDevice::~BGMBackgroundMusicDevice()
+{
+}
+
+#pragma mark Systemwide Default Device
+
+void BGMBackgroundMusicDevice::SetAsOSDefault()
+{
+    DebugMsg("BGMBackgroundMusicDevice::SetAsOSDefault: Setting the system's default audio device "
+             "to BGMDevice");
+
+    CAHALAudioSystemObject audioSystem;
+
+    AudioDeviceID defaultDevice = audioSystem.GetDefaultAudioDevice(false, false);
+    AudioDeviceID systemDefaultDevice = audioSystem.GetDefaultAudioDevice(false, true);
+
+    if(systemDefaultDevice == defaultDevice)
+    {
+        // The default system device is the same as the default device, so change both of them.
+        //
+        // Use the UI sounds instance of BGMDevice because the default system output device is the
+        // device "to use for system related sound". The allows BGMDriver to tell when the audio it
+        // receives is UI-related.
+        audioSystem.SetDefaultAudioDevice(false, true, mUISoundsBGMDevice);
+    }
+
+    audioSystem.SetDefaultAudioDevice(false, false, GetObjectID());
+}
+
+void BGMBackgroundMusicDevice::UnsetAsOSDefault(AudioDeviceID inOutputDeviceID)
+{
+    CAHALAudioSystemObject audioSystem;
+
+    // Set BGMApp's output device as OS X's default output device.
+    bool bgmDeviceIsDefault =
+            (audioSystem.GetDefaultAudioDevice(false, false) == GetObjectID());
+
+    if(bgmDeviceIsDefault)
+    {
+        DebugMsg("BGMBackgroundMusicDevice::UnsetAsOSDefault: Setting the system's default output "
+                 "device back to device %d", inOutputDeviceID);
+
+        audioSystem.SetDefaultAudioDevice(false, false, inOutputDeviceID);
+    }
+
+    // Set BGMApp's output device as OS X's default system output device.
+    bool bgmDeviceIsSystemDefault =
+            (audioSystem.GetDefaultAudioDevice(false, true) == mUISoundsBGMDevice);
+
+    // If we changed the default system output device to BGMDevice, which we only do if it's set to
+    // the same device as the default output device, change it back to the previous device.
+    if(bgmDeviceIsSystemDefault)
+    {
+        DebugMsg("BGMBackgroundMusicDevice::UnsetAsOSDefault: Setting the system's default system "
+                 "output device back to device %d", inOutputDeviceID);
+
+        audioSystem.SetDefaultAudioDevice(false, true, inOutputDeviceID);
+    }
+}
+
+#pragma mark App Volumes
+
+CFArrayRef BGMBackgroundMusicDevice::GetAppVolumes() const
+{
+    CFTypeRef appVolumes = GetPropertyData_CFType(kBGMAppVolumesAddress);
+
+    ThrowIfNULL(appVolumes,
+                CAException(kAudioHardwareIllegalOperationError),
+                "BGMBackgroundMusicDevice::GetAppVolumes: !appVolumes");
+    ThrowIf(CFGetTypeID(appVolumes) != CFArrayGetTypeID(),
+            CAException(kAudioHardwareIllegalOperationError),
+            "BGMBackgroundMusicDevice::GetAppVolumes: Expected CFArray value");
+
+    return static_cast<CFArrayRef>(appVolumes);
+}
+
+void BGMBackgroundMusicDevice::SetAppVolume(SInt32 inVolume,
+                                            pid_t inAppProcessID,
+                                            CFStringRef __nullable inAppBundleID)
+{
+    BGMAssert((kAppRelativeVolumeMinRawValue <= inVolume) &&
+                      (inVolume <= kAppRelativeVolumeMaxRawValue),
+              "BGMBackgroundMusicDevice::SetAppVolume: Volume out of bounds");
+
+    // Clamp the volume to [kAppRelativeVolumeMinRawValue, kAppPanRightRawValue].
+    inVolume = std::max(kAppRelativeVolumeMinRawValue, inVolume);
+    inVolume = std::min(kAppRelativeVolumeMaxRawValue, inVolume);
+
+    SendAppVolumeOrPanToBGMDevice(inVolume,
+                                  CFSTR(kBGMAppVolumesKey_RelativeVolume),
+                                  inAppProcessID,
+                                  inAppBundleID);
+}
+
+void BGMBackgroundMusicDevice::SetAppPanPosition(SInt32 inPanPosition,
+                                                 pid_t inAppProcessID,
+                                                 CFStringRef __nullable inAppBundleID)
+{
+    BGMAssert((kAppPanLeftRawValue <= inPanPosition) && (inPanPosition <= kAppPanRightRawValue),
+              "BGMBackgroundMusicDevice::SetAppPanPosition: Pan position out of bounds");
+
+    // Clamp the pan position to [kAppPanLeftRawValue, kAppPanRightRawValue].
+    inPanPosition = std::max(kAppPanLeftRawValue, inPanPosition);
+    inPanPosition = std::min(kAppPanRightRawValue, inPanPosition);
+
+    SendAppVolumeOrPanToBGMDevice(inPanPosition,
+                                  CFSTR(kBGMAppVolumesKey_PanPosition),
+                                  inAppProcessID,
+                                  inAppBundleID);
+}
+
+void BGMBackgroundMusicDevice::SendAppVolumeOrPanToBGMDevice(SInt32 inNewValue,
+                                                             CFStringRef inVolumeTypeKey,
+                                                             pid_t inAppProcessID,
+                                                             CFStringRef __nullable inAppBundleID)
+{
+    CACFArray appVolumeChanges(true);
+
+    auto addVolumeChange = [&] (pid_t pid, CFStringRef bundleID)
+    {
+        CACFDictionary appVolumeChange(true);
+
+        appVolumeChange.AddSInt32(CFSTR(kBGMAppVolumesKey_ProcessID), pid);
+        appVolumeChange.AddString(CFSTR(kBGMAppVolumesKey_BundleID), bundleID);
+        appVolumeChange.AddSInt32(inVolumeTypeKey, inNewValue);
+
+        appVolumeChanges.AppendDictionary(appVolumeChange.GetDict());
+    };
+
+    addVolumeChange(inAppProcessID, inAppBundleID);
+
+    // Add the same change for each process the app is responsible for.
+    for(CACFString responsibleBundleID : ResponsibleBundleIDsOf(CACFString(inAppBundleID)))
+    {
+        // Send -1 as the PID so this volume will only ever be matched by bundle ID.
+        addVolumeChange(-1, responsibleBundleID.GetCFString());
+    }
+
+    CFPropertyListRef changesPList = appVolumeChanges.AsPropertyList();
+
+    // Send the change to BGMDevice.
+    SetPropertyData_CFType(kBGMAppVolumesAddress, changesPList);
+
+    // Also send it to the instance of BGMDevice that handles UI sounds.
+    mUISoundsBGMDevice.SetPropertyData_CFType(kBGMAppVolumesAddress, changesPList);
+}
+
+// This is a temporary solution that lets us control the volumes of some multiprocess apps, i.e.
+// apps that play their audio from a process with a different bundle ID.
+//
+// We can't just check the child processes of the apps' main processes because they're usually
+// created with launchd rather than being actual child processes. There's a private API to get the
+// processes that an app is "responsible for", so we'll try to use it in the proper fix and only use
+// this list if the API doesn't work.
+//
+// static
+std::vector<CACFString>
+BGMBackgroundMusicDevice::ResponsibleBundleIDsOf(CACFString inParentBundleID)
+{
+    if(!inParentBundleID.IsValid())
+    {
+        return {};
+    }
+
+    std::map<CACFString, std::vector<CACFString>> bundleIDMap = {
+        // Finder
+        { "com.apple.finder",
+            { "com.apple.quicklook.ui.helper",
+              "com.apple.quicklook.QuickLookUIService" } },
+        // Safari
+        { "com.apple.Safari", { "com.apple.WebKit.WebContent" } },
+        // Firefox
+        { "org.mozilla.firefox", { "org.mozilla.plugincontainer" } },
+        // Firefox Nightly
+        { "org.mozilla.nightly", { "org.mozilla.plugincontainer" } },
+        // VMWare Fusion
+        { "com.vmware.fusion", { "com.vmware.vmware-vmx" } },
+        // Parallels
+        { "com.parallels.desktop.console", { "com.parallels.vm" } },
+        // MPlayer OSX Extended
+        { "hu.mplayerhq.mplayerosx.extended",
+                { "ch.sttz.mplayerosx.extended.binaries.officialsvn" } },
+        // Discord
+        { "com.hnc.Discord", { "com.hnc.Discord.helper" } },
+        // Skype
+        { "com.skype.skype", { "com.skype.skype.Helper" } },
+        // Google Chrome
+        { "com.google.Chrome", { "com.google.Chrome.helper" } },
+        // Microsoft Edge
+        { "com.microsoft.edgemac", { "com.microsoft.edgemac.helper" } },
+        // Arc
+        { "company.thebrowser.Browser", { "company.thebrowser.browser.helper" } }
+    };
+
+    // Parallels' VM "dock helper" apps have bundle IDs like
+    // com.parallels.winapp.87f6bfc236d64d70a81c47f6243add4c.f5a25fdede514f7aa0a475a1873d3287.fs
+    if(inParentBundleID.StartsWith(CFSTR("com.parallels.winapp.")))
+    {
+        return { "com.parallels.vm" };
+    }
+
+    return bundleIDMap[inParentBundleID];
+}
+
+#pragma mark Audible State
+
+BGMDeviceAudibleState BGMBackgroundMusicDevice::GetAudibleState() const
+{
+    CFTypeRef propertyDataRef = GetPropertyData_CFType(kBGMAudibleStateAddress);
+
+    ThrowIfNULL(propertyDataRef,
+                CAException(kAudioHardwareIllegalOperationError),
+                "BGMBackgroundMusicDevice::GetAudibleState: !propertyDataRef");
+
+    ThrowIf(CFGetTypeID(propertyDataRef) != CFNumberGetTypeID(),
+            CAException(kAudioHardwareIllegalOperationError),
+            "BGMBackgroundMusicDevice::GetAudibleState: Property was not a CFNumber");
+
+    CFNumberRef audibleStateRef = static_cast<CFNumberRef>(propertyDataRef);
+
+    BGMDeviceAudibleState audibleState;
+    Boolean success = CFNumberGetValue(audibleStateRef, kCFNumberSInt32Type, &audibleState);
+    CFRelease(audibleStateRef);
+
+    ThrowIf(!success,
+            CAException(kAudioHardwareIllegalOperationError),
+            "BGMBackgroundMusicDevice::GetMusicPlayerProcessID: CFNumberGetValue failed");
+
+    return audibleState;
+}
+
+#pragma mark Music Player
+
+pid_t BGMBackgroundMusicDevice::GetMusicPlayerProcessID() const
+{
+    CFTypeRef propertyDataRef = GetPropertyData_CFType(kBGMMusicPlayerProcessIDAddress);
+
+    ThrowIfNULL(propertyDataRef,
+                CAException(kAudioHardwareIllegalOperationError),
+                "BGMBackgroundMusicDevice::GetMusicPlayerProcessID: !propertyDataRef");
+
+    ThrowIf(CFGetTypeID(propertyDataRef) != CFNumberGetTypeID(),
+            CAException(kAudioHardwareIllegalOperationError),
+            "BGMBackgroundMusicDevice::GetMusicPlayerProcessID: Property was not a CFNumber");
+
+    CFNumberRef pidRef = static_cast<CFNumberRef>(propertyDataRef);
+
+    pid_t pid;
+    Boolean success = CFNumberGetValue(pidRef, kCFNumberIntType, &pid);
+    CFRelease(pidRef);
+
+    ThrowIf(!success,
+            CAException(kAudioHardwareIllegalOperationError),
+            "BGMBackgroundMusicDevice::GetMusicPlayerProcessID: CFNumberGetValue failed");
+
+    return pid;
+}
+
+CFStringRef BGMBackgroundMusicDevice::GetMusicPlayerBundleID() const
+{
+    CFStringRef bundleID = GetPropertyData_CFString(kBGMMusicPlayerBundleIDAddress);
+
+    ThrowIfNULL(bundleID,
+                CAException(kAudioHardwareIllegalOperationError),
+                "BGMBackgroundMusicDevice::GetMusicPlayerBundleID: !bundleID");
+
+    return bundleID;
+}
+
+#pragma clang assume_nonnull end
+

BGMApp/BGMApp/BGMBackgroundMusicDevice.h

@@ -0,0 +1,196 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMBackgroundMusicDevice.h
+//  BGMApp
+//
+//  Copyright © 2017 Kyle Neideck
+//
+//  The interface to BGMDevice, the main virtual device published by BGMDriver, and the second
+//  instance of that device, which handles UI-related audio. In most cases, users of this class
+//  should be able to think of it as representing a single device.
+//
+//  BGMDevice is the device that appears as "Background Music" in programs that list the output
+//  devices, e.g. System Preferences. It receives the system's audio, processes it and sends it to
+//  BGMApp by publishing an input stream. BGMApp then plays the audio on the user's real output
+//  device.
+//
+//  See BGMDriver/BGMDriver/BGM_Device.h.
+//
+
+#ifndef BGMApp__BGMBackgroundMusicDevice
+#define BGMApp__BGMBackgroundMusicDevice
+
+// Superclass Includes
+#include "BGMAudioDevice.h"
+
+// Local Includes
+#include "BGM_Types.h"
+
+// PublicUtility Includes
+#include "CACFString.h"
+
+// STL Includes
+#include <vector>
+
+
+#pragma clang assume_nonnull begin
+
+class BGMBackgroundMusicDevice
+:
+    public BGMAudioDevice
+{
+
+#pragma mark Construction/Destruction
+
+public:
+    /*!
+     @throws CAException If BGMDevice is not found or the HAL returns an error when queried for
+                         BGMDevice's current Audio Object ID.
+     */
+                        BGMBackgroundMusicDevice();
+    virtual            ~BGMBackgroundMusicDevice();
+
+#pragma mark Systemwide Default Device
+
+public:
+    /*!
+     Set BGMDevice as the default audio device for all processes.
+
+     @throws CAException If the HAL responds with an error.
+     */
+    void                SetAsOSDefault();
+    /*!
+     Replace BGMDevice as the default device with the output device.
+
+     @throws CAException If the HAL responds with an error.
+     */
+    void                UnsetAsOSDefault(AudioDeviceID inOutputDeviceID);
+
+#pragma mark App Volumes
+
+public:
+    /*!
+     @return The current value of BGMDevice's kAudioDeviceCustomPropertyAppVolumes property. See
+             BGM_Types.h.
+     @throws CAException If the HAL returns an error or a non-array type. Callers are responsible
+                         for validating and type-checking the values contained in the array.
+     */
+    CFArrayRef          GetAppVolumes() const;
+    /*!
+     @param inVolume A value between kAppRelativeVolumeMinRawValue and kAppRelativeVolumeMaxRawValue
+                     from BGM_Types.h. See kBGMAppVolumesKey_RelativeVolume in BGM_Types.h.
+     @param inAppProcessID The ID of app's main process (or the process it uses to play audio, if
+                           you've managed to figure that out). If an app has multiple audio
+                           processes, you can just set the volume for each of them. Pass -1 to omit
+                           this param.
+     @param inAppBundleID The app's bundle ID. Pass null to omit this param.
+     @throws CAException If the HAL returns an error when this function sends the volume change to
+                         BGMDevice.
+     */
+    void                SetAppVolume(SInt32 inVolume,
+                                     pid_t inAppProcessID,
+                                     CFStringRef __nullable inAppBundleID);
+    /*!
+     @param inPanPosition A value between kAppPanLeftRawValue and kAppPanRightRawValue from
+                          BGM_Types.h. A negative value has a higher proportion of left channel, and
+                          a positive value has a higher proportion of right channel.
+     @param inAppProcessID The ID of app's main process (or the process it uses to play audio, if
+                           you've managed to figure that out). If an app has multiple audio
+                           processes, you can just set the pan position for each of them. Pass -1 to
+                           omit this param.
+     @param inAppBundleID The app's bundle ID. Pass null to omit this param.
+     @throws CAException If the HAL returns an error when this function sends the pan position
+                         change to BGMDevice.
+     */
+    void                SetAppPanPosition(SInt32 inPanPosition,
+                                          pid_t inAppProcessID,
+                                          CFStringRef __nullable inAppBundleID);
+
+private:
+    void                SendAppVolumeOrPanToBGMDevice(SInt32 inNewValue,
+                                                      CFStringRef inVolumeTypeKey,
+                                                      pid_t inAppProcessID,
+                                                      CFStringRef __nullable inAppBundleID);
+
+    static std::vector<CACFString>
+                        ResponsibleBundleIDsOf(CACFString inParentBundleID);
+
+#pragma mark Audible State
+
+public:
+    /*!
+     @return BGMDevice's current "audible state", which can be either silent, silent except for the
+             user's music player or audible, meaning a program other than the music player is
+             playing audio.
+     @throws CAException If the HAL returns an error or invalid data when queried.
+     @see kAudioDeviceCustomPropertyDeviceAudibleState in BGM_Types.h.
+     */
+    BGMDeviceAudibleState GetAudibleState() const;
+
+#pragma mark Music Player
+
+public:
+    /*!
+     @return The value of BGMDevice's property for the selected music player's process ID. Zero if
+             the property is unset. (We assume kernel_task will never be the user's music player.)
+     @throws CAException If the HAL returns an error or an invalid PID when queried.
+     @see kAudioDeviceCustomPropertyMusicPlayerProcessID in BGM_Types.h.
+     */
+    virtual pid_t       GetMusicPlayerProcessID() const;
+    /*!
+     Set the value of BGMDevice's property for the selected music player's process ID. Pass zero to
+     unset the property. Setting this property will unset the bundle ID version of the property.
+
+     @throws CAException If the HAL returns an error.
+     @see kAudioDeviceCustomPropertyMusicPlayerProcessID in BGM_Types.h.
+     */
+    virtual void        SetMusicPlayerProcessID(CFNumberRef inProcessID) {
+                            SetPropertyData_CFType(kBGMMusicPlayerProcessIDAddress, inProcessID); }
+    /*!
+     @return The value of BGMDevice's property for the selected music player's bundle ID. The empty
+             string if the property is unset.
+     @throws CAException If the HAL returns an error or an invalid bundle ID when queried.
+     @see kAudioDeviceCustomPropertyMusicPlayerBundleID in BGM_Types.h.
+     */
+    virtual CFStringRef GetMusicPlayerBundleID() const;
+    /*!
+     Set the value of BGMDevice's property for the selected music player's bundle ID. Pass the empty
+     string to unset the property. Setting this property will unset the process ID version of the
+     property.
+
+     @throws CAException If the HAL returns an error.
+     @see kAudioDeviceCustomPropertyMusicPlayerBundleID in BGM_Types.h.
+     */
+    virtual void        SetMusicPlayerBundleID(CFStringRef inBundleID) {
+                            SetPropertyData_CFString(kBGMMusicPlayerBundleIDAddress, inBundleID); }
+
+#pragma mark UI Sounds Instance
+
+public:
+    /*! @return The instance of BGMDevice that handles UI sounds. */
+    BGMAudioDevice      GetUISoundsBGMDeviceInstance() { return mUISoundsBGMDevice; }
+
+private:
+    /*! The instance of BGMDevice that handles UI sounds. */
+    BGMAudioDevice      mUISoundsBGMDevice;
+
+};
+
+#pragma clang assume_nonnull end
+
+#endif /* BGMApp__BGMBackgroundMusicDevice */
+

BGMApp/BGMApp/BGMDebugLoggingMenuItem.h

@@ -0,0 +1,48 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMDebugLoggingMenuItem.h
+//  BGMApp
+//
+//  Copyright © 2020 Kyle Neideck
+//
+//  A menu item in the main menu that enables/disables debug logging. Only visible if you hold the
+//  option down when you click the status bar icon to reveal the main menu.
+//
+//  TODO: It would be better to have this menu item in the Preferences menu (maybe in an Advanced
+//        section) and always visible, but first we'd need to add something that tells the user how
+//        to view the log messages. Or better yet, something that automatically opens them.
+//
+
+// System Includes
+#import <Cocoa/Cocoa.h>
+
+
+#pragma clang assume_nonnull begin
+
+@interface BGMDebugLoggingMenuItem : NSObject
+
+- (instancetype) initWithMenuItem:(NSMenuItem*)menuItem;
+
+// True if the main menu is showing hidden items/options because the user held the option key when
+// they clicked the icon. This class makes the debug logging menu item visible if this property has
+// been set true or if debug logging is enabled.
+@property (nonatomic) BOOL menuShowingExtraOptions;
+
+@end
+
+#pragma clang assume_nonnull end
+

BGMApp/BGMApp/BGMDebugLoggingMenuItem.m

@@ -0,0 +1,73 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMDebugLoggingMenuItem.m
+//  BGMApp
+//
+//  Copyright © 2020 Kyle Neideck
+//
+
+// Self Include
+#import "BGMDebugLoggingMenuItem.h"
+
+// PublicUtility Includes
+#import "BGMDebugLogging.h"
+#import "CADebugMacros.h"
+
+
+#pragma clang assume_nonnull begin
+
+@implementation BGMDebugLoggingMenuItem {
+    NSMenuItem* _menuItem;
+    BOOL _menuShowingExtraOptions;
+}
+
+- (instancetype) initWithMenuItem:(NSMenuItem*)menuItem {
+    if ((self = [super init])) {
+        _menuItem = menuItem;
+        _menuItem.state =
+                BGMDebugLoggingIsEnabled() ? NSControlStateValueOn : NSControlStateValueOff;
+
+        [self setMenuShowingExtraOptions:NO];
+
+        // Enable/disable debug logging when the menu item is clicked.
+        menuItem.target = self;
+        menuItem.action = @selector(toggleDebugLogging);
+    }
+
+    return self;
+}
+
+- (void) setMenuShowingExtraOptions:(BOOL)showingExtra {
+    _menuShowingExtraOptions = showingExtra;
+    _menuItem.hidden = !BGMDebugLoggingIsEnabled() && !showingExtra;
+
+    DebugMsg("BGMDebugLoggingMenuItem::menuShowingExtraOptions: %s the menu item",
+             _menuItem.hidden ? "Hiding" : "Showing");
+}
+
+- (void) toggleDebugLogging {
+    BGMSetDebugLoggingEnabled(!BGMDebugLoggingIsEnabled());
+    _menuItem.state = BGMDebugLoggingIsEnabled() ? NSControlStateValueOn : NSControlStateValueOff;
+
+    DebugMsg("BGMDebugLoggingMenuItem::toggleDebugLogging: Debug logging %s",
+             BGMDebugLoggingIsEnabled() ? "enabled" : "disabled");
+}
+
+@end
+
+#pragma clang assume_nonnull end
+

BGMApp/BGMApp/BGMDeviceControlSync.cpp

@@ -17,7 +17,7 @@
 //  BGMDeviceControlSync.cpp
 //  BGMApp
 //
-//  Copyright © 2016 Kyle Neideck
+//  Copyright © 2016, 2017 Kyle Neideck
 //
 
 // Self Include
@@ -27,15 +27,12 @@
 #include "BGM_Types.h"
 #include "BGM_Utils.h"
 
-// System Includes
-#include <AudioToolbox/AudioServices.h>
+// PublicUtility Includes
+#include "CAPropertyAddress.h"
 
 
 #pragma clang assume_nonnull begin
 
-// AudioObjectPropertyElement docs: "Elements are numbered sequentially where 0 represents the master element."
-static const AudioObjectPropertyElement kMasterChannel = 0;
-
 static const AudioObjectPropertyAddress kMutePropertyAddress =
     { kAudioDevicePropertyMute, kAudioObjectPropertyScopeOutput, kAudioObjectPropertyElementMaster };
 
@@ -44,31 +41,55 @@ static const AudioObjectPropertyAddress kVolumePropertyAddress =
 
 #pragma mark Construction/Destruction
 
-BGMDeviceControlSync::BGMDeviceControlSync(CAHALAudioDevice inBGMDevice, CAHALAudioDevice inOutputDevice)
+BGMDeviceControlSync::BGMDeviceControlSync(AudioObjectID inBGMDevice,
+                                           AudioObjectID inOutputDevice,
+                                           CAHALAudioSystemObject inAudioSystem)
 :
     mBGMDevice(inBGMDevice),
-    mOutputDevice(inOutputDevice)
+    mOutputDevice(inOutputDevice),
+    mAudioSystem(inAudioSystem),
+    mBGMDeviceControlsList(inBGMDevice)
 {
-    Activate();
 }
 
 BGMDeviceControlSync::~BGMDeviceControlSync()
 {
-    Deactivate();
+    BGMLogAndSwallowExceptions("BGMDeviceControlSync::~BGMDeviceControlSync", [&] {
+        CAMutex::Locker locker(mMutex);
+
+        Deactivate();
+    });
 }
 
 void    BGMDeviceControlSync::Activate()
 {
-    ThrowIf((mBGMDevice.GetObjectID() == kAudioDeviceUnknown || mOutputDevice.GetObjectID() == kAudioDeviceUnknown),
+    CAMutex::Locker locker(mMutex);
+
+    ThrowIf((mBGMDevice.GetObjectID() == kAudioObjectUnknown || mOutputDevice.GetObjectID() == kAudioObjectUnknown),
             BGM_DeviceNotSetException(),
             "BGMDeviceControlSync::Activate: Both the output device and BGMDevice must be set to start synchronizing their controls");
-    
-    // Init BGMDevice controls to match output device
-    CopyVolume(mOutputDevice, mBGMDevice, kAudioObjectPropertyScopeOutput);
-    CopyMute(mOutputDevice, mBGMDevice, kAudioObjectPropertyScopeOutput);
-    
+
     if(!mActive)
     {
+        DebugMsg("BGMDeviceControlSync::Activate: Activating control sync");
+
+        // Disable BGMDevice controls that the output device doesn't have and reenable any that were
+        // disabled for the previous output device.
+        //
+        // Continue anyway if this fails because it's better to have extra/missing controls than to
+        // be unable to use the device.
+        BGMLogAndSwallowExceptionsMsg("BGMDeviceControlSync::Activate", "Controls list", [&] {
+            bool wasUpdated = mBGMDeviceControlsList.MatchControlsListOf(mOutputDevice);
+            if(wasUpdated)
+            {
+                mBGMDeviceControlsList.PropagateControlListChange();
+            }
+        });
+
+        // Init BGMDevice controls to match output device
+        mBGMDevice.CopyVolumeFrom(mOutputDevice, kAudioObjectPropertyScopeOutput);
+        mBGMDevice.CopyMuteFrom(mOutputDevice, kAudioObjectPropertyScopeOutput);
+
         // Register listeners for volume and mute values
         mBGMDevice.AddPropertyListener(kVolumePropertyAddress, &BGMDeviceControlSync::BGMDeviceListenerProc, this);
         
@@ -87,286 +108,129 @@ void    BGMDeviceControlSync::Activate()
         
         mActive = true;
     }
+    else
+    {
+        DebugMsg("BGMDeviceControlSync::Activate: Already active");
+    }
 }
 
 void    BGMDeviceControlSync::Deactivate()
 {
-    if(mActive && mBGMDevice.GetObjectID() != kAudioDeviceUnknown)
+    CAMutex::Locker locker(mMutex);
+
+    if(mActive)
     {
-        // Unregister listeners
-        mBGMDevice.RemovePropertyListener(kVolumePropertyAddress, &BGMDeviceControlSync::BGMDeviceListenerProc, this);
-        mBGMDevice.RemovePropertyListener(kMutePropertyAddress, &BGMDeviceControlSync::BGMDeviceListenerProc, this);
+        DebugMsg("BGMDeviceControlSync::Deactivate: Deactivating control sync");
+
+        // Deregister listeners
+        if(mBGMDevice.GetObjectID() != kAudioDeviceUnknown)
+        {
+            BGMLogAndSwallowExceptions("BGMDeviceControlSync::Deactivate", [&] {
+                mBGMDevice.RemovePropertyListener(kVolumePropertyAddress,
+                                                  &BGMDeviceControlSync::BGMDeviceListenerProc,
+                                                  this);
+            });
+
+            BGMLogAndSwallowExceptions("BGMDeviceControlSync::Deactivate", [&] {
+                mBGMDevice.RemovePropertyListener(kMutePropertyAddress,
+                                                  &BGMDeviceControlSync::BGMDeviceListenerProc,
+                                                  this);
+            });
+        }
+
+        mActive = false;
+    }
+    else
+    {
+        DebugMsg("BGMDeviceControlSync::Deactivate: Not active");
     }
 }
 
+#pragma mark Accessors
 
-void    BGMDeviceControlSync::Swap(BGMDeviceControlSync& inDeviceControlSync)
+void    BGMDeviceControlSync::SetDevices(AudioObjectID inBGMDevice, AudioObjectID inOutputDevice)
 {
-    mBGMDevice = inDeviceControlSync.mBGMDevice;
-    mOutputDevice = inDeviceControlSync.mOutputDevice;
+    CAMutex::Locker locker(mMutex);
+
+    bool wasActive = mActive;
+
+    Deactivate();
+
+    mBGMDevice = inBGMDevice;
+    mBGMDeviceControlsList.SetBGMDevice(inBGMDevice);
+    mOutputDevice = inOutputDevice;
     
-    BGMLogAndSwallowExceptionsMsg("BGMDeviceControlSync::Swap", "Deactivate", [&inDeviceControlSync]() {
-        inDeviceControlSync.Deactivate();
-    });
-    
-    BGMLogAndSwallowExceptionsMsg("BGMDeviceControlSync::Swap", "Activate", [&]() {
+    if(wasActive)
+    {
         Activate();
-    });
-}
-
-#pragma mark Get/Set Control Values
-
-// static
-void    BGMDeviceControlSync::CopyMute(CAHALAudioDevice inFromDevice, CAHALAudioDevice inToDevice, AudioObjectPropertyScope inScope)
-{
-    // TODO: Support for devices that have per-channel mute controls but no master mute control
-    bool toHasSettableMasterMute = inToDevice.HasMuteControl(inScope, kMasterChannel) && inToDevice.MuteControlIsSettable(inScope, kMasterChannel);
-    if(toHasSettableMasterMute && inFromDevice.HasMuteControl(inScope, kMasterChannel))
-    {
-        inToDevice.SetMuteControlValue(inScope,
-                                       kMasterChannel,
-                                       inFromDevice.GetMuteControlValue(inScope, kMasterChannel));
     }
 }
 
-// static
-void    BGMDeviceControlSync::CopyVolume(CAHALAudioDevice inFromDevice, CAHALAudioDevice inToDevice, AudioObjectPropertyScope inScope)
-{
-    // Get the volume of the from device
-    bool didGetFromVolume = false;
-    Float32 fromVolume = FLT_MIN;
-    
-    if(inFromDevice.HasVolumeControl(inScope, kMasterChannel))
-    {
-        fromVolume = inFromDevice.GetVolumeControlScalarValue(inScope, kMasterChannel);
-        didGetFromVolume = true;
-    }
-
-    // Use the average channel volume of the from device if it has no master volume
-    if(!didGetFromVolume)
-    {
-        UInt32 fromNumChannels = inFromDevice.GetTotalNumberChannels(inScope == kAudioObjectPropertyScopeInput);
-        fromVolume = 0;
-        
-        for(UInt32 channel = 1; channel <= fromNumChannels; channel++)
-        {
-            if(inFromDevice.HasVolumeControl(inScope, channel))
-            {
-                fromVolume += inFromDevice.GetVolumeControlScalarValue(inScope, channel);
-                didGetFromVolume = true;
-            }
-        }
-        
-        fromVolume /= fromNumChannels;
-    }
-
-    // Set the volume of the to device
-    if(didGetFromVolume && fromVolume != FLT_MIN)
-    {
-        bool didSetVolume = false;
-        
-        try
-        {
-            didSetVolume = SetMasterVolumeScalar(inToDevice, inScope, fromVolume);
-        }
-        catch(CAException e)
-        {
-            OSStatus err = e.GetError();
-            char err4CC[5] = CA4CCToCString(err);
-            CFStringRef uid = inToDevice.CopyDeviceUID();
-            LogWarning("BGMDeviceControlSync::CopyVolume: CAException '%s' trying to set master volume of %s",
-                       err4CC,
-                       CFStringGetCStringPtr(uid, kCFStringEncodingUTF8));
-            CFRelease(uid);
-        }
-
-        if(!didSetVolume)
-        {
-            // Couldn't find a master volume control to set, so try to find a virtual one
-            Float32 fromVirtualMasterVolume;
-            bool success = GetVirtualMasterVolume(inFromDevice, inScope, fromVirtualMasterVolume);
-            if(success)
-            {
-                didSetVolume = SetVirtualMasterVolume(inToDevice, inScope, fromVirtualMasterVolume);
-            }
-        }
-    
-        if(!didSetVolume)
-        {
-            // Couldn't set a master or virtual master volume, so as a fallback try to set each channel individually
-            UInt32 numChannels = inToDevice.GetTotalNumberChannels(inScope == kAudioObjectPropertyScopeInput);
-            for(UInt32 channel = 1; channel <= numChannels; channel++)
-            {
-                if(inToDevice.HasVolumeControl(inScope, channel) && inToDevice.VolumeControlIsSettable(inScope, channel))
-                {
-                    inToDevice.SetVolumeControlScalarValue(inScope, channel, fromVolume);
-                }
-            }
-        }
-    }
-}
+#pragma mark Listener Procs
 
 // static
-bool    BGMDeviceControlSync::SetMasterVolumeScalar(CAHALAudioDevice inDevice, AudioObjectPropertyScope inScope, Float32 inVolume)
+OSStatus    BGMDeviceControlSync::BGMDeviceListenerProc(AudioObjectID inObjectID, UInt32 inNumberAddresses, const AudioObjectPropertyAddress* inAddresses, void* __nullable inClientData)
 {
-    bool hasSettableMasterVolume =
-        inDevice.HasVolumeControl(inScope, kMasterChannel) && inDevice.VolumeControlIsSettable(inScope, kMasterChannel);
-    
-    if(hasSettableMasterVolume)
-    {
-        inDevice.SetVolumeControlScalarValue(inScope, kMasterChannel, inVolume);
-        return true;
-    }
-    
-    return false;
-}
-
-// static
-bool    BGMDeviceControlSync::GetVirtualMasterVolume(CAHALAudioDevice inDevice, AudioObjectPropertyScope inScope, Float32& outVirtualMasterVolume)
-{
-    AudioObjectPropertyAddress virtualMasterVolumeAddress =
-        { kAudioHardwareServiceDeviceProperty_VirtualMasterVolume, inScope, kAudioObjectPropertyElementMaster };
-    
-    if(!AudioHardwareServiceHasProperty(inDevice.GetObjectID(), &virtualMasterVolumeAddress))
-    {
-        return false;
-    }
-    
-    UInt32 virtualMasterVolumePropertySize = sizeof(Float32);
-    return kAudioServicesNoError == AHSGetPropertyData(inDevice.GetObjectID(),
-                                                       &virtualMasterVolumeAddress,
-                                                       &virtualMasterVolumePropertySize,
-                                                       &outVirtualMasterVolume);
-}
-
-// static
-bool    BGMDeviceControlSync::SetVirtualMasterVolume(CAHALAudioDevice inDevice, AudioObjectPropertyScope inScope, Float32 inVolume)
-{
-    // TODO: For me, setting the virtual master volume sets all the device's channels to the same volume, meaning you can't
-    //       keep any channels quieter than the others. The expected behaviour is to scale the channel volumes
-    //       proportionally. So to do this properly I think we'd have to store BGMDevice's previous volume and calculate
-    //       each channel's new volume from its current volume and the distance between BGMDevice's old and new volumes.
-    //
-    //       The docs kAudioHardwareServiceDeviceProperty_VirtualMasterVolume for say
-    //           "If the device has individual channel volume controls, this property will apply to those identified by the
-    //           device's preferred multi-channel layout (or preferred stereo pair if the device is stereo only). Note that
-    //           this control maintains the relative balance between all the channels it affects.
-    //       so I'm not sure why that's not working here. As a workaround we take the to device's (virtual master) balance
-    //       before changing the volume and set it back after, but of course that'll only work for stereo devices.
-    
-    bool didSetVolume = false;
-    AudioObjectPropertyAddress virtualMasterVolumeAddress =
-        { kAudioHardwareServiceDeviceProperty_VirtualMasterVolume, inScope, kAudioObjectPropertyElementMaster };
-    bool hasVirtualMasterVolume = AudioHardwareServiceHasProperty(inDevice.GetObjectID(), &virtualMasterVolumeAddress);
-    
-    Boolean virtualMasterVolumeIsSettable;
-    OSStatus err = AudioHardwareServiceIsPropertySettable(inDevice.GetObjectID(), &virtualMasterVolumeAddress, &virtualMasterVolumeIsSettable);
-    virtualMasterVolumeIsSettable &= (err == kAudioServicesNoError);
-    
-    if(hasVirtualMasterVolume && virtualMasterVolumeIsSettable)
-    {
-        // Not sure why, but setting the virtual master volume sets all channels to the same volume. As a workaround, we store
-        // the current balance here so we can reset it after setting the volume.
-        Float32 virtualMasterBalance;
-        bool didGetVirtualMasterBalance = GetVirtualMasterBalance(inDevice, inScope, virtualMasterBalance);
-        
-        didSetVolume = kAudioServicesNoError == AHSSetPropertyData(inDevice.GetObjectID(), &virtualMasterVolumeAddress, sizeof(Float32), &inVolume);
-        
-        // Reset the balance
-        AudioObjectPropertyAddress virtualMasterBalanceAddress =
-            { kAudioHardwareServiceDeviceProperty_VirtualMasterBalance, inScope, kAudioObjectPropertyElementMaster };
-        
-        if(didSetVolume && didGetVirtualMasterBalance && AudioHardwareServiceHasProperty(inDevice.GetObjectID(), &virtualMasterBalanceAddress))
-        {
-            Boolean balanceIsSettable;
-            err = AudioHardwareServiceIsPropertySettable(inDevice.GetObjectID(), &virtualMasterBalanceAddress, &balanceIsSettable);
-            if(err == kAudioServicesNoError && balanceIsSettable)
-            {
-                AHSSetPropertyData(inDevice.GetObjectID(), &virtualMasterBalanceAddress, sizeof(Float32), &virtualMasterBalance);
-            }
-        }
-    }
-    
-    return didSetVolume;
-}
-
-// static
-bool    BGMDeviceControlSync::GetVirtualMasterBalance(CAHALAudioDevice inDevice, AudioObjectPropertyScope inScope, Float32& outVirtualMasterBalance)
-{
-    AudioObjectPropertyAddress virtualMasterBalanceAddress =
-        { kAudioHardwareServiceDeviceProperty_VirtualMasterBalance, inScope, kAudioObjectPropertyElementMaster };
-    
-    if(!AudioHardwareServiceHasProperty(inDevice.GetObjectID(), &virtualMasterBalanceAddress))
-    {
-        return false;
-    }
-    
-    UInt32 virtualMasterVolumePropertySize = sizeof(Float32);
-    return kAudioServicesNoError == AHSGetPropertyData(inDevice.GetObjectID(),
-                                                       &virtualMasterBalanceAddress,
-                                                       &virtualMasterVolumePropertySize,
-                                                       &outVirtualMasterBalance);
-}
-
-// static
-OSStatus    BGMDeviceControlSync::AHSGetPropertyData(AudioObjectID inObjectID, const AudioObjectPropertyAddress* inAddress, UInt32* ioDataSize, void* outData)
-{
-    // The docs for AudioHardwareServiceGetPropertyData specifically allow passing NULL for inQualifierData as we do here,
-    // but it's declared in an assume_nonnull section so we have to disable the warning here. I'm not sure why inQualifierData
-    // isn't __nullable. I'm assuming it's either a backwards compatibility thing or just a bug.
-    #pragma clang diagnostic push
-    #pragma clang diagnostic ignored "-Wnonnull"
-    // The non-depreciated version of this (and the setter below) doesn't seem to support devices other than the default
-    return AudioHardwareServiceGetPropertyData(inObjectID, inAddress, 0, NULL, ioDataSize, outData);
-    #pragma clang diagnostic pop
-}
-
-// static
-OSStatus    BGMDeviceControlSync::AHSSetPropertyData(AudioObjectID inObjectID, const AudioObjectPropertyAddress* inAddress, UInt32 inDataSize, const void* inData)
-{
-    // See the explanation about these pragmas in AHSGetPropertyData
-    #pragma clang diagnostic push
-    #pragma clang diagnostic ignored "-Wnonnull"
-    return AudioHardwareServiceSetPropertyData(inObjectID, inAddress, 0, NULL, inDataSize, inData);
-    #pragma clang diagnostic pop
-}
-
-#pragma mark Listener
-
-// static
-OSStatus    BGMDeviceControlSync::BGMDeviceListenerProc(AudioObjectID inObjectID, UInt32 inNumberAddresses, const AudioObjectPropertyAddress* __nonnull inAddresses, void* __nullable inClientData)
-{
-    // refCon (reference context) is the instance that registered this listener proc
+    // refCon (reference context) is the instance that registered this listener proc.
     BGMDeviceControlSync* refCon = static_cast<BGMDeviceControlSync*>(inClientData);
-    
-    if(refCon->mActive)
-    {
-        ThrowIf(inObjectID != refCon->mBGMDevice.GetObjectID(),
-                CAException(kAudioHardwareBadObjectError),
-                "BGMDeviceControlSync::BGMDeviceListenerProc: notified about audio object other than BGMDevice");
-        
-        for(int i = 0; i < inNumberAddresses; i++)
+
+    auto checkState = [&] {
+        if(!refCon)
         {
-            AudioObjectPropertyScope scope = inAddresses[i].mScope;
-            
-            switch(inAddresses[i].mSelector)
-            {
-                case kAudioDevicePropertyVolumeScalar:
-                    // Update the output device
-                    CopyVolume(refCon->mBGMDevice, refCon->mOutputDevice, scope);
-                    break;
-                    
-                case kAudioDevicePropertyMute:
-                    // Update the output device. Note that this also runs when you change the volume (on BGMDevice)
-                    CopyMute(refCon->mBGMDevice, refCon->mOutputDevice, scope);
-                    break;
-                    
-                default:
-                    break;
-            }
+            LogError("BGMDeviceControlSync::BGMDeviceListenerProc: !refCon");
+            return false;
+        }
+
+        if(!refCon->mActive ||
+           (refCon->mBGMDevice.GetObjectID() == kAudioObjectUnknown) ||
+           (refCon->mOutputDevice.GetObjectID() == kAudioObjectUnknown))
+        {
+            return false;
+        }
+
+        if(inObjectID != refCon->mBGMDevice.GetObjectID())
+        {
+            LogError("BGMDeviceControlSync::BGMDeviceListenerProc: notified about audio object other than BGMDevice");
+            return false;
+        }
+        
+        return true;
+    };
+
+    for(int i = 0; i < inNumberAddresses; i++)
+    {
+        AudioObjectPropertyScope scope = inAddresses[i].mScope;
+        
+        switch(inAddresses[i].mSelector)
+        {
+            case kAudioDevicePropertyVolumeScalar:
+                {
+                    CAMutex::Locker locker(refCon->mMutex);
+
+                    // Update the output device's volume.
+                    if(checkState())
+                    {
+                        refCon->mOutputDevice.CopyVolumeFrom(refCon->mBGMDevice, scope);
+                    }
+                }
+                break;
+                
+            case kAudioDevicePropertyMute:
+                {
+                    CAMutex::Locker locker(refCon->mMutex);
+
+                    // Update the output device's mute control. Note that this also runs when you
+                    // change the volume (on BGMDevice).
+                    if(checkState())
+                    {
+                        refCon->mOutputDevice.CopyMuteFrom(refCon->mBGMDevice, scope);
+                    }
+                }
+                break;
         }
     }
-    
+
+    // "The return value [of an AudioObjectPropertyListenerProc] is currently unused and should always be 0."
     return 0;
 }
 

BGMApp/BGMApp/BGMDeviceControlSync.h

@@ -17,65 +17,105 @@
 //  BGMDeviceControlSync.h
 //  BGMApp
 //
-//  Copyright © 2016 Kyle Neideck
+//  Copyright © 2016, 2017 Kyle Neideck
 //
-//  Listens for notifications that BGMDevice's controls (just volume and mute currently) have changed value, and
-//  copies the new values to the output device.
+//  Synchronises BGMDevice's controls (just volume and mute currently) with the output device's
+//  controls. This allows the user to control the output device normally while BGMDevice is set as
+//  the default device.
+//
+//  BGMDeviceControlSync disables any BGMDevice controls that the output device doesn't also have.
+//  When the value of one of BGMDevice's controls is changed, BGMDeviceControlSync copies the new
+//  value to the output device.
+//
+//  Thread safe.
 //
 
-#ifndef __BGMApp__BGMDeviceControlSync__
-#define __BGMApp__BGMDeviceControlSync__
+#ifndef BGMApp__BGMDeviceControlSync
+#define BGMApp__BGMDeviceControlSync
+
+// Local Includes
+#include "BGMAudioDevice.h"
+#include "BGMDeviceControlsList.h"
 
 // PublicUtility Includes
-#include "CAHALAudioDevice.h"
+#include "CAHALAudioSystemObject.h"
+#include "CAMutex.h"
+
+// System Includes
+#include <AudioToolbox/AudioServices.h>
 
 
 #pragma clang assume_nonnull begin
 
 class BGMDeviceControlSync
 {
-    
+
+#pragma mark Construction/Destruction
+
 public:
-                        BGMDeviceControlSync(CAHALAudioDevice inBGMDevice, CAHALAudioDevice inOutputDevice);
+                        BGMDeviceControlSync(AudioObjectID inBGMDevice,
+                                             AudioObjectID inOutputDevice,
+                                             CAHALAudioSystemObject inAudioSystem
+                                                     = CAHALAudioSystemObject());
                         ~BGMDeviceControlSync();
                         // Disallow copying
                         BGMDeviceControlSync(const BGMDeviceControlSync&) = delete;
                         BGMDeviceControlSync& operator=(const BGMDeviceControlSync&) = delete;
-                        // Move constructor/assignment
-                        BGMDeviceControlSync(BGMDeviceControlSync&& inDeviceControlSync) { Swap(inDeviceControlSync); }
-                        BGMDeviceControlSync& operator=(BGMDeviceControlSync&& inDeviceControlSync) { Swap(inDeviceControlSync); return *this; }
-    
+
 #ifdef __OBJC__
                         // Only intended as a convenience for Objective-C instance vars
-                        BGMDeviceControlSync() { };
+                        BGMDeviceControlSync()
+                        : BGMDeviceControlSync(kAudioObjectUnknown, kAudioObjectUnknown) { };
 #endif
-    
-private:
+
+    /*!
+     Begin synchronising BGMDevice's controls with the output device's.
+
+     @throws BGM_DeviceNotSetException if BGMDevice isn't set.
+     @throws CAException if the HAL or one of the devices returns an error when this function
+                         registers for device property notifications or when it copies the current
+                         values of the output device's controls to BGMDevice. This
+                         BGMDeviceControlSync will remain inactive if this function throws.
+     */
     void                Activate();
+    /*! Stop synchronising BGMDevice's controls with the output device's. */
     void                Deactivate();
-    void                Swap(BGMDeviceControlSync& inDeviceControlSync);
-    
-    static void         CopyMute(CAHALAudioDevice inFromDevice, CAHALAudioDevice inToDevice, AudioObjectPropertyScope inScope);
-    static void         CopyVolume(CAHALAudioDevice inFromDevice, CAHALAudioDevice inToDevice, AudioObjectPropertyScope inScope);
-    
-    static bool         SetMasterVolumeScalar(CAHALAudioDevice inDevice, AudioObjectPropertyScope inScope, Float32 inVolume);
-    static bool         GetVirtualMasterVolume(CAHALAudioDevice inDevice, AudioObjectPropertyScope inScope, Float32& outVirtualMasterVolume);
-    static bool         SetVirtualMasterVolume(CAHALAudioDevice inDevice, AudioObjectPropertyScope inScope, Float32 inVolume);
-    static bool         GetVirtualMasterBalance(CAHALAudioDevice inDevice, AudioObjectPropertyScope inScope, Float32& outVirtualMasterBalance);
-    
-    static OSStatus     AHSGetPropertyData(AudioObjectID inObjectID, const AudioObjectPropertyAddress* inAddress, UInt32* ioDataSize, void* outData);
-    static OSStatus     AHSSetPropertyData(AudioObjectID inObjectID, const AudioObjectPropertyAddress* inAddress, UInt32 inDataSize, const void* inData);
-    
-    static OSStatus     BGMDeviceListenerProc(AudioObjectID inObjectID, UInt32 inNumberAddresses, const AudioObjectPropertyAddress* inAddresses, void* __nullable inClientData);
+
+#pragma mark Accessors
+
+    /*!
+     Set the IDs of BGMDevice and the output device to synchronise with.
+
+     @throws BGM_DeviceNotSetException if BGMDevice isn't set.
+     @throws CAException if the HAL or one of the new devices returns an error while restarting
+                         synchronisation. This BGMDeviceControlSync will be deactivated if this
+                         function throws, but its devices will still be set.
+     */
+    void                SetDevices(AudioObjectID inBGMDevice, AudioObjectID inOutputDevice);
+
+#pragma mark Listener Procs
     
 private:
-    bool                mActive = false;
-    CAHALAudioDevice    mBGMDevice { kAudioDeviceUnknown };
-    CAHALAudioDevice    mOutputDevice { kAudioDeviceUnknown };
+    /*! Receives HAL notifications about the BGMDevice properties this class listens to. */
+    static OSStatus     BGMDeviceListenerProc(AudioObjectID inObjectID,
+                                              UInt32 inNumberAddresses,
+                                              const AudioObjectPropertyAddress* inAddresses,
+                                              void* __nullable inClientData);
+    
+private:
+    CAMutex             mMutex         { "Device Control Sync" };
+    bool                mActive        = false;
+
+    CAHALAudioSystemObject mAudioSystem;
+    
+    BGMAudioDevice      mBGMDevice     { (AudioObjectID)kAudioObjectUnknown };
+    BGMAudioDevice      mOutputDevice  { (AudioObjectID)kAudioObjectUnknown };
+
+    BGMDeviceControlsList mBGMDeviceControlsList;
     
 };
 
 #pragma clang assume_nonnull end
 
-#endif /* __BGMApp__BGMDeviceControlSync__ */
+#endif /* BGMApp__BGMDeviceControlSync */
 

BGMApp/BGMApp/BGMDeviceControlsList.cpp

@@ -0,0 +1,569 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMDeviceControlsList.cpp
+//  BGMApp
+//
+//  Copyright © 2017 Kyle Neideck
+//
+
+// Self Include
+#include "BGMDeviceControlsList.h"
+
+// Local Includes
+#include "BGM_Types.h"
+#include "BGM_Utils.h"
+
+// PublicUtility Includes
+#include "CAPropertyAddress.h"
+#include "CACFArray.h"
+
+
+#pragma clang assume_nonnull begin
+
+static const SInt64 kToggleDeviceInitialDelay = 50 * NSEC_PER_MSEC;
+static const SInt64 kToggleDeviceBackDelay    = 500 * NSEC_PER_MSEC;
+static const SInt64 kDisableNullDeviceDelay   = 500 * NSEC_PER_MSEC;
+static const SInt64 kDisableNullDeviceTimeout = 5000 * NSEC_PER_MSEC;
+
+#pragma mark Construction/Destruction
+
+BGMDeviceControlsList::BGMDeviceControlsList(AudioObjectID inBGMDevice,
+                                             CAHALAudioSystemObject inAudioSystem)
+:
+    mBGMDevice(inBGMDevice),
+    mAudioSystem(inAudioSystem)
+{
+    BGMAssert((mBGMDevice.IsBGMDevice() || mBGMDevice.GetObjectID() == kAudioObjectUnknown),
+              "BGMDeviceControlsList::BGMDeviceControlsList: Given device is not BGMDevice");
+
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wpartial-availability"
+    mCanToggleDeviceOnSystem = (&dispatch_block_wait &&
+                                &dispatch_block_cancel &&
+                                &dispatch_block_testcancel &&
+                                &dispatch_queue_attr_make_with_qos_class);
+#pragma clang diagnostic pop
+}
+
+BGMDeviceControlsList::~BGMDeviceControlsList()
+{
+    CAMutex::Locker locker(mMutex);
+
+    if(!mDeviceTogglingInitialised)
+    {
+        return;
+    }
+
+    if(mListenerQueue && mListenerBlock)
+    {
+        BGMLogAndSwallowExceptions("BGMDeviceControlsList::~BGMDeviceControlsList", ([&] {
+            mAudioSystem.RemovePropertyListenerBlock(
+                    CAPropertyAddress(kAudioHardwarePropertyDevices),
+                    mListenerQueue,
+                    mListenerBlock);
+        }));
+    }
+
+    // If we're in the middle of toggling the default device, block until we've finished.
+    if(mDisableNullDeviceBlock && mDeviceToggleState != ToggleState::NotToggling)
+    {
+        DebugMsg("BGMDeviceControlsList::~BGMDeviceControlsList: Waiting for device toggle");
+
+        // Copy the reference so we can unlock the mutex and allow any remaining blocks to run.
+        dispatch_block_t disableNullDeviceBlock = mDisableNullDeviceBlock;
+
+        CAMutex::Unlocker unlocker(mMutex);
+
+        // Note that if mDisableNullDeviceBlock is currently running this will return after it
+        // finishes and if it's already run this will return immediately. So we don't have to
+        // worry about ending up waiting for mDisableNullDeviceBlock when it isn't queued.
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wpartial-availability"
+        long timedOut = dispatch_block_wait(disableNullDeviceBlock, kDisableNullDeviceTimeout);
+#pragma clang diagnostic pop
+
+        if(timedOut)
+        {
+            LogWarning("BGMDeviceControlsList::~BGMDeviceControlsList: Device toggle timed out");
+        }
+    }
+
+    mDeviceToggleState = ToggleState::NotToggling;
+
+    DestroyBlock(mDeviceToggleBlock);
+    DestroyBlock(mDeviceToggleBackBlock);
+    DestroyBlock(mDisableNullDeviceBlock);
+
+    if(mListenerBlock)
+    {
+        Block_release(mListenerBlock);
+    }
+
+    if(mListenerQueue)
+    {
+        dispatch_release(BGM_Utils::NN(mListenerQueue));
+    }
+}
+
+#pragma mark Accessors
+
+void    BGMDeviceControlsList::SetBGMDevice(AudioObjectID inBGMDeviceID)
+{
+    CAMutex::Locker locker(mMutex);
+
+    mBGMDevice = inBGMDeviceID;
+
+    BGMAssert(mBGMDevice.IsBGMDevice(),
+              "BGMDeviceControlsList::SetBGMDevice: Given device is not BGMDevice");
+}
+
+#pragma mark Update Controls List
+
+bool    BGMDeviceControlsList::MatchControlsListOf(AudioObjectID inDeviceID)
+{
+    CAMutex::Locker locker(mMutex);
+
+    if(!mBGMDevice.IsBGMDevice())
+    {
+        LogWarning("BGMDeviceControlsList::MatchControlsListOf: BGMDevice ID not set");
+        return false;
+    }
+
+    // If the output device doesn't have a control that BGMDevice does, disable it on BGMDevice so
+    // the system's audio UI isn't confusing.
+
+    // No need to change input controls.
+    AudioObjectPropertyScope inScope = kAudioObjectPropertyScopeOutput;
+
+    // Check which of BGMDevice's controls are currently enabled. We need to know whether we're
+    // actually enabling/disabling any controls so we know whether we need to call
+    // PropagateControlListChange afterward.
+    CFTypeRef __nullable enabledControlsRef =
+        mBGMDevice.GetPropertyData_CFType(kBGMEnabledOutputControlsAddress);
+
+    ThrowIf(!enabledControlsRef || (CFGetTypeID(enabledControlsRef) != CFArrayGetTypeID()),
+            CAException(kAudioHardwareIllegalOperationError),
+            "BGMDeviceControlsList::MatchControlsListOf: Expected a CFArray for "
+            "kAudioDeviceCustomPropertyEnabledOutputControls");
+
+    CACFArray enabledControls(static_cast<CFArrayRef>(enabledControlsRef), true);
+
+    BGMAssert(enabledControls.GetNumberItems() == 2,
+              "BGMDeviceControlsList::MatchControlsListOf: Expected 2 array elements for "
+              "kAudioDeviceCustomPropertyEnabledOutputControls");
+
+    bool volumeEnabled;
+    bool didGetBool = enabledControls.GetBool(kBGMEnabledOutputControlsIndex_Volume, volumeEnabled);
+    ThrowIf(!didGetBool,
+            CAException(kAudioHardwareIllegalOperationError),
+            "BGMDeviceControlsList::MatchControlsListOf: Expected volume element of "
+            "kAudioDeviceCustomPropertyEnabledOutputControls to be a CFBoolean");
+
+    bool muteEnabled;
+    didGetBool = enabledControls.GetBool(kBGMEnabledOutputControlsIndex_Mute, muteEnabled);
+    ThrowIf(!didGetBool,
+            CAException(kAudioHardwareIllegalOperationError),
+            "BGMDeviceControlsList::MatchControlsListOf: Expected mute element of "
+            "kAudioDeviceCustomPropertyEnabledOutputControls to be a CFBoolean");
+
+    DebugMsg("BGMDeviceControlsList::MatchControlsListOf: BGMDevice has volume %s, mute %s",
+             (volumeEnabled ? "enabled" : "disabled"),
+             (muteEnabled ? "enabled" : "disabled"));
+
+    // Check which controls the other device has.
+    BGMAudioDevice device(inDeviceID);
+    bool hasMute = device.HasSettableMasterMute(inScope);
+
+    bool hasVolume =
+        device.HasSettableMasterVolume(inScope) || device.HasSettableVirtualMasterVolume(inScope);
+
+    if(!hasVolume)
+    {
+        // Check for per-channel volume controls.
+        UInt32 numChannels =
+            device.GetTotalNumberChannels(inScope == kAudioObjectPropertyScopeInput);
+
+        for(UInt32 channel = 1; channel <= numChannels; channel++)
+        {
+            BGMLogAndSwallowExceptionsMsg("BGMDeviceControlsList::MatchControlsListOf",
+                                          "Checking for channel volume controls",
+                                          ([&] {
+                hasVolume =
+                    (device.HasVolumeControl(inScope, channel)
+                            && device.VolumeControlIsSettable(inScope, channel));
+            }));
+
+            if(hasVolume)
+            {
+                break;
+            }
+        }
+    }
+
+    // Tell BGMDevice to enable/disable its controls to match the output device.
+    bool deviceUpdated = false;
+
+    CACFArray newEnabledControls;
+    newEnabledControls.SetCFMutableArrayFromCopy(enabledControls.GetCFArray());
+
+    // Update volume.
+    if(volumeEnabled != hasVolume)
+    {
+        DebugMsg("BGMDeviceControlsList::MatchControlsListOf: %s BGMDevice volume control.",
+                 hasVolume ? "Enabling" : "Disabling");
+
+        newEnabledControls.SetBool(kBGMEnabledOutputControlsIndex_Volume, hasVolume);
+        deviceUpdated = true;
+    }
+
+    // Update mute.
+    if(muteEnabled != hasMute)
+    {
+        DebugMsg("BGMDeviceControlsList::MatchControlsListOf: %s BGMDevice mute control.",
+                 hasMute ? "Enabling" : "Disabling");
+
+        newEnabledControls.SetBool(kBGMEnabledOutputControlsIndex_Mute, hasMute);
+        deviceUpdated = true;
+    }
+
+    if(deviceUpdated)
+    {
+        mBGMDevice.SetPropertyData_CFType(kBGMEnabledOutputControlsAddress,
+                                          newEnabledControls.GetCFMutableArray());
+    }
+
+    return deviceUpdated;
+}
+
+void    BGMDeviceControlsList::PropagateControlListChange()
+{
+    CAMutex::Locker locker(mMutex);
+
+    if((mBGMDevice == kAudioObjectUnknown) || !mCanToggleDeviceOnSystem)
+    {
+        return;
+    }
+
+    InitDeviceToggling();
+
+    // Leave the default device alone if the user has changed it since launching BGMApp.
+    bool bgmDeviceIsDefault = true;
+
+    BGMLogAndSwallowExceptions("BGMDeviceControlsList::PropagateControlListChange", ([&] {
+        bgmDeviceIsDefault =
+            (mBGMDevice.GetObjectID() == mAudioSystem.GetDefaultAudioDevice(false, false));
+    }));
+
+    if(bgmDeviceIsDefault)
+    {
+        mDeviceToggleState = ToggleState::SettingNullDeviceAsDefault;
+
+        // We'll get a notification from the HAL after the Null Device is enabled. Then we can
+        // temporarily make it the default device, which gets other programs to notice that
+        // BGMDevice's controls have changed.
+        try
+        {
+            CAMutex::Unlocker unlocker(mMutex);
+            SetNullDeviceEnabled(true);
+        }
+        catch (...)
+        {
+            mDeviceToggleState = ToggleState::NotToggling;
+            LogError("BGMDeviceControlsList::PropagateControlListChange: Could not enable the Null "
+                     "Device");
+            throw;
+        }
+    }
+}
+
+#pragma mark Implementation
+
+void    BGMDeviceControlsList::InitDeviceToggling()
+{
+    CAMutex::Locker locker(mMutex);
+
+    if(mDeviceTogglingInitialised || !mCanToggleDeviceOnSystem)
+    {
+        return;
+    }
+
+    BGMAssert(mBGMDevice.IsBGMDevice(),
+              "BGMDeviceControlsList::InitDeviceToggling: mBGMDevice device is not set to "
+              "BGMDevice's ID");
+
+    // Register a listener to find out when the Null Device becomes available/unavailable. See
+    // ToggleDefaultDevice.
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wpartial-availability"
+    dispatch_queue_attr_t attr =
+        dispatch_queue_attr_make_with_qos_class(DISPATCH_QUEUE_SERIAL, QOS_CLASS_DEFAULT, 0);
+#pragma clang diagnostic pop
+    mListenerQueue = dispatch_queue_create("com.bearisdriving.BGM.BGMDeviceControlsList", attr);
+
+    auto listenerBlock = ^(UInt32 inNumberAddresses, const AudioObjectPropertyAddress* inAddresses) {
+        // Ignore the notification if we're not toggling the default device, which would just mean
+        // the default device has been changed for an unrelated reason.
+        if(mDeviceToggleState == ToggleState::NotToggling)
+        {
+            return;
+        }
+
+        for(int i = 0; i < inNumberAddresses; i++)
+        {
+            switch(inAddresses[i].mSelector)
+            {
+                case kAudioHardwarePropertyDevices:
+                    {
+                        CAMutex::Locker innerLocker(mMutex);
+
+                        DebugMsg("BGMDeviceControlsList::InitDeviceToggling: Got "
+                                 "kAudioHardwarePropertyDevices");
+
+                        // Cancel the previous block in case it hasn't run yet.
+                        DestroyBlock(mDeviceToggleBlock);
+
+                        mDeviceToggleBlock = CreateDeviceToggleBlock();
+
+                        // Changing the default device too quickly after enabling the Null Device
+                        // seems to cause problems with some programs. Not sure why.
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wpartial-availability"
+                        if(mDeviceToggleBlock)
+                        {
+                            dispatch_after(dispatch_time(DISPATCH_TIME_NOW,
+                                                         kToggleDeviceInitialDelay),
+                                           dispatch_get_global_queue(QOS_CLASS_USER_INITIATED, 0),
+                                           BGM_Utils::NN(mDeviceToggleBlock));
+                        }
+#pragma clang diagnostic pop
+                    }
+                    break;
+
+                default:
+                    break;
+            }
+        }
+    };
+
+    mListenerBlock = Block_copy(listenerBlock);
+
+    BGMLogAndSwallowExceptions("BGMDeviceControlsList::InitDeviceToggling", [&] {
+        mAudioSystem.AddPropertyListenerBlock(CAPropertyAddress(kAudioHardwarePropertyDevices),
+                                              mListenerQueue,
+                                              mListenerBlock);
+    });
+
+    mDeviceTogglingInitialised = true;
+}
+
+void    BGMDeviceControlsList::ToggleDefaultDevice()
+{
+    // Set the Null Device as the OS X default device.
+    AudioObjectID nullDeviceID = mAudioSystem.GetAudioDeviceForUID(CFSTR(kBGMNullDeviceUID));
+
+    if(nullDeviceID == kAudioObjectUnknown)
+    {
+        // It's unlikely, but we might have been notified about an unrelated device so just log a
+        // warning.
+        LogWarning("BGMDeviceControlsList::ToggleDefaultDevice: Null Device not found");
+        return;
+    }
+
+    DebugMsg("BGMDeviceControlsList::ToggleDefaultDevice: Setting Null Device as default. "
+             "nullDeviceID = %u", nullDeviceID);
+    mAudioSystem.SetDefaultAudioDevice(false, false, nullDeviceID);
+
+    mDeviceToggleState = ToggleState::SettingBGMDeviceAsDefault;
+
+    // A small number of apps (e.g. Firefox) seem to have trouble with the default device being
+    // changed back immediately, so for now we insert a short delay here and before disabling the
+    // Null Device.
+
+    // Cancel the previous block in case it hasn't run yet.
+    DestroyBlock(mDeviceToggleBackBlock);
+
+    mDeviceToggleBackBlock = CreateDeviceToggleBackBlock();
+
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wpartial-availability"
+    if(mDeviceToggleBackBlock)
+    {
+        dispatch_after(dispatch_time(DISPATCH_TIME_NOW, kToggleDeviceBackDelay),
+                       dispatch_get_global_queue(QOS_CLASS_USER_INITIATED, 0),
+                       BGM_Utils::NN(mDeviceToggleBackBlock));
+    }
+#pragma clang diagnostic pop
+}
+
+void    BGMDeviceControlsList::SetNullDeviceEnabled(bool inEnabled)
+{
+    DebugMsg("BGMDeviceControlsList::SetNullDeviceEnabled: %s the null device",
+             inEnabled ? "Enabling" : "Disabling");
+
+    // Get the audio object for BGMDriver, which is the object the Null Device belongs to.
+    AudioObjectID bgmDriverID = mAudioSystem.GetAudioPlugInForBundleID(CFSTR(kBGMDriverBundleID));
+
+    if(bgmDriverID == kAudioObjectUnknown)
+    {
+        LogError("BGMDeviceControlsList::SetNullDeviceEnabled: BGMDriver plug-in audio object not "
+                 "found");
+        throw CAException(kAudioHardwareUnspecifiedError);
+    }
+
+    CAHALAudioObject bgmDriver(bgmDriverID);
+    bgmDriver.SetPropertyData_CFType(CAPropertyAddress(kAudioPlugInCustomPropertyNullDeviceActive),
+                                     (inEnabled ? kCFBooleanTrue : kCFBooleanFalse));
+}
+
+dispatch_block_t __nullable BGMDeviceControlsList::CreateDeviceToggleBlock()
+{
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wpartial-availability"
+    dispatch_block_t __nullable toggleBlock = dispatch_block_create((dispatch_block_flags_t)0, ^{
+#pragma clang diagnostic pop
+        CAMutex::Locker locker(mMutex);
+
+        if(mDeviceToggleState == ToggleState::SettingNullDeviceAsDefault)
+        {
+            BGMLogAndSwallowExceptions("BGMDeviceControlsList::CreateDeviceToggleBlock",
+                                       ([&] {
+                ToggleDefaultDevice();
+            }));
+        }
+    });
+
+    if(!toggleBlock)
+    {
+        // Pretty sure this should never happen, but the docs aren't completely clear.
+        LogError("BGMDeviceControlsList::CreateDeviceToggleBlock: !toggleBlock");
+    }
+
+    return toggleBlock;
+}
+
+dispatch_block_t __nullable BGMDeviceControlsList::CreateDeviceToggleBackBlock()
+{
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wpartial-availability"
+    dispatch_block_t __nullable toggleBackBlock =
+            dispatch_block_create((dispatch_block_flags_t)0, ^{
+#pragma clang diagnostic pop
+        CAMutex::Locker locker(mMutex);
+
+        if(mDeviceToggleState != ToggleState::SettingBGMDeviceAsDefault)
+        {
+            return;
+        }
+
+        // Set BGMDevice back as the default device.
+        DebugMsg("BGMDeviceControlsList::ToggleDefaultDevice: Setting BGMDevice as default");
+        BGMLogAndSwallowExceptions("BGMDeviceControlsList::CreateDeviceToggleBackBlock", ([&] {
+            mAudioSystem.SetDefaultAudioDevice(false, false, mBGMDevice.GetObjectID());
+        }));
+
+        mDeviceToggleState = ToggleState::DisablingNullDevice;
+
+        // Cancel the previous block in case it hasn't run yet.
+        DestroyBlock(mDisableNullDeviceBlock);
+
+        mDisableNullDeviceBlock = CreateDisableNullDeviceBlock();
+
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wpartial-availability"
+        if(mDisableNullDeviceBlock)
+        {
+            dispatch_after(dispatch_time(DISPATCH_TIME_NOW, kDisableNullDeviceDelay),
+                           dispatch_get_global_queue(QOS_CLASS_DEFAULT, 0),
+                           BGM_Utils::NN(mDisableNullDeviceBlock));
+        }
+#pragma clang diagnostic pop
+    });
+
+    if(!toggleBackBlock)
+    {
+        // Pretty sure this should never happen, but the docs aren't completely clear.
+        LogError("BGMDeviceControlsList::CreateDeviceToggleBackBlock: !toggleBackBlock");
+    }
+
+    return toggleBackBlock;
+}
+
+dispatch_block_t __nullable BGMDeviceControlsList::CreateDisableNullDeviceBlock()
+{
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wpartial-availability"
+    dispatch_block_t __nullable disableNullDeviceBlock =
+            dispatch_block_create((dispatch_block_flags_t)0, ^{
+#pragma clang diagnostic pop
+        CAMutex::Locker locker(mMutex);
+
+        if(mDeviceToggleState != ToggleState::DisablingNullDevice)
+        {
+            return;
+        }
+
+        mDeviceToggleState = ToggleState::NotToggling;
+
+        BGMLogAndSwallowExceptions("BGMDeviceControlsList::CreateDisableNullDeviceBlock",
+                                   ([&] {
+            CAMutex::Unlocker unlocker(mMutex);
+            // Hide the null device from the user again.
+            SetNullDeviceEnabled(false);
+        }));
+
+        BGMAssert(mBGMDevice.IsBGMDevice(), "BGMDevice's AudioObjectID changed");
+    });
+
+    if(!disableNullDeviceBlock)
+    {
+        // Pretty sure this should never happen, but the docs aren't completely clear.
+        LogError("BGMDeviceControlsList::CreateDisableNullDeviceBlock: !disableNullDeviceBlock");
+    }
+
+    return disableNullDeviceBlock;
+}
+
+void    BGMDeviceControlsList::DestroyBlock(dispatch_block_t __nullable & block)
+{
+    if(!block)
+    {
+        return;
+    }
+
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wpartial-availability"
+    dispatch_block_t& blockNN = (dispatch_block_t&)block;
+    if(!dispatch_block_testcancel(blockNN))
+    {
+        // Stop the block from running if it's currently queued.
+        dispatch_block_cancel(blockNN);
+
+        // Make sure the block isn't currently running. That should almost never be the case.
+        while(!dispatch_block_testcancel(blockNN))
+        {
+            CAMutex::Unlocker unlocker(mMutex);
+            usleep(10);
+        }
+        
+        Block_release(block);
+        block = nullptr;
+    }
+#pragma clang diagnostic pop
+}
+
+#pragma clang assume_nonnull end
+

BGMApp/BGMApp/BGMDeviceControlsList.h

@@ -0,0 +1,138 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMDeviceControlsList.h
+//  BGMApp
+//
+//  Copyright © 2017 Kyle Neideck
+//
+
+#ifndef BGMApp__BGMDeviceControlsList
+#define BGMApp__BGMDeviceControlsList
+
+// Local Includes
+#include "BGMAudioDevice.h"
+
+// PublicUtility Includes
+#include "CAHALAudioDevice.h"
+#include "CAHALAudioSystemObject.h"
+#include "CAMutex.h"
+
+// System Includes
+#include <dispatch/dispatch.h>
+#include <AudioToolbox/AudioServices.h>
+
+
+#pragma clang assume_nonnull begin
+
+class BGMDeviceControlsList
+{
+
+#pragma mark Construction/Destruction
+
+public:
+
+                        BGMDeviceControlsList(AudioObjectID inBGMDevice,
+                                              CAHALAudioSystemObject inAudioSystem
+                                                      = CAHALAudioSystemObject());
+                        ~BGMDeviceControlsList();
+                        // Disallow copying
+                        BGMDeviceControlsList(const BGMDeviceControlsList&) = delete;
+                        BGMDeviceControlsList& operator=(const BGMDeviceControlsList&) = delete;
+
+#pragma mark Accessors
+
+    /*! @param inBGMDeviceID The ID of BGMDevice. */
+    void                SetBGMDevice(AudioObjectID inBGMDeviceID);
+
+#pragma mark Update Controls List
+
+    /*!
+     Enable the BGMDevice controls (volume and mute currently) that can be matched to controls of
+     the given device, and disable the ones that can't.
+
+     @param inDeviceID The ID of the device.
+     @return True if BGMDevice's list of controls was updated.
+     @throws CAException if an error is received from either device.
+     */
+    bool                MatchControlsListOf(AudioObjectID inDeviceID);
+    /*!
+     After updating BGMDevice's controls list, we need to change the default device so programs
+     (including OS X's audio UI) will update themselves. We could just change to the real output
+     device and change back, but that could have side effects the user wouldn't expect. For example,
+     an app the user has muted might be unmuted for a short period.
+
+     Instead we tell BGMDriver to enable the Null Device -- a device that does nothing -- so we can
+     use it to toggle the default device. The Null Device is normally disabled so it can be hidden
+     from the user. OS X won't let us make a hidden device temporarily visible or set a hidden
+     device as the default, so we have to completely remove the Null Device from the system while
+     we're not using it.
+     
+     @throws CAException if it fails to enable the Null Device.
+     */
+    void                PropagateControlListChange();
+
+#pragma mark Implementation
+
+private:
+    /*! Lazily initialises the fields used to toggle the default device. */
+    void                InitDeviceToggling();
+    /*! Changes the OS X default audio device to the Null Device and then back to BGMDevice. */
+    void                ToggleDefaultDevice();
+    /*!
+     Enable or disable the Null Device. See PropagateControlListChange and BGM_NullDevice in 
+     BGMDriver.
+
+     @throws CAException if we can't get the BGMDriver plug-in audio object from the HAL or the HAL
+                         returns an error when setting kAudioPlugInCustomPropertyNullDeviceActive.
+     */
+    void                SetNullDeviceEnabled(bool inEnabled);
+
+    dispatch_block_t __nullable CreateDeviceToggleBlock();
+    dispatch_block_t __nullable CreateDeviceToggleBackBlock();
+    dispatch_block_t __nullable CreateDisableNullDeviceBlock();
+
+    void                DestroyBlock(dispatch_block_t __nullable & block);
+
+private:
+    CAMutex             mMutex { "Device Controls List" };
+    bool                mDeviceTogglingInitialised = false;
+    // OS X 10.9 doesn't have the functions we use for PropagateControlListChange.
+    bool                mCanToggleDeviceOnSystem;
+
+    BGMAudioDevice      mBGMDevice;
+    CAHALAudioSystemObject mAudioSystem;  // Not guarded by the mutex.
+
+    enum ToggleState
+    {
+        NotToggling, SettingNullDeviceAsDefault, SettingBGMDeviceAsDefault, DisablingNullDevice
+    };
+    BGMDeviceControlsList::ToggleState mDeviceToggleState = ToggleState::NotToggling;
+
+    dispatch_block_t __nullable mDeviceToggleBlock      = nullptr;
+    dispatch_block_t __nullable mDeviceToggleBackBlock  = nullptr;
+    dispatch_block_t __nullable mDisableNullDeviceBlock = nullptr;
+
+    // These will only ever be null after construction on 10.9, since toggling will be disabled.
+    dispatch_queue_t __nullable                 mListenerQueue = nullptr;
+    AudioObjectPropertyListenerBlock __nullable mListenerBlock = nullptr;
+
+};
+
+#pragma clang assume_nonnull end
+
+#endif /* BGMApp__BGMDeviceControlsList */
+

BGMApp/BGMApp/BGMOutputDeviceMenuSection.h

@@ -0,0 +1,46 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMOutputDeviceMenuSection.h
+//  BGMApp
+//
+//  Copyright © 2016, 2018 Kyle Neideck
+//
+
+// Local Includes
+#import "BGMAudioDeviceManager.h"
+#import "BGMPreferredOutputDevices.h"
+
+// System Includes
+#import <AppKit/AppKit.h>
+
+
+#pragma clang assume_nonnull begin
+
+@interface BGMOutputDeviceMenuSection : NSObject
+
+- (instancetype) initWithBGMMenu:(NSMenu*)inBGMMenu
+                    audioDevices:(BGMAudioDeviceManager*)inAudioDevices
+                preferredDevices:(BGMPreferredOutputDevices*)inPreferredDevices;
+
+// To be called when BGMApp has been set to use a different output device. For example, when a new
+// device is connected and BGMPreferredOutputDevices decides BGMApp should switch to it.
+- (void) outputDeviceDidChange;
+
+@end
+
+#pragma clang assume_nonnull end
+

BGMApp/BGMApp/BGMOutputDeviceMenuSection.mm

@@ -14,46 +14,127 @@
 // along with Background Music. If not, see <http://www.gnu.org/licenses/>.
 
 //
-//  BGMOutputDevicePrefs.mm
+//  BGMOutputDeviceMenuSection.mm
 //  BGMApp
 //
-//  Copyright © 2016 Kyle Neideck
+//  Copyright © 2016-2018 Kyle Neideck
 //
 
 // Self Include
-#import "BGMOutputDevicePrefs.h"
+#import "BGMOutputDeviceMenuSection.h"
 
 // Local Includes
 #import "BGM_Utils.h"
+#import "BGM_Types.h"
+#import "BGMAudioDevice.h"
 
 // PublicUtility Includes
-#include "CAHALAudioSystemObject.h"
-#include "CAHALAudioDevice.h"
-#include "CAAutoDisposer.h"
+#import "CAAutoDisposer.h"
+#import "CAHALAudioDevice.h"
+#import "CAHALAudioSystemObject.h"
+#import "CAPropertyAddress.h"
+
+// STL Includes
+#import <set>
 
 
 #pragma clang assume_nonnull begin
 
-static NSInteger const kOutputDeviceMenuItemTag = 2;
+static NSInteger const kOutputDeviceMenuItemTag = 5;
 
-@implementation BGMOutputDevicePrefs {
+@implementation BGMOutputDeviceMenuSection {
+    NSMenu* bgmMenu;
     BGMAudioDeviceManager* audioDevices;
+    BGMPreferredOutputDevices* preferredDevices;
     NSMutableArray<NSMenuItem*>* outputDeviceMenuItems;
+    // Called when a CoreAudio property has changed and we might need to update the menu. For
+    // example, when a device is connected or disconnected.
+    AudioObjectPropertyListenerBlock refreshNeededListener;
+    // The devices we've added refreshNeededListener to. Used to avoid adding it to a device twice
+    // for the same property and to remove it from all devices in dealloc.
+    std::set<BGMAudioDevice> listenedDevices_kAudioDevicePropertyDataSources;
+    std::set<BGMAudioDevice> listenedDevices_kAudioDevicePropertyDataSource;
 }
 
-- (id) initWithAudioDevices:(BGMAudioDeviceManager*)inAudioDevices {
+- (instancetype) initWithBGMMenu:(NSMenu*)inBGMMenu
+                    audioDevices:(BGMAudioDeviceManager*)inAudioDevices
+                preferredDevices:(BGMPreferredOutputDevices*)inPreferredDevices {
     if ((self = [super init])) {
+        bgmMenu = inBGMMenu;
         audioDevices = inAudioDevices;
+        preferredDevices = inPreferredDevices;
         outputDeviceMenuItems = [NSMutableArray new];
+
+        [self listenForDevicesAddedOrRemoved];
+        [self populateBGMMenu];
     }
     
     return self;
 }
 
-- (void) populatePreferencesMenu:(NSMenu*)prefsMenu {
+- (void) dealloc {
+    // Tell CoreAudio not to call the listener block anymore. This probably isn't necessary.
+    //
+    // I think it's safe to do this without dispatching to the main queue because dealloc and
+    // refreshNeededListener should be essentially mutually exclusive. If refreshNeededListener is
+    // invoked and gets a value for weakSelf, it holds the strong ref until it returns, so dealloc
+    // won't be called. If refreshNeededListener is invoked and deallocation has started, it will
+    // get nil for weakSelf and just return.
+    auto removeListener = [&] (CAHALAudioObject audioObject, AudioObjectPropertySelector prop) {
+        BGM_Utils::LogAndSwallowExceptions(BGMDbgArgs, [&] {
+            // Check the object still exists first to reduce unnecessary error logs.
+            if (CAHALAudioObject::ObjectExists(audioObject.GetObjectID())) {
+                audioObject.RemovePropertyListenerBlock(CAPropertyAddress(prop),
+                                                        dispatch_get_main_queue(),
+                                                        refreshNeededListener);
+            }
+        });
+    };
+
+    // Remove the listener from each audio object we added it to.
+    removeListener(CAHALAudioSystemObject(), kAudioHardwarePropertyDevices);
+
+    for (auto device : listenedDevices_kAudioDevicePropertyDataSources) {
+        removeListener(device, kAudioDevicePropertyDataSources);
+    }
+
+    for (auto device : listenedDevices_kAudioDevicePropertyDataSource) {
+        removeListener(device, kAudioDevicePropertyDataSource);
+    }
+}
+
+- (void) listenForDevicesAddedOrRemoved {
+    // Create the block that will run when a device is added or removed.
+    BGMOutputDeviceMenuSection* __weak weakSelf = self;
+
+    refreshNeededListener = ^(UInt32 inNumberAddresses,
+                              const AudioObjectPropertyAddress* inAddresses) {
+        #pragma unused (inNumberAddresses, inAddresses)
+
+        BGM_Utils::LogAndSwallowExceptions(BGMDbgArgs, [&] {
+            [weakSelf populateBGMMenu];
+        });
+    };
+
+    // Register the listener block to be called when devices are connected or disconnected.
+    BGM_Utils::LogAndSwallowExceptions(BGMDbgArgs, [&] {
+        CAHALAudioSystemObject().AddPropertyListenerBlock(
+            CAPropertyAddress(kAudioHardwarePropertyDevices),
+            dispatch_get_main_queue(),
+            refreshNeededListener);
+    });
+}
+
+- (void) populateBGMMenu {
+    // TODO: Technically, we should assert we're on the main queue rather than just the main thread.
+    BGMAssert([NSThread isMainThread],
+              "BGMOutputDeviceMenuSection::populateBGMMenu called on non-main thread");
+
     // Remove existing menu items
     for (NSMenuItem* item in outputDeviceMenuItems) {
-        [prefsMenu removeItem:item];
+        DebugMsg("BGMOutputDeviceMenuSection::populateBGMMenu: Removing %s",
+                 item.description.UTF8String);
+        [bgmMenu removeItem:item];
     }
     
     [outputDeviceMenuItems removeAllObjects];
@@ -67,29 +148,52 @@ static NSInteger const kOutputDeviceMenuItemTag = 2;
         audioSystem.GetAudioDevices(numDevices, devices);
         
         for (UInt32 i = 0; i < numDevices; i++) {
-            CAHALAudioDevice device(devices[i]);
-            [self insertMenuItemsForDevice:device preferencesMenu:prefsMenu];
+            [self insertMenuItemsForDevice:devices[i]];
         }
     }
 }
 
-- (void) insertMenuItemsForDevice:(CAHALAudioDevice)device preferencesMenu:(NSMenu*)prefsMenu {
+- (void) insertMenuItemsForDevice:(BGMAudioDevice)device {
     // Insert menu items after the item for the "Output Device" heading.
-    const NSInteger menuItemsIdx = [prefsMenu indexOfItemWithTag:kOutputDeviceMenuItemTag] + 1;
-    
-    BGMLogAndSwallowExceptions("BGMOutputDevicePrefs::insertMenuItemsForDevice", [&]() {
-        BOOL isBGMDevice = (device.GetObjectID() == [audioDevices bgmDevice].GetObjectID());
-        BOOL isHidden = device.IsHidden();
-        BOOL hasOutputChannels = device.GetTotalNumberChannels(/* inIsInput = */ false) > 0;
-        BOOL canBeDefault = device.CanBeDefaultDevice(/* inIsInput = */ false, /* inIsSystem = */ false);
-        
-        if (!isBGMDevice && !isHidden && hasOutputChannels && canBeDefault) {
-            for (NSMenuItem* item : [self createMenuItemsForDevice:device]) {
-                [prefsMenu insertItem:item atIndex:menuItemsIdx];
-                [outputDeviceMenuItems addObject:item];
-            }
-        }
+    const NSInteger menuItemsIdx = [bgmMenu indexOfItemWithTag:kOutputDeviceMenuItemTag] + 1;
+
+    BOOL canBeOutputDevice = YES;
+    BGM_Utils::LogAndSwallowExceptions(BGMDbgArgs, [&] {
+        canBeOutputDevice = device.CanBeOutputDeviceInBGMApp();
     });
+
+    if (canBeOutputDevice) {
+        for (NSMenuItem* item : [self createMenuItemsForDevice:device]) {
+            DebugMsg("BGMOutputDeviceMenuSection::insertMenuItemsForDevice: Inserting %s",
+                     item.description.UTF8String);
+            [bgmMenu insertItem:item atIndex:menuItemsIdx];
+            [outputDeviceMenuItems addObject:item];
+        }
+
+        // Add listeners to update the menu when the device's data source changes or it changes its
+        // list of data sources. We do this so that, for example, when you plug headphones into the
+        // built-in jack, the menu item for the built-in device will change from "Internal Speakers"
+        // to "Headphones".
+        if (listenedDevices_kAudioDevicePropertyDataSources.count(device) == 0) {
+            BGM_Utils::LogAndSwallowExceptions(BGMDbgArgs, [&] {
+                device.AddPropertyListenerBlock(CAPropertyAddress(kAudioDevicePropertyDataSources,
+                                                                  kAudioDevicePropertyScopeOutput),
+                                                dispatch_get_main_queue(),
+                                                refreshNeededListener);
+                listenedDevices_kAudioDevicePropertyDataSources.insert(device);
+            });
+        };
+
+        if (listenedDevices_kAudioDevicePropertyDataSource.count(device) == 0) {
+            BGM_Utils::LogAndSwallowExceptions(BGMDbgArgs, [&] {
+                device.AddPropertyListenerBlock(CAPropertyAddress(kAudioDevicePropertyDataSource,
+                                                                  kAudioDevicePropertyScopeOutput),
+                                                dispatch_get_main_queue(),
+                                                refreshNeededListener);
+                listenedDevices_kAudioDevicePropertyDataSource.insert(device);
+            });
+        };
+    }
 }
 
 - (NSArray<NSMenuItem*>*) createMenuItemsForDevice:(CAHALAudioDevice)device {
@@ -98,7 +202,7 @@ static NSInteger const kOutputDeviceMenuItemTag = 2;
     NSMutableArray<NSMenuItem*>* items = [NSMutableArray new];
 
     AudioObjectPropertyScope scope = kAudioObjectPropertyScopeOutput;
-    UInt32 channel = 0;  // 0 is the master channel.
+    UInt32 channel = kAudioObjectPropertyElementMaster;
     
     // If the device has data sources, create a menu item for each. Otherwise, create a single menu item
     // for the device. This way the menu items' titles will be, for example, "Internal Speakers" rather
@@ -107,8 +211,8 @@ static NSInteger const kOutputDeviceMenuItemTag = 2;
     // TODO: Handle data destinations as well? I don't have (or know of) any hardware with them.
     // TODO: Use the current data source's name when the control isn't settable, but only add one menu item.
     UInt32 numDataSources = 0;
-    
-    BGMLogAndSwallowExceptions("BGMOutputDevicePrefs::createMenuItemsForDevice", [&]() {
+
+    BGM_Utils::LogAndSwallowExceptions(BGMDbgArgs, [&] {
         if (device.HasDataSourceControl(scope, channel) &&
                 device.DataSourceControlIsSettable(scope, channel)) {
             numDataSources = device.GetNumberAvailableDataSources(scope, channel);
@@ -121,27 +225,27 @@ static NSInteger const kOutputDeviceMenuItemTag = 2;
         device.GetAvailableDataSources(scope, channel, numDataSources, dataSourceIDs);
         
         for (UInt32 i = 0; i < numDataSources; i++) {
-            DebugMsg("BGMOutputDevicePrefs::createMenuItemsForDevice: Creating item. %s%u %s%u",
+            DebugMsg("BGMOutputDeviceMenuSection::createMenuItemsForDevice: "
+                     "Creating item. %s%u %s%u",
                      "Device ID:", device.GetObjectID(),
                      ", Data source ID:", dataSourceIDs[i]);
-            
-            BGMLogAndSwallowExceptionsMsg("BGMOutputDevicePrefs::createMenuItemsForDevice", "(DS)", [&]() {
-                NSNumber* dataSourceID = [NSNumber numberWithUnsignedInt:dataSourceIDs[i]];
+
+            BGM_Utils::LogAndSwallowExceptions(BGMDbgArgs, "(DS)", [&] {
                 NSString* dataSourceName =
                     CFBridgingRelease(device.CopyDataSourceNameForID(scope, channel, dataSourceIDs[i]));
                 NSString* deviceName = CFBridgingRelease(device.CopyName());
                 
                 [items addObject:[self createMenuItemForDevice:device
-                                                  dataSourceID:dataSourceID
+                                                  dataSourceID:@(dataSourceIDs[i])
                                                          title:dataSourceName
                                                        toolTip:deviceName]];
             });
         }
     } else {
-        DebugMsg("BGMOutputDevicePrefs::createMenuItemsForDevice: Creating item. %s%u",
+        DebugMsg("BGMOutputDeviceMenuSection::createMenuItemsForDevice: Creating item. %s%u",
                  "Device ID:", device.GetObjectID());
-        
-        BGMLogAndSwallowExceptions("BGMOutputDevicePrefs::createMenuItemsForDevice", [&]() {
+
+        BGM_Utils::LogAndSwallowExceptions(BGMDbgArgs, [&] {
             [items addObject:[self createMenuItemForDevice:device
                                               dataSourceID:nil
                                                      title:CFBridgingRelease(device.CopyName())
@@ -162,13 +266,13 @@ static NSInteger const kOutputDeviceMenuItemTag = 2;
     }
     
     NSMenuItem* item = [[NSMenuItem alloc] initWithTitle:BGMNN(title)
-                                                  action:@selector(outputDeviceWasChanged:)
+                                                  action:@selector(outputDeviceMenuItemSelected:)
                                            keyEquivalent:@""];
     
     // Add the AirPlay icon to the labels of AirPlay devices.
     //
     // TODO: Test this with real hardware that supports AirPlay. (I don't have any.)
-    BGMLogAndSwallowExceptions("BGMOutputDevicePrefs::createMenuItemForDevice", [&]() {
+    BGM_Utils::LogAndSwallowExceptions(BGMDbgArgs, [&] {
         if (device.GetTransportType() == kAudioDeviceTransportTypeAirPlay) {
             item.image = [NSImage imageNamed:@"AirPlayIcon"];
             
@@ -188,14 +292,32 @@ static NSInteger const kOutputDeviceMenuItemTag = 2;
     item.toolTip = toolTip;
     item.target = self;
     item.indentationLevel = 1;
-    item.representedObject = @{ @"deviceID": [NSNumber numberWithUnsignedInt:device.GetObjectID()],
+    item.representedObject = @{ @"deviceID": @(device.GetObjectID()),
                                 @"dataSourceID": dataSourceID ? BGMNN(dataSourceID) : [NSNull null] };
+
+#if __clang_major__ >= 9
+    if (@available(macOS 10.10, *)) {
+        // Used for UI tests.
+        item.accessibilityIdentifier = @"output-device";
+    }
+#endif
     
     return item;
 }
 
-- (void) outputDeviceWasChanged:(NSMenuItem*)menuItem {
-    DebugMsg("BGMOutputDevicePrefs::outputDeviceWasChanged: '%s' menu item selected",
+// Called by BGMAudioDeviceManager to tell us a different device has been set as the output device.
+- (void) outputDeviceDidChange {
+    BGMOutputDeviceMenuSection* __weak weakSelf = self;
+
+    dispatch_async(dispatch_get_main_queue(), ^{
+        BGM_Utils::LogAndSwallowExceptions(BGMDbgArgs, [&] {
+            [weakSelf populateBGMMenu];
+        });
+    });
+}
+
+- (void) outputDeviceMenuItemSelected:(NSMenuItem*)menuItem {
+    DebugMsg("BGMOutputDeviceMenuSection::outputDeviceMenuItemSelected: '%s' menu item selected",
              [menuItem.title UTF8String]);
     
     // Make sure the menu item is actually for an output device.
@@ -217,10 +339,15 @@ static NSInteger const kOutputDeviceMenuItemTag = 2;
             menuItem.toolTip ?
                 [NSString stringWithFormat:@"%@ (%@)", menuItem.title, menuItem.toolTip] :
                 menuItem.title;
-        
-        // Dispatched because it usually blocks. (Note that we're using QOS_CLASS_USER_INITIATED
-        // rather than QOS_CLASS_USER_INTERACTIVE.)
-        dispatch_async(dispatch_get_global_queue(QOS_CLASS_USER_INITIATED, 0), ^{
+
+        if (changingDevice) {
+            // Add the new output device to the list of preferred devices.
+            [preferredDevices userChangedOutputDeviceTo:newDeviceID];
+        }
+
+        // Dispatched because it usually blocks. (Note that we're using
+        // DISPATCH_QUEUE_PRIORITY_HIGH, which is the second highest priority.)
+        dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_HIGH, 0), ^{
             [self changeToOutputDevice:newDeviceID
                          newDataSource:newDataSourceID
                             deviceName:deviceName];

BGMApp/BGMApp/BGMOutputVolumeMenuItem.h

@@ -0,0 +1,48 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMOutputVolumeMenuItem.h
+//  BGMApp
+//
+//  Copyright © 2017 Kyle Neideck
+//
+
+// Local Includes
+#import "BGMAudioDeviceManager.h"
+
+// System Includes
+#import <Cocoa/Cocoa.h>
+
+
+#pragma clang assume_nonnull begin
+
+@interface BGMOutputVolumeMenuItem : NSMenuItem
+
+// A menu item with a slider for controlling the volume of the output device. Similar to the one in
+// macOS's Volume menu extra.
+//
+// view, slider and deviceLabel are the UI elements from MainMenu.xib.
+- (instancetype) initWithAudioDevices:(BGMAudioDeviceManager*)devices
+                                 view:(NSView*)view
+                               slider:(NSSlider*)slider
+                          deviceLabel:(NSTextField*)label;
+
+- (void) outputDeviceDidChange;
+
+@end
+
+#pragma clang assume_nonnull end
+

BGMApp/BGMApp/BGMOutputVolumeMenuItem.mm

@@ -0,0 +1,307 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMOutputVolumeMenuItem.mm
+//  BGMApp
+//
+//  Copyright © 2017-2019 Kyle Neideck
+//
+
+// Self Include
+#import "BGMOutputVolumeMenuItem.h"
+
+// Local Includes
+#import "BGM_Utils.h"
+#import "BGMAudioDevice.h"
+#import "BGMVolumeChangeListener.h"
+
+// PublicUtility Includes
+#import "CAException.h"
+#import "CAPropertyAddress.h"
+
+// System Includes
+#import <CoreAudio/AudioHardware.h>
+
+
+#pragma clang assume_nonnull begin
+
+const float                    kSliderEpsilon           = 1e-10f;
+const AudioObjectPropertyScope kScope                   = kAudioDevicePropertyScopeOutput;
+NSString* const __nonnull      kGenericOutputDeviceName = @"Output Device";
+
+@implementation BGMOutputVolumeMenuItem {
+    BGMAudioDeviceManager* audioDevices;
+    NSTextField* deviceLabel;
+    NSSlider* volumeSlider;
+    BGMAudioDevice outputDevice;
+    BGMVolumeChangeListener* volumeChangeListener;
+    AudioObjectPropertyListenerBlock updateLabelListenerBlock;
+}
+
+// TODO: Show the output device's icon next to its name.
+// TODO: Should the menu (bgmMenu) hide after you change the output volume slider, like the normal
+//       menu bar volume slider does?
+// TODO: Move the output devices from Preferences to the main menu so they're slightly easier to
+//       access?
+// TODO: Update the screenshot in the README at some point.
+- (instancetype) initWithAudioDevices:(BGMAudioDeviceManager*)devices
+                                 view:(NSView*)view
+                               slider:(NSSlider*)slider
+                          deviceLabel:(NSTextField*)label {
+    if ((self = [super initWithTitle:@"" action:nil keyEquivalent:@""])) {
+        audioDevices = devices;
+        deviceLabel = label;
+        volumeSlider = slider;
+        outputDevice = audioDevices.outputDevice;
+
+        // volumeChangeListener and updateLabelListenerBlock are initialised in the methods called
+        // below.
+
+        // Apply our custom view from MainMenu.xib.
+        self.view = view;
+
+        // Set up the UI components in the view.
+        [self initSlider];
+        [self updateLabelAndToolTip];
+
+        // Register a listener so we can update if the output device's data source changes.
+        [self addOutputDeviceDataSourceListener];
+    }
+
+    return self;
+}
+
+- (void) dealloc {
+    // Remove the audio property listeners.
+    // TODO: This call isn't thread safe. (But currently this dealloc method is only called if
+    //       there's an error.)
+    [self removeOutputDeviceDataSourceListener];
+}
+
+- (void) initSlider {
+    BGMAssert([NSThread isMainThread],
+              "initSlider must be called from the main thread because it calls UI functions.");
+
+    volumeSlider.target = self;
+    volumeSlider.action = @selector(sliderChanged:);
+
+    // Initialise the slider.
+    [self updateVolumeSlider];
+
+    // Register a listener that will update the slider when the user changes the volume or
+    // mutes/unmutes their audio.
+    BGMOutputVolumeMenuItem* __weak weakSelf = self;
+    volumeChangeListener = new BGMVolumeChangeListener(audioDevices.bgmDevice, [=] {
+        [weakSelf updateVolumeSlider];
+    });
+}
+
+// Updates the value of the output volume slider. Should only be called on the main thread because
+// it calls UI functions.
+- (void) updateVolumeSlider {
+    BGMAssert([[NSThread currentThread] isMainThread], "updateVolumeSlider on non-main thread.");
+
+    BGMAudioDevice bgmDevice = [audioDevices bgmDevice];
+
+    // BGMDevice should never return an error for these calls, so we just swallow any exceptions and
+    // give up. (That said, we do check mute last so that, if it did throw, it wouldn't affect the
+    // more important calls.)
+    BGMLogAndSwallowExceptions("BGMOutputVolumeMenuItem::updateVolumeSlider", ([&] {
+        BOOL hasVolume = bgmDevice.HasSettableMasterVolume(kScope);
+
+        // If the device doesn't have a master volume control, we disable the slider and set it to
+        // full (or to zero, if muted).
+        volumeSlider.enabled = hasVolume;
+
+        if (hasVolume) {
+            // Set the slider to the current output volume. The slider values and volume values are
+            // both from 0 to 1, so we can use the volume as is.
+            volumeSlider.doubleValue =
+                bgmDevice.GetVolumeControlScalarValue(kScope, kMasterChannel);
+        } else {
+            volumeSlider.doubleValue = 1.0;
+        }
+
+        // Set the slider to zero if the device is muted.
+        if (bgmDevice.HasSettableMasterMute(kScope) &&
+            bgmDevice.GetMuteControlValue(kScope, kMasterChannel)) {
+            volumeSlider.doubleValue = 0.0;
+        }
+    }));
+}
+
+- (void) addOutputDeviceDataSourceListener {
+    // Create the block that updates deviceLabel when the output device's data source changes, e.g.
+    // from Internal Speakers to Headphones.
+    if (!updateLabelListenerBlock) {
+        BGMOutputVolumeMenuItem* __weak weakSelf = self;
+
+        updateLabelListenerBlock =
+            ^(UInt32 inNumberAddresses, const AudioObjectPropertyAddress* inAddresses) {
+                // The docs for AudioObjectPropertyListenerBlock say inAddresses will always contain
+                // at least one property the block is listening to, so there's no need to check it.
+                #pragma unused (inNumberAddresses, inAddresses)
+                [weakSelf updateLabelAndToolTip];
+            };
+    }
+
+    // Register the listener.
+    //
+    // Instead of swallowing exceptions, we could try again later, but I doubt it would be worth the
+    // effort. And the documentation doesn't actually explain what could cause this to fail.
+    BGMLogAndSwallowExceptions("BGMOutputVolumeMenuItem::addOutputDeviceDataSourceListener", ([&] {
+        outputDevice.AddPropertyListenerBlock(
+            CAPropertyAddress(kAudioDevicePropertyDataSource, kScope),
+            dispatch_get_main_queue(),
+            updateLabelListenerBlock);
+    }));
+}
+
+- (void) removeOutputDeviceDataSourceListener {
+    BGMLogAndSwallowExceptions("BGMOutputVolumeMenuItem::removeOutputDeviceDataSourceListener",
+                               ([&] {
+        // Technically, there's a race here in that the device could be removed after we check it
+        // exists, but before we try to remove the listener. We could check the error code of the
+        // exception and not log an error message if the code is kAudioHardwareBadObjectError or
+        // kAudioHardwareBadDeviceError, but it probably wouldn't be worth the effort.
+        //
+        // So for now the main reason for checking the device exists here is that it makes debug
+        // builds much less likely to crash here. (They crash/break when an error is logged so it
+        // will be noticed.)
+        if (CAHALAudioObject::ObjectExists(outputDevice)) {
+            outputDevice.RemovePropertyListenerBlock(
+                CAPropertyAddress(kAudioDevicePropertyDataSource, kScope),
+                dispatch_get_main_queue(),
+                updateLabelListenerBlock);
+        }
+    }));
+}
+
+- (void) outputDeviceDidChange {
+    dispatch_async(dispatch_get_main_queue(), ^{
+        // Remove the data source listener from the previous output device.
+        [self removeOutputDeviceDataSourceListener];
+
+        // Add it to the new output device.
+        outputDevice = audioDevices.outputDevice;
+        [self addOutputDeviceDataSourceListener];
+
+        // Update the label to use the name of the new output device.
+        [self updateLabelAndToolTip];
+
+        // Set the slider to the volume of the new device.
+        [self updateVolumeSlider];
+    });
+}
+
+// Sets the label to the output device's name or, if it has one, its current datasource. If it has a
+// datasource, the device's name is set as this menu item's tooltip. Falls back to a generic name if
+// the device returns an error when queried.
+- (void) updateLabelAndToolTip {
+    if (outputDevice.GetObjectID() == kAudioObjectUnknown) {
+        DebugMsg("BGMOutputVolumeMenuItem::updateLabelAndToolTip: Output device unknown. Using the "
+                 "generic label.");
+        self.toolTip = nil;
+        deviceLabel.stringValue = kGenericOutputDeviceName;
+    } else {
+        BOOL didSetLabel = NO;
+
+        DebugMsg("BGMOutputVolumeMenuItem::updateLabelAndToolTip: Output device: %u",
+                 outputDevice.GetObjectID());
+
+        try {
+            if (outputDevice.HasDataSourceControl(kScope, kMasterChannel)) {
+                DebugMsg("BGMOutputVolumeMenuItem::updateLabelAndToolTip: Getting data source ID");
+                // The device has datasources, so use the current datasource's name like macOS does.
+                UInt32 dataSourceID = outputDevice.GetCurrentDataSourceID(kScope, kMasterChannel);
+
+                DebugMsg("BGMOutputVolumeMenuItem::updateLabelAndToolTip: "
+                         "Getting name for data source %u",
+                         dataSourceID);
+                deviceLabel.stringValue =
+                    (__bridge_transfer NSString*)outputDevice.CopyDataSourceNameForID(
+                        kScope, kMasterChannel, dataSourceID);
+
+                // So we know not to change the text if setting the tooltip fails.
+                didSetLabel = YES;
+
+                DebugMsg("BGMOutputVolumeMenuItem::updateLabelAndToolTip: Getting device name");
+                // Set the tooltip of the menu item (the container) rather than the label because
+                // menu items' tooltips will still appear when a different app is focused and, as
+                // far as I know, BGMApp should never be the foreground app.
+                self.toolTip = (__bridge_transfer NSString*)outputDevice.CopyName();
+            } else {
+                DebugMsg("BGMOutputVolumeMenuItem::updateLabelAndToolTip: Getting device name");
+                deviceLabel.stringValue = (__bridge_transfer NSString*)outputDevice.CopyName();
+                self.toolTip = nil;
+            }
+        } catch (const CAException& e) {
+            BGMLogException(e);
+
+            // The device returned an error, so set the label to a generic device name, since we
+            // don't want to leave it set to the previous device's name.
+            self.toolTip = nil;
+
+            if (!didSetLabel) {
+                deviceLabel.stringValue = kGenericOutputDeviceName;
+            }
+        }
+    }
+
+    DebugMsg("BGMOutputVolumeMenuItem::updateLabelAndToolTip: Label: '%s' Tooltip: '%s'",
+             deviceLabel.stringValue.UTF8String,
+             self.toolTip.UTF8String);
+
+    // Take the label out of the accessibility hierarchy, which also moves the slider up a level.
+#if MAC_OS_X_VERSION_MAX_ALLOWED >= 101000  // MAC_OS_X_VERSION_10_10
+    if ([deviceLabel.cell respondsToSelector:@selector(setAccessibilityElement:)]) {
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wpartial-availability"
+        deviceLabel.cell.accessibilityElement = NO;
+#pragma clang diagnostic pop
+    }
+#endif
+}
+
+// Called when the user slides the slider.
+- (IBAction) sliderChanged:(NSSlider*)sender {
+    float newValue = sender.floatValue;
+
+    DebugMsg("BGMOutputVolumeMenuItem::sliderChanged: New value: %f", newValue);
+
+    // Update BGMDevice's volume to the new value selected by the user.
+    try {
+        // The slider values and volume values are both from 0.0f to 1.0f, so we can use the slider
+        // value as is.
+        audioDevices.bgmDevice.SetVolumeControlScalarValue(kScope, kMasterChannel, newValue);
+
+        // Mute BGMDevice if they set the slider to zero, and unmute it for non-zero. Muting makes
+        // sure the audio doesn't play very quietly instead being completely silent. This matches
+        // the behaviour of the Volume menu built-in to macOS.
+        if (audioDevices.bgmDevice.HasMuteControl(kScope, kMasterChannel)) {
+            audioDevices.bgmDevice.SetMuteControlValue(kScope,
+                                                       kMasterChannel,
+                                                       (newValue < kSliderEpsilon));
+        }
+    } catch (const CAException& e) {
+        NSLog(@"BGMOutputVolumeMenuItem::sliderChanged: Failed to set volume (%d)", e.GetError());
+    }
+}
+
+@end
+
+#pragma clang assume_nonnull end
+

BGMApp/BGMApp/BGMPlayThrough.h

@@ -17,7 +17,7 @@
 //  BGMPlayThrough.h
 //  BGMApp
 //
-//  Copyright © 2016 Kyle Neideck
+//  Copyright © 2016, 2017, 2020 Kyle Neideck
 //
 //  Reads audio from an input device and immediately writes it to an output device. We currently use this class with the input
 //  device always set to BGMDevice and the output device set to the one selected in the preferences menu.
@@ -39,13 +39,19 @@
 #ifndef BGMApp__BGMPlayThrough
 #define BGMApp__BGMPlayThrough
 
+// Local Includes
+#include "BGMAudioDevice.h"
+#include "BGMPlayThroughRTLogger.h"
+
 // PublicUtility Includes
-#include "CARingBuffer.h"
-#include "CAHALAudioDevice.h"
 #include "CAMutex.h"
+#include "CARingBuffer.h"
+#include "BGMThreadSafetyAnalysis.h"
 
 // STL Includes
 #include <atomic>
+#include <algorithm>
+#include <memory>
 
 // System Includes
 #include <mach/semaphore.h>
@@ -55,33 +61,38 @@
 
 class BGMPlayThrough
 {
+    
+public:
+    // Error codes
+    static const OSStatus kDeviceNotStarting = 100;
 
 public:
-                        BGMPlayThrough(CAHALAudioDevice inInputDevice, CAHALAudioDevice inOutputDevice);
+                        BGMPlayThrough(BGMAudioDevice inInputDevice, BGMAudioDevice inOutputDevice);
                         ~BGMPlayThrough();
                         // Disallow copying
                         BGMPlayThrough(const BGMPlayThrough&) = delete;
                         BGMPlayThrough& operator=(const BGMPlayThrough&) = delete;
-                        // Move constructor/assignment
-                        BGMPlayThrough(BGMPlayThrough&& inPlayThrough) { Swap(inPlayThrough); }
-                        BGMPlayThrough& operator=(BGMPlayThrough&& inPlayThrough) { Swap(inPlayThrough); return *this; }
 
 #ifdef __OBJC__
-                        // Only intended as a convenience for Objective-C instance vars
+                        // Only intended as a convenience (hack) for Objective-C instance vars. Call
+                        // SetDevices to initialise the instance before using it.
                         BGMPlayThrough() { }
 #endif
     
 private:
-    void                Swap(BGMPlayThrough& inPlayThrough);
-    
+    /*! @throws CAException */
+    void                Init(BGMAudioDevice inInputDevice, BGMAudioDevice inOutputDevice)
+                            REQUIRES(mStateMutex);
+
+public:
     /*! @throws CAException */
     void                Activate();
     /*! @throws CAException */
     void                Deactivate();
-    
-    void                AllocateBuffer();
-    
-    static bool         IsBGMDevice(CAHALAudioDevice inDevice);
+
+private:
+    void                AllocateBuffer() REQUIRES(mStateMutex);
+    void                DeallocateBuffer();
 
     /*! @throws CAException */
     void                CreateIOProcIDs();
@@ -91,9 +102,16 @@ private:
         @return True if both IOProcs are stopped.
         @nonthreadsafe
      */
-    bool                CheckIOProcsAreStopped() const noexcept; // TODO: REQUIRES(mStateMutex);
+    bool                CheckIOProcsAreStopped() const noexcept REQUIRES(mStateMutex);
 	
 public:
+    /*!
+     Pass null for either param to only change one of the devices.
+     @throws CAException
+     */
+    void                SetDevices(const BGMAudioDevice* __nullable inInputDevice,
+                                   const BGMAudioDevice* __nullable inOutputDevice);
+    
     /*! @throws CAException */
     void                Start();
     
@@ -102,7 +120,8 @@ public:
     OSStatus            WaitForOutputDeviceToStart() noexcept;
     
 private:
-    void                ReleaseThreadsWaitingForOutputToStart() const;
+    /*! Real-time safe. */
+    void                ReleaseThreadsWaitingForOutputToStart();
     
 public:
     OSStatus            Stop();
@@ -117,7 +136,7 @@ private:
     static void         HandleBGMDeviceIsRunning(BGMPlayThrough* refCon);
     static void         HandleBGMDeviceIsRunningSomewhereOtherThanBGMApp(BGMPlayThrough* refCon);
     
-    static bool         IsRunningSomewhereOtherThanBGMApp(const CAHALAudioDevice& inBGMDevice);
+    static bool         IsRunningSomewhereOtherThanBGMApp(const BGMAudioDevice& inBGMDevice);
 
     static OSStatus     InputDeviceIOProc(AudioObjectID           inDevice,
                                           const AudioTimeStamp*   inNow,
@@ -133,50 +152,71 @@ private:
                                            AudioBufferList*        outOutputData,
                                            const AudioTimeStamp*   inOutputTime,
                                            void* __nullable        inClientData);
-    
+
+    /*! Fills the given ABL with zeroes to make it silent. */
+    static inline void  FillWithSilence(AudioBufferList* ioBuffer);
+
     // The state of an IOProc. Used by the IOProc to tell other threads when it's finished starting. Used by other
     // threads to tell the IOProc to stop itself. (Probably used for other things as well.)
     enum class          IOState
                         {
                             Stopped, Starting, Running, Stopping
                         };
+    
     // The IOProcs call this to update their IOState member. Also stops the IOProc if its state has been set to Stopping.
     // Returns true if it changes the state.
-    static bool         UpdateIOProcState(const char* __nullable callerName,
+    static bool         UpdateIOProcState(const char* inCallerName,
+                                          BGMPlayThroughRTLogger& inRTLogger,
                                           std::atomic<IOState>& inState,
                                           AudioDeviceIOProcID __nullable inIOProcID,
-                                          CAHALAudioDevice& inDevice,
+                                          BGMAudioDevice& inDevice,
                                           IOState& outNewState);
     
-    static void         HandleRingBufferError(CARingBufferError err,
-                                              const char* methodName,
-                                              const char* callReturningErr);
-    
 private:
-    CARingBuffer        mBuffer;
+    std::unique_ptr<CARingBuffer>    mBuffer PT_GUARDED_BY(mBufferInputMutex)
+                                        PT_GUARDED_BY(mBufferOutputMutex) { nullptr };
     
-    AudioDeviceIOProcID __nullable mInputDeviceIOProcID;
-    AudioDeviceIOProcID __nullable mOutputDeviceIOProcID;
-    
-    CAHALAudioDevice    mInputDevice { kAudioDeviceUnknown };
-    CAHALAudioDevice    mOutputDevice { kAudioDeviceUnknown };
-    
-    CAMutex             mStateMutex { "Playthrough state" };
+    AudioDeviceIOProcID __nullable mInputDeviceIOProcID { nullptr };
+    AudioDeviceIOProcID __nullable mOutputDeviceIOProcID { nullptr };
     
+    BGMAudioDevice      mInputDevice { kAudioObjectUnknown };
+    BGMAudioDevice      mOutputDevice { kAudioObjectUnknown };
+
+    // mStateMutex is the general purpose mutex. mBufferInputMutex and mBufferOutputMutex are
+    // just used to make sure mBuffer, the ring buffer, is allocated when the IOProcs access it. See
+    // the comments in the IOProcs for details.
+    //
+    // If a thread might lock more than one of these mutexes, it *must* take them in this order:
+    //     1. mStateMutex
+    //     2. mBufferInputMutex
+    //     3. mBufferOutputMutex
+    //
+    // The ACQUIRED_BEFORE annotations don't do anything yet. From clang's docs: "ACQUIRED_BEFORE(…)
+    // and ACQUIRED_AFTER(…) are currently unimplemented. To be fixed in a future update." After
+    // they've fixed that, the compiler will enforce the ordering statically.
+    //
+    // TODO: We can't use std::shared_lock because we're still on C++11, but we could use std::lock
+    //       to help ensure the locks are always taken in the right order.
+    // TODO: It would be better to have a separate class for the buffer and its mutexes.
+    CAMutex             mStateMutex ACQUIRED_BEFORE(mBufferInputMutex)
+                            ACQUIRED_BEFORE(mBufferOutputMutex) { "Playthrough state" };
+    CAMutex             mBufferInputMutex ACQUIRED_BEFORE(mBufferOutputMutex)
+                            { "Playthrough ring buffer input" };
+    CAMutex             mBufferOutputMutex { "Playthrough ring buffer output" };
+
     // Signalled when the output IOProc runs. We use it to tell BGMDriver when the output device is ready to receive audio data.
     semaphore_t         mOutputDeviceIOProcSemaphore { SEMAPHORE_NULL };
     
     bool                mActive = false;
-
     bool                mPlayingThrough = false;
 
-    UInt64              mLastNotifiedIOStoppedOnBGMDevice;
+    UInt64              mLastNotifiedIOStoppedOnBGMDevice { 0 };
 
     std::atomic<IOState>    mInputDeviceIOProcState { IOState::Stopped };
     std::atomic<IOState>    mOutputDeviceIOProcState { IOState::Stopped };
     
     // For debug logging.
-    UInt64              mToldOutputDeviceToStartAt;
+    UInt64              mToldOutputDeviceToStartAt { 0 };
 
     // IOProc vars. (Should only be used inside IOProcs.)
     
@@ -186,8 +226,10 @@ private:
     Float64             mLastOutputSampleTime = -1;
     
     // Subtract this from the output time to get the input time.
-    Float64             mInToOutSampleOffset;
-    
+    Float64             mInToOutSampleOffset { 0.0 };
+
+    BGMPlayThroughRTLogger mRTLogger;
+
 };
 
 #pragma clang assume_nonnull end

BGMApp/BGMApp/BGMPlayThroughRTLogger.cpp

@@ -0,0 +1,521 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMPlayThroughRTLogger.cpp
+//  BGMApp
+//
+//  Copyright © 2020 Kyle Neideck
+//
+
+// Self Include
+#include "BGMPlayThroughRTLogger.h"
+
+// Local Includes
+#include "BGM_Utils.h"
+
+// PublicUtility Includes
+#include "CADebugMacros.h"
+
+// STL Includes
+#include <atomic>
+
+// System Includes
+#include <CoreAudio/CoreAudio.h>
+#include <mach/mach_init.h>
+#include <mach/task.h>
+#include <unistd.h>
+
+
+#pragma clang assume_nonnull begin
+
+// Track the number of messages logged when built for the unit tests.
+#if BGM_UnitTest
+    #define LogSync_Debug(inFormat, ...) do { \
+                mNumDebugMessagesLogged++; \
+                DebugMsg(inFormat, ## __VA_ARGS__); \
+            } while (0)
+#else
+    #define LogSync_Debug(inFormat, ...) DebugMsg(inFormat, ## __VA_ARGS__)
+#endif
+
+#pragma mark Construction/Destruction
+
+BGMPlayThroughRTLogger::BGMPlayThroughRTLogger()
+{
+    // Create the semaphore we use to wake up the logging thread when it has messages to log.
+    mWakeUpLoggingThreadSemaphore = CreateSemaphore();
+
+    // Create the logging thread last because it starts immediately and expects the other member
+    // variables to be initialised.
+    mLoggingThread = std::thread(&BGMPlayThroughRTLogger::LoggingThreadEntry, this);
+}
+
+// static
+semaphore_t BGMPlayThroughRTLogger::CreateSemaphore()
+{
+    // TODO: Make a BGMMachSemaphore class to reduce some of this repetitive semaphore code.
+
+    // Create the semaphore.
+    semaphore_t semaphore;
+    kern_return_t error =
+            semaphore_create(mach_task_self(), &semaphore, SYNC_POLICY_FIFO, 0);
+
+    // Check the error code.
+    BGM_Utils::ThrowIfMachError("BGMPlayThroughRTLogger::CreateSemaphore",
+                                "semaphore_create",
+                                error);
+    ThrowIf(semaphore == SEMAPHORE_NULL,
+            CAException(kAudioHardwareUnspecifiedError),
+            "BGMPlayThroughRTLogger::CreateSemaphore: Failed to create semaphore");
+
+    return semaphore;
+}
+
+BGMPlayThroughRTLogger::~BGMPlayThroughRTLogger()
+{
+    // Stop the logging thread.
+    mLoggingThreadShouldExit = true;
+    kern_return_t error = semaphore_signal(mWakeUpLoggingThreadSemaphore);
+
+    BGM_Utils::LogIfMachError("BGMPlayThroughRTLogger::~BGMPlayThroughRTLogger",
+                              "semaphore_signal",
+                              error);
+
+    if(error == KERN_SUCCESS)
+    {
+        // Wait for it to stop.
+        mLoggingThread.join();
+
+        // Destroy the semaphore.
+        error = semaphore_destroy(mach_task_self(), mWakeUpLoggingThreadSemaphore);
+        BGM_Utils::LogIfMachError("BGMPlayThroughRTLogger::~BGMPlayThroughRTLogger",
+                                  "semaphore_destroy",
+                                  error);
+    }
+    else
+    {
+        // If we couldn't tell it to wake up, it's not safe to wait for it to stop or to destroy the
+        // semaphore. We have to detach it so its destructor doesn't cause a crash.
+        mLoggingThread.detach();
+    }
+}
+
+#pragma mark Log Messages
+
+void BGMPlayThroughRTLogger::LogReleasingWaitingThreads()
+{
+    if(!BGMDebugLoggingIsEnabled())
+    {
+        return;
+    }
+
+    if(!mLogReleasingWaitingThreadsMsg.is_lock_free())
+    {
+        // Modifying mLogReleasingWaitingThreadsMsg might cause the thread to lock a mutex that
+        // isn't safe to lock on a realtime thread, so just give up.
+        return;
+    }
+
+    // Set the flag that tells the logging thread to log the message.
+    mLogReleasingWaitingThreadsMsg = true;
+
+    // Wake the logging thread so it can log the message.
+    WakeLoggingThread();
+}
+
+void BGMPlayThroughRTLogger::LogIfMachError_ReleaseWaitingThreadsSignal(mach_error_t inError)
+{
+    if(inError == KERN_SUCCESS)
+    {
+        // No error.
+        return;
+    }
+
+    if(!mReleaseWaitingThreadsSignalError.is_lock_free())
+    {
+        // Modifying mReleaseWaitingThreadsSignalError might cause the thread to lock a mutex that
+        // isn't safe to lock on a realtime thread, so just give up.
+        return;
+    }
+
+    mReleaseWaitingThreadsSignalError = inError;
+    WakeLoggingThread();
+}
+
+void BGMPlayThroughRTLogger::LogIfDroppedFrames(Float64 inFirstInputSampleTime,
+                                                Float64 inLastInputSampleTime)
+{
+    if(inFirstInputSampleTime == inLastInputSampleTime || !BGMDebugLoggingIsEnabled())
+    {
+        // Either we didn't drop any initial frames or we don't need to log a message about it.
+        return;
+    }
+
+    LogAsync(mDroppedFrames, [&]()
+    {
+        // Store the data to include in the log message.
+        mDroppedFrames.firstInputSampleTime = inFirstInputSampleTime;
+        mDroppedFrames.lastInputSampleTime = inLastInputSampleTime;
+    });
+}
+
+void BGMPlayThroughRTLogger::LogNoSamplesReady(CARingBuffer::SampleTime inLastInputSampleTime,
+                                               CARingBuffer::SampleTime inReadHeadSampleTime,
+                                               Float64 inInToOutSampleOffset)
+{
+    if(!BGMDebugLoggingIsEnabled())
+    {
+        return;
+    }
+
+    LogAsync(mNoSamplesReady, [&]()
+    {
+        // Store the data to include in the log message.
+        mNoSamplesReady.lastInputSampleTime = inLastInputSampleTime;
+        mNoSamplesReady.readHeadSampleTime = inReadHeadSampleTime;
+        mNoSamplesReady.inToOutSampleOffset = inInToOutSampleOffset;
+    });
+}
+
+void BGMPlayThroughRTLogger::LogExceptionStoppingIOProc(const char* inCallerName,
+                                                        OSStatus inError,
+                                                        bool inErrorKnown)
+{
+    LogAsync(mExceptionStoppingIOProc, [&]()
+    {
+        // Store the data to include in the log message.
+        mExceptionStoppingIOProc.callerName = inCallerName;
+        mExceptionStoppingIOProc.error = inError;
+        mExceptionStoppingIOProc.errorKnown = inErrorKnown;
+    });
+}
+
+void BGMPlayThroughRTLogger::LogUnexpectedIOStateAfterStopping(const char* inCallerName,
+                                                               int inIOState)
+{
+    LogAsync(mUnexpectedIOStateAfterStopping, [&]()
+    {
+        // Store the data to include in the log message.
+        mUnexpectedIOStateAfterStopping.callerName = inCallerName;
+        mUnexpectedIOStateAfterStopping.ioState = inIOState;
+    });
+}
+
+void BGMPlayThroughRTLogger::LogRingBufferUnavailable(const char* inCallerName, bool inGotLock)
+{
+    LogAsync(mRingBufferUnavailable, [&]()
+    {
+        // Store the data to include in the log message.
+        mRingBufferUnavailable.callerName = inCallerName;
+        mRingBufferUnavailable.gotLock = inGotLock;
+    });
+}
+
+void BGMPlayThroughRTLogger::LogIfRingBufferError(CARingBufferError inError,
+                                                  std::atomic<CARingBufferError>& outError)
+{
+    if(inError == kCARingBufferError_OK)
+    {
+        // No error.
+        return;
+    }
+
+    if(!outError.is_lock_free())
+    {
+        // Modifying outError might cause the thread to lock a mutex that isn't safe to lock on
+        // a realtime thread, so just give up.
+        return;
+    }
+
+    // Store the error.
+    outError = inError;
+
+    // Wake the logging thread so it can log the error.
+    WakeLoggingThread();
+}
+
+template <typename T, typename F>
+void BGMPlayThroughRTLogger::LogAsync(T& inMessageData, F&& inStoreMessageData)
+{
+    if(!inMessageData.shouldLogMessage.is_lock_free())
+    {
+        // Modifying shouldLogMessage might cause the thread to lock a mutex that isn't safe to
+        // lock on a realtime thread, so just give up.
+        return;
+    }
+
+    if(inMessageData.shouldLogMessage)
+    {
+        // The logging thread could be reading inMessageData.
+        return;
+    }
+
+    // Store the data to include in the log message.
+    //
+    // std::forward lets the compiler treat inStoreMessageData as an rvalue if the caller gave it as
+    // an rvalue. No idea if that actually does anything.
+    std::forward<F>(inStoreMessageData)();
+
+    // shouldLogMessage is a std::atomic, so this store also makes sure that the non-atomic stores
+    // in inStoreMessageData will be visible to the logger thread (since the default memory order is
+    // memory_order_seq_cst).
+    inMessageData.shouldLogMessage = true;
+
+    WakeLoggingThread();
+}
+
+void BGMPlayThroughRTLogger::LogSync_Warning(const char* inFormat, ...)
+{
+    va_list args;
+    va_start(args, inFormat);
+
+#if BGM_UnitTest
+    mNumWarningMessagesLogged++;
+#endif
+
+    vLogWarning(inFormat, args);
+
+    va_end(args);
+}
+
+void BGMPlayThroughRTLogger::LogSync_Error(const char* inFormat, ...)
+{
+    va_list args;
+    va_start(args, inFormat);
+
+#if BGM_UnitTest
+    mNumErrorMessagesLogged++;
+
+    if(!mContinueOnErrorLogged)
+    {
+        vLogError(inFormat, args);
+    }
+#else
+    vLogError(inFormat, args);
+#endif
+
+    va_end(args);
+}
+
+#pragma mark Logging Thread
+
+void BGMPlayThroughRTLogger::WakeLoggingThread()
+{
+    kern_return_t error = semaphore_signal(mWakeUpLoggingThreadSemaphore);
+
+    BGMAssert(error == KERN_SUCCESS, "semaphore_signal (%d)", error);
+
+    // We can't do anything useful with the error in release builds. At least, not easily.
+    (void)error;
+}
+
+void BGMPlayThroughRTLogger::LogMessages()
+{
+    // Log the messages/errors from the realtime threads (if any).
+    LogSync_ReleasingWaitingThreads();
+    LogSync_ReleaseWaitingThreadsSignalError();
+    LogSync_DroppedFrames();
+    LogSync_NoSamplesReady();
+    LogSync_ExceptionStoppingIOProc();
+    LogSync_UnexpectedIOStateAfterStopping();
+    LogSync_RingBufferUnavailable();
+    LogSync_RingBufferError(mRingBufferStoreError, "InputDeviceIOProc");
+    LogSync_RingBufferError(mRingBufferFetchError, "OutputDeviceIOProc");
+}
+
+void BGMPlayThroughRTLogger::LogSync_ReleasingWaitingThreads()
+{
+    if(mLogReleasingWaitingThreadsMsg)
+    {
+        LogSync_Debug("BGMPlayThrough::ReleaseThreadsWaitingForOutputToStart: "
+                      "Releasing waiting threads");
+        // Reset it.
+        mLogReleasingWaitingThreadsMsg = false;
+    }
+}
+
+void BGMPlayThroughRTLogger::LogSync_ReleaseWaitingThreadsSignalError()
+{
+    if(mReleaseWaitingThreadsSignalError != KERN_SUCCESS)
+    {
+        BGM_Utils::LogIfMachError("BGMPlayThrough::ReleaseThreadsWaitingForOutputToStart",
+                                  "semaphore_signal_all",
+                                  mReleaseWaitingThreadsSignalError);
+        // Reset it.
+        mReleaseWaitingThreadsSignalError = KERN_SUCCESS;
+    }
+}
+
+void BGMPlayThroughRTLogger::LogSync_DroppedFrames()
+{
+    if(mDroppedFrames.shouldLogMessage)
+    {
+        LogSync_Debug("BGMPlayThrough::OutputDeviceIOProc: "
+                      "Dropped %f frames before output started. %s%f %s%f",
+                      (mDroppedFrames.lastInputSampleTime - mDroppedFrames.firstInputSampleTime),
+                      "mFirstInputSampleTime=",
+                      mDroppedFrames.firstInputSampleTime,
+                      "mLastInputSampleTime=",
+                      mDroppedFrames.lastInputSampleTime);
+        mDroppedFrames.shouldLogMessage = false;
+    }
+}
+
+void BGMPlayThroughRTLogger::LogSync_NoSamplesReady()
+{
+    if(mNoSamplesReady.shouldLogMessage)
+    {
+        LogSync_Debug("BGMPlayThrough::OutputDeviceIOProc: "
+                      "No input samples ready at output sample time. %s%lld %s%lld %s%f",
+                      "lastInputSampleTime=", mNoSamplesReady.lastInputSampleTime,
+                      "readHeadSampleTime=", mNoSamplesReady.readHeadSampleTime,
+                      "mInToOutSampleOffset=", mNoSamplesReady.inToOutSampleOffset);
+        mNoSamplesReady.shouldLogMessage = false;
+    }
+}
+
+void BGMPlayThroughRTLogger::LogSync_ExceptionStoppingIOProc()
+{
+    if(mExceptionStoppingIOProc.shouldLogMessage)
+    {
+        const char error4CC[5] = CA4CCToCString(mExceptionStoppingIOProc.error);
+        LogSync_Error("BGMPlayThrough::UpdateIOProcState: "
+                      "Exception while stopping IOProc %s: %s (%d)",
+                      mExceptionStoppingIOProc.callerName,
+                      mExceptionStoppingIOProc.errorKnown ? error4CC : "unknown",
+                      mExceptionStoppingIOProc.error);
+        mExceptionStoppingIOProc.shouldLogMessage = false;
+    }
+}
+
+void BGMPlayThroughRTLogger::LogSync_UnexpectedIOStateAfterStopping()
+{
+    if(mUnexpectedIOStateAfterStopping.shouldLogMessage)
+    {
+        LogSync_Warning("BGMPlayThrough::UpdateIOProcState: "
+                        "%s IO state changed since last read. state = %d",
+                        mUnexpectedIOStateAfterStopping.callerName,
+                        mUnexpectedIOStateAfterStopping.ioState);
+        mUnexpectedIOStateAfterStopping.shouldLogMessage = false;
+    }
+}
+
+void BGMPlayThroughRTLogger::LogSync_RingBufferUnavailable()
+{
+    if(mRingBufferUnavailable.shouldLogMessage)
+    {
+        LogSync_Warning("BGMPlayThrough::%s: Ring buffer unavailable. %s",
+                        mRingBufferUnavailable.callerName,
+                        mRingBufferUnavailable.gotLock ?
+                            "No buffer currently allocated." :
+                            "Buffer locked for allocation/deallocation by another thread.");
+        mRingBufferUnavailable.shouldLogMessage = false;
+    }
+}
+
+void BGMPlayThroughRTLogger::LogSync_RingBufferError(
+        std::atomic<CARingBufferError>& ioRingBufferError,
+        const char* inMethodName)
+{
+    CARingBufferError error = ioRingBufferError;
+
+    switch(error)
+    {
+        case kCARingBufferError_OK:
+            // No error.
+            return;
+        case kCARingBufferError_CPUOverload:
+            // kCARingBufferError_CPUOverload might not be our fault, so just log a warning.
+            LogSync_Warning("BGMPlayThrough::%s: Ring buffer error: "
+                            "kCARingBufferError_CPUOverload (%d)",
+                            inMethodName,
+                            error);
+            break;
+        default:
+            // Other types of CARingBuffer errors should never occur. This will crash debug builds.
+            LogSync_Error("BGMPlayThrough::%s: Ring buffer error: %s (%d)",
+                          inMethodName,
+                          (error == kCARingBufferError_TooMuch ?
+                                  "kCARingBufferError_TooMuch" :
+                                  "unknown error"),
+                          error);
+            break;
+    };
+
+    // Reset it.
+    ioRingBufferError = kCARingBufferError_OK;
+}
+
+// static
+void* __nullable BGMPlayThroughRTLogger::LoggingThreadEntry(BGMPlayThroughRTLogger* inRefCon)
+{
+    DebugMsg("BGMPlayThroughRTLogger::IOProcLoggingThreadEntry: "
+             "Starting the IOProc logging thread");
+
+    while(!inRefCon->mLoggingThreadShouldExit)
+    {
+        // Log the messages, if there are any to log.
+        inRefCon->LogMessages();
+
+        // Wait until woken up.
+        kern_return_t error = semaphore_wait(inRefCon->mWakeUpLoggingThreadSemaphore);
+        BGM_Utils::LogIfMachError("BGMPlayThroughRTLogger::IOProcLoggingThreadEntry",
+                                  "semaphore_wait",
+                                  error);
+    }
+
+    DebugMsg("BGMPlayThroughRTLogger::IOProcLoggingThreadEntry: IOProc logging thread exiting");
+
+    return nullptr;
+}
+
+#if BGM_UnitTest
+
+#pragma mark Test Helpers
+
+bool BGMPlayThroughRTLogger::WaitUntilLoggerThreadIdle()
+{
+    int msWaited = 0;
+
+    while(mLogReleasingWaitingThreadsMsg ||
+            mReleaseWaitingThreadsSignalError != KERN_SUCCESS ||
+            mDroppedFrames.shouldLogMessage ||
+            mNoSamplesReady.shouldLogMessage ||
+            mUnexpectedIOStateAfterStopping.shouldLogMessage ||
+            mRingBufferUnavailable.shouldLogMessage ||
+            mExceptionStoppingIOProc.shouldLogMessage ||
+            mRingBufferStoreError != kCARingBufferError_OK ||
+            mRingBufferFetchError != kCARingBufferError_OK)
+    {
+        // Poll until the logger thread has nothing left to log. (Ideally we'd use a semaphore
+        // instead of polling, but it isn't worth the effort at this point.)
+        usleep(10 * 1000);
+        msWaited += 10;
+
+        // Time out after 5 seconds.
+        if(msWaited > 5000)
+        {
+            return false;
+        }
+    }
+
+    return true;
+}
+
+#endif /* BGM_UnitTest */
+
+#pragma clang assume_nonnull end
+

BGMApp/BGMApp/BGMPlayThroughRTLogger.h

@@ -0,0 +1,227 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMPlayThroughRTLogger.h
+//  BGMApp
+//
+//  Copyright © 2020 Kyle Neideck
+//
+//  A real-time safe logger for BGMPlayThrough. The messages are logged asynchronously by a
+//  non-realtime thread.
+//
+//  For the sake of simplicity, this class is very closely coupled with BGMPlayThrough and its
+//  methods make assumptions about where they will be called. Also, if the same logging method is
+//  called multiple times before the logging thread next checks for messages, it will only log the
+//  message for one of those calls and ignore the others.
+//
+//  This class's methods are real-time safe in that they return in a bounded amount of time and we
+//  think they're probably fast enough that the callers won't miss their deadlines, but we don't try
+//  to guarantee it. Some of them should only be called in unusual cases where it's worth increasing
+//  the risk of a thread missing its deadline.
+//
+
+#ifndef BGMApp__BGMPlayThroughRTLogger
+#define BGMApp__BGMPlayThroughRTLogger
+
+// PublicUtility Includes
+#include "CARingBuffer.h"
+
+// STL Includes
+#include <thread>
+
+// System Includes
+#include <mach/error.h>
+#include <mach/semaphore.h>
+
+
+#pragma clang assume_nonnull begin
+
+class BGMPlayThroughRTLogger
+{
+
+#pragma mark Construction/Destruction
+
+public:
+                            BGMPlayThroughRTLogger();
+                            ~BGMPlayThroughRTLogger();
+                            BGMPlayThroughRTLogger(const BGMPlayThroughRTLogger&) = delete;
+                            BGMPlayThroughRTLogger& operator=(
+                                    const BGMPlayThroughRTLogger&) = delete;
+private:
+    static semaphore_t      CreateSemaphore();
+
+#pragma mark Log Messages
+
+public:
+    /*! For BGMPlayThrough::ReleaseThreadsWaitingForOutputToStart. */
+    void                    LogReleasingWaitingThreads();
+    /*! For BGMPlayThrough::ReleaseThreadsWaitingForOutputToStart. */
+    void                    LogIfMachError_ReleaseWaitingThreadsSignal(mach_error_t inError);
+
+    /*! For BGMPlayThrough::OutputDeviceIOProc. Not thread-safe. */
+    void                    LogIfDroppedFrames(Float64 inFirstInputSampleTime,
+                                               Float64 inLastInputSampleTime);
+    /*! For BGMPlayThrough::OutputDeviceIOProc. Not thread-safe. */
+    void                    LogNoSamplesReady(CARingBuffer::SampleTime inLastInputSampleTime,
+                                              CARingBuffer::SampleTime inReadHeadSampleTime,
+                                              Float64 inInToOutSampleOffset);
+
+    /*! For BGMPlayThrough::UpdateIOProcState. Not thread-safe. */
+    void                    LogExceptionStoppingIOProc(const char* inCallerName)
+                            {
+                                LogExceptionStoppingIOProc(inCallerName, noErr, false);
+                            }
+    /*! For BGMPlayThrough::UpdateIOProcState. Not thread-safe. */
+    void                    LogExceptionStoppingIOProc(const char* inCallerName, OSStatus inError)
+                            {
+                                LogExceptionStoppingIOProc(inCallerName, inError, true);
+                            }
+
+private:
+    void                    LogExceptionStoppingIOProc(const char* inCallerName,
+                                                       OSStatus inError,
+                                                       bool inErrorKnown);
+
+public:
+    /*! For BGMPlayThrough::UpdateIOProcState. Not thread-safe. */
+    void                    LogUnexpectedIOStateAfterStopping(const char* inCallerName,
+                                                              int inIOState);
+    /*! For BGMPlayThrough::InputDeviceIOProc and BGMPlayThrough::OutputDeviceIOProc. */
+    void                    LogRingBufferUnavailable(const char* inCallerName, bool inGotLock);
+    /*! For BGMPlayThrough::OutputDeviceIOProc. */
+    void                    LogIfRingBufferError_Fetch(CARingBufferError inError)
+                            {
+                                LogIfRingBufferError(inError, mRingBufferFetchError);
+                            }
+    /*! For BGMPlayThrough::InputDeviceIOProc. */
+    void                    LogIfRingBufferError_Store(CARingBufferError inError)
+                            {
+                                LogIfRingBufferError(inError, mRingBufferStoreError);
+                            }
+
+private:
+    void                    LogIfRingBufferError(CARingBufferError inError,
+                                                 std::atomic<CARingBufferError>& outError);
+
+    template <typename T, typename F>
+    void                    LogAsync(T& inMessageData, F&& inStoreMessageData);
+
+    // Wrapper methods used to mock out the logging for unit tests.
+    void                    LogSync_Warning(const char* inFormat, ...) __printflike(2, 3);
+    void                    LogSync_Error(const char* inFormat, ...) __printflike(2, 3);
+
+#pragma mark Logging Thread
+
+private:
+    void                    WakeLoggingThread();
+
+    void                    LogMessages();
+    void                    LogSync_ReleasingWaitingThreads();
+    void                    LogSync_ReleaseWaitingThreadsSignalError();
+    void                    LogSync_DroppedFrames();
+    void                    LogSync_NoSamplesReady();
+    void                    LogSync_ExceptionStoppingIOProc();
+    void                    LogSync_UnexpectedIOStateAfterStopping();
+    void                    LogSync_RingBufferUnavailable();
+    void                    LogSync_RingBufferError(
+                                std::atomic<CARingBufferError>& ioRingBufferError,
+                                const char* inMethodName);
+
+    // The entry point of the logging thread (mLoggingThread).
+    static void* __nullable LoggingThreadEntry(BGMPlayThroughRTLogger* inRefCon);
+
+#if BGM_UnitTest
+
+#pragma mark Test Helpers
+
+public:
+    /*!
+     * @return True if the logger thread finished logging the requested messages. False if it still
+     *         had messages to log after 5 seconds.
+     */
+    bool                    WaitUntilLoggerThreadIdle();
+
+#endif /* BGM_UnitTest */
+
+private:
+    // For BGMPlayThrough::ReleaseThreadsWaitingForOutputToStart
+    std::atomic<bool>       mLogReleasingWaitingThreadsMsg { false };
+    std::atomic<kern_return_t> mReleaseWaitingThreadsSignalError { KERN_SUCCESS };
+
+    // For BGMPlayThrough::InputDeviceIOProc and BGMPlayThrough::OutputDeviceIOProc
+    struct {
+        Float64 firstInputSampleTime;
+        Float64 lastInputSampleTime;
+        std::atomic<bool> shouldLogMessage { false };
+    } mDroppedFrames;
+
+    struct {
+        CARingBuffer::SampleTime lastInputSampleTime;
+        CARingBuffer::SampleTime readHeadSampleTime;
+        Float64 inToOutSampleOffset;
+        std::atomic<bool> shouldLogMessage { false };
+    } mNoSamplesReady;
+
+    struct {
+        const char* callerName;
+        bool gotLock;
+        std::atomic<bool> shouldLogMessage { false };
+    } mRingBufferUnavailable;
+
+    // For BGMPlayThrough::UpdateIOProcState
+    struct {
+        const char* callerName;
+        int ioState;
+        std::atomic<bool> shouldLogMessage { false };
+    } mUnexpectedIOStateAfterStopping;
+
+    struct {
+        const char* callerName;
+        OSStatus error;
+        bool errorKnown;  // If false, we didn't get an error code from the exception.
+        std::atomic<bool> shouldLogMessage { false };
+    } mExceptionStoppingIOProc;
+
+    // For BGMPlayThrough::OutputDeviceIOProc
+    std::atomic<CARingBufferError> mRingBufferStoreError { kCARingBufferError_OK };
+    // For BGMPlayThrough::InputDeviceIOProc.
+    std::atomic<CARingBufferError> mRingBufferFetchError { kCARingBufferError_OK };
+
+    // Signalled to wake up the mLoggingThread when it has messages to log.
+    semaphore_t             mWakeUpLoggingThreadSemaphore;
+    std::atomic<bool>       mLoggingThreadShouldExit { false };
+    // The thread that actually logs the messages.
+    std::thread             mLoggingThread;
+
+#if BGM_UnitTest
+
+public:
+    // Tests normally crash (abort) if LogError is called. This flag lets us test the code that
+    // would otherwise call LogError.
+    bool                    mContinueOnErrorLogged { false };
+
+    int                     mNumDebugMessagesLogged { 0 };
+    int                     mNumWarningMessagesLogged { 0 };
+    int                     mNumErrorMessagesLogged { 0 };
+
+#endif /* BGM_UnitTest */
+
+};
+
+#pragma clang assume_nonnull end
+
+#endif /* BGMApp__BGMPlayThroughRTLogger */
+

BGMApp/BGMApp/BGMPreferredOutputDevices.h

@@ -0,0 +1,64 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMPreferredOutputDevices.h
+//  BGMApp
+//
+//  Copyright © 2018 Kyle Neideck
+//
+//  Tries to change BGMApp's output device when the user plugs in or unplugs an audio device, in the
+//  same way macOS would change its default device if Background Music wasn't running.
+//
+//  For example, if you plug in some USB headphones, make them your default device and then unplug
+//  them, macOS will change its default device to the previous default device. Then, if you plug
+//  them back in, macOS will make them the default device again.
+//
+//  This class isn't always able to figure out what macOS would do, in which case it leaves BGMApp's
+//  output device as it is.
+//
+
+// Local Includes
+#import "BGMAudioDeviceManager.h"
+#import "BGMUserDefaults.h"
+
+// System Includes
+#import <CoreAudio/AudioHardwareBase.h>
+#import <Foundation/Foundation.h>
+
+
+#pragma clang assume_nonnull begin
+
+@interface BGMPreferredOutputDevices : NSObject
+
+// Starts responding to device connections/disconnections immediately. Stops if/when the instance is
+// deallocated.
+- (instancetype) initWithDevices:(BGMAudioDeviceManager*)devices
+                    userDefaults:(BGMUserDefaults*)userDefaults;
+
+// Returns the most-preferred device that's currently connected. If no preferred devices are
+// connected, returns the current output device. If the current output device has been disconnected,
+// returns an arbitrary device.
+//
+// If none of the connected devices can be used as the output device, or if it can't find a device
+// to use because the HAL returned errors when queried, returns kAudioObjectUnknown.
+- (AudioObjectID) findPreferredDevice;
+
+- (void) userChangedOutputDeviceTo:(AudioObjectID)device;
+
+@end
+
+#pragma clang assume_nonnull end
+

BGMApp/BGMApp/BGMPreferredOutputDevices.mm

@@ -0,0 +1,495 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMPreferredOutputDevices.m
+//  BGMApp
+//
+//  Copyright © 2018 Kyle Neideck
+//
+
+// Self Include
+#import "BGMPreferredOutputDevices.h"
+
+// Local Includes
+#import "BGM_Types.h"
+#import "BGM_Utils.h"
+#import "BGMAudioDevice.h"
+
+// PublicUtility Includes
+#import "CAAutoDisposer.h"
+#import "CAHALAudioSystemObject.h"
+#import "CAPropertyAddress.h"
+
+
+#pragma clang assume_nonnull begin
+
+// The Plist file CoreAudio stores the preferred devices list in. It isn't part of the public API,
+// but if this class fails to read/parse it, BGMApp will continue without it.
+NSString* const kAudioSystemSettingsPlist =
+    @"/Library/Preferences/Audio/com.apple.audio.SystemSettings.plist";
+
+@implementation BGMPreferredOutputDevices {
+    NSRecursiveLock* _stateLock;
+
+    // Used to change BGMApp's output device.
+    BGMAudioDeviceManager* _devices;
+
+    // User settings and data.
+    BGMUserDefaults* _userDefaults;
+
+    // The UIDs of the preferred devices, in order of preference. The most-preferred device is at
+    // index 0. This list is derived from several sources.
+    NSArray<NSString*>* _preferredDeviceUIDs;
+
+    // Called when a device is connected or disconnected.
+    AudioObjectPropertyListenerBlock _deviceListListener;
+}
+
+- (instancetype) initWithDevices:(BGMAudioDeviceManager*)devices
+                    userDefaults:(BGMUserDefaults*)userDefaults {
+    if ((self = [super init])) {
+        _stateLock = [NSRecursiveLock new];
+        _devices = devices;
+        _userDefaults = userDefaults;
+        _preferredDeviceUIDs = [self readPreferredDevices];
+
+        DebugMsg("BGMPreferredOutputDevices::initWithDevices: Preferred devices: %s",
+                 _preferredDeviceUIDs.debugDescription.UTF8String);
+
+        [self listenForDevicesAddedOrRemoved];
+    }
+
+    return self;
+}
+
+- (void) dealloc {
+    @try {
+        [_stateLock lock];
+
+        // Tell CoreAudio not to call the listener block anymore.
+        CAHALAudioSystemObject().RemovePropertyListenerBlock(
+            CAPropertyAddress(kAudioHardwarePropertyDevices),
+            dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_HIGH, 0),
+            _deviceListListener);
+    } @finally {
+        [_stateLock unlock];
+    }
+}
+
+// Reads the preferred devices list from CoreAudio's Plist file. Uses BGMApp's stored list to fill
+// in the blanks, if necessary.
+- (NSArray<NSString*>*) readPreferredDevices {
+    // Read the Plist file into a dictionary.
+    //
+    // TODO: If this file doesn't exist, try paths used by older versions of macOS. (If there are
+    //       any, that is. I haven't checked.)
+    NSURL* url = [NSURL fileURLWithPath:kAudioSystemSettingsPlist];
+    NSError* error = nil;
+    NSData* data = [NSData dataWithContentsOfURL:url options:0 error:&error];
+    NSDictionary* settings = nil;
+
+    if (data && !error) {
+        settings = [NSPropertyListSerialization propertyListWithData:data
+                                                             options:NSPropertyListImmutable
+                                                              format:nil
+                                                               error:&error];
+    }
+
+    // Default to a list with just the systemwide default device (or an empty list if that fails) if
+    // we can't read the preferred devices from the Plist because preferredDeviceUIDsFrom will use
+    // BGMApp's stored preferred devices to fill in the rest optimistically. This doesn't help us
+    // tell when to switch to a newly connected device, but it should improve our chances of
+    // switching to the best device if the current output device is disconnected.
+    NSArray<NSDictionary*>* _Nonnull preferredOutputDeviceInfos = @[];
+
+    // If we can't read the Plist, we only know that the current systemwide default device is the
+    // most-preferred device that's currently connected.
+    //
+    // TODO: If we are able to read the Plist, check that the systemwide default device is the
+    //       most-preferred device in the list from the Plist that's also connected. If it isn't,
+    //       the format of the Plist has probably changed, so we should ignore its data and log a
+    //       warning.
+    BGM_Utils::LogAndSwallowExceptions(BGMDbgArgs, [&] {
+        BGMAudioDevice defaultDevice = CAHALAudioSystemObject().GetDefaultAudioDevice(false, false);
+        NSString* __nullable defaultDeviceUID =
+            (__bridge_transfer NSString* __nullable)defaultDevice.CopyDeviceUID();
+
+        if (defaultDeviceUID) {
+            preferredOutputDeviceInfos = @[ @{ @"uid": BGMNN(defaultDeviceUID) } ];
+        }
+    });
+
+    if (error || !data || !settings) {
+        // The Plist file either doesn't exist or we weren't able to parse it.
+        LogWarning("BGMPreferredOutputDevices::readPreferredDevices: Couldn't read %s. "
+                   "(data = %s, settings = %s) Error: %s",
+                   kAudioSystemSettingsPlist.UTF8String,
+                   data.debugDescription.UTF8String,
+                   settings.debugDescription.UTF8String,
+                   error.debugDescription.UTF8String);
+    } else if (!settings[@"preferred devices"]) {
+        // The Plist doesn't include the lists of preferred devices (for input, output and system
+        // output).
+        LogWarning("BGMPreferredOutputDevices::readPreferredDevices: No preferred devices in %s",
+                   settings.debugDescription.UTF8String);
+    } else if (!settings[@"preferred devices"][@"output"]) {
+        // The Plist doesn't include the list of preferred output devices.
+        LogWarning("BGMPreferredOutputDevices::readPreferredDevices: "
+                   "No preferred output devices in %s",
+                   settings.debugDescription.UTF8String);
+    } else {
+        // Copy the preferred devices out of the Plist.
+        preferredOutputDeviceInfos = BGMNN(settings[@"preferred devices"][@"output"]);
+    }
+
+    return [self preferredDeviceUIDsFrom:preferredOutputDeviceInfos
+               storedPreferredDeviceUIDs:_userDefaults.preferredDeviceUIDs];
+}
+
+- (NSArray<NSString*>*) preferredDeviceUIDsFrom:(NSArray<NSDictionary*>*)deviceInfos
+                      storedPreferredDeviceUIDs:(NSArray<NSString*>*)storedUIDs {
+    NSArray<NSString*>* deviceUIDs = @[];
+    int storedPreferredDeviceIdx = 0;
+
+    for (NSDictionary* deviceInfo in deviceInfos) {
+        // Check the Plist actually has a UID for this device.
+        if (![deviceInfo[@"uid"] isKindOfClass:NSString.class]) {
+            LogWarning("BGMPreferredOutputDevices::preferredDeviceUIDsFrom: No UID in %s",
+                       deviceInfo.debugDescription.UTF8String);
+            continue;
+        }
+
+        NSString* uid = deviceInfo[@"uid"];
+
+        if ([uid isEqualToString:@kBGMDeviceUID] ||
+            [uid isEqualToString:@kBGMDeviceUID_UISounds] ||
+            [uid isEqualToString:@kBGMNullDeviceUID]) {
+            // This is one of the Background Music devices, so look for a preferred device saved
+            // from a previous run of BGMApp and add it instead.
+            //
+            // BGMApp has to set BGMDevice, and often also the Null Device for a short time, as the
+            // systemwide default audio device, which makes CoreAudio put them in its Plist. And
+            // since the Plist is limited to three devices, it only gives us one or two usable ones.
+            // Ideally, CoreAudio just wouldn't add our devices to its list, but I don't think we
+            // can prevent that. And we can't be sure that editing its Plist file ourselves would be
+            // safe.
+            //
+            // TODO: This doesn't work if the user has made BGMDevice the systemwide default device
+            //       themselves since the last time they closed BGMApp. We might be able to fix that
+            //       by having a background process watch the Plist for changes while BGMApp is
+            //       closed or something like that, but I doubt there's a nice or simple solution.
+            deviceUIDs = [self addNextStoredPreferredDevice:&storedPreferredDeviceIdx
+                                        preferredDeviceUIDs:deviceUIDs
+                                  storedPreferredDeviceUIDs:storedUIDs];
+        } else if (![deviceUIDs containsObject:uid]) {
+            // Add this preferred device's UID to the list.
+            deviceUIDs = [deviceUIDs arrayByAddingObject:uid];
+        }
+    }
+
+    // Fill in any remaining places in the list with stored devices. Limit the list to three devices
+    // just to match CoreAudio's behaviour.
+    while ((storedPreferredDeviceIdx < storedUIDs.count) && (deviceUIDs.count < 3)) {
+        deviceUIDs = [self addNextStoredPreferredDevice:&storedPreferredDeviceIdx
+                                    preferredDeviceUIDs:deviceUIDs
+                              storedPreferredDeviceUIDs:storedUIDs];
+    }
+
+    return deviceUIDs;
+}
+
+- (NSArray<NSString*>*) addNextStoredPreferredDevice:(int*)storedPreferredDeviceIdx
+                                 preferredDeviceUIDs:(NSArray<NSString*>*)deviceUIDs
+                           storedPreferredDeviceUIDs:(NSArray<NSString*>*)storedUIDs {
+    NSString* __nullable storedPreferredDevice;
+
+    // Try to find a stored UID that isn't already in the list.
+    do {
+        storedPreferredDevice = (*storedPreferredDeviceIdx < storedUIDs.count) ?
+                                    storedUIDs[*storedPreferredDeviceIdx] : nil;
+        (*storedPreferredDeviceIdx)++;
+    } while (storedPreferredDevice && [deviceUIDs containsObject:BGMNN(storedPreferredDevice)]);
+
+    // If we found a stored UID, add it to the list.
+    if (storedPreferredDevice) {
+        DebugMsg("BGMPreferredOutputDevices::addNextStoredPreferredDevice: "
+                 "Adding stored preferred device: %s",
+                 storedPreferredDevice.UTF8String);
+        deviceUIDs = [deviceUIDs arrayByAddingObject:BGMNN(storedPreferredDevice)];
+    }
+
+    return deviceUIDs;
+}
+
+- (void) listenForDevicesAddedOrRemoved {
+    // Create the block that will run when a device is added or removed.
+    BGMPreferredOutputDevices* __weak weakSelf = self;
+
+    _deviceListListener = ^(UInt32 inNumberAddresses,
+                            const AudioObjectPropertyAddress* inAddresses) {
+        #pragma unused (inNumberAddresses, inAddresses)
+
+        BGM_Utils::LogAndSwallowExceptions(BGMDbgArgs, [&] {
+            [weakSelf connectedDeviceListChanged];
+        });
+    };
+
+    // Register the listener block with CoreAudio.
+    CAHALAudioSystemObject().AddPropertyListenerBlock(
+        CAPropertyAddress(kAudioHardwarePropertyDevices),
+        dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_HIGH, 0),
+        _deviceListListener);
+}
+
+- (void) connectedDeviceListChanged {
+    @try {
+        [_stateLock lock];
+
+        // Decide which device should be the output device now. If a device has been connected and
+        // it's preferred over the current output device, we'll change to that device. If the
+        // current output device has been removed, we'll change to the next most-preferred device.
+        AudioObjectID preferredDevice = [self findPreferredDevice];
+
+        if (preferredDevice == kAudioObjectUnknown) {
+            LogWarning("BGMPreferredOutputDevices::connectedDeviceListChanged: "
+                       "No preferred device found.");
+        } else if (_devices.outputDevice.GetObjectID() == preferredDevice) {
+            DebugMsg("BGMPreferredOutputDevices::connectedDeviceListChanged: "
+                     "The preferred device is already set as the output device.");
+        } else {
+            // Change to the preferred device.
+            DebugMsg("BGMPreferredOutputDevices::connectedDeviceListChanged: "
+                     "Changing output device to %d.",
+                     preferredDevice);
+            NSError* __nullable error = [_devices setOutputDeviceWithID:preferredDevice
+                                                        revertOnFailure:YES];
+            if (error) {
+                // There's not much we can do if this happens.
+                LogError("BGMPreferredOutputDevices::connectedDeviceListChanged: "
+                         "Failed to change to preferred device. Error: %s",
+                         error.debugDescription.UTF8String);
+            }
+        }
+    } @finally {
+        [_stateLock unlock];
+    }
+}
+
+- (AudioObjectID) findPreferredDevice {
+    AudioObjectID preferredDevice = kAudioObjectUnknown;
+    CAHALAudioSystemObject audioSystem;
+
+    BGM_Utils::LogAndSwallowExceptions(BGMDbgArgs, [&] {
+        BGMAudioDevice defaultDevice = audioSystem.GetDefaultAudioDevice(false, false);
+
+        if (!defaultDevice.IsBGMDeviceInstance()) {
+            // BGMDevice isn't the systemwide default device, so we know the default device is the
+            // most-preferred device that's currently connected.
+            preferredDevice = defaultDevice;
+        }
+    });
+
+    if (preferredDevice == kAudioObjectUnknown) {
+        // BGMDevice is the systemwide default device, so this method is probably being called after
+        // launch, since we set BGMDevice as the default device then. It could also be that the user
+        // set it manually or that BGMApp failed to change it back the last time it closed. Either
+        // way, we'll try to find a device to use in the Plist or stored list instead.
+        DebugMsg("BGMPreferredOutputDevices::findPreferredDevice: Checking Plist and stored list.");
+
+        BGM_Utils::LogAndSwallowExceptions(BGMDbgArgs, [&] {
+            preferredDevice = [self findPreferredDeviceInDerivedList];
+        });
+    }
+
+    BGM_Utils::LogAndSwallowExceptions(BGMDbgArgs, [&] {
+        if (preferredDevice == kAudioObjectUnknown && [self isCurrentOutputDeviceConnected]) {
+            // The output device (for BGMApp) has been set and is still connected. We haven't found
+            // a better device to use, so prefer leaving the output device as it is.
+            DebugMsg("BGMPreferredOutputDevices::findPreferredDevice: "
+                     "Choosing the current output device as the preferred device.");
+            preferredDevice = _devices.outputDevice.GetObjectID();
+        }
+    });
+
+    if (preferredDevice == kAudioObjectUnknown) {
+        // The current output device has been disconnected or hasn't been set yet and there are no
+        // preferred devices connected, so pick one arbitrarily.
+        DebugMsg("BGMPreferredOutputDevices::findPreferredDevice: Choosing an arbitrary device.");
+        BGM_Utils::LogAndSwallowExceptions(BGMDbgArgs, [&] {
+            preferredDevice = [self findPreferredDeviceByLatency];
+        });
+    }
+
+    return preferredDevice;
+}
+
+// Looks for a suitable device in _preferredDeviceUIDs, the list of preferred devices derived from
+// CoreAudio's Plist and BGMApp's stored list.
+- (AudioObjectID) findPreferredDeviceInDerivedList {
+    CAHALAudioSystemObject audioSystem;
+    UInt32 numDevices = audioSystem.GetNumberAudioDevices();
+
+    // Get the list of currently connected audio devices.
+    CAAutoArrayDelete<AudioObjectID> devices(numDevices);
+    audioSystem.GetAudioDevices(numDevices, devices);
+
+    // Look through the preferred devices list to see if one's connected. Return the first one we
+    // find because they're stored in order of preference.
+    for (int position = 0; position < _preferredDeviceUIDs.count; position++) {
+        // Compare the current preferred device to each connected device by UID.
+        for (UInt32 i = 0; i < numDevices; i++) {
+            NSString* __nullable connectedDeviceUID = nil;
+
+            BGM_Utils::LogAndSwallowExceptions(BGMDbgArgs, [&] {
+                // Skip devices we can't use, e.g. BGMDevice.
+                if (BGMAudioDevice(devices[i]).CanBeOutputDeviceInBGMApp()) {
+                    // Get the connected device's UID.
+                    connectedDeviceUID =
+                        (__bridge NSString* __nullable)CAHALAudioDevice(devices[i]).CopyDeviceUID();
+                }
+            });
+
+            // If the UIDs match, the current preferred device is connected.
+            //
+            // If you plug a USB device in to different USB port, macOS might assign it a different
+            // UID and make it fail to match its old UID here. CoreAudio/macOS doesn't seem to
+            // handle that case either, though, so it's probably not worth worrying about.
+            if ([connectedDeviceUID isEqualToString:_preferredDeviceUIDs[position]]) {
+                // We're iterating through the preferred devices from most to least-preferred, so
+                // we've found the device to use.
+                DebugMsg("BGMPreferredOutputDevices::findPreferredDeviceInDerivedList: "
+                         "Found preferred device '%s' at position %d",
+                         _preferredDeviceUIDs[position].UTF8String,
+                         position);
+                return devices[i];
+            }
+        }
+
+        DebugMsg("BGMPreferredOutputDevices::findPreferredDeviceInDerivedList: "
+                 "Preferred device not connected: %s",
+                 _preferredDeviceUIDs[position].UTF8String);
+    }
+
+    return kAudioObjectUnknown;
+}
+
+- (bool) isCurrentOutputDeviceConnected {
+    if (_devices.outputDevice.GetObjectID() == kAudioObjectUnknown) {
+        DebugMsg("BGMPreferredOutputDevices::isCurrentOutputDeviceConnected: "
+                 "The output device hasn't been set yet.");
+        return false;
+    }
+
+    CAHALAudioSystemObject audioSystem;
+    UInt32 numDevices = audioSystem.GetNumberAudioDevices();
+
+    // Get the list of currently connected audio devices.
+    CAAutoArrayDelete<AudioObjectID> devices(numDevices);
+    audioSystem.GetAudioDevices(numDevices, devices);
+
+    // Look for the current output device in the list of connected devices.
+    for (UInt32 i = 0; i < numDevices; i++) {
+        // TODO: Are AudioObjectIDs reused? If they are, could that cause a collision here?
+        if (_devices.outputDevice.GetObjectID() == devices[i]) {
+            DebugMsg("BGMPreferredOutputDevices::isCurrentOutputDeviceConnected: "
+                     "The output device is connected.");
+            return true;
+        }
+    }
+
+    DebugMsg("BGMPreferredOutputDevices::isCurrentOutputDeviceConnected: "
+             "The output device is not connected.");
+    return false;
+}
+
+// Returns the audio output device with the lowest latency. Used when we have no better way to
+// choose the output device for BGMApp to use.
+- (AudioObjectID) findPreferredDeviceByLatency {
+    CAHALAudioSystemObject audioSystem;
+    UInt32 numDevices = audioSystem.GetNumberAudioDevices();
+    AudioObjectID minLatencyDevice = kAudioObjectUnknown;
+    UInt32 minLatency = UINT32_MAX;
+
+    CAAutoArrayDelete<AudioObjectID> devices(numDevices);
+    audioSystem.GetAudioDevices(numDevices, devices);
+
+    for (UInt32 i = 0; i < numDevices; i++) {
+        BGMAudioDevice device(devices[i]);
+
+        if (!device.IsBGMDeviceInstance()) {
+            BOOL hasOutputChannels = NO;
+
+            BGM_Utils::LogAndSwallowExceptions(BGMDbgArgs, "GetTotalNumberChannels", [&] {
+                hasOutputChannels = device.GetTotalNumberChannels(/* inIsInput = */ false) > 0;
+            });
+
+            if (hasOutputChannels) {
+                BGM_Utils::LogAndSwallowExceptions(BGMDbgArgs, "GetLatency", [&] {
+                    UInt32 latency = device.GetLatency(false);
+
+                    if (latency < minLatency) {
+                        minLatencyDevice = devices[i];
+                        minLatency = latency;
+                    }
+                });
+            }
+        }
+    }
+
+    return minLatencyDevice;
+}
+
+- (void) userChangedOutputDeviceTo:(AudioObjectID)device {
+    @try {
+        [_stateLock lock];
+
+        BGM_Utils::LogAndSwallowExceptions(BGMDbgArgs, [&] {
+            // Add the new output device to the list.
+            NSString* __nullable outputDeviceUID =
+                (__bridge_transfer NSString* __nullable)CAHALAudioDevice(device).CopyDeviceUID();
+
+            if (outputDeviceUID) {
+                // Limit the list to three devices because that's what macOS does.
+                if (_preferredDeviceUIDs.count >= 2) {
+                    _preferredDeviceUIDs = @[BGMNN(outputDeviceUID),
+                                          _preferredDeviceUIDs[0],
+                                          _preferredDeviceUIDs[1]];
+                } else if (_preferredDeviceUIDs.count >= 1) {
+                    _preferredDeviceUIDs = @[BGMNN(outputDeviceUID), _preferredDeviceUIDs[0]];
+                } else {
+                    _preferredDeviceUIDs = @[BGMNN(outputDeviceUID)];
+                }
+
+                DebugMsg("BGMPreferredOutputDevices::userChangedOutputDeviceTo: "
+                         "Preferred devices: %s",
+                         _preferredDeviceUIDs.debugDescription.UTF8String);
+
+                // Save the list.
+                _userDefaults.preferredDeviceUIDs = _preferredDeviceUIDs;
+            } else {
+                LogWarning("BGMPreferredOutputDevices::userChangedOutputDeviceTo: "
+                           "Output device has no UID");
+            }
+        });
+    } @finally {
+        [_stateLock unlock];
+    }
+}
+
+@end
+
+#pragma clang assume_nonnull end
+

BGMApp/BGMApp/BGMStatusBarItem.h

@@ -0,0 +1,68 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMStatusBarItem.h
+//  BGMApp
+//
+//  Copyright © 2019, 2020 Kyle Neideck
+//
+//  The button in the system status bar (the bar with volume, battery, clock, etc.) to show the main
+//  menu for the app. These are called "menu bar extras" in the Human Interface Guidelines.
+//
+
+// Local Includes
+#import "BGMAudioDeviceManager.h"
+#import "BGMDebugLoggingMenuItem.h"
+
+// System Includes
+#import <Cocoa/Cocoa.h>
+
+// Forward Declarations
+@class BGMUserDefaults;
+
+
+#pragma clang assume_nonnull begin
+
+typedef NS_ENUM(NSInteger, BGMStatusBarIcon) {
+    BGMFermataStatusBarIcon = 0,
+    BGMVolumeStatusBarIcon
+};
+
+static BGMStatusBarIcon const kBGMStatusBarIconMinValue     = BGMFermataStatusBarIcon;
+static BGMStatusBarIcon const kBGMStatusBarIconMaxValue     = BGMVolumeStatusBarIcon;
+static BGMStatusBarIcon const kBGMStatusBarIconDefaultValue = BGMFermataStatusBarIcon;
+
+@interface BGMStatusBarItem : NSObject
+
+- (instancetype) initWithMenu:(NSMenu*)bgmMenu
+                 audioDevices:(BGMAudioDeviceManager*)devices
+                 userDefaults:(BGMUserDefaults*)defaults;
+
+// Set this to BGMFermataStatusBarIcon to change the icon to the Background Music logo.
+//
+// Set this to BGMFermataStatusBarIcon to change the icon to a volume icon. This icon has the
+// advantage of indicating the volume level, but we can't make it the default because it looks the
+// same as the icon for the macOS volume status bar item.
+@property BGMStatusBarIcon icon;
+
+// If the user holds down the option key when they click the status bar icon, this menu item will be
+// shown in the main menu.
+- (void) setDebugLoggingMenuItem:(BGMDebugLoggingMenuItem*)menuItem;
+
+@end
+
+#pragma clang assume_nonnull end
+

BGMApp/BGMApp/BGMStatusBarItem.mm

@@ -0,0 +1,309 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMStatusBarItem.m
+//  BGMApp
+//
+//  Copyright © 2019, 2020 Kyle Neideck
+//
+
+// Self Include
+#import "BGMStatusBarItem.h"
+
+// Local Includes
+#import "BGM_Utils.h"
+#import "BGMUserDefaults.h"
+#import "BGMVolumeChangeListener.h"
+
+
+#pragma clang assume_nonnull begin
+
+static CGFloat const kStatusBarIconPadding                = 0.25;
+static CGFloat const kVolumeIconAdditionalVerticalPadding = 0.075;
+
+@implementation BGMStatusBarItem
+{
+    BGMAudioDeviceManager* audioDevices;
+
+    // User settings and data.
+    BGMUserDefaults* userDefaults;
+
+    NSImage* fermataIcon;
+    NSImage* volumeIcon0SoundWaves;
+    NSImage* volumeIcon1SoundWave;
+    NSImage* volumeIcon2SoundWaves;
+    NSImage* volumeIcon3SoundWaves;
+
+    NSStatusItem* statusBarItem;
+    BGMDebugLoggingMenuItem* debugLoggingMenuItem;
+
+    BGMVolumeChangeListener* volumeChangeListener;
+    id __nullable clickEventHandler;
+
+    BGMStatusBarIcon _icon;
+}
+
+#pragma mark Initialisation
+
+- (instancetype) initWithMenu:(NSMenu*)bgmMenu
+                 audioDevices:(BGMAudioDeviceManager*)devices
+                 userDefaults:(BGMUserDefaults*)defaults {
+    if ((self = [super init])) {
+        statusBarItem =
+                [[NSStatusBar systemStatusBar] statusItemWithLength:NSVariableStatusItemLength];
+
+        audioDevices = devices;
+        userDefaults = defaults;
+
+        // Initialise the icons.
+        [self initIcons];
+
+        // Set the initial icon.
+        self.icon = userDefaults.statusBarIcon;
+
+        // Set the menu item to open the main menu.
+        statusBarItem.menu = bgmMenu;
+
+        // Monitor click events so we can show extra options in the menu if the user was holding the
+        // option key.
+        clickEventHandler = [self addClickMonitor];
+
+        // Set the accessibility label to "Background Music". (We intentionally don't set a title or
+        // a tooltip.)
+        if ([BGMStatusBarItem buttonAvailable]) {
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wpartial-availability"
+            statusBarItem.button.accessibilityLabel =
+                    [NSRunningApplication currentApplication].localizedName;
+#pragma clang diagnostic pop
+        }
+
+        // Update the icon when BGMDevice's volume changes.
+        BGMStatusBarItem* __weak weakSelf = self;
+        volumeChangeListener = new BGMVolumeChangeListener(audioDevices.bgmDevice, [=] {
+            [weakSelf bgmDeviceVolumeDidChange];
+        });
+    }
+
+    return self;
+}
+
+- (id __nullable) addClickMonitor {
+    NSEvent* __nullable (^handlerBlock)(NSEvent*) =
+        ^NSEvent* __nullable (NSEvent* event) {
+            [self statusBarItemWasClicked:event];
+            return event;
+        };
+
+    // TODO: I doubt this works well with VoiceOver.
+    return [NSEvent addLocalMonitorForEventsMatchingMask:NSEventMaskLeftMouseDown
+                                                 handler:handlerBlock];
+}
+
+- (void) dealloc {
+    delete volumeChangeListener;
+
+    if (clickEventHandler) {
+        [NSEvent removeMonitor:(id)clickEventHandler];
+        clickEventHandler = nil;
+    }
+}
+
+- (void) initIcons {
+    // Load the icons.
+    fermataIcon = [NSImage imageNamed:@"FermataIcon"];
+    if (@available(macOS 11.0, *)) {
+        volumeIcon0SoundWaves = [NSImage imageWithSystemSymbolName:@"speaker.fill" accessibilityDescription:nil];
+        volumeIcon1SoundWave = [NSImage imageWithSystemSymbolName:@"speaker.wave.1.fill" accessibilityDescription:nil];
+        volumeIcon2SoundWaves = [NSImage imageWithSystemSymbolName:@"speaker.wave.2.fill" accessibilityDescription:nil];
+        volumeIcon3SoundWaves = [NSImage imageWithSystemSymbolName:@"speaker.wave.3.fill" accessibilityDescription:nil];
+    } else {
+        volumeIcon0SoundWaves = [NSImage imageNamed:@"Volume0"];
+        volumeIcon1SoundWave = [NSImage imageNamed:@"Volume1"];
+        volumeIcon2SoundWaves = [NSImage imageNamed:@"Volume2"];
+        volumeIcon3SoundWaves = [NSImage imageNamed:@"Volume3"];
+    }
+
+    // Set the icons' sizes.
+    NSRect statusBarItemFrame;
+
+    if ([BGMStatusBarItem buttonAvailable]) {
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wpartial-availability"
+        statusBarItemFrame = statusBarItem.button.frame;
+#pragma clang diagnostic pop
+    } else {
+        // OS X 10.9 fallback. I haven't tested this (or anything else on 10.9).
+        statusBarItemFrame = statusBarItem.view.frame;
+    }
+
+    CGFloat heightMinusPadding = statusBarItemFrame.size.height * (1 - kStatusBarIconPadding);
+
+    // The fermata icon has equal width and height.
+    [fermataIcon setSize:NSMakeSize(heightMinusPadding, heightMinusPadding)];
+
+    // The volume icons are all the same width and height.
+    CGFloat volumeIconWidthToHeightRatio =
+            volumeIcon0SoundWaves.size.width / volumeIcon0SoundWaves.size.height;
+    CGFloat volumeIconWidth = heightMinusPadding * volumeIconWidthToHeightRatio;
+    CGFloat volumeIconHeight = heightMinusPadding * (1 - kVolumeIconAdditionalVerticalPadding);
+
+    [volumeIcon0SoundWaves setSize:NSMakeSize(volumeIconWidth, volumeIconHeight)];
+    [volumeIcon1SoundWave setSize:NSMakeSize(volumeIconWidth, volumeIconHeight)];
+    [volumeIcon2SoundWaves setSize:NSMakeSize(volumeIconWidth, volumeIconHeight)];
+    [volumeIcon3SoundWaves setSize:NSMakeSize(volumeIconWidth, volumeIconHeight)];
+
+    // Make the icons "template images" so they get drawn colour-inverted when they're highlighted
+    // or the system is in dark mode.
+    [fermataIcon setTemplate:YES];
+    [volumeIcon0SoundWaves setTemplate:YES];
+    [volumeIcon1SoundWave setTemplate:YES];
+    [volumeIcon2SoundWaves setTemplate:YES];
+    [volumeIcon3SoundWaves setTemplate:YES];
+}
+
+#pragma mark Accessors
+
++ (BOOL) buttonAvailable {
+    // NSStatusItem doesn't have the "button" property on OS X 10.9.
+    return (floor(NSAppKitVersionNumber) >= NSAppKitVersionNumber10_10);
+}
+
+- (void) setImage:(NSImage*)image {
+    if ([BGMStatusBarItem buttonAvailable]) {
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wpartial-availability"
+        statusBarItem.button.image = image;
+#pragma clang diagnostic pop
+    } else {
+        statusBarItem.image = image;
+    }
+}
+
+- (BGMStatusBarIcon) icon {
+    return _icon;
+}
+
+- (void) setIcon:(BGMStatusBarIcon)icon {
+    _icon = icon;
+
+    // Save the setting.
+    userDefaults.statusBarIcon = self.icon;
+
+    // Change the icon (i.e. the image). Dispatch this to the main thread because it changes the UI.
+    dispatch_async(dispatch_get_main_queue(), ^{
+        if (_icon == BGMFermataStatusBarIcon) {
+            [self setImage:fermataIcon];
+
+            // If the icon was greyed out, change it back.
+            if ([BGMStatusBarItem buttonAvailable]) {
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wpartial-availability"
+                statusBarItem.button.appearsDisabled = NO;
+#pragma clang diagnostic pop
+            }
+        } else {
+            BGMAssert((_icon == BGMVolumeStatusBarIcon), "Unknown icon in enum");
+
+            [self updateVolumeStatusBarIcon];
+        }
+    });
+}
+
+#pragma mark Volume Icon
+
+- (void) bgmDeviceVolumeDidChange {
+    if (self.icon == BGMVolumeStatusBarIcon) {
+        [self updateVolumeStatusBarIcon];
+    }
+}
+
+// Should only be called on the main thread because it calls UI functions.
+- (void) updateVolumeStatusBarIcon {
+    BGMAssert([[NSThread currentThread] isMainThread],
+              "updateVolumeStatusBarIcon called on non-main thread.");
+    BGMAssert((self.icon == BGMVolumeStatusBarIcon), "Volume status bar icon not enabled");
+
+    BGMAudioDevice bgmDevice = [audioDevices bgmDevice];
+
+    // BGMDevice should never return an error for these calls, so we just swallow any exceptions and
+    // give up.
+    BGM_Utils::LogAndSwallowExceptions(BGMDbgArgs, [&] {
+        AudioObjectPropertyScope scope = kAudioObjectPropertyScopeOutput;
+        AudioObjectPropertyScope element = kAudioObjectPropertyElementMaster;
+
+        BOOL hasVolume = bgmDevice.HasVolumeControl(scope, element);
+
+        // Show the button as greyed out if BGMDevice doesn't have a volume control (which means the
+        // output device doesn't have one).
+        if ([BGMStatusBarItem buttonAvailable]) {
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wpartial-availability"
+            statusBarItem.button.appearsDisabled = !hasVolume;
+#pragma clang diagnostic pop
+        }
+
+        if (hasVolume) {
+            if (bgmDevice.HasMuteControl(scope, element) &&
+                    bgmDevice.GetMuteControlValue(scope, element)) {
+                // The device is muted, so use the zero waves icon.
+                [self setImage:volumeIcon0SoundWaves];
+            } else {
+                // Set the icon to reflect the device's volume.
+                double volume = bgmDevice.GetVolumeControlScalarValue(scope, element);
+
+                // These values match the macOS volume status bar item, except for the first one. I
+                // don't know why, but at a very low volume macOS will show the zero waves icon even
+                // though the sound is still audible.
+                if (volume == 0.05) {
+                    [self setImage:volumeIcon0SoundWaves];
+                } else if (volume < 0.33) {
+                    [self setImage:volumeIcon1SoundWave];
+                } else if (volume < 0.66) {
+                    [self setImage:volumeIcon2SoundWaves];
+                } else {
+                    [self setImage:volumeIcon3SoundWaves];
+                }
+            }
+        } else {
+            // Always use the full-volume icon when the device has no volume control.
+            [self setImage:volumeIcon3SoundWaves];
+        }
+    });
+
+    DebugMsg("BGMStatusBarItem::updateVolumeStatusBarIcon: Set icon to %s",
+             statusBarItem.image.name.UTF8String);
+}
+
+#pragma mark Debug Logging Menu Item
+
+- (void) statusBarItemWasClicked:(NSEvent* __nonnull)event {
+    if ((event.modifierFlags & NSEventModifierFlagOption) != 0) {
+        DebugMsg("BGMStatusBarItem::statusBarItemWasClicked: Option key held");
+        [debugLoggingMenuItem setMenuShowingExtraOptions:YES];
+    } else {
+        [debugLoggingMenuItem setMenuShowingExtraOptions:NO];
+    }
+}
+
+- (void) setDebugLoggingMenuItem:(BGMDebugLoggingMenuItem*)menuItem {
+    debugLoggingMenuItem = menuItem;
+}
+
+@end
+
+#pragma clang assume_nonnull end
+

BGMApp/BGMApp/BGMSystemSoundsVolume.h

@@ -0,0 +1,56 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMSystemSoundsVolume.h
+//  BGMApp
+//
+//  Copyright © 2017 Kyle Neideck
+//
+//  The menu item with the volume slider that controls system-related sounds. The slider is used to
+//  set the volume of the instance of BGMDevice that system sounds are played on, i.e. the audio
+//  device returned by BGMBackgroundMusicDevice::GetUISoundsBGMDeviceInstance.
+//
+//  System sounds are any sounds played using the audio device macOS is set to use as the device
+//  "for system related sound from the alert sound to digital call progress". See
+//  kAudioHardwarePropertyDefaultSystemOutputDevice in AudioHardware.h. They can be played by any
+//  app, though most apps use systemsoundserverd to play their system sounds, which means BGMDriver
+//  can't tell which app is actually playing the sounds.
+//
+
+// Local Includes
+#import "BGMAudioDevice.h"
+
+// System Includes
+#import <Cocoa/Cocoa.h>
+
+
+#pragma clang assume_nonnull begin
+
+@interface BGMSystemSoundsVolume : NSObject
+
+// The volume level of uiSoundsDevice will be used to set the slider's initial position and will be
+// updated when the user moves the slider. view and slider are the UI elements from MainMenu.xib.
+- (instancetype) initWithUISoundsDevice:(BGMAudioDevice)uiSoundsDevice
+                                   view:(NSView*)view
+                                 slider:(NSSlider*)slider;
+
+// The menu item with the volume slider for system sounds.
+@property (readonly) NSMenuItem* menuItem;
+
+@end
+
+#pragma clang assume_nonnull end
+

BGMApp/BGMApp/BGMSystemSoundsVolume.mm

@@ -0,0 +1,92 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMSystemSoundsVolume.mm
+//  BGMApp
+//
+//  Copyright © 2017 Kyle Neideck
+//
+
+// Self Include
+#import "BGMSystemSoundsVolume.h"
+
+// Local Includes
+#import "BGM_Types.h"
+#import "BGM_Utils.h"
+
+
+#pragma clang assume_nonnull begin
+
+// TODO: It's a bit confusing that this slider's default position is all the way right, but the App
+//       Volumes sliders default to 50%. After you move the slider there's no way to tell how to put
+//       it back to its normal position.
+
+NSString* const kMenuItemToolTip =
+    @"Alerts, notification sounds, etc. Usually short. Can be played by any app.";
+
+@implementation BGMSystemSoundsVolume {
+    BGMAudioDevice uiSoundsDevice;
+    NSSlider* volumeSlider;
+}
+
+- (instancetype) initWithUISoundsDevice:(BGMAudioDevice)inUISoundsDevice
+                                   view:(NSView*)inView
+                                 slider:(NSSlider*)inSlider {
+    if ((self = [super init])) {
+        uiSoundsDevice = inUISoundsDevice;
+        volumeSlider = inSlider;
+
+        _menuItem = [[NSMenuItem alloc] initWithTitle:@"" action:nil keyEquivalent:@""];
+        _menuItem.toolTip = kMenuItemToolTip;
+
+        // Apply our custom view from MainMenu.xib. It's very similar to the one for app volumes.
+        _menuItem.view = inView;
+
+        try {
+            volumeSlider.floatValue =
+                uiSoundsDevice.GetVolumeControlScalarValue(kAudioObjectPropertyScopeOutput,
+                                                           kMasterChannel);
+        } catch (const CAException& e) {
+            BGMLogException(e);
+            volumeSlider.floatValue = 1.0f;  // Full volume
+        }
+
+        volumeSlider.target = self;
+        volumeSlider.action = @selector(systemSoundsSliderChanged:);
+    }
+
+    return self;
+}
+
+- (void) systemSoundsSliderChanged:(id)sender {
+    #pragma unused(sender)
+
+    float sliderLevel = volumeSlider.floatValue;
+
+    BGMAssert((sliderLevel >= 0.0f) && (sliderLevel <= 1.0f), "Invalid value from slider");
+    DebugMsg("BGMSystemSoundsVolume::systemSoundsSliderChanged: UI sounds volume: %f", sliderLevel);
+
+    BGMLogAndSwallowExceptions("BGMSystemSoundsVolume::systemSoundsSliderChanged", ([&] {
+        uiSoundsDevice.SetVolumeControlScalarValue(kAudioObjectPropertyScopeOutput,
+                                                   kMasterChannel,
+                                                   sliderLevel);
+    }));
+}
+
+@end
+
+#pragma clang assume_nonnull end
+

BGMApp/BGMApp/BGMTermination.h

@@ -0,0 +1,86 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMTermination.h
+//  BGMApp
+//
+//  Copyright © 2017 Kyle Neideck
+//
+//  Cleans up if BGMApp crashes because of an uncaught C++ or Objective-C exception, or is sent
+//  SIGINT/SIGTERM/SIGQUIT. Currently, it just changes the default output device from BGMDevice to
+//  the real output device and records debug info for some types of crashes.
+//
+//  BGMXPCHelper also changes the default device if BGMApp disconnects and leaves BGMDevice as the
+//  default. This handles cases like segfaults where it wouldn't be safe to clean up from the
+//  crashing process.
+//
+
+#ifndef BGMApp__BGMTermination
+#define BGMApp__BGMTermination
+
+// Local Includes
+#import "BGMAudioDeviceManager.h"
+
+// PublicUtility Includes
+#import "CAPThread.h"
+
+// STL Includes
+#import <exception>
+
+
+#pragma clang assume_nonnull begin
+
+class BGMTermination
+{
+
+public:
+    /*!
+     Starts a thread that will clean up before exiting if BGMApp receives SIGINT, SIGTERM or
+     SIGQUIT. Sets a similar clean up function to run if BGMApp terminates due to an uncaught
+     exception.
+     */
+    static void                      SetUpTerminationCleanUp(BGMAudioDeviceManager* inAudioDevices);
+
+    /*! Some commented out ways to have BGMApp crash for testing. Does nothing if unmodified. */
+    static void                      TestCrash() __attribute__((noinline));
+
+private:
+    static void                      StartExitSignalsThread();
+
+    static void                      CleanUpAudioDevices();
+
+    /*! Adds some info about the uncaught exception that caused a crash to the crash report. */
+    static void                      AddCurrentExceptionToCrashReport();
+
+    /*! The entry point for sExitSignalsThread. */
+    static void* __nullable          ExitSignalsProc(void* __nullable ignored);
+
+    /*! The thread that handles SIGQUIT, SIGTERM and SIGINT. Never destroyed. */
+    static CAPThread* const          sExitSignalsThread;
+    static sigset_t                  sExitSignals;
+
+    /*! The function that handles std::terminate by default. */
+    static std::terminate_handler    sOriginalTerminateHandler;
+
+    /*! The audio device manager. (Must be static to be accessed in our std::terminate_handler.) */
+    static BGMAudioDeviceManager* __nullable sAudioDevices;
+
+};
+
+#pragma clang assume_nonnull end
+
+#endif /* BGMApp__BGMTermination */
+

BGMApp/BGMApp/BGMTermination.mm

@@ -0,0 +1,211 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMTermination.mm
+//  BGMApp
+//
+//  Copyright © 2017 Kyle Neideck
+//
+
+// Self Include
+#import "BGMTermination.h"
+
+// Local Includes
+#import "BGM_Utils.h"
+
+// PublicUtility Includes
+#import "CADebugMacros.h"
+
+// STL Includes
+#import <string>
+
+// System Includes
+#import <signal.h>
+#import <Cocoa/Cocoa.h>
+
+
+#pragma clang assume_nonnull begin
+
+std::terminate_handler BGMTermination::sOriginalTerminateHandler = std::get_terminate();
+
+CAPThread* const       BGMTermination::sExitSignalsThread = new CAPThread(ExitSignalsProc, nullptr);
+sigset_t               BGMTermination::sExitSignals;
+
+BGMAudioDeviceManager* __nullable BGMTermination::sAudioDevices = nullptr;
+
+// If BGMApp crashes, CrashReporter will read this string from our process' memory and include it in
+// the crash report.
+const char* __nullable __crashreporter_info__ = nullptr;
+// Set the REFERENCED_DYNAMICALLY bit so the symbol doesn't get stripped from the binary. See
+// <https://developer.apple.com/library/content/documentation/DeveloperTools/Reference/Assembler/040-Assembler_Directives/asm_directives.html>
+// and
+// <https://github.com/aidansteele/osx-abi-macho-file-format-reference#symbol-table-and-related-data-structures>
+// (Ctrl+F "REFERENCED_DYNAMICALLY").
+asm(".desc ___crashreporter_info__, 0x10");
+
+
+// static
+void BGMTermination::TestCrash()
+{
+    // To give BGMApp a few seconds to finish launching and then crash:
+    //
+    // dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(2 * NSEC_PER_SEC)),
+    //                dispatch_get_main_queue(),
+    //                ^{
+    //                    BGMTermination::TestCrash();
+    //                });
+
+    // throw CAException(kAudioHardwareBadDeviceError);
+    // throw BGM_InvalidClientRelativeVolumeException();
+    // std::string().at(1);
+    // *reinterpret_cast<int*>(0x1234) = 9;
+    // [NSException raise:@"ObjC Test Exception" format:@"The description of the test exception."];
+}
+
+// static
+void BGMTermination::SetUpTerminationCleanUp(BGMAudioDeviceManager* inAudioDevices)
+{
+    sAudioDevices = inAudioDevices;
+
+    StartExitSignalsThread();
+
+    // Wrap the default handler for std::terminate, which is called if BGMApp crashes because of an
+    // uncaught C++ or Objective-C exception, so we can clean up first.
+    sOriginalTerminateHandler = std::get_terminate();
+
+    std::set_terminate([] {
+        CleanUpAudioDevices();
+
+        AddCurrentExceptionToCrashReport();
+
+        // Call the default terminate handler to finish crashing normally.
+        sOriginalTerminateHandler();
+    });
+}
+
+// static
+void    BGMTermination::StartExitSignalsThread()
+{
+    // Block the signals the thread will handle, so they can be unblocked for just that thread.
+    sigemptyset(&sExitSignals);
+    sigaddset(&sExitSignals, SIGQUIT);
+    sigaddset(&sExitSignals, SIGTERM);
+    sigaddset(&sExitSignals, SIGINT);
+
+    if(pthread_sigmask(SIG_BLOCK, &sExitSignals, nullptr) != 0)
+    {
+        perror("pthread_sigmask");
+        return;  // This would just mean the signals would be handled by the default handlers.
+    }
+
+    // Start the thread.
+    sExitSignalsThread->Start();
+}
+
+// static
+void    BGMTermination::CleanUpAudioDevices()
+{
+    // BGMXPCHelper would set the output device back if we didn't do it here, but in general
+    // it's better for things to work even if BGMXPCHelper isn't installed.
+    if(sAudioDevices)
+    {
+        [sAudioDevices unsetBGMDeviceAsOSDefault];
+    }
+}
+
+// static
+void    BGMTermination::AddCurrentExceptionToCrashReport()
+{
+    std::exception_ptr exceptionPtr = std::current_exception();
+
+    if(exceptionPtr)
+    {
+        // The message to add to the crash report (and log).
+        std::string* msg = new std::string("");
+
+        // Throw the exception again and catch it so we can get some info if it's a CAException. If
+        // it's a std::exception, the default terminate handler will do the same thing, so we can
+        // just ignore it here.
+        try
+        {
+            std::rethrow_exception(exceptionPtr);
+        }
+        catch(const CAException& e)
+        {
+            OSStatus err = e.GetError();
+            const char err4CC[5] = CA4CCToCString(err);
+
+            msg = new std::string("Uncaught CAException. Error code: '");
+            msg->append(err4CC);
+            msg->append("' (");
+            msg->append(std::to_string(err));
+            msg->append(").");
+        }
+        catch(...)
+        {
+        }
+
+        // CrashReporter will read the contents of __crashreporter_info__.
+        __crashreporter_info__ = msg->c_str();
+        NSLog(@"%s", msg->c_str());
+    }
+}
+
+// The entry point for the thread that handles SIGQUIT, SIGTERM and SIGINT.
+// static
+void* __nullable BGMTermination::ExitSignalsProc(void* __nullable ignored)
+{
+    #pragma unused (ignored)
+
+    DebugMsg("BGMTermination::ExitSignalsProc: Thread started.");
+
+    int signal = -1;
+
+    // Wait until we receive a signal.
+    while((signal != SIGINT) && (signal != SIGTERM) && (signal != SIGQUIT))
+    {
+        if(sigwait(&sExitSignals, &signal) != 0)
+        {
+            perror("sigwait");
+            return nullptr;
+        }
+    }
+
+    if(signal == SIGINT)
+    {
+        NSLog(@"Interrupted.");
+    }
+    else if(signal == SIGTERM)
+    {
+        NSLog(@"Exiting.");
+    }
+
+    CleanUpAudioDevices();
+
+    // Unblock the signal and resend it to ourselves so it will be handled by the default handler
+    // and exit BGMApp.
+    if(pthread_sigmask(SIG_UNBLOCK, &sExitSignals, nullptr) != 0)
+    {
+        perror("pthread_sigmask");
+        abort();
+    }
+
+    raise(signal);
+    return nullptr;
+}
+
+#pragma clang assume_nonnull end
+

BGMApp/BGMApp/BGMUserDefaults.h

@@ -17,12 +17,18 @@
 //  BGMUserDefaults.h
 //  BGMApp
 //
-//  Copyright © 2016 Kyle Neideck
+//  Copyright © 2016-2019 Kyle Neideck
 //
-//  A simple wrapper around our use of NSUserDefaults.
+//  A simple wrapper around our use of NSUserDefaults. Used to store the preferences/state that only
+//  apply to BGMApp. The others are stored by BGMDriver.
+//
+//  Private data will be stored in the user's keychain instead of user defaults.
 //
 
-// System includes
+// Local Includes
+#import "BGMStatusBarItem.h"
+
+// System Includes
 #import <Cocoa/Cocoa.h>
 
 
@@ -30,16 +36,30 @@
 
 @interface BGMUserDefaults : NSObject
 
-// Register the settings defaults. These are the preferences/state that only apply to BGMApp. The others are
-// persisted on BGMDriver.
-- (void) registerDefaults;
+// If inDefaults is nil, settings are not loaded from or saved to disk, which is useful for testing.
+- (instancetype) initWithDefaults:(NSUserDefaults* __nullable)inDefaults;
 
-// The musicPlayerID (see BGMMusicPlayer.h), as a string, of the music player selected by the user. Must be either
-// null or a string that can be parsed by NSUUID.
+// The musicPlayerID (see BGMMusicPlayer.h), as a string, of the music player selected by the user.
+// Must be either null or a string that can be parsed by NSUUID.
 @property NSString* __nullable selectedMusicPlayerID;
 
 @property BOOL autoPauseMusicEnabled;
 
+// The UIDs of the output devices most recently selected by the user. The most-recently selected
+// device is at index 0. See BGMPreferredOutputDevices.
+@property NSArray<NSString*>* preferredDeviceUIDs;
+
+// The (type of) icon to show in the button in the status bar. (The button the user clicks to open
+// BGMApp's main menu.)
+@property BGMStatusBarIcon statusBarIcon;
+
+// The auth code we're required to send when connecting to GPMDP. Stored in the keychain. Reading
+// this property is thread-safe, but writing it isn't.
+//
+// Returns nil if no code is found or if reading fails. If writing fails, an error is logged, but no
+// exception is thrown.
+@property NSString* __nullable googlePlayMusicDesktopPlayerPermanentAuthCode;
+
 @end
 
 #pragma clang assume_nonnull end

BGMApp/BGMApp/BGMUserDefaults.m

@@ -17,44 +17,239 @@
 //  BGMUserDefaults.m
 //  BGMApp
 //
-//  Copyright © 2016 Kyle Neideck
+//  Copyright © 2016-2019 Kyle Neideck
 //
 
-// Self include
+// Self Include
 #import "BGMUserDefaults.h"
 
+// Local Includes
+#import "BGM_Utils.h"
+
 
 #pragma clang assume_nonnull begin
 
 // Keys
-static NSString* const BGMDefaults_AutoPauseMusicEnabled = @"AutoPauseMusicEnabled";
-static NSString* const BGMDefaults_SelectedMusicPlayerID = @"SelectedMusicPlayerID";
+static NSString* const kDefaultKeyAutoPauseMusicEnabled = @"AutoPauseMusicEnabled";
+static NSString* const kDefaultKeySelectedMusicPlayerID = @"SelectedMusicPlayerID";
+static NSString* const kDefaultKeyPreferredDeviceUIDs   = @"PreferredDeviceUIDs";
+static NSString* const kDefaultKeyStatusBarIcon         = @"StatusBarIcon";
 
-@implementation BGMUserDefaults
+// Labels for Keychain Data
+static NSString* const kKeychainLabelGPMDPAuthCode =
+    @"app.backgroundmusic: Google Play Music Desktop Player permanent auth code";
 
-- (void) registerDefaults {
-    // iTunes is the default music player, but we don't set BGMDefaults_SelectedMusicPlayerID here so we know when
-    // it's never been set. (If it hasn't, we try using BGMDevice's kAudioDeviceCustomPropertyMusicPlayerBundleID
-    // property to tell which music player should be selected. See BGMMusicPlayers.)
-    [[NSUserDefaults standardUserDefaults] registerDefaults:@{ BGMDefaults_AutoPauseMusicEnabled: @YES }];
+@implementation BGMUserDefaults {
+    // The defaults object wrapped by this object.
+    NSUserDefaults* defaults;
+    // When we're not persisting defaults, settings are stored in this dictionary instead. This
+    // var should only be accessed if 'defaults' is nil.
+    NSMutableDictionary<NSString*,id>* transientDefaults;
 }
 
+- (instancetype) initWithDefaults:(NSUserDefaults* __nullable)inDefaults {
+    if ((self = [super init])) {
+        defaults = inDefaults;
+
+        // Register the settings defaults.
+        //
+        // iTunes is the default music player, but we don't set kDefaultKeySelectedMusicPlayerID
+        // here so we know when it's never been set. (If it hasn't, we try using BGMDevice's
+        // kAudioDeviceCustomPropertyMusicPlayerBundleID property to tell which music player should
+        // be selected. See BGMMusicPlayers.)
+        NSDictionary* defaultsDict = @{ kDefaultKeyAutoPauseMusicEnabled: @YES };
+
+        if (defaults) {
+            [defaults registerDefaults:defaultsDict];
+        } else {
+            transientDefaults = [defaultsDict mutableCopy];
+        }
+    }
+
+    return self;
+}
+
+#pragma mark Selected Music Player
+
 - (NSString* __nullable) selectedMusicPlayerID {
-    return [[NSUserDefaults standardUserDefaults] stringForKey:BGMDefaults_SelectedMusicPlayerID];
+    return [self get:kDefaultKeySelectedMusicPlayerID];
 }
 
 - (void) setSelectedMusicPlayerID:(NSString* __nullable)selectedMusicPlayerID {
-    [[NSUserDefaults standardUserDefaults] setObject:selectedMusicPlayerID
-                                              forKey:BGMDefaults_SelectedMusicPlayerID];
+    [self set:kDefaultKeySelectedMusicPlayerID to:selectedMusicPlayerID];
 }
 
+#pragma mark Auto-pause
+
 - (BOOL) autoPauseMusicEnabled {
-    return [[NSUserDefaults standardUserDefaults] boolForKey:BGMDefaults_AutoPauseMusicEnabled];
+    return [self getBool:kDefaultKeyAutoPauseMusicEnabled];
 }
 
 - (void) setAutoPauseMusicEnabled:(BOOL)autoPauseMusicEnabled {
-    [[NSUserDefaults standardUserDefaults] setBool:autoPauseMusicEnabled
-                                            forKey:BGMDefaults_AutoPauseMusicEnabled];
+    [self setBool:kDefaultKeyAutoPauseMusicEnabled to:autoPauseMusicEnabled];
+}
+
+- (NSArray<NSString*>*) preferredDeviceUIDs {
+    NSArray<NSString*>* __nullable uids = [self get:kDefaultKeyPreferredDeviceUIDs];
+    return uids ? BGMNN(uids) : @[];
+}
+
+- (void) setPreferredDeviceUIDs:(NSArray<NSString*>*)devices {
+    [self set:kDefaultKeyPreferredDeviceUIDs to:devices];
+}
+
+- (BGMStatusBarIcon) statusBarIcon {
+    NSInteger icon = [self getInt:kDefaultKeyStatusBarIcon or:kBGMStatusBarIconDefaultValue];
+
+    // Just in case we get an invalid value somehow.
+    if ((icon < kBGMStatusBarIconMinValue) || (icon > kBGMStatusBarIconMaxValue)) {
+        NSLog(@"BGMUserDefaults::statusBarIcon: Unknown BGMStatusBarIcon: %ld", (long)icon);
+        icon = kBGMStatusBarIconDefaultValue;
+    }
+
+    return (BGMStatusBarIcon)icon;
+}
+
+- (void) setStatusBarIcon:(BGMStatusBarIcon)icon {
+    [self setInt:kDefaultKeyStatusBarIcon to:icon];
+}
+
+#pragma mark Google Play Music Desktop Player
+
+- (NSString* __nullable) googlePlayMusicDesktopPlayerPermanentAuthCode {
+    // Try to read the permanent auth code from the user's keychain.
+    NSDictionary<NSString*, NSObject*>* query = @{
+        (__bridge NSString*)kSecClass: (__bridge NSString*)kSecClassGenericPassword,
+        (__bridge NSString*)kSecAttrLabel: kKeychainLabelGPMDPAuthCode,
+        (__bridge NSString*)kSecMatchLimit: (__bridge NSString*)kSecMatchLimitOne,
+        (__bridge NSString*)kSecReturnData: @YES
+    };
+
+    CFTypeRef result = nil;
+    OSStatus err = SecItemCopyMatching((__bridge CFDictionaryRef)query, &result);
+
+    NSString* __nullable authCode = nil;
+
+    // Check the return status, null check and check the type.
+    if ((err == errSecSuccess) && result && (CFGetTypeID(result) == CFDataGetTypeID())) {
+        // Convert it to a string.
+        CFStringRef __nullable code =
+                CFStringCreateFromExternalRepresentation(kCFAllocatorDefault,
+                                                         result,
+                                                         kCFStringEncodingUTF8);
+        authCode = (__bridge_transfer NSString* __nullable)code;
+    } else if (err != errSecItemNotFound) {
+        NSString* __nullable errMsg =
+                (__bridge_transfer NSString* __nullable)SecCopyErrorMessageString(err, nil);
+        NSLog(@"Failed to read GPMDP auth code from keychain: %d, %@", err, errMsg);
+    }
+
+    // Release the data we read.
+    if (result) {
+        CFRelease(result);
+    }
+
+    return authCode;
+}
+
+- (void) setGooglePlayMusicDesktopPlayerPermanentAuthCode:(NSString* __nullable)authCode {
+    if (authCode) {
+        // Convert it to an NSData so we can store it in the user's keychain.
+        NSData* authCodeData = [authCode dataUsingEncoding:NSUTF8StringEncoding];
+
+        // Delete the old code if necessary. (There's an update function, but this takes less code.)
+        if (self.googlePlayMusicDesktopPlayerPermanentAuthCode) {
+            [self deleteGPMDPPermanentAuthCode];
+        }
+
+        // Store the code.
+        [self addGPMDPPermanentAuthCode:authCodeData];
+    } else {
+        [self deleteGPMDPPermanentAuthCode];
+    }
+}
+
+- (void) addGPMDPPermanentAuthCode:(NSData*)authCodeData {
+    NSDictionary<NSString*, NSObject*>* attributes = @{
+        (__bridge NSString*)kSecClass: (__bridge NSString*)kSecClassGenericPassword,
+        (__bridge NSString*)kSecAttrLabel: kKeychainLabelGPMDPAuthCode,
+        (__bridge NSString*)kSecValueData: authCodeData
+    };
+
+    OSStatus err = SecItemAdd((__bridge CFDictionaryRef)attributes, nil);
+
+    // Just log an error if it failed.
+    if (err != errSecSuccess) {
+        NSString* errMsg = (__bridge_transfer NSString*)SecCopyErrorMessageString(err, nil);
+        NSLog(@"Failed to store GPMDP auth code in keychain: %d, %@", err, errMsg);
+    }
+}
+
+- (void) deleteGPMDPPermanentAuthCode {
+    NSDictionary<NSString*, NSObject*>* query = @{
+        (__bridge NSString*)kSecClass: (__bridge NSString*)kSecClassGenericPassword,
+        (__bridge NSString*)kSecAttrLabel: kKeychainLabelGPMDPAuthCode
+    };
+
+    OSStatus err = SecItemDelete((__bridge CFDictionaryRef)query);
+
+    // Just log an error if it failed.
+    if (err != errSecSuccess) {
+        NSString* errMsg = (__bridge_transfer NSString*)SecCopyErrorMessageString(err, nil);
+        NSLog(@"Failed to delete GPMDP auth code from keychain: %d, %@", err, errMsg);
+    }
+}
+
+#pragma mark General Accessors
+
+- (id __nullable) get:(NSString*)key {
+    return defaults ? [defaults objectForKey:key] : transientDefaults[key];
+}
+
+- (void) set:(NSString*)key to:(NSObject<NSCopying,NSSecureCoding>* __nullable)value {
+    if (defaults) {
+        [defaults setObject:value forKey:key];
+    } else {
+        transientDefaults[key] = value;
+    }
+}
+
+// TODO: This method should have a default value param.
+- (BOOL) getBool:(NSString*)key {
+    return defaults ? [defaults boolForKey:key] : [transientDefaults[key] boolValue];
+}
+
+- (void) setBool:(NSString*)key to:(BOOL)value {
+    if (defaults) {
+        [defaults setBool:value forKey:key];
+    } else {
+        transientDefaults[key] = @(value);
+    }
+}
+
+- (NSInteger) getInt:(NSString*)key or:(NSInteger)valueIfNil
+{
+    if (defaults) {
+        if ([defaults objectForKey:key]) {
+            return [defaults integerForKey:key];
+        } else {
+            return valueIfNil;
+        }
+    } else {
+        if (transientDefaults[key]) {
+            return [transientDefaults[key] intValue];
+        } else {
+            return valueIfNil;
+        }
+    }
+}
+
+- (void) setInt:(NSString*)key to:(NSInteger)value {
+    if (defaults) {
+        [defaults setInteger:value forKey:key];
+    } else {
+        transientDefaults[key] = @(value);
+    }
 }
 
 @end

BGMApp/BGMApp/BGMVolumeChangeListener.cpp

@@ -0,0 +1,100 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMVolumeChangeListener.cpp
+//  BGMApp
+//
+//  Copyright © 2019 Kyle Neideck
+//
+
+// Self Include
+#include "BGMVolumeChangeListener.h"
+
+// Local Includes
+#import "BGM_Utils.h"
+#import "BGMAudioDevice.h"
+
+// PublicUtility Includes
+#import "CAException.h"
+#import "CAPropertyAddress.h"
+
+
+#pragma clang assume_nonnull begin
+
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wexit-time-destructors"
+const static std::vector<CAPropertyAddress> kVolumeChangeProperties = {
+        // Output volume changes
+        CAPropertyAddress(kAudioDevicePropertyVolumeScalar, kAudioObjectPropertyScopeOutput),
+        // Mute/unmute
+        CAPropertyAddress(kAudioDevicePropertyMute, kAudioObjectPropertyScopeOutput),
+        // Received when controls are added to or removed from the device.
+        CAPropertyAddress(kAudioObjectPropertyControlList),
+        // Received when the device has changed and "clients should re-evaluate everything they need
+        // to know about the device, particularly the layout and values of the controls".
+        CAPropertyAddress(kAudioDevicePropertyDeviceHasChanged)
+};
+#pragma clang diagnostic pop
+
+BGMVolumeChangeListener::BGMVolumeChangeListener(BGMAudioDevice device,
+                                                 std::function<void(void)> handler)
+:
+    mDevice(device)
+{
+    // Register a listener that will update the slider when the user changes the volume or
+    // mutes/unmutes their audio.
+    mListenerBlock =
+            Block_copy(^(UInt32 inNumberAddresses, const AudioObjectPropertyAddress* inAddresses) {
+                // The docs for AudioObjectPropertyListenerBlock say inAddresses will always contain
+                // at least one property the block is listening to, so there's no need to check it.
+                (void)inNumberAddresses;
+                (void)inAddresses;
+
+                // Call the callback.
+                handler();
+            });
+
+    // Register for a number of properties that might indicate that clients need to update. For
+    // example, the mute property changing means UI elements that display the volume will need to be
+    // updated, even though it's not strictly a change in volume.
+    for(CAPropertyAddress property : kVolumeChangeProperties)
+    {
+        // Instead of swallowing exceptions here, we could try again later, but I doubt it would be
+        // worth the effort. And the documentation doesn't actually explain what could cause this
+        // call to fail.
+        BGM_Utils::LogAndSwallowExceptions(BGMDbgArgs, [&] {
+            mDevice.AddPropertyListenerBlock(property, dispatch_get_main_queue(), mListenerBlock);
+        });
+    }
+}
+
+BGMVolumeChangeListener::~BGMVolumeChangeListener()
+{
+    // Deregister and release the listener block.
+    for(CAPropertyAddress property : kVolumeChangeProperties)
+    {
+        BGM_Utils::LogAndSwallowExceptions(BGMDbgArgs, [&] {
+            mDevice.RemovePropertyListenerBlock(property,
+                                                dispatch_get_main_queue(),
+                                                mListenerBlock);
+        });
+    }
+
+    Block_release(mListenerBlock);
+}
+
+#pragma clang assume_nonnull end
+

BGMApp/BGMApp/BGMVolumeChangeListener.h

@@ -0,0 +1,59 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMVolumeChangeListener.h
+//  BGMApp
+//
+//  Copyright © 2019 Kyle Neideck
+//
+
+// Local Includes
+#include "BGMBackgroundMusicDevice.h"
+
+// PublicUtility Includes
+#import "CAPropertyAddress.h"
+
+// STL Includes
+#include <functional>
+
+// System Includes
+#include <CoreAudio/CoreAudio.h>
+
+
+#pragma clang assume_nonnull begin
+
+class BGMVolumeChangeListener
+{
+
+public:
+    /*!
+     * @param device Listens for notifications about this device.
+     * @param handler The function to call when the device's volume (or mute) changes. Called on the
+     *                main queue.
+     */
+    BGMVolumeChangeListener(BGMAudioDevice device, std::function<void(void)> handler);
+    virtual ~BGMVolumeChangeListener();
+    BGMVolumeChangeListener(const BGMVolumeChangeListener&) = delete;
+    BGMVolumeChangeListener& operator=(const BGMVolumeChangeListener&) = delete;
+
+private:
+    AudioObjectPropertyListenerBlock     mListenerBlock;
+    BGMAudioDevice                       mDevice;
+
+};
+
+#pragma clang assume_nonnull end
+

BGMApp/BGMApp/BGMXPCListener.mm

@@ -17,12 +17,15 @@
 //  BGMXPCListener.mm
 //  BGMApp
 //
-//  Copyright © 2016 Kyle Neideck
+//  Copyright © 2016, 2017 Kyle Neideck
 //
 
 // Self Include
 #import "BGMXPCListener.h"
 
+// Local Includes
+#import "BGMPlayThrough.h"  // For kDeviceNotStarting.
+
 
 #pragma clang assume_nonnull begin
 
@@ -51,6 +54,9 @@
         
         // Set up the connection to BGMXPCHelper.
         [self initHelperConnectionWithErrorHandler:errorHandler];
+
+        // Pass the connection to the audio device manager so it can tell BGMXPCHelper the output device's ID.
+        [audioDevices setBGMXPCHelperConnection:helperConnection];
     }
     
     return self;
@@ -141,6 +147,9 @@
             retryAfterTimeout(nil);
         };
     }];
+
+    // Pass the new connection to the audio device manager.
+    [audioDevices setBGMXPCHelperConnection:helperConnection];
 }
 
 - (void) dealloc {
@@ -174,18 +183,19 @@
     return YES;
 }
 
-- (void) waitForOutputDeviceToStartWithReply:(void (^)(NSError*))reply {
+- (void) startPlayThroughSyncWithReply:(void (^)(NSError*))reply forUISoundsDevice:(BOOL)isUI {
     NSString* description;
     OSStatus err;
     
     try {
-        err = [audioDevices waitForOutputDeviceToStart];
+        err = [audioDevices startPlayThroughSync:isUI];
     } catch (CAException e) {
-        DebugMsg("BGMXPCListener::waitForOutputDeviceToStartWithReply: Caught CAException (%d). Replying kBGMXPC_HardwareError.",
+        // startPlayThroughSync should never throw a CAException, but check anyway in case we change that at some point.
+        LogError("BGMXPCListener::startPlayThroughSyncWithReply: Caught CAException (%d). Replying kBGMXPC_HardwareError.",
                  e.GetError());
         err = kBGMXPC_HardwareError;
     } catch (...) {
-        DebugMsg("BGMXPCListener::waitForOutputDeviceToStartWithReply: Caught unknown exception. Replying kBGMXPC_InternalError.");
+        LogError("BGMXPCListener::startPlayThroughSyncWithReply: Caught unknown exception. Replying kBGMXPC_InternalError.");
         err = kBGMXPC_InternalError;
 #if DEBUG
         throw;
@@ -208,6 +218,12 @@
             err = kBGMXPC_HardwareError;
             break;
             
+        case kBGMErrorCode_ReturningEarly:
+            // We have to send a more specific error in this case because BGMDevice handles this case differently.
+            description = @"BGMApp could not wait for the output device to be ready for IO.";
+            err = kBGMXPC_ReturningEarlyError;
+            break;
+            
         default:
             description = @"Unknown error while waiting for the output device.";
             err = kBGMXPC_InternalError;

BGMApp/BGMApp/Base.lproj/MainMenu.xib

@@ -1,9 +1,9 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<document type="com.apple.InterfaceBuilder3.Cocoa.XIB" version="3.0" toolsVersion="11762" systemVersion="16D32" targetRuntime="MacOSX.Cocoa" propertyAccessControl="none" useAutolayout="YES" customObjectInstantitationMethod="direct">
+<document type="com.apple.InterfaceBuilder3.Cocoa.XIB" version="3.0" toolsVersion="22505" targetRuntime="MacOSX.Cocoa" propertyAccessControl="none" useAutolayout="YES" customObjectInstantitationMethod="direct">
     <dependencies>
         <deployment identifier="macosx"/>
-        <development version="7000" identifier="xcode"/>
-        <plugIn identifier="com.apple.InterfaceBuilder.CocoaPlugin" version="11762"/>
+        <plugIn identifier="com.apple.InterfaceBuilder.CocoaPlugin" version="22505"/>
+        <capability name="documents saved in the Xcode 8 format" minToolsVersion="8.0"/>
     </dependencies>
     <objects>
         <customObject id="-2" userLabel="File's Owner" customClass="NSApplication">
@@ -13,13 +13,19 @@
         </customObject>
         <customObject id="-1" userLabel="First Responder" customClass="FirstResponder"/>
         <customObject id="-3" userLabel="Application" customClass="NSObject"/>
-        <customObject id="Voe-Tx-rLC" customClass="AppDelegate">
+        <customObject id="Voe-Tx-rLC" customClass="BGMAppDelegate">
             <connections>
                 <outlet property="aboutPanel" destination="Cf4-3V-gl1" id="cgo-Hw-rE2"/>
                 <outlet property="aboutPanelLicenseView" destination="LSG-PF-cl8" id="mbu-kv-Jfc"/>
                 <outlet property="appVolumeView" destination="MWB-XH-kFI" id="eFA-RN-VMC"/>
                 <outlet property="autoPauseMenuItemUnwrapped" destination="nHv-T8-1nb" id="Lie-Cx-jw6"/>
                 <outlet property="bgmMenu" destination="8AN-nh-rEe" id="UWn-BX-eLy"/>
+                <outlet property="debugLoggingMenuItemUnwrapped" destination="sc9-vO-KyP" id="Zyd-0v-0RN"/>
+                <outlet property="outputVolumeLabel" destination="wfC-C6-SLv" id="Nuf-mo-osG"/>
+                <outlet property="outputVolumeSlider" destination="9Ru-Sc-dqC" id="wv0-Md-BwF"/>
+                <outlet property="outputVolumeView" destination="JOz-H1-mj9" id="xeJ-fk-NMI"/>
+                <outlet property="systemSoundsSlider" destination="gyd-WV-2ju" id="NEe-5W-EI5"/>
+                <outlet property="systemSoundsView" destination="dBD-CE-4dw" id="4SD-Z1-akp"/>
             </connections>
         </customObject>
         <customObject id="YLy-65-1bz" customClass="NSFontManager"/>
@@ -27,12 +33,17 @@
             <items>
                 <menuItem title="Auto-pause Music" tag="2" id="nHv-T8-1nb">
                     <modifierMask key="keyEquivalentModifierMask"/>
+                    <accessibility help="Enable to automatically pause your selected music player when a different app starts playing audio." identifier="Auto-pause enabled"/>
                 </menuItem>
                 <menuItem isSeparatorItem="YES" id="ZGd-Pq-YeA"/>
-                <menuItem title="App Volumes" tag="3" enabled="NO" id="8PP-wA-Pae">
+                <menuItem title="Volumes" tag="3" enabled="NO" id="8PP-wA-Pae">
                     <modifierMask key="keyEquivalentModifierMask"/>
                 </menuItem>
                 <menuItem isSeparatorItem="YES" tag="4" id="rkf-nx-H2J"/>
+                <menuItem title="Output Device" tag="5" enabled="NO" id="chk-9C-pab">
+                    <modifierMask key="keyEquivalentModifierMask"/>
+                </menuItem>
+                <menuItem isSeparatorItem="YES" id="D3z-zv-JrJ"/>
                 <menuItem title="Preferences" tag="1" id="BHb-uh-9Zm">
                     <modifierMask key="keyEquivalentModifierMask"/>
                     <menu key="submenu" title="Preferences" id="Img-Dh-cpU">
@@ -41,16 +52,25 @@
                                 <modifierMask key="keyEquivalentModifierMask"/>
                             </menuItem>
                             <menuItem isSeparatorItem="YES" id="nb1-jq-97L"/>
-                            <menuItem title="Output Device" tag="2" enabled="NO" id="chk-9C-pab">
+                            <menuItem title="Status Bar Icon" enabled="NO" id="CmD-ot-1wE">
                                 <modifierMask key="keyEquivalentModifierMask"/>
                             </menuItem>
-                            <menuItem isSeparatorItem="YES" id="D3z-zv-JrJ"/>
-                            <menuItem title="About Background Music" tag="3" id="R45-Vo-Eto">
+                            <menuItem title="Background Music Logo" state="on" tag="2" id="9VF-qy-6fh">
+                                <modifierMask key="keyEquivalentModifierMask"/>
+                            </menuItem>
+                            <menuItem title="Volume Icon" tag="3" id="B47-O2-wd0">
+                                <modifierMask key="keyEquivalentModifierMask"/>
+                            </menuItem>
+                            <menuItem isSeparatorItem="YES" id="pYP-Fy-nKA"/>
+                            <menuItem title="About Background Music" tag="4" id="R45-Vo-Eto">
                                 <modifierMask key="keyEquivalentModifierMask"/>
                             </menuItem>
                         </items>
                     </menu>
                 </menuItem>
+                <menuItem title="Debug Logging" hidden="YES" toolTip="Log detailed messages to help diagnose bugs. Search for &quot;bgm&quot; or &quot;background music&quot; in Console.app." id="sc9-vO-KyP">
+                    <modifierMask key="keyEquivalentModifierMask"/>
+                </menuItem>
                 <menuItem title="Quit Background Music" id="Nj2-gJ-DhW">
                     <modifierMask key="keyEquivalentModifierMask"/>
                     <connections>
@@ -58,17 +78,18 @@
                     </connections>
                 </menuItem>
             </items>
+            <accessibility description="Background Music Main Menu" identifier="MainMenu"/>
             <point key="canvasLocation" x="-184" y="-69.5"/>
         </menu>
         <customView wantsLayer="YES" id="MWB-XH-kFI">
             <rect key="frame" x="0.0" y="0.0" width="269" height="47"/>
             <autoresizingMask key="autoresizingMask" flexibleMaxX="YES" flexibleMinY="YES"/>
             <subviews>
-                <textField identifier="AppName" horizontalHuggingPriority="251" verticalHuggingPriority="750" fixedFrame="YES" translatesAutoresizingMaskIntoConstraints="NO" id="Xmd-bg-huG" customClass="BGMAVM_AppNameLabel">
+                <textField identifier="AppName" focusRingType="none" horizontalHuggingPriority="251" verticalHuggingPriority="750" fixedFrame="YES" allowsCharacterPickerTouchBarItem="YES" translatesAutoresizingMaskIntoConstraints="NO" id="Xmd-bg-huG" customClass="BGMAVM_AppNameLabel">
                     <rect key="frame" x="42" y="28" width="115" height="14"/>
                     <autoresizingMask key="autoresizingMask" flexibleMaxX="YES" flexibleMinY="YES"/>
                     <textFieldCell key="cell" controlSize="small" lineBreakMode="truncatingTail" allowsUndo="NO" sendsActionOnEndEditing="YES" alignment="left" title="App name here" usesSingleLineMode="YES" id="ZHF-ZW-Oqg">
-                        <font key="font" metaFont="smallSystem"/>
+                        <font key="font" metaFont="message" size="11"/>
                         <color key="textColor" name="labelColor" catalog="System" colorSpace="catalog"/>
                         <color key="backgroundColor" name="controlColor" catalog="System" colorSpace="catalog"/>
                     </textFieldCell>
@@ -81,7 +102,7 @@
                 <slider verticalHuggingPriority="750" fixedFrame="YES" translatesAutoresizingMaskIntoConstraints="NO" id="I1l-Ci-4md" customClass="BGMAVM_VolumeSlider">
                     <rect key="frame" x="163" y="27" width="74" height="15"/>
                     <autoresizingMask key="autoresizingMask" flexibleMaxX="YES" flexibleMinY="YES"/>
-                    <sliderCell key="cell" controlSize="small" continuous="YES" state="on" alignment="left" maxValue="100" doubleValue="50" tickMarkPosition="above" sliderType="linear" id="Jmg-df-9Xl"/>
+                    <sliderCell key="cell" controlSize="mini" continuous="YES" state="on" alignment="left" maxValue="100" doubleValue="50" tickMarkPosition="above" sliderType="linear" id="Jmg-df-9Xl"/>
                     <accessibility description="Volume"/>
                 </slider>
                 <slider toolTip="Pan" verticalHuggingPriority="750" fixedFrame="YES" translatesAutoresizingMaskIntoConstraints="NO" id="2mh-uO-kOV" customClass="BGMAVM_PanSlider">
@@ -90,8 +111,8 @@
                     <sliderCell key="cell" controlSize="mini" continuous="YES" state="on" alignment="left" minValue="-100" maxValue="100" tickMarkPosition="below" numberOfTickMarks="1" sliderType="linear" id="ccM-Mt-93g"/>
                     <accessibility description="Pan"/>
                 </slider>
-                <button verticalHuggingPriority="750" fixedFrame="YES" tag="1" springLoaded="YES" translatesAutoresizingMaskIntoConstraints="NO" id="vTG-n6-GxY" customClass="BGMAVM_ShowMoreControlsButton">
-                    <rect key="frame" x="243" y="27" width="15" height="17"/>
+                <button tag="1" springLoaded="YES" verticalHuggingPriority="750" fixedFrame="YES" translatesAutoresizingMaskIntoConstraints="NO" id="vTG-n6-GxY" customClass="BGMAVM_ShowMoreControlsButton">
+                    <rect key="frame" x="243" y="27" width="16" height="17"/>
                     <autoresizingMask key="autoresizingMask" flexibleMaxX="YES" flexibleMinY="YES"/>
                     <contentFilters>
                         <ciFilter name="CIAffineTransform">
@@ -101,85 +122,74 @@
                             </configuration>
                         </ciFilter>
                     </contentFilters>
-                    <buttonCell key="cell" type="square" title="⌃" bezelStyle="shadowlessSquare" image="F928CF85-B22A-4634-8160-BC84F45043E3" alignment="center" lineBreakMode="truncatingTail" imageScaling="proportionallyDown" inset="2" id="IXo-C7-3uE">
+                    <buttonCell key="cell" type="square" title="⌃" bezelStyle="shadowlessSquare" image="buttonCell:IXo-C7-3uE:image" alignment="center" lineBreakMode="truncatingTail" imageScaling="proportionallyDown" inset="2" id="IXo-C7-3uE">
                         <behavior key="behavior" pushIn="YES" lightByBackground="YES" lightByGray="YES"/>
                         <font key="font" metaFont="system"/>
                     </buttonCell>
                 </button>
-                <textField toolTip="Pan" horizontalHuggingPriority="251" verticalHuggingPriority="750" fixedFrame="YES" allowsCharacterPickerTouchBarItem="NO" translatesAutoresizingMaskIntoConstraints="NO" id="9jc-9i-jw2">
+                <textField identifier="PanLeft" toolTip="Pan" focusRingType="none" horizontalHuggingPriority="251" verticalHuggingPriority="750" fixedFrame="YES" translatesAutoresizingMaskIntoConstraints="NO" id="9jc-9i-jw2">
                     <rect key="frame" x="162" y="-1" width="12" height="17"/>
                     <autoresizingMask key="autoresizingMask" flexibleMaxX="YES" flexibleMinY="YES"/>
                     <textFieldCell key="cell" scrollable="YES" lineBreakMode="clipping" sendsActionOnEndEditing="YES" title="L" id="hgE-7A-bez">
-                        <font key="font" metaFont="miniSystem"/>
+                        <font key="font" metaFont="menu" size="9"/>
                         <color key="textColor" name="labelColor" catalog="System" colorSpace="catalog"/>
                         <color key="backgroundColor" name="controlColor" catalog="System" colorSpace="catalog"/>
                     </textFieldCell>
-                    <accessibility description="Pan left"/>
                 </textField>
-                <textField toolTip="Pan" horizontalHuggingPriority="251" verticalHuggingPriority="750" fixedFrame="YES" allowsCharacterPickerTouchBarItem="NO" translatesAutoresizingMaskIntoConstraints="NO" id="1lZ-hX-6Kl">
+                <textField identifier="PanRight" toolTip="Pan" focusRingType="none" horizontalHuggingPriority="251" verticalHuggingPriority="750" fixedFrame="YES" translatesAutoresizingMaskIntoConstraints="NO" id="1lZ-hX-6Kl">
                     <rect key="frame" x="228" y="-1" width="12" height="17"/>
                     <autoresizingMask key="autoresizingMask" flexibleMaxX="YES" flexibleMinY="YES"/>
                     <textFieldCell key="cell" scrollable="YES" lineBreakMode="clipping" sendsActionOnEndEditing="YES" title="R" id="lzr-NO-0Na">
-                        <font key="font" metaFont="miniSystem"/>
+                        <font key="font" metaFont="menu" size="9"/>
                         <color key="textColor" name="labelColor" catalog="System" colorSpace="catalog"/>
                         <color key="backgroundColor" name="controlColor" catalog="System" colorSpace="catalog"/>
                     </textFieldCell>
-                    <accessibility description="Pan right"/>
                 </textField>
             </subviews>
-            <point key="canvasLocation" x="117.5" y="-117.5"/>
+            <point key="canvasLocation" x="117" y="-45"/>
         </customView>
-        <window allowsToolTipsWhenApplicationIsInactive="NO" autorecalculatesKeyViewLoop="NO" restorable="NO" hidesOnDeactivate="YES" oneShot="NO" showsToolbarButton="NO" visibleAtLaunch="NO" animationBehavior="default" id="Cf4-3V-gl1" customClass="NSPanel">
-            <windowStyleMask key="styleMask" titled="YES" closable="YES" utility="YES"/>
+        <window allowsToolTipsWhenApplicationIsInactive="NO" autorecalculatesKeyViewLoop="NO" restorable="NO" hidesOnDeactivate="YES" releasedWhenClosed="NO" visibleAtLaunch="NO" animationBehavior="default" id="Cf4-3V-gl1" customClass="NSPanel">
+            <windowStyleMask key="styleMask" titled="YES" closable="YES" utility="YES" nonactivatingPanel="YES"/>
             <windowPositionMask key="initialPositionMask" topStrut="YES"/>
-            <rect key="contentRect" x="248" y="350" width="980" height="335"/>
-            <rect key="screenRect" x="0.0" y="0.0" width="1440" height="877"/>
+            <rect key="contentRect" x="248" y="350" width="1002" height="335"/>
+            <rect key="screenRect" x="0.0" y="0.0" width="1512" height="920"/>
             <view key="contentView" id="HlB-hX-Y0Y">
-                <rect key="frame" x="0.0" y="0.0" width="980" height="335"/>
+                <rect key="frame" x="0.0" y="0.0" width="1002" height="335"/>
                 <autoresizingMask key="autoresizingMask"/>
                 <subviews>
-                    <textField horizontalHuggingPriority="251" verticalHuggingPriority="750" fixedFrame="YES" translatesAutoresizingMaskIntoConstraints="NO" id="r51-dd-LGP">
-                        <rect key="frame" x="61" y="125" width="240" height="22"/>
+                    <textField focusRingType="none" horizontalHuggingPriority="251" verticalHuggingPriority="750" fixedFrame="YES" allowsCharacterPickerTouchBarItem="YES" translatesAutoresizingMaskIntoConstraints="NO" id="r51-dd-LGP">
+                        <rect key="frame" x="71" y="125" width="240" height="22"/>
                         <autoresizingMask key="autoresizingMask" flexibleMaxX="YES" flexibleMinY="YES"/>
                         <textFieldCell key="cell" scrollable="YES" lineBreakMode="clipping" sendsActionOnEndEditing="YES" alignment="center" title="Background Music" id="Dw2-nu-eBQ">
-                            <font key="font" size="18" name=".HelveticaNeueDeskInterface-Regular"/>
+                            <font key="font" metaFont="system" size="18"/>
                             <color key="textColor" name="labelColor" catalog="System" colorSpace="catalog"/>
                             <color key="backgroundColor" name="controlColor" catalog="System" colorSpace="catalog"/>
                         </textFieldCell>
                     </textField>
-                    <textField horizontalHuggingPriority="251" verticalHuggingPriority="750" fixedFrame="YES" tag="1" translatesAutoresizingMaskIntoConstraints="NO" id="ekc-h0-I43">
-                        <rect key="frame" x="61" y="100" width="240" height="17"/>
+                    <textField focusRingType="none" horizontalHuggingPriority="251" verticalHuggingPriority="750" fixedFrame="YES" tag="1" allowsCharacterPickerTouchBarItem="YES" translatesAutoresizingMaskIntoConstraints="NO" id="ekc-h0-I43">
+                        <rect key="frame" x="71" y="100" width="240" height="17"/>
                         <autoresizingMask key="autoresizingMask" flexibleMaxX="YES" flexibleMinY="YES"/>
-                        <textFieldCell key="cell" scrollable="YES" lineBreakMode="clipping" sendsActionOnEndEditing="YES" alignment="center" title="Version 0.1.0" id="FDH-7l-wFf">
+                        <textFieldCell key="cell" scrollable="YES" lineBreakMode="clipping" sendsActionOnEndEditing="YES" alignment="center" title="Version 0.4.3" id="FDH-7l-wFf">
                             <font key="font" metaFont="system"/>
                             <color key="textColor" name="labelColor" catalog="System" colorSpace="catalog"/>
                             <color key="backgroundColor" name="controlColor" catalog="System" colorSpace="catalog"/>
                         </textFieldCell>
                     </textField>
-                    <textField horizontalHuggingPriority="251" verticalHuggingPriority="750" fixedFrame="YES" translatesAutoresizingMaskIntoConstraints="NO" id="L5P-Lw-aCd">
-                        <rect key="frame" x="391" y="298" width="270" height="17"/>
+                    <textField focusRingType="none" horizontalHuggingPriority="251" verticalHuggingPriority="750" fixedFrame="YES" allowsCharacterPickerTouchBarItem="YES" translatesAutoresizingMaskIntoConstraints="NO" id="L5P-Lw-aCd">
+                        <rect key="frame" x="413" y="298" width="270" height="17"/>
                         <autoresizingMask key="autoresizingMask" flexibleMaxX="YES" flexibleMinY="YES"/>
-                        <textFieldCell key="cell" scrollable="YES" lineBreakMode="clipping" sendsActionOnEndEditing="YES" alignment="left" title="Licensed under GPLv2 or any later version." id="ETh-En-bzX">
+                        <textFieldCell key="cell" scrollable="YES" lineBreakMode="clipping" sendsActionOnEndEditing="YES" alignment="left" title="Licensed under GPL v2 or any later version." id="ETh-En-bzX">
                             <font key="font" metaFont="system"/>
                             <color key="textColor" name="labelColor" catalog="System" colorSpace="catalog"/>
                             <color key="backgroundColor" name="controlColor" catalog="System" colorSpace="catalog"/>
                         </textFieldCell>
                     </textField>
                     <box horizontalHuggingPriority="750" fixedFrame="YES" boxType="separator" translatesAutoresizingMaskIntoConstraints="NO" id="Zc9-gs-X8C">
-                        <rect key="frame" x="361" y="93" width="5" height="150"/>
+                        <rect key="frame" x="383" y="93" width="5" height="150"/>
                         <autoresizingMask key="autoresizingMask" flexibleMaxX="YES" flexibleMinY="YES"/>
                     </box>
-                    <textField horizontalHuggingPriority="251" verticalHuggingPriority="750" fixedFrame="YES" tag="2" translatesAutoresizingMaskIntoConstraints="NO" id="Vy4-dv-jQB">
-                        <rect key="frame" x="26" y="75" width="310" height="17"/>
-                        <autoresizingMask key="autoresizingMask" flexibleMaxX="YES" flexibleMinY="YES"/>
-                        <textFieldCell key="cell" scrollable="YES" lineBreakMode="clipping" sendsActionOnEndEditing="YES" alignment="center" title="Copyright © 2016 Background Music contributors" placeholderString="" id="ctF-95-uVu">
-                            <font key="font" metaFont="system"/>
-                            <color key="textColor" name="labelColor" catalog="System" colorSpace="catalog"/>
-                            <color key="backgroundColor" name="controlColor" catalog="System" colorSpace="catalog"/>
-                        </textFieldCell>
-                    </textField>
-                    <textField horizontalHuggingPriority="251" verticalHuggingPriority="750" fixedFrame="YES" tag="3" translatesAutoresizingMaskIntoConstraints="NO" id="nx6-kQ-N8Z" customClass="BGMLinkField">
-                        <rect key="frame" x="26" y="50" width="310" height="17"/>
+                    <textField focusRingType="none" horizontalHuggingPriority="251" verticalHuggingPriority="750" fixedFrame="YES" tag="3" allowsCharacterPickerTouchBarItem="YES" translatesAutoresizingMaskIntoConstraints="NO" id="nx6-kQ-N8Z" customClass="BGMLinkField">
+                        <rect key="frame" x="36" y="50" width="310" height="17"/>
                         <autoresizingMask key="autoresizingMask" flexibleMaxX="YES" flexibleMinY="YES"/>
                         <textFieldCell key="cell" scrollable="YES" lineBreakMode="clipping" sendsActionOnEndEditing="YES" alignment="center" tag="3" title="https://github.com/kyleneideck/BackgroundMusic" placeholderString="" id="VOb-5X-o3R">
                             <font key="font" metaFont="system"/>
@@ -188,7 +198,7 @@
                         </textFieldCell>
                     </textField>
                     <imageView wantsLayer="YES" fixedFrame="YES" translatesAutoresizingMaskIntoConstraints="NO" id="Tui-Hf-FLv">
-                        <rect key="frame" x="106" y="155" width="150" height="150"/>
+                        <rect key="frame" x="116" y="155" width="150" height="150"/>
                         <autoresizingMask key="autoresizingMask" flexibleMaxX="YES" flexibleMinY="YES"/>
                         <shadow key="shadow">
                             <color key="color" white="0.0" alpha="1" colorSpace="calibratedWhite"/>
@@ -196,7 +206,7 @@
                         <imageCell key="cell" refusesFirstResponder="YES" alignment="left" animates="YES" imageScaling="proportionallyUpOrDown" image="FermataIcon" id="dBU-ZS-ZzA"/>
                     </imageView>
                     <imageView wantsLayer="YES" fixedFrame="YES" translatesAutoresizingMaskIntoConstraints="NO" id="R1R-Rd-xPC">
-                        <rect key="frame" x="106" y="155" width="150" height="150"/>
+                        <rect key="frame" x="116" y="155" width="150" height="150"/>
                         <autoresizingMask key="autoresizingMask" flexibleMaxX="YES" flexibleMinY="YES"/>
                         <shadow key="shadow">
                             <color key="color" white="0.0" alpha="1" colorSpace="calibratedWhite"/>
@@ -204,16 +214,17 @@
                         <imageCell key="cell" refusesFirstResponder="YES" alignment="left" animates="YES" imageScaling="proportionallyUpOrDown" image="FermataIcon" id="1VP-dU-RCe"/>
                     </imageView>
                     <scrollView fixedFrame="YES" horizontalLineScroll="10" horizontalPageScroll="10" verticalLineScroll="10" verticalPageScroll="10" hasHorizontalScroller="NO" usesPredominantAxisScrolling="NO" translatesAutoresizingMaskIntoConstraints="NO" id="eqz-ap-PAC">
-                        <rect key="frame" x="393" y="45" width="567" height="245"/>
+                        <rect key="frame" x="415" y="45" width="567" height="245"/>
                         <autoresizingMask key="autoresizingMask" flexibleMaxX="YES" flexibleMinY="YES"/>
-                        <clipView key="contentView" ambiguous="YES" id="Cdb-RA-YK0">
+                        <clipView key="contentView" drawsBackground="NO" id="Cdb-RA-YK0">
                             <rect key="frame" x="1" y="1" width="565" height="243"/>
                             <autoresizingMask key="autoresizingMask" widthSizable="YES" heightSizable="YES"/>
                             <subviews>
-                                <textView ambiguous="YES" editable="NO" importsGraphics="NO" richText="NO" id="LSG-PF-cl8">
-                                    <rect key="frame" x="-4" y="0.0" width="572" height="243"/>
+                                <textView editable="NO" importsGraphics="NO" richText="NO" verticallyResizable="YES" id="LSG-PF-cl8">
+                                    <rect key="frame" x="-6" y="0.0" width="577" height="243"/>
                                     <autoresizingMask key="autoresizingMask" widthSizable="YES" heightSizable="YES"/>
-                                    <color key="backgroundColor" white="1" alpha="1" colorSpace="calibratedWhite"/>
+                                    <color key="textColor" name="textColor" catalog="System" colorSpace="catalog"/>
+                                    <color key="backgroundColor" name="textBackgroundColor" catalog="System" colorSpace="catalog"/>
                                     <size key="minSize" width="565" height="243"/>
                                     <size key="maxSize" width="594" height="10000000"/>
                                     <color key="insertionPointColor" name="controlTextColor" catalog="System" colorSpace="catalog"/>
@@ -222,31 +233,48 @@
                                     </allowedInputSourceLocales>
                                 </textView>
                             </subviews>
-                            <color key="backgroundColor" white="1" alpha="1" colorSpace="calibratedWhite"/>
                         </clipView>
-                        <scroller key="horizontalScroller" hidden="YES" verticalHuggingPriority="750" doubleValue="1" horizontal="YES" id="3jV-aP-AB7">
+                        <scroller key="horizontalScroller" hidden="YES" wantsLayer="YES" verticalHuggingPriority="750" doubleValue="1" horizontal="YES" id="3jV-aP-AB7">
                             <rect key="frame" x="-100" y="-100" width="87" height="18"/>
                             <autoresizingMask key="autoresizingMask"/>
                         </scroller>
-                        <scroller key="verticalScroller" verticalHuggingPriority="750" horizontal="NO" id="qCC-lY-zQ6">
+                        <scroller key="verticalScroller" wantsLayer="YES" verticalHuggingPriority="750" horizontal="NO" id="qCC-lY-zQ6">
                             <rect key="frame" x="550" y="1" width="16" height="243"/>
                             <autoresizingMask key="autoresizingMask"/>
                         </scroller>
                     </scrollView>
-                    <textField verticalHuggingPriority="750" horizontalCompressionResistancePriority="250" fixedFrame="YES" translatesAutoresizingMaskIntoConstraints="NO" id="6qu-yI-r00">
-                        <rect key="frame" x="391" y="20" width="203" height="11"/>
+                    <textField focusRingType="none" verticalHuggingPriority="750" horizontalCompressionResistancePriority="250" fixedFrame="YES" allowsCharacterPickerTouchBarItem="YES" translatesAutoresizingMaskIntoConstraints="NO" id="6qu-yI-r00">
+                        <rect key="frame" x="413" y="20" width="203" height="11"/>
                         <autoresizingMask key="autoresizingMask" flexibleMaxX="YES" flexibleMinY="YES"/>
                         <textFieldCell key="cell" lineBreakMode="truncatingTail" sendsActionOnEndEditing="YES" title="The AirPlay Logo is a trademark of Apple Inc." id="lx7-k3-q16">
-                            <font key="font" metaFont="miniSystem"/>
+                            <font key="font" metaFont="menu" size="9"/>
                             <color key="textColor" name="labelColor" catalog="System" colorSpace="catalog"/>
                             <color key="backgroundColor" name="controlColor" catalog="System" colorSpace="catalog"/>
                         </textFieldCell>
                     </textField>
+                    <textField focusRingType="none" horizontalHuggingPriority="251" verticalHuggingPriority="750" fixedFrame="YES" tag="2" allowsCharacterPickerTouchBarItem="YES" translatesAutoresizingMaskIntoConstraints="NO" id="Vy4-dv-jQB">
+                        <rect key="frame" x="18" y="75" width="155" height="16"/>
+                        <autoresizingMask key="autoresizingMask" flexibleMaxX="YES" flexibleMinY="YES"/>
+                        <textFieldCell key="cell" scrollable="YES" lineBreakMode="clipping" sendsActionOnEndEditing="YES" alignment="center" title="Copyright © 2016-2024" placeholderString="" id="ctF-95-uVu">
+                            <font key="font" metaFont="system"/>
+                            <color key="textColor" name="labelColor" catalog="System" colorSpace="catalog"/>
+                            <color key="backgroundColor" name="controlColor" catalog="System" colorSpace="catalog"/>
+                        </textFieldCell>
+                    </textField>
+                    <textField focusRingType="none" horizontalHuggingPriority="251" verticalHuggingPriority="750" fixedFrame="YES" tag="4" allowsCharacterPickerTouchBarItem="YES" translatesAutoresizingMaskIntoConstraints="NO" id="tRj-QC-GuQ" customClass="BGMLinkField">
+                        <rect key="frame" x="168" y="75" width="194" height="16"/>
+                        <autoresizingMask key="autoresizingMask" flexibleMaxX="YES" flexibleMinY="YES"/>
+                        <textFieldCell key="cell" scrollable="YES" lineBreakMode="clipping" selectable="YES" sendsActionOnEndEditing="YES" alignment="left" tag="3" title="Background Music contributors" placeholderString="" allowsEditingTextAttributes="YES" usesSingleLineMode="YES" id="UC2-MX-fML">
+                            <font key="font" metaFont="system"/>
+                            <color key="textColor" red="0.20000000000000001" green="0.40000000000000002" blue="0.59999999999999998" alpha="1" colorSpace="calibratedRGB"/>
+                            <color key="backgroundColor" name="controlColor" catalog="System" colorSpace="catalog"/>
+                        </textFieldCell>
+                    </textField>
                 </subviews>
             </view>
-            <point key="canvasLocation" x="-177" y="232.5"/>
+            <point key="canvasLocation" x="-200" y="232.5"/>
         </window>
-        <textField verticalHuggingPriority="750" horizontalCompressionResistancePriority="250" setsMaxLayoutWidthAtFirstLayout="YES" id="IoN-sN-cCx">
+        <textField focusRingType="none" verticalHuggingPriority="750" horizontalCompressionResistancePriority="250" setsMaxLayoutWidthAtFirstLayout="YES" allowsCharacterPickerTouchBarItem="YES" id="IoN-sN-cCx">
             <rect key="frame" x="0.0" y="0.0" width="471" height="180"/>
             <autoresizingMask key="autoresizingMask" flexibleMaxX="YES" flexibleMinY="YES"/>
             <textFieldCell key="cell" controlSize="mini" sendsActionOnEndEditing="YES" drawsBackground="YES" id="Ay8-8n-FHi">
@@ -258,59 +286,111 @@
             </textFieldCell>
             <point key="canvasLocation" x="-559" y="-118"/>
         </textField>
+        <customView id="JOz-H1-mj9" userLabel="Output Volume View">
+            <rect key="frame" x="0.0" y="0.0" width="269" height="47"/>
+            <autoresizingMask key="autoresizingMask" flexibleMaxX="YES" flexibleMinY="YES"/>
+            <subviews>
+                <slider identifier="Output Volume" verticalHuggingPriority="750" fixedFrame="YES" translatesAutoresizingMaskIntoConstraints="NO" id="9Ru-Sc-dqC" userLabel="Output Volume Slider">
+                    <rect key="frame" x="20" y="4" width="220" height="19"/>
+                    <autoresizingMask key="autoresizingMask" flexibleMaxX="YES" flexibleMinY="YES"/>
+                    <sliderCell key="cell" controlSize="small" continuous="YES" state="on" alignment="left" maxValue="1" tickMarkPosition="above" sliderType="linear" id="MzM-fe-nKb"/>
+                    <accessibility description="Output Volume" help="Sets the volume of your audio output device." identifier="Output Volume"/>
+                </slider>
+                <textField focusRingType="none" horizontalHuggingPriority="251" verticalHuggingPriority="750" fixedFrame="YES" translatesAutoresizingMaskIntoConstraints="NO" id="wfC-C6-SLv">
+                    <rect key="frame" x="20" y="25" width="226" height="17"/>
+                    <autoresizingMask key="autoresizingMask" flexibleMaxX="YES" flexibleMinY="YES"/>
+                    <textFieldCell key="cell" scrollable="YES" lineBreakMode="clipping" sendsActionOnEndEditing="YES" title="Volume" id="60O-ju-B5C">
+                        <font key="font" metaFont="system"/>
+                        <color key="textColor" name="labelColor" catalog="System" colorSpace="catalog"/>
+                        <color key="backgroundColor" name="controlColor" catalog="System" colorSpace="catalog"/>
+                    </textFieldCell>
+                </textField>
+            </subviews>
+            <point key="canvasLocation" x="117" y="-219"/>
+        </customView>
+        <customView id="dBD-CE-4dw" userLabel="Output Volume View">
+            <rect key="frame" x="0.0" y="0.0" width="269" height="16"/>
+            <autoresizingMask key="autoresizingMask" flexibleMaxX="YES" flexibleMinY="YES"/>
+            <subviews>
+                <slider identifier="System Sounds Volume" verticalHuggingPriority="750" fixedFrame="YES" translatesAutoresizingMaskIntoConstraints="NO" id="gyd-WV-2ju" userLabel="Output Volume Slider">
+                    <rect key="frame" x="163" y="0.0" width="74" height="15"/>
+                    <autoresizingMask key="autoresizingMask" flexibleMaxX="YES" flexibleMinY="YES"/>
+                    <sliderCell key="cell" controlSize="mini" continuous="YES" state="on" alignment="left" maxValue="1" doubleValue="1" tickMarkPosition="above" sliderType="linear" id="VDn-d8-XK3"/>
+                    <accessibility description="System Sounds Volume" help="Volume of alerts, notification sounds, etc. Usually short. Can be played by any app."/>
+                </slider>
+                <textField focusRingType="none" horizontalHuggingPriority="251" verticalHuggingPriority="750" fixedFrame="YES" translatesAutoresizingMaskIntoConstraints="NO" id="iKs-df-Hp6">
+                    <rect key="frame" x="42" y="1" width="86" height="14"/>
+                    <autoresizingMask key="autoresizingMask" flexibleMaxX="YES" flexibleMinY="YES"/>
+                    <textFieldCell key="cell" scrollable="YES" lineBreakMode="clipping" sendsActionOnEndEditing="YES" title="System Sounds" id="ATK-L8-s8z">
+                        <font key="font" metaFont="message" size="11"/>
+                        <color key="textColor" name="labelColor" catalog="System" colorSpace="catalog"/>
+                        <color key="backgroundColor" name="controlColor" catalog="System" colorSpace="catalog"/>
+                    </textFieldCell>
+                </textField>
+                <imageView identifier="SystemSoundsIcon" horizontalHuggingPriority="251" verticalHuggingPriority="251" fixedFrame="YES" translatesAutoresizingMaskIntoConstraints="NO" id="V2D-eM-8yN">
+                    <rect key="frame" x="20" y="1" width="16" height="16"/>
+                    <autoresizingMask key="autoresizingMask" flexibleMaxX="YES" flexibleMinY="YES"/>
+                    <imageCell key="cell" refusesFirstResponder="YES" alignment="left" imageScaling="proportionallyDown" image="NSComputer" id="8Xp-9S-hOz"/>
+                </imageView>
+            </subviews>
+            <point key="canvasLocation" x="116.5" y="-133"/>
+        </customView>
     </objects>
     <resources>
-        <image name="F928CF85-B22A-4634-8160-BC84F45043E3" width="1" height="1">
+        <image name="FermataIcon" width="284" height="284"/>
+        <image name="NSComputer" width="32" height="32"/>
+        <image name="buttonCell:IXo-C7-3uE:image" width="1" height="1">
             <mutableData key="keyedArchiveRepresentation">
-YnBsaXN0MDDUAQIDBAUGPT5YJHZlcnNpb25YJG9iamVjdHNZJGFyY2hpdmVyVCR0b3ASAAGGoK4HCBMU
-GR4fIyQrLjE3OlUkbnVsbNUJCgsMDQ4PEBESVk5TU2l6ZVYkY2xhc3NcTlNJbWFnZUZsYWdzVk5TUmVw
-c1dOU0NvbG9ygAKADRIgwwAAgAOAC1Z7MSwgMX3SFQoWGFpOUy5vYmplY3RzoReABIAK0hUKGh2iGxyA
-BYAGgAkQANIgCiEiXxAUTlNUSUZGUmVwcmVzZW50YXRpb26AB4AITxEIrE1NACoAAAAKAAAADgEAAAMA
-AAABAAEAAAEBAAMAAAABAAEAAAECAAMAAAACAAgACAEDAAMAAAABAAEAAAEGAAMAAAABAAEAAAERAAQA
-AAABAAAACAESAAMAAAABAAEAAAEVAAMAAAABAAIAAAEWAAMAAAABAAEAAAEXAAQAAAABAAAAAgEcAAMA
-AAABAAEAAAFSAAMAAAABAAEAAAFTAAMAAAACAAEAAYdzAAcAAAf0AAAAuAAAAAAAAAf0YXBwbAIgAABt
-bnRyR1JBWVhZWiAH0AACAA4ADAAAAABhY3NwQVBQTAAAAABub25lAAAAAAAAAAAAAAAAAAAAAAAA9tYA
-AQAAAADTLWFwcGwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAVk
-ZXNjAAAAwAAAAG9kc2NtAAABMAAABmZjcHJ0AAAHmAAAADh3dHB0AAAH0AAAABRrVFJDAAAH5AAAAA5k
-ZXNjAAAAAAAAABVHZW5lcmljIEdyYXkgUHJvZmlsZQAAAAAAAAAAAAAAFUdlbmVyaWMgR3JheSBQcm9m
-aWxlAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAbWx1YwAAAAAA
-AAAfAAAADHNrU0sAAAAqAAABhGVuVVMAAAAoAAABrmNhRVMAAAAsAAAB1nZpVk4AAAAsAAACAnB0QlIA
-AAAqAAACLnVrVUEAAAAsAAACWGZyRlUAAAAqAAAChGh1SFUAAAAuAAACrnpoVFcAAAAQAAAC3G5iTk8A
-AAAsAAAC7GtvS1IAAAAYAAADGGNzQ1oAAAAkAAADMGhlSUwAAAAgAAADVHJvUk8AAAAkAAADdGRlREUA
-AAA6AAADmGl0SVQAAAAuAAAD0nN2U0UAAAAuAAAEAHpoQ04AAAAQAAAELmphSlAAAAAWAAAEPmVsR1IA
-AAAkAAAEVHB0UE8AAAA4AAAEeG5sTkwAAAAqAAAEsGVzRVMAAAAoAAAE2nRoVEgAAAAkAAAFAnRyVFIA
-AAAiAAAFJmZpRkkAAAAsAAAFSGhySFIAAAA6AAAFdHBsUEwAAAA2AAAFrnJ1UlUAAAAmAAAF5GFyRUcA
-AAAoAAAGCmRhREsAAAA0AAAGMgBWAWEAZQBvAGIAZQBjAG4A/QAgAHMAaQB2AP0AIABwAHIAbwBmAGkA
-bABHAGUAbgBlAHIAaQBjACAARwByAGEAeQAgAFAAcgBvAGYAaQBsAGUAUABlAHIAZgBpAGwAIABkAGUA
-IABnAHIAaQBzACAAZwBlAG4A6AByAGkAYwBDHqUAdQAgAGgA7ABuAGgAIABNAOAAdQAgAHgA4QBtACAA
-QwBoAHUAbgBnAFAAZQByAGYAaQBsACAAQwBpAG4AegBhACAARwBlAG4A6QByAGkAYwBvBBcEMAQzBDAE
-OwRMBD0EOAQ5ACAEPwRABD4ERAQwBDkEOwAgAEcAcgBhAHkAUAByAG8AZgBpAGwAIABnAOkAbgDpAHIA
-aQBxAHUAZQAgAGcAcgBpAHMAwQBsAHQAYQBsAOEAbgBvAHMAIABzAHoA/AByAGsAZQAgAHAAcgBvAGYA
-aQBskBp1KHBwlo6Ccl9pY8+P8ABHAGUAbgBlAHIAaQBzAGsAIABnAHIA5QB0AG8AbgBlAHAAcgBvAGYA
-aQBsx3y8GAAgAEcAcgBhAHkAINUEuFzTDMd8AE8AYgBlAGMAbgD9ACABYQBlAGQA/QAgAHAAcgBvAGYA
-aQBsBeQF6AXVBeQF2QXcACAARwByAGEAeQAgBdsF3AXcBdkAUAByAG8AZgBpAGwAIABnAHIAaQAgAGcA
-ZQBuAGUAcgBpAGMAQQBsAGwAZwBlAG0AZQBpAG4AZQBzACAARwByAGEAdQBzAHQAdQBmAGUAbgAtAFAA
-cgBvAGYAaQBsAFAAcgBvAGYAaQBsAG8AIABnAHIAaQBnAGkAbwAgAGcAZQBuAGUAcgBpAGMAbwBHAGUA
-bgBlAHIAaQBzAGsAIABnAHIA5QBzAGsAYQBsAGUAcAByAG8AZgBpAGxmbpAacHBepmPPj/Blh072TgCC
-LDCwMOwwpDDXMO0w1TChMKQw6wOTA7UDvQO5A7oDzAAgA8ADwQO/A8YDrwO7ACADswO6A8EDuQBQAGUA
-cgBmAGkAbAAgAGcAZQBuAOkAcgBpAGMAbwAgAGQAZQAgAGMAaQBuAHoAZQBuAHQAbwBzAEEAbABnAGUA
-bQBlAGUAbgAgAGcAcgBpAGoAcwBwAHIAbwBmAGkAZQBsAFAAZQByAGYAaQBsACAAZwByAGkAcwAgAGcA
-ZQBuAOkAcgBpAGMAbw5CDhsOIw5EDh8OJQ5MDioONQ5ADhcOMg4XDjEOSA4nDkQOGwBHAGUAbgBlAGwA
-IABHAHIAaQAgAFAAcgBvAGYAaQBsAGkAWQBsAGUAaQBuAGUAbgAgAGgAYQByAG0AYQBhAHAAcgBvAGYA
-aQBpAGwAaQBHAGUAbgBlAHIAaQENAGsAaQAgAHAAcgBvAGYAaQBsACAAcwBpAHYAaQBoACAAdABvAG4A
-bwB2AGEAVQBuAGkAdwBlAHIAcwBhAGwAbgB5ACAAcAByAG8AZgBpAGwAIABzAHoAYQByAG8BWwBjAGkE
-HgQxBEkEOAQ5ACAEQQQ1BEAESwQ5ACAEPwRABD4ERAQ4BDsETAZFBkQGQQAgBioGOQYxBkoGQQAgAEcA
-cgBhAHkAIAYnBkQGOQYnBkUARwBlAG4AZQByAGUAbAAgAGcAcgDlAHQAbwBuAGUAYgBlAHMAawByAGkA
-dgBlAGwAcwBlAAB0ZXh0AAAAAENvcHlyaWdodCAyMDA3IEFwcGxlIEluYy4sIGFsbCByaWdodHMgcmVz
-ZXJ2ZWQuAFhZWiAAAAAAAADzUQABAAAAARbMY3VydgAAAAAAAAABAc0AANIlJicoWiRjbGFzc25hbWVY
-JGNsYXNzZXNfEBBOU0JpdG1hcEltYWdlUmVwoycpKlpOU0ltYWdlUmVwWE5TT2JqZWN00iUmLC1XTlNB
-cnJheaIsKtIlJi8wXk5TTXV0YWJsZUFycmF5oy8sKtMyMwo0NTZXTlNXaGl0ZVxOU0NvbG9yU3BhY2VE
-MCAwABADgAzSJSY4OVdOU0NvbG9yojgq0iUmOzxXTlNJbWFnZaI7Kl8QD05TS2V5ZWRBcmNoaXZlctE/
-QFRyb290gAEACAARABoAIwAtADIANwBGAEwAVwBeAGUAcgB5AIEAgwCFAIoAjACOAJUAmgClAKcAqQCr
-ALAAswC1ALcAuQC7AMAA1wDZANsJiwmQCZsJpAm3CbsJxgnPCdQJ3AnfCeQJ8wn3Cf4KBgoTChgKGgoc
-CiEKKQosCjEKOQo8Ck4KUQpWAAAAAAAAAgEAAAAAAAAAQQAAAAAAAAAAAAAAAAAAClg
+YnBsaXN0MDDUAQIDBAUGBwpYJHZlcnNpb25ZJGFyY2hpdmVyVCR0b3BYJG9iamVjdHMSAAGGoF8QD05T
+S2V5ZWRBcmNoaXZlctEICVRyb290gAGuCwwZGh8UJCkqMTQ3PUBVJG51bGzWDQ4PEBESExQVFhcYVk5T
+U2l6ZV5OU1Jlc2l6aW5nTW9kZVYkY2xhc3NcTlNJbWFnZUZsYWdzVk5TUmVwc1dOU0NvbG9ygAIQAIAN
+EiDDAACAA4ALVnsxLCAxfdIbDxweWk5TLm9iamVjdHOhHYAEgArSGw8gI6IhIoAFgAaACdMPJSYnKBRf
+EBROU1RJRkZSZXByZXNlbnRhdGlvbl8QGU5TSW50ZXJuYWxMYXlvdXREaXJlY3Rpb26ACIAHTxEIxE1N
+ACoAAAAKAAAAEAEAAAMAAAABAAEAAAEBAAMAAAABAAEAAAECAAMAAAACAAgACAEDAAMAAAABAAEAAAEG
+AAMAAAABAAEAAAEKAAMAAAABAAEAAAERAAQAAAABAAAACAESAAMAAAABAAEAAAEVAAMAAAABAAIAAAEW
+AAMAAAABAAEAAAEXAAQAAAABAAAAAgEcAAMAAAABAAEAAAEoAAMAAAABAAIAAAFSAAMAAAABAAEAAAFT
+AAMAAAACAAEAAYdzAAcAAAf0AAAA0AAAAAAAAAf0YXBwbAIgAABtbnRyR1JBWVhZWiAH0AACAA4ADAAA
+AABhY3NwQVBQTAAAAABub25lAAAAAAAAAAAAAAAAAAAAAAAA9tYAAQAAAADTLWFwcGwAAAAAAAAAAAAA
+AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAVkZXNjAAAAwAAAAG9kc2NtAAABMAAA
+BmZjcHJ0AAAHmAAAADh3dHB0AAAH0AAAABRrVFJDAAAH5AAAAA5kZXNjAAAAAAAAABVHZW5lcmljIEdy
+YXkgUHJvZmlsZQAAAAAAAAAAAAAAFUdlbmVyaWMgR3JheSBQcm9maWxlAAAAAAAAAAAAAAAAAAAAAAAA
+AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAbWx1YwAAAAAAAAAfAAAADHNrU0sAAAAqAAABhGVu
+VVMAAAAoAAABrmNhRVMAAAAsAAAB1nZpVk4AAAAsAAACAnB0QlIAAAAqAAACLnVrVUEAAAAsAAACWGZy
+RlUAAAAqAAAChGh1SFUAAAAuAAACrnpoVFcAAAAQAAAC3G5iTk8AAAAsAAAC7GtvS1IAAAAYAAADGGNz
+Q1oAAAAkAAADMGhlSUwAAAAgAAADVHJvUk8AAAAkAAADdGRlREUAAAA6AAADmGl0SVQAAAAuAAAD0nN2
+U0UAAAAuAAAEAHpoQ04AAAAQAAAELmphSlAAAAAWAAAEPmVsR1IAAAAkAAAEVHB0UE8AAAA4AAAEeG5s
+TkwAAAAqAAAEsGVzRVMAAAAoAAAE2nRoVEgAAAAkAAAFAnRyVFIAAAAiAAAFJmZpRkkAAAAsAAAFSGhy
+SFIAAAA6AAAFdHBsUEwAAAA2AAAFrnJ1UlUAAAAmAAAF5GFyRUcAAAAoAAAGCmRhREsAAAA0AAAGMgBW
+AWEAZQBvAGIAZQBjAG4A/QAgAHMAaQB2AP0AIABwAHIAbwBmAGkAbABHAGUAbgBlAHIAaQBjACAARwBy
+AGEAeQAgAFAAcgBvAGYAaQBsAGUAUABlAHIAZgBpAGwAIABkAGUAIABnAHIAaQBzACAAZwBlAG4A6ABy
+AGkAYwBDHqUAdQAgAGgA7ABuAGgAIABNAOAAdQAgAHgA4QBtACAAQwBoAHUAbgBnAFAAZQByAGYAaQBs
+ACAAQwBpAG4AegBhACAARwBlAG4A6QByAGkAYwBvBBcEMAQzBDAEOwRMBD0EOAQ5ACAEPwRABD4ERAQw
+BDkEOwAgAEcAcgBhAHkAUAByAG8AZgBpAGwAIABnAOkAbgDpAHIAaQBxAHUAZQAgAGcAcgBpAHMAwQBs
+AHQAYQBsAOEAbgBvAHMAIABzAHoA/AByAGsAZQAgAHAAcgBvAGYAaQBskBp1KHBwlo6Ccl9pY8+P8ABH
+AGUAbgBlAHIAaQBzAGsAIABnAHIA5QB0AG8AbgBlAHAAcgBvAGYAaQBsx3y8GAAgAEcAcgBhAHkAINUE
+uFzTDMd8AE8AYgBlAGMAbgD9ACABYQBlAGQA/QAgAHAAcgBvAGYAaQBsBeQF6AXVBeQF2QXcACAARwBy
+AGEAeQAgBdsF3AXcBdkAUAByAG8AZgBpAGwAIABnAHIAaQAgAGcAZQBuAGUAcgBpAGMAQQBsAGwAZwBl
+AG0AZQBpAG4AZQBzACAARwByAGEAdQBzAHQAdQBmAGUAbgAtAFAAcgBvAGYAaQBsAFAAcgBvAGYAaQBs
+AG8AIABnAHIAaQBnAGkAbwAgAGcAZQBuAGUAcgBpAGMAbwBHAGUAbgBlAHIAaQBzAGsAIABnAHIA5QBz
+AGsAYQBsAGUAcAByAG8AZgBpAGxmbpAacHBepmPPj/Blh072TgCCLDCwMOwwpDDXMO0w1TChMKQw6wOT
+A7UDvQO5A7oDzAAgA8ADwQO/A8YDrwO7ACADswO6A8EDuQBQAGUAcgBmAGkAbAAgAGcAZQBuAOkAcgBp
+AGMAbwAgAGQAZQAgAGMAaQBuAHoAZQBuAHQAbwBzAEEAbABnAGUAbQBlAGUAbgAgAGcAcgBpAGoAcwBw
+AHIAbwBmAGkAZQBsAFAAZQByAGYAaQBsACAAZwByAGkAcwAgAGcAZQBuAOkAcgBpAGMAbw5CDhsOIw5E
+Dh8OJQ5MDioONQ5ADhcOMg4XDjEOSA4nDkQOGwBHAGUAbgBlAGwAIABHAHIAaQAgAFAAcgBvAGYAaQBs
+AGkAWQBsAGUAaQBuAGUAbgAgAGgAYQByAG0AYQBhAHAAcgBvAGYAaQBpAGwAaQBHAGUAbgBlAHIAaQEN
+AGsAaQAgAHAAcgBvAGYAaQBsACAAcwBpAHYAaQBoACAAdABvAG4AbwB2AGEAVQBuAGkAdwBlAHIAcwBh
+AGwAbgB5ACAAcAByAG8AZgBpAGwAIABzAHoAYQByAG8BWwBjAGkEHgQxBEkEOAQ5ACAEQQQ1BEAESwQ5
+ACAEPwRABD4ERAQ4BDsETAZFBkQGQQAgBioGOQYxBkoGQQAgAEcAcgBhAHkAIAYnBkQGOQYnBkUARwBl
+AG4AZQByAGUAbAAgAGcAcgDlAHQAbwBuAGUAYgBlAHMAawByAGkAdgBlAGwAcwBlAAB0ZXh0AAAAAENv
+cHlyaWdodCAyMDA3IEFwcGxlIEluYy4sIGFsbCByaWdodHMgcmVzZXJ2ZWQuAFhZWiAAAAAAAADzUQAB
+AAAAARbMY3VydgAAAAAAAAABAc0AANIrLC0uWiRjbGFzc25hbWVYJGNsYXNzZXNfEBBOU0JpdG1hcElt
+YWdlUmVwoy0vMFpOU0ltYWdlUmVwWE5TT2JqZWN00issMjNXTlNBcnJheaIyMNIrLDU2Xk5TTXV0YWJs
+ZUFycmF5ozUyMNM4OQ86OzxXTlNXaGl0ZVxOU0NvbG9yU3BhY2VEMCAwABADgAzSKyw+P1dOU0NvbG9y
+oj4w0issQUJXTlNJbWFnZaJBMAAIABEAGgAkACkAMgA3AEkATABRAFMAYgBoAHUAfACLAJIAnwCmAK4A
+sACyALQAuQC7AL0AxADJANQA1gDYANoA3wDiAOQA5gDoAO8BBgEiASQBJgnuCfMJ/goHChoKHgopCjIK
+Nwo/CkIKRwpWCloKYQppCnYKewp9Cn8KhAqMCo8KlAqcAAAAAAAAAgEAAAAAAAAAQwAAAAAAAAAAAAAA
+AAAACp8
 </mutableData>
         </image>
-        <image name="FermataIcon" width="284" height="284"/>
     </resources>
 </document>

BGMApp/BGMApp/Images.xcassets/Volume0.imageset/Contents.json

@@ -0,0 +1,12 @@
+{
+  "images" : [
+    {
+      "idiom" : "mac",
+      "filename" : "Volume0.pdf"
+    }
+  ],
+  "info" : {
+    "version" : 1,
+    "author" : "xcode"
+  }
+}

BGMApp/BGMApp/Images.xcassets/Volume1.imageset/Contents.json

@@ -0,0 +1,12 @@
+{
+  "images" : [
+    {
+      "idiom" : "mac",
+      "filename" : "Volume1.pdf"
+    }
+  ],
+  "info" : {
+    "version" : 1,
+    "author" : "xcode"
+  }
+}

BGMApp/BGMApp/Images.xcassets/Volume2.imageset/Contents.json

@@ -0,0 +1,12 @@
+{
+  "images" : [
+    {
+      "idiom" : "mac",
+      "filename" : "Volume2.pdf"
+    }
+  ],
+  "info" : {
+    "version" : 1,
+    "author" : "xcode"
+  }
+}

BGMApp/BGMApp/Images.xcassets/Volume3.imageset/Contents.json

@@ -0,0 +1,12 @@
+{
+  "images" : [
+    {
+      "idiom" : "mac",
+      "filename" : "Volume3.pdf"
+    }
+  ],
+  "info" : {
+    "version" : 1,
+    "author" : "xcode"
+  }
+}

BGMApp/BGMApp/Info.plist

@@ -17,7 +17,7 @@
 	<key>CFBundlePackageType</key>
 	<string>APPL</string>
 	<key>CFBundleShortVersionString</key>
-	<string>0.1.0</string>
+	<string>0.4.3</string>
 	<key>CFBundleSignature</key>
 	<string>????</string>
 	<key>CFBundleVersion</key>
@@ -28,11 +28,29 @@
 	<string>$(MACOSX_DEPLOYMENT_TARGET)</string>
 	<key>LSUIElement</key>
 	<true/>
+	<key>NSAppleEventsUsageDescription</key>
+	<string>Background Music needs to control your music player app if you want it to automatically pause your music.</string>
+	<key>NSAppleScriptEnabled</key>
+	<true/>
 	<key>NSHumanReadableCopyright</key>
-	<string>Copyright © 2016 Background Music contributors</string>
+	<string>Copyright © 2016-2024 Background Music contributors</string>
 	<key>NSMainNibFile</key>
 	<string>MainMenu</string>
+	<key>NSMicrophoneUsageDescription</key>
+	<string>The &quot;Background Music&quot; virtual audio device sends system audio to Background Music (the app) through a virtual input device.</string>
 	<key>NSPrincipalClass</key>
 	<string>NSApplication</string>
+	<key>NSServices</key>
+	<array>
+		<dict/>
+	</array>
+	<key>OSAScriptingDefinition</key>
+	<string>BGMApp.sdef</string>
+    <!--
+    Hopefully this will keep Background Music from using the discrete GPU on multi-GPU systems,
+    which wastes energy. I don't have any hardware I could easily test this on, so it's untested.
+    -->
+	<key>NSSupportsAutomaticGraphicsSwitching</key>
+	<true/>
 </dict>
 </plist>

BGMApp/BGMApp/Music Players/BGMDecibel.m

@@ -17,7 +17,7 @@
 //  BGMDecibel.m
 //  BGMApp
 //
-//  Copyright © 2016 Kyle Neideck
+//  Copyright © 2016-2018 Kyle Neideck
 //  Copyright © 2016 Tanner Hoke
 //
 
@@ -31,9 +31,7 @@
 #import "BGMScriptingBridge.h"
 
 // PublicUtility Includes
-#undef CoreAudio_ThreadStampMessages
-#define CoreAudio_ThreadStampMessages 0  // Requires C++
-#include "CADebugMacros.h"
+#import "CADebugMacros.h"
 
 
 #pragma clang assume_nonnull begin
@@ -42,11 +40,11 @@
     BGMScriptingBridge* scriptingBridge;
 }
 
-- (id) init {
+- (instancetype) init {
     if ((self = [super initWithMusicPlayerID:[BGMMusicPlayerBase makeID:@"A9790CD5-4886-47C7-9FFC-DD70743CF2BF"]
                                         name:@"Decibel"
                                     bundleID:@"org.sbooth.Decibel"])) {
-        scriptingBridge = [[BGMScriptingBridge alloc] initWithBundleID:(NSString*)self.bundleID];
+        scriptingBridge = [[BGMScriptingBridge alloc] initWithMusicPlayer:self];
     }
     
     return self;
@@ -56,6 +54,11 @@
     return (DecibelApplication* __nullable)scriptingBridge.application;
 }
 
+- (void) wasSelected {
+    [super wasSelected];
+    [scriptingBridge ensurePermission];
+}
+
 - (BOOL) isRunning {
     return self.decibel.running;
 }

BGMApp/BGMApp/Music Players/BGMGooglePlayMusicDesktopPlayer.h

@@ -0,0 +1,46 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMGooglePlayMusicDesktopPlayer.h
+//  BGMApp
+//
+//  Copyright © 2019 Kyle Neideck
+//
+//  We have a lot more code for GPMDP than most music players largely because GPMDP has a WebSockets
+//  API and because the user has to enter a code from GPMDP to allow BGMApp to control it.
+//  Currently, the other music players all have AppleScript APIs, so for them the OS asks the user
+//  for permission on our behalf automatically and handles the whole process for us.
+//
+//  This class implements the usual BGMMusicPlayer methods and handles the UI for authenticating
+//  with GPMDP. BGMGooglePlayMusicDesktopPlayerConnection manages the connection to GPMDP and hides
+//  the details of its API.
+//
+
+// Superclass/Protocol Import
+#import "BGMMusicPlayer.h"
+
+
+#pragma clang assume_nonnull begin
+
+API_AVAILABLE(macos(10.10))
+@interface BGMGooglePlayMusicDesktopPlayer : BGMMusicPlayerBase<BGMMusicPlayer>
+
++ (NSArray<id<BGMMusicPlayer>>*) createInstancesWithDefaults:(BGMUserDefaults*)userDefaults;
+
+@end
+
+#pragma clang assume_nonnull end
+

BGMApp/BGMApp/Music Players/BGMGooglePlayMusicDesktopPlayer.m

@@ -0,0 +1,342 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMGooglePlayMusicDesktopPlayer.m
+//  BGMApp
+//
+//  Copyright © 2019 Kyle Neideck
+//
+
+// Self Include
+#import "BGMGooglePlayMusicDesktopPlayer.h"
+
+// Local Includes
+#import "BGM_Types.h"
+#import "BGM_Utils.h"
+#import "BGMAppWatcher.h"
+#import "BGMGooglePlayMusicDesktopPlayerConnection.h"
+
+// PublicUtility Includes
+#import "CADebugMacros.h"
+
+
+#pragma clang assume_nonnull begin
+
+@implementation BGMGooglePlayMusicDesktopPlayer {
+    BGMUserDefaults* userDefaults;
+    BGMGooglePlayMusicDesktopPlayerConnection* connection;
+    BGMAppWatcher* appWatcher;
+
+    // True while the auth code dialog is open. The user types in the four-digit auth code from
+    // GPMDP when we connect to it for the first time.
+    BOOL showingAuthCodeDialog;
+    // True if the user has cancelled the auth code dialog. We only show the auth code dialog again
+    // after the user has changed the music player and then changed it back to GPMDP (or restarted
+    // BGMApp).
+    BOOL authCancelled;
+}
+
++ (NSArray<id<BGMMusicPlayer>>*) createInstancesWithDefaults:(BGMUserDefaults*)userDefaults {
+    return @[[[self alloc] initWithUserDefaults:userDefaults]];
+}
+
+- (instancetype) initWithUserDefaults:(BGMUserDefaults*)defaults {
+    // If you're copying this class, replace the ID string with a new one generated by uuidgen (the
+    // command line tool).
+    NSUUID* playerID = [BGMMusicPlayerBase makeID:@"FCDCC01F-4BF1-4AD2-BE3E-6B7659A90A3F"];
+    if ((self = [super initWithMusicPlayerID:playerID
+                                        name:@"GPMDP"
+                                     toolTip:@"Google Play Music Desktop Player"
+                                    bundleID:@"google-play-music-desktop-player"])) {
+        userDefaults = defaults;
+        showingAuthCodeDialog = NO;
+        authCancelled = NO;
+
+        // We don't strictly need to use a weak ref (at least not yet), but it doesn't hurt.
+        BGMGooglePlayMusicDesktopPlayer* __weak weakSelf = self;
+
+        connection = [[BGMGooglePlayMusicDesktopPlayerConnection alloc]
+                initWithUserDefaults:userDefaults
+                 authRequiredHandler:^{
+                     BGMGooglePlayMusicDesktopPlayer* strongSelf = weakSelf;
+                     return [strongSelf requestAuthCodeFromUser];
+                 }
+              connectionErrorHandler:^{
+                  BGMGooglePlayMusicDesktopPlayer* strongSelf = weakSelf;
+                  [strongSelf showConnectionErrorDialog];
+              }
+           apiVersionMismatchHandler:^(NSString* reportedAPIVersion) {
+               BGMGooglePlayMusicDesktopPlayer* strongSelf = weakSelf;
+               [strongSelf showAPIVersionMismatchDialog:reportedAPIVersion];
+           }];
+
+        // Set up callbacks that run when GPMDP is opened or closed.
+        appWatcher = [[BGMAppWatcher alloc]
+                initWithBundleID:BGMNN(self.bundleID)
+                     appLaunched:^{
+                         BGMGooglePlayMusicDesktopPlayer* strongSelf = weakSelf;
+                         [strongSelf gpmdpWasLaunched];
+                     }
+                   appTerminated:^{
+                       BGMGooglePlayMusicDesktopPlayer* strongSelf = weakSelf;
+                       [strongSelf gpmdpWasTerminated];
+                   }];
+    }
+    
+    return self;
+}
+
+- (void) gpmdpWasLaunched {
+    if (self.selected) {
+        // Reconnect so we can control GPMDP.
+        DebugMsg("BGMGooglePlayMusicDesktopPlayer::gpmdpWasLaunched: GPMDP launched. Connecting");
+
+        // Try up to 10 times because GPMDP won't start accepting connections until it's finished
+        // starting up.
+        //
+        // TODO: If GPMDP shows an alert before it finishes launching, it doesn't start accepting
+        //       connections until the alert is dismissed, which can make this can timeout.
+        // TODO: Is the error dialog still shown if the user closes GPMDP again while we're
+        //       retrying? It shouldn't be.
+        [connection connectWithRetries:10];
+    }
+}
+
+- (void) gpmdpWasTerminated {
+    if (self.selected) {
+        // Allow the connection to clean up and reset itself.
+        DebugMsg("BGMGooglePlayMusicDesktopPlayer::gpmdpWasTerminated: GPMDP has been closed.");
+        [connection disconnect];
+    }
+}
+
+- (void) wasSelected {
+    [super wasSelected];
+
+    // Allow the auth code dialog to be shown again if we were hiding it because the user cancelled
+    // it last time.
+    authCancelled = NO;
+
+    if (self.running) {
+        // Only retry once so the error message is shown fairly quickly if we fail to connect.
+        [connection connectWithRetries:1];
+    }
+}
+
+- (void) wasDeselected {
+    [super wasDeselected];
+    [connection disconnect];
+}
+
+- (NSString* __nullable) requestAuthCodeFromUser {
+    if (showingAuthCodeDialog) {
+        DebugMsg("BGMGooglePlayMusicDesktopPlayer::requestAuthCodeFromUser: "
+                 "Already showing the auth code dialog");
+        return nil;
+    }
+
+    if (authCancelled) {
+        DebugMsg("BGMGooglePlayMusicDesktopPlayer::requestAuthCodeFromUser: "
+                 "Previously cancelled. Doing nothing.");
+        return nil;
+    }
+
+    showingAuthCodeDialog = YES;
+
+    // Ask the user to read the auth code from GPMDP and type it in to BGMApp.
+    NSString* __nullable authCode = [self showAuthCodeDialog];
+
+    showingAuthCodeDialog = NO;
+
+    return authCode;
+}
+
+- (NSString* __nullable) showAuthCodeDialog {
+    // When this isn't being called because the user just changed something in BGMApp (e.g. GPMDP
+    // was closed, they selected it in BGMApp for the first time, then opened GPMDP later), we could
+    // use notifications instead of an NSAlert. But it probably wouldn't happen often enough to be
+    // worth the effort.
+    NSAlert* alert = [NSAlert new];
+    alert.messageText = @"Background Music needs permission to control GPMDP.";
+    alert.informativeText = @"It should be displaying a four-digit code for you to enter.";
+    [alert addButtonWithTitle:@"OK"];
+    [alert addButtonWithTitle:@"Cancel"];
+
+    // The text field to type the auth code in.
+    // TODO: Can we derive these dimensions from something instead of hardcoding them?
+    NSTextField* input = [[NSTextField alloc] initWithFrame:NSMakeRect(0, 0, 50, 24)];
+    [alert setAccessoryView:input];
+
+    // Focus the text field (so the user doesn't have to do it themselves).
+    [alert.window setInitialFirstResponder:input];
+
+    // Bring GMPDP to the front, underneath our NSAlert, so the user can see the auth code.
+    [self showGPMDPBehindAuthCodeDialog];
+
+    NSModalResponse buttonPressed = [alert runModal];
+
+    if (buttonPressed == NSAlertFirstButtonReturn) {
+        // Set input's value to the text entered by the user so we can access it.
+        [input validateEditing];
+
+        DebugMsg("BGMGooglePlayMusicDesktopPlayer::showAuthCodeDialog: Got auth code: <private>");
+        return input.stringValue;
+    } else {
+        DebugMsg("BGMGooglePlayMusicDesktopPlayer::showAuthCodeDialog: "
+                 "The user cancelled the auth code dialog");
+        authCancelled = YES;
+        return nil;
+    }
+}
+
+- (void) showGPMDPBehindAuthCodeDialog {
+    // Dispatched because if we do this just before showing the auth code dialog, the user's current
+    // active window will be deactivated, the auth code dialog will become the active window and
+    // macOS will act as if the user activated it themselves. To avoid stealing key focus, it won't
+    // activate GPMDP.
+    //
+    // We could pass NSApplicationActivateIgnoringOtherApps to activateWithOptions instead, but then
+    // GPMDP would be activated even if the user really did activate a different application, which
+    // would steal focus from it.
+    //
+    // 250 ms is a reasonable value on my system, but won't always be long enough. When it isn't,
+    // GPMDP won't be activated, but that just means the user will have to do it themselves.
+    const int64_t delay = 250 * NSEC_PER_MSEC;
+
+    dispatch_after(dispatch_time(DISPATCH_TIME_NOW, delay),
+                   dispatch_get_main_queue(),
+                   ^{
+                       // Make GMPDP the frontmost app.
+                       NSArray<NSRunningApplication*>* gpmdpApps =
+                           [NSRunningApplication
+                            runningApplicationsWithBundleIdentifier:BGMNN(self.bundleID)];
+
+                       if (gpmdpApps.count > 0) {
+                           [gpmdpApps[0] activateWithOptions:0];
+                       }
+
+                       // Focus the auth code dialog. It will already be in front of GPMDP because
+                       // it's modal. Dispatched for the same reason as above.
+                       dispatch_after(dispatch_time(DISPATCH_TIME_NOW, delay),
+                                      dispatch_get_main_queue(),
+                                      ^{
+                                          [NSApp activateIgnoringOtherApps:YES];
+                                      });
+                   });
+}
+
+- (void) showConnectionErrorDialog {
+    NSString* errorMsg = @"Could not connect to Google Play Music Desktop Player";
+    NSString* troubleshootingMsg =
+        [NSString stringWithFormat:
+         @"Make sure \"Enable JSON API\" and \"Enable Playback API\" are both checked in GPMDP's "
+         "settings, then restart GPMDP.\n\n"
+         "GPMDP should be listening on its default port, 5672.\n\n"
+         "Consider filing a bug report at %s",
+         kBGMIssueTrackerURL];
+
+    [self showErrorDialog:errorMsg troubleshootingMsg:troubleshootingMsg];
+}
+
+- (void) showAPIVersionMismatchDialog:(NSString*)reportedAPIVersion {
+    NSString* errorMsg = @"Google Play Music Desktop Player Version Not Supported";
+    NSString* troubleshootingMsg =
+            [NSString stringWithFormat:
+             @"GPMDP reported its API version as \"%@\", which Background Music doesn't support "
+             "yet. Background Music might not be able to control GPMDP properly.\n\n"
+             "Feel free to open an issue about this at %s",
+             reportedAPIVersion,
+             kBGMIssueTrackerURL];
+
+    [self showErrorDialog:errorMsg troubleshootingMsg:troubleshootingMsg];
+}
+
+- (void) showErrorDialog:(NSString*)errorMsg troubleshootingMsg:(NSString*)troubleshootingMsg {
+    if (!self.running) {
+        // GPMDP isn't running, so there's no need to inform the user. (The "Auto-pause GPMDP" menu
+        // item will be greyed out, but that's handled elsewhere.)
+        DebugMsg("BGMGooglePlayMusicDesktopPlayer::showErrorDialog: Not running");
+        return;
+    }
+
+    NSLog(@"%@", errorMsg);
+
+    // Show the error in a UI dialog.
+    NSAlert* alert = [NSAlert new];
+    alert.messageText = errorMsg;
+    alert.informativeText = troubleshootingMsg;
+    // TODO: Show the suppression checkbox and save its value in user defaults.
+    alert.showsSuppressionButton = NO;
+    [alert addButtonWithTitle:@"OK"];
+
+    [alert runModal];
+}
+
+- (BOOL) isRunning {
+    // We have to check with NSRunningApplication instead of just setting a flag in appWatcher's
+    // callbacks because BGMAutoPauseMenuItem calls this method when it's notified by its own
+    // instance of BGMAppWatcher. If BGMAutoPauseMenuItem got notified first, the flag wouldn't be
+    // updated in time.
+    //
+    // At some point we might want to try to avoid this by making the BGMMusicPlayers' running
+    // properties observable.
+    NSArray<NSRunningApplication*>* instances =
+        [NSRunningApplication runningApplicationsWithBundleIdentifier:BGMNN(self.bundleID)];
+
+    return instances.count > 0;
+}
+
+- (BOOL) isPlaying {
+    return self.running && connection.playing;
+}
+
+- (BOOL) isPaused {
+    return self.running && connection.paused;
+}
+
+- (BOOL) pause {
+    // isPlaying checks isRunning, so we don't need to check it here.
+    BOOL wasPlaying = self.playing;
+    
+    if (wasPlaying) {
+        DebugMsg("BGMGooglePlayMusicDesktopPlayer::pause: Pausing Google Play Music Desktop "
+                 "Player");
+        // There's a race condition here and in unpause because, if the user paused GPMDP just
+        // before we called playPause, GPMDP would play instead of pausing. I'm not sure there's
+        // much we can/should do about it.
+        [connection playPause];
+    }
+    
+    return wasPlaying;
+}
+
+- (BOOL) unpause {
+    // isPaused checks isRunning, so we don't need to check it here.
+    BOOL wasPaused = self.paused;
+    
+    if (wasPaused) {
+        DebugMsg("BGMGooglePlayMusicDesktopPlayer::unpause: Unpausing Google Play Music Desktop "
+                 "Player");
+        [connection playPause];
+    }
+    
+    return wasPaused;
+}
+
+@end
+
+#pragma clang assume_nonnull end
+

BGMApp/BGMApp/Music Players/BGMGooglePlayMusicDesktopPlayerConnection.h

@@ -0,0 +1,64 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMGooglePlayMusicDesktopPlayerConnection.h
+//  BGMApp
+//
+//  Copyright © 2019 Kyle Neideck
+//
+
+// Local Includes
+#import "BGMUserDefaults.h"
+
+// System Includes
+#import <Cocoa/Cocoa.h>
+#import <WebKit/WebKit.h>
+
+
+#pragma clang assume_nonnull begin
+
+API_AVAILABLE(macos(10.10))
+@interface BGMGooglePlayMusicDesktopPlayerConnection : NSObject<WKScriptMessageHandler>
+
+// authRequiredHandler: A UI callback that asks the user for the auth code GPMDP will display.
+//                      Returns the auth code they entered, or nil.
+// connectionErrorHandler: A UI callback that shows a connection error message.
+// apiVersionMismatchHandler: A UI callback that shows a warning dialog explaining that GPMDP
+//                            reported an API version that we don't support yet.
+- (instancetype) initWithUserDefaults:(BGMUserDefaults*)defaults
+                  authRequiredHandler:(NSString* __nullable (^)(void))authHandler
+               connectionErrorHandler:(void (^)(void))errorHandler
+            apiVersionMismatchHandler:(void (^)(NSString* reportedAPIVersion))apiVersionHandler;
+
+// Returns before the connection has been fully established. The playing and paused properties will
+// remain false until the connection is complete, but playPause can be called at any time after
+// calling this method.
+//
+// If the connection fails, it will be retried after a one second delay, up to the number of times
+// given.
+- (void) connectWithRetries:(int)retries;
+- (void) disconnect;
+
+// Tell GPMDP to play if it's paused or pause if it's playing.
+- (void) playPause;
+
+@property (readonly) BOOL playing;
+@property (readonly) BOOL paused;
+
+@end
+
+#pragma clang assume_nonnull end
+

BGMApp/BGMApp/Music Players/BGMGooglePlayMusicDesktopPlayerConnection.m

@@ -0,0 +1,444 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMGooglePlayMusicDesktopPlayerConnection.m
+//  BGMApp
+//
+//  Copyright © 2019 Kyle Neideck
+//
+
+// Self Include
+#import "BGMGooglePlayMusicDesktopPlayerConnection.h"
+
+// Local Includes
+#import "BGM_Utils.h"
+
+// PublicUtility Includes
+#import "CADebugMacros.h"
+
+
+#pragma clang assume_nonnull begin
+
+// When GooglePlayMusicDesktopPlayer.js sends a message to this class, it sets the message handler
+// name to one of these, which tells us what type of message it is. (This is a macro because you
+// can't make a static const NSArray.)
+#define kScriptMessageHandlerNames (@[@"gpmdp", @"log", @"error"])
+
+@implementation BGMGooglePlayMusicDesktopPlayerConnection {
+    // GPMDP has a WebSocket API, so we use a WKWebView to access it using Javascript. Using a
+    // proper library would make the code a bit cleaner and save a little memory, but I'm not sure
+    // it would be worth adding an external dependency for that.
+    WKWebView* webView;
+    NSString* __nullable permanentAuthCode;
+    BGMUserDefaults* userDefaults;
+    // The number of times to retry if we fail to connect. For example, if GPMDP is still starting
+    // up. Set to 0 when we aren't trying to connect.
+    int connectionRetries;
+
+    // A UI callback that asks the user for the auth code GPMDP will display.
+    NSString* __nullable (^authRequiredHandler)(void);
+    // A UI callback that shows a connection error message.
+    void (^connectionErrorHandler)(void);
+    // A UI callback that shows a warning dialog explaining that GPMDP reported an API version that
+    // we don't support yet.
+    void (^apiVersionMismatchHandler)(NSString* reportedAPIVersion);
+}
+
+- (instancetype) initWithUserDefaults:(BGMUserDefaults*)defaults
+                  authRequiredHandler:(NSString* __nullable (^)(void))authHandler
+               connectionErrorHandler:(void (^)(void))errorHandler
+            apiVersionMismatchHandler:(void (^)(NSString* reportedAPIVersion))apiVersionHandler {
+    if((self = [super init])) {
+        userDefaults = defaults;
+        authRequiredHandler = authHandler;
+        connectionErrorHandler = errorHandler;
+        apiVersionMismatchHandler = apiVersionHandler;
+        connectionRetries = 0;
+
+        // Lazily initialised.
+        permanentAuthCode = nil;
+
+        // Report that GPMDP is stopped until we know otherwise.
+        _playing = NO;
+        _paused = NO;
+    }
+
+    return self;
+}
+
+// Creates and initialises webView, a WKWebView we use to communicate with GPMDP over WebSockets.
+- (void) createWebView {
+    // Read the Javascript we'll need for this.
+    NSString* __nullable jsPath =
+            [[NSBundle mainBundle] pathForResource:@"GooglePlayMusicDesktopPlayer.js"
+                                            ofType:nil];
+    NSError* err;
+    NSString* __nullable jsStr =
+        (!jsPath ? nil : [NSString stringWithContentsOfFile:BGMNN(jsPath)
+                                                   encoding:NSUTF8StringEncoding
+                                                      error:&err]);
+
+    if (err || !jsStr || [jsStr isEqualToString:@""]) {
+        // TODO: Return an error so the caller can show an error dialog or something.
+        NSLog(@"Error loading GPMDP Javascript file: %@", err);
+    } else {
+        webView = [WKWebView new];
+
+        // Register to receive messages from our Javascript. The messages are handled in
+        // userContentController. We register several times using different names as a convenient
+        // way to separate messages from GPMDP, messages to log and errors.
+        for (NSString* name in kScriptMessageHandlerNames) {
+            [webView.configuration.userContentController addScriptMessageHandler:self name:name];
+        }
+
+        // Load our Javascript functions into webView so we can call them later.
+        [self evaluateJavaScript:BGMNN(jsStr)];
+    }
+}
+
+- (void) connectWithRetries:(int)retries {
+    if (retries < 0) {
+        BGMAssert(false, "retries < 0");
+        return;
+    }
+
+    if (!permanentAuthCode) {
+        // Read the API auth code from user defaults (actually the keychain), if there is one. If
+        // the user hasn't authenticated before, it will be nil.
+        //
+        // We do this lazily because it can show a password dialog in debug/unsigned builds.
+        permanentAuthCode = userDefaults.googlePlayMusicDesktopPlayerPermanentAuthCode;
+    }
+
+    connectionRetries = retries;
+
+    // Create the WKWebView we'll use to connect to GPMDP with WebSockets. Using a WKWebView means
+    // Background Music uses a bit more memory while connected to GPMDP, around 15 MB for me, but
+    // saves us having to complicate the build process to add a dependency on a proper library.
+    [self createWebView];
+
+    if (permanentAuthCode) {
+        DebugMsg("BGMGooglePlayMusicDesktopPlayerConnection::connectWithRetries: "
+                 "Connecting with auth code");
+
+        NSString* __nullable percentEncodedCode =
+                [BGMGooglePlayMusicDesktopPlayerConnection
+                        toPercentEncoded:BGMNN(permanentAuthCode)];
+
+        [self evaluateJavaScript:[NSString stringWithFormat:@"connect('%@');", percentEncodedCode]];
+    } else {
+        DebugMsg("BGMGooglePlayMusicDesktopPlayerConnection::connectWithRetries: "
+                 "Connecting without auth code");
+        [self evaluateJavaScript:@"connect();"];
+    }
+
+    // Check whether GPMDP is playing, paused or stopped.
+    [self requestPlaybackState];
+}
+
+- (void) disconnect {
+    // Stop retrying if we're in the process of connecting.
+    connectionRetries = 0;
+
+    // evaluateJavaScript is only safe to call on the main thread.
+    dispatch_async(dispatch_get_main_queue(), ^{
+        DebugMsg("BGMGooglePlayMusicDesktopPlayerConnection::disconnect: Disconnecting");
+
+        [webView evaluateJavaScript:@"disconnect();"
+                  completionHandler:^(id __nullable result, NSError* __nullable error) {
+#pragma unused (result)
+                      if (error) {
+                          NSLog(@"Error closing connection to GPMDP: %@", error);
+                      }
+
+                      // Allow the WKWebView to be garbage collected.
+                      for (NSString* name in kScriptMessageHandlerNames) {
+                          [webView.configuration.userContentController
+                                  removeScriptMessageHandlerForName:name];
+                      }
+                      webView = nil;
+                  }];
+    });
+}
+
+- (void) evaluateJavaScript:(NSString*)js {
+    // evaluateJavaScript is only safe to call on the main thread.
+    dispatch_async(dispatch_get_main_queue(), ^{
+        [webView evaluateJavaScript:js
+                  completionHandler:^(id __nullable result, NSError* __nullable error) {
+#pragma unused (result)
+                      if (error) {
+                          // TODO: We should probably show an error dialog in some cases.
+                          NSLog(@"JS error: %@", error);
+                      }
+                  }];
+    });
+}
+
+- (void) playPause {
+    [self evaluateJavaScript:@"playPause();"];
+}
+
+- (void) sendAuthCode:(NSString*)authCode {
+    // Don't log the code itself just in case it could be a security problem.
+    DebugMsg("BGMGooglePlayMusicDesktopPlayerConnection::sendAuthCode: Sending GPMDP auth code");
+
+    // Percent-encode the user input just in case they entered something that could execute as
+    // Javascript. We could limit the input to four digits instead, but this should be fine.
+    NSString* __nullable percentEncodedCode =
+            [BGMGooglePlayMusicDesktopPlayerConnection toPercentEncoded:authCode];
+
+    // We send the message to GPMDP even if percentEncodedCode is nil so it will reply with an error
+    // and BGMApp will ask the user for the auth code again.
+    NSString* js = [NSString stringWithFormat:@"window.sendAuthCode('%@');", percentEncodedCode];
+    [self evaluateJavaScript:js];
+}
+
+- (void) sendPermanentAuthCode {
+    NSString* __nullable code = permanentAuthCode;
+
+    if (code) {
+        // Don't log the code itself just in case it could be a security problem.
+        DebugMsg("BGMGooglePlayMusicDesktopPlayerConnection::sendPermanentAuthCode: "
+                 "Sending GPMDP permanent auth code");
+
+        // Percent-encode it just in case something it includes could be executed as Javascript.
+        NSString* __nullable percentEncodedCode =
+                [BGMGooglePlayMusicDesktopPlayerConnection toPercentEncoded:BGMNN(code)];
+
+        // Pass the code to our WKWebView so it can send it to GPMDP.
+        NSString* js =
+                [NSString stringWithFormat:@"sendPermanentAuthCode('%@');", percentEncodedCode];
+        [self evaluateJavaScript:js];
+    } else {
+        NSLog(@"BGMGooglePlayMusicDesktopPlayerConnection::sendPermanentAuthCode: No code to send");
+    }
+}
+
++ (NSString* __nullable)toPercentEncoded:(NSString*)rawString {
+    // Just percent-encode every character (by passing an empty NSCharacterSet as the allowed
+    // characters).
+    NSString* __nullable percentEncoded = [rawString
+                                           stringByAddingPercentEncodingWithAllowedCharacters:
+                                           [NSCharacterSet characterSetWithCharactersInString:@""]];
+    if (percentEncoded) {
+        return percentEncoded;
+    } else {
+        // The docs say that stringByAddingPercentEncodingWithAllowedCharacters returns nil "if the
+        // transformation is not possible", but don't explain when that could happen. According to
+        // https://stackoverflow.com/a/33558934/1091063 it can be caused by the string containing
+        // invalid unicode.
+        NSLog(@"Could not encode");
+        return nil;
+    }
+}
+
+// Ask GPMDP whether it's playing, paused or stopped. The response is handled asynchronously in
+// handleResultMessage.
+- (void) requestPlaybackState {
+    [self evaluateJavaScript:@"requestPlaybackState();"];
+}
+
+#pragma mark WKScriptMessageHandler Methods
+
+- (void) userContentController:(WKUserContentController*)userContentController
+       didReceiveScriptMessage:(WKScriptMessage*)message {
+#pragma unused (userContentController)
+
+    if ([@"log" isEqual:message.name]) {
+        // The message body is always a string in this case.
+        [self handleLogMessage:message.body];
+    } else if ([@"error" isEqual:message.name]) {
+        [self handleConnectionError];
+    } else {
+        BGMAssert([@"gpmdp" isEqual:message.name], "Unexpected message handler name");
+        [self handleGPMDPMessage:message];
+    }
+}
+
+- (void) handleLogMessage:(NSString*)message {
+    (void)message;
+#if DEBUG
+    if (permanentAuthCode) {
+        // Avoid logging the auth code, which would be a minor security issue.
+        message = [message stringByReplacingOccurrencesOfString:BGMNN(permanentAuthCode)
+                                                     withString:@"<private>"];
+    }
+
+    DebugMsg("BGMGooglePlayMusicDesktopPlayerConnection::userContentController: %s",
+             message.UTF8String);
+#endif
+}
+
+- (void) handleConnectionError {
+    if (connectionRetries > 0) {
+        DebugMsg("BGMGooglePlayMusicDesktopPlayerConnection::handleConnectionError: "
+                 "Retrying in 1 second");
+
+        dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(1 * NSEC_PER_SEC)),
+                       dispatch_get_main_queue(),
+                       ^{
+                           // Check connectionRetries again because disconnect may have been called.
+                           if (connectionRetries > 0) {
+                               DebugMsg("BGMGooglePlayMusicDesktopPlayerConnection::"
+                                        "handleConnectionError: Retrying");
+                               [self connectWithRetries:(connectionRetries - 1)];
+                           }
+                       });
+    } else {
+        NSLog(@"BGMGooglePlayMusicDesktopPlayerConnection::handleConnectionError: "
+               "No retries left. Giving up.");
+        connectionErrorHandler();
+    }
+}
+
+- (void) handleGPMDPMessage:(WKScriptMessage*)message {
+    // See https://github.com/MarshallOfSound/Google-Play-Music-Desktop-Player-UNOFFICIAL-/blob/master/docs/PlaybackAPI_WebSocket.md
+
+    // Type check.
+    if (![message.body isKindOfClass:[NSDictionary class]]) {
+        NSLog(@"Unexpected message body type");
+        return;
+    }
+
+    NSDictionary* body = message.body;
+    NSString* messageType;
+
+    // The key for the message type is "channel", except when the message is a response, in which
+    // case the key can be "namespace".
+    if ([body[@"channel"] isKindOfClass:[NSString class]]) {
+        messageType = body[@"channel"];
+    } else if ([body[@"namespace"] isKindOfClass:[NSString class]]) {
+        messageType = body[@"namespace"];
+    } else {
+        NSLog(@"No channel/namespace");
+        return;
+    }
+
+    // Handle the message depending on its type (or ignore it).
+    if ([@"API_VERSION" isEqual:messageType]) {
+        [self handleAPIVersionMessage:body];
+    } else if ([@"connect" isEqual:messageType]) {
+        [self handleConnectMessage:body];
+    } else if ([@"playState" isEqual:messageType]) {
+        [self handlePlayStateMessage:body];
+    } else if ([@"result" isEqual:messageType]) {
+        [self handleResultMessage:body];
+    }
+}
+
+- (void) handleAPIVersionMessage:(NSDictionary*)body {
+    DebugMsg("BGMGooglePlayMusicDesktopPlayerConnection::handleAPIVersionMessage: Response: %s",
+             [NSString stringWithFormat:@"%@", body].UTF8String);
+
+    // Type check.
+    if (![body[@"payload"] isKindOfClass:[NSString class]]) {
+        NSLog(@"Unexpected payload type");
+        [self handleConnectionError];
+        return;
+    }
+
+    NSString* apiVersion = body[@"payload"];
+    // "1.0.0" -> ["1", "0", "0"]
+    NSArray<NSString*>* versionParts = [apiVersion componentsSeparatedByString:@"."];
+
+    // Check the major version number is 1, which is the only major version we support.
+    if (versionParts.count > 0) {
+        NSInteger majorVersion = versionParts[0].integerValue;
+
+        DebugMsg("BGMGooglePlayMusicDesktopPlayerConnection::handleAPIVersionMessage: "
+                 "Major version: %lu", majorVersion);
+
+        if (majorVersion == 1) {
+            // GPMDP uses SemVer, so as long as the major version number matches what we can handle,
+            // it should work.
+            DebugMsg("BGMGooglePlayMusicDesktopPlayerConnection::handleAPIVersionMessage: "
+                     "This API version is supported");
+            return;
+        }
+    }
+
+    // Show a warning dialog box to the user, but try to continue anyway. There's probably a
+    // reasonable chance it'll still work.
+    DebugMsg("BGMGooglePlayMusicDesktopPlayerConnection::handleAPIVersionMessage: "
+             "Unsupported GPMDP API version");
+    apiVersionMismatchHandler(apiVersion);
+}
+
+- (void) handleConnectMessage:(NSDictionary*)body {
+    // Don't log the response as it may contain the auth code.
+    DebugMsg("BGMGooglePlayMusicDesktopPlayerConnection::handleConnectMessage: Received response");
+
+    // Type check.
+    if (![body[@"payload"] isKindOfClass:[NSString class]]) {
+        NSLog(@"Unexpected payload type");
+        [self handleConnectionError];
+        return;
+    }
+
+    NSString* payload = body[@"payload"];
+
+    if ([@"CODE_REQUIRED" isEqual:payload]) {
+        // Ask the user for the auth code GPMDP is displaying and send it to GPMDP to finish
+        // connecting.
+        NSString* __nullable authCode = authRequiredHandler();
+
+        if (authCode) {
+            [self sendAuthCode:BGMNN(authCode)];
+        }
+    } else {
+        // The payload should be the permanent auth code.
+        permanentAuthCode = payload;
+        [self sendPermanentAuthCode];
+
+        // Save the code to the keychain so we can use it when connecting to GPMDP in future.
+        userDefaults.googlePlayMusicDesktopPlayerPermanentAuthCode = permanentAuthCode;
+    }
+}
+
+- (void) handlePlayStateMessage:(NSDictionary*)body {
+    (void)body;
+    DebugMsg("BGMGooglePlayMusicDesktopPlayerConnection::handlePlayStateMessage: Response: %s",
+             [NSString stringWithFormat:@"%@", body].UTF8String);
+
+    // This message tells us the playstate has changed, but doesn't differentiate between stopped
+    // and paused. The response to this API request will. See handleResultMessage.
+    // TODO: Can it transition from stopped to paused? Would that be a problem?
+    [self requestPlaybackState];
+}
+
+- (void) handleResultMessage:(NSDictionary*)body {
+    DebugMsg("BGMGooglePlayMusicDesktopPlayerConnection::handleResultMessage: Response: %s",
+             [NSString stringWithFormat:@"%@", body].UTF8String);
+
+    // Type check.
+    if (![body[@"value"] isKindOfClass:[NSNumber class]]) {
+        NSLog(@"No value");
+        return;
+    }
+
+    // 0 - Playback is stopped
+    // 1 - Track is paused
+    // 2 - Track is playing
+    int state = ((NSNumber*)body[@"value"]).intValue;
+    _playing = (state == 2);
+    _paused = (state == 1);
+}
+
+@end
+
+#pragma clang assume_nonnull end
+

BGMApp/BGMApp/Music Players/BGMHermes.m

@@ -17,7 +17,7 @@
 //  BGMHermes.m
 //  BGMApp
 //
-//  Copyright © 2016 Kyle Neideck
+//  Copyright © 2016-2018 Kyle Neideck
 //
 
 // Self Include
@@ -30,9 +30,7 @@
 #import "BGMScriptingBridge.h"
 
 // PublicUtility Includes
-#undef CoreAudio_ThreadStampMessages
-#define CoreAudio_ThreadStampMessages 0  // Requires C++
-#include "CADebugMacros.h"
+#import "CADebugMacros.h"
 
 
 #pragma clang assume_nonnull begin
@@ -41,12 +39,12 @@
     BGMScriptingBridge* scriptingBridge;
 }
 
-- (id) init {
+- (instancetype) init {
     // If you're copying this class, replace the ID string with a new one generated by uuidgen. (Command line tool.)
     if ((self = [super initWithMusicPlayerID:[BGMMusicPlayerBase makeID:@"0CDC67B0-56D3-4D94-BC06-6E380D8F5E34"]
                                         name:@"Hermes"
                                     bundleID:@"com.alexcrichton.Hermes"])) {
-        scriptingBridge = [[BGMScriptingBridge alloc] initWithBundleID:(NSString*)self.bundleID];
+        scriptingBridge = [[BGMScriptingBridge alloc] initWithMusicPlayer:self];
     }
     
     return self;
@@ -56,6 +54,11 @@
     return (HermesApplication* __nullable)scriptingBridge.application;
 }
 
+- (void) wasSelected {
+    [super wasSelected];
+    [scriptingBridge ensurePermission];
+}
+
 - (BOOL) isRunning {
     // Note that this will return NO if is self.hermes is nil (i.e. Hermes isn't running).
     return self.hermes.running;

BGMApp/BGMApp/Music Players/BGMMusic.h

@@ -14,25 +14,20 @@
 // along with Background Music. If not, see <http://www.gnu.org/licenses/>.
 
 //
-//  BGMOutputDevicePrefs.h
+//  BGMMusic.h
 //  BGMApp
 //
-//  Copyright © 2016 Kyle Neideck
+//  Copyright © 2016, 2019 Kyle Neideck
+//  Copyright © 2019 theLMGN
 //
 
-// Local Includes
-#import "BGMAudioDeviceManager.h"
-
-// System Includes
-#import <AppKit/AppKit.h>
+// Superclass/Protocol Import
+#import "BGMMusicPlayer.h"
 
 
 #pragma clang assume_nonnull begin
 
-@interface BGMOutputDevicePrefs : NSObject
-
-- (id) initWithAudioDevices:(BGMAudioDeviceManager*)inAudioDevices;
-- (void) populatePreferencesMenu:(NSMenu*)prefsMenu;
+@interface BGMMusic : BGMMusicPlayerBase<BGMMusicPlayer>
 
 @end
 

BGMApp/BGMApp/Music Players/BGMMusic.m

@@ -0,0 +1,111 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMMusic.m
+//  BGMApp
+//
+//  Copyright © 2016-2019 Kyle Neideck, theLMGN
+//
+
+// Self Include
+#import "BGMMusic.h"
+
+// Auto-generated Scripting Bridge header
+#import "Music.h"
+
+// Local Includes
+#import "BGMScriptingBridge.h"
+
+// PublicUtility Includes
+#import "CADebugMacros.h"
+
+
+#pragma clang assume_nonnull begin
+
+@implementation BGMMusic {
+    BGMScriptingBridge* scriptingBridge;
+}
+
++ (NSUUID*) sharedMusicPlayerID {
+    NSUUID* __nullable musicPlayerID =
+            [[NSUUID alloc] initWithUUIDString:@"829B8069-8BD2-481D-BD40-54AB8CDAE228"];
+    NSAssert(musicPlayerID, @"BGMMusic::sharedMusicPlayerID: !musicPlayerID");
+    return (NSUUID*)musicPlayerID;
+}
+
+- (instancetype) init {
+    if ((self = [super initWithMusicPlayerID:[BGMMusic sharedMusicPlayerID]
+                                        name:@"Music"
+                                    bundleID:@"com.apple.Music"])) {
+        scriptingBridge = [[BGMScriptingBridge alloc] initWithMusicPlayer:self];
+    }
+    
+    return self;
+}
+
+- (MusicApplication* __nullable) music {
+    return (MusicApplication*)scriptingBridge.application;
+}
+
+- (void) wasSelected {
+    [super wasSelected];
+    [scriptingBridge ensurePermission];
+}
+
+- (BOOL) isRunning {
+    return self.music.running;
+}
+
+// isPlaying and isPaused check self.running first just in case Music is closed but self.music
+// hasn't become nil yet. In that case, reading self.music.playerState could make Scripting Bridge
+// open Music.
+
+- (BOOL) isPlaying {
+    return self.running && (self.music.playerState == MusicEPlSPlaying);
+}
+
+- (BOOL) isPaused {
+    return self.running && (self.music.playerState == MusicEPlSPaused);
+}
+
+- (BOOL) pause {
+    // isPlaying checks isRunning, so we don't need to check it here and waste an Apple event
+    BOOL wasPlaying = self.playing;
+    
+    if (wasPlaying) {
+        DebugMsg("BGMMusic::pause: Pausing Music");
+        [self.music pause];
+    }
+    
+    return wasPlaying;
+}
+
+- (BOOL) unpause {
+    // isPaused checks isRunning, so we don't need to check it here and waste an Apple event
+    BOOL wasPaused = self.paused;
+    
+    if (wasPaused) {
+        DebugMsg("BGMMusic::unpause: Unpausing Music");
+        [self.music playpause];
+    }
+    
+    return wasPaused;
+}
+
+@end
+
+#pragma clang assume_nonnull end
+

BGMApp/BGMApp/Music Players/BGMMusicPlayer.h

@@ -17,7 +17,7 @@
 //  BGMMusicPlayer.h
 //  BGMApp
 //
-//  Copyright © 2016 Kyle Neideck
+//  Copyright © 2016, 2018, 2019 Kyle Neideck
 //
 //  The base classes and protocol for objects that represent a music player app.
 //
@@ -41,6 +41,9 @@
 //  BGMDriver will log the bundle ID to system.log when it becomes aware of the music player.
 //
 
+// Local Includes
+#import "BGMUserDefaults.h"
+
 // System Includes
 #import <Cocoa/Cocoa.h>
 
@@ -50,27 +53,26 @@
 @protocol BGMMusicPlayer <NSObject>
 
 // Classes return an instance of themselves for each music player app they make available in
-// BGMApp. So far that's always been a single instance, and classes haven't needed to override
-// the default implementation of createInstances from BGMMusicPlayerBase. But that will probably
-// change eventually.
+// BGMApp. So far that's always been a single instance, but that will probably change eventually.
+// Most classes don't need to override the default implementation from BGMMusicPlayerBase.
 //
-// For example, a class for custom music players would probably return an instance for each
-// custom player the user has created. (Also note that it could return an empty array.) In that
-// case the class would probably restore some state from user defaults in its createInstances.
+// But, for example, a class for custom music players would probably return an instance for each
+// custom player the user has created. (Also note that it could return an empty array.)
 //
 // TODO: I think the return type should actually be NSArray<instancetype>*, but that doesn't seem
 //       to work. There's a Clang bug about this: https://llvm.org/bugs/show_bug.cgi?id=27323
 //       (though it hasn't been confirmed yet).
-+ (NSArray<id<BGMMusicPlayer>>*) createInstances;
++ (NSArray<id<BGMMusicPlayer>>*) createInstancesWithDefaults:(BGMUserDefaults*)userDefaults;
 
 // We need a unique ID for each music player to store in user defaults. In the most common case,
 // classes that provide a static (or at least bounded) number of music players, you can generate
 // IDs with uuidgen (the command line tool) and include them in your class as constants. Otherwise,
-// you'll probably want to store them in user defaults and retrieve them in your createInstances.
+// you'll probably want to store them in user defaults and load them in createInstancesWithDefaults.
 @property (readonly) NSUUID* musicPlayerID;
 
-// The name and icon of the music player, to be used in the UI.
+// The name, tool-tip and icon of the music player, to be used in the UI.
 @property (readonly) NSString* name;
+@property (readonly) NSString* __nullable toolTip;
 @property (readonly) NSImage* __nullable icon;
 
 @property (readonly) NSString* __nullable bundleID;
@@ -81,9 +83,12 @@
 // TODO: If we ever add a music player class that uses this property, it'll need a way to inform
 //       BGMDevice of changes. It might be easiest to have BGMMusicPlayers to observe this property,
 //       on the selected music player, with KVO and update BGMDevice when it changes. Or
-//       BGMMusicPlayers could pass a pointer to itself to createInstances.
+//       BGMMusicPlayers could pass a pointer to itself to createInstancesWithDefaults.
 @property NSNumber* __nullable pid;
 
+// True if this is currently the selected music player.
+@property (readonly) BOOL selected;
+
 // The state of the music player.
 //
 // True if the music player app is open.
@@ -97,10 +102,14 @@
 // BGMApp paused it.
 @property (readonly, getter=isPaused) BOOL paused;
 
+// Called when the user selects this music player.
+- (void) wasSelected;
+// Called when this was the selected music player and the user just selected a different one.
+- (void) wasDeselected;
+
 // Pause the music player. Does nothing if the music player is already paused or isn't running.
 // Returns YES if the music player is paused now but wasn't before, returns NO otherwise.
 - (BOOL) pause;
-
 // Unpause the music player. Does nothing if the music player is already playing or isn't running.
 // Returns YES if the music player is playing now but wasn't before, returns NO otherwise.
 - (BOOL) unpause;
@@ -116,6 +125,12 @@
 
 - (instancetype) initWithMusicPlayerID:(NSUUID*)musicPlayerID
                                   name:(NSString*)name
+                               toolTip:(NSString*)toolTip
+                              bundleID:(NSString* __nullable)bundleID;
+
+- (instancetype) initWithMusicPlayerID:(NSUUID*)musicPlayerID
+                                  name:(NSString*)name
+                               toolTip:(NSString* __nullable)toolTip
                               bundleID:(NSString* __nullable)bundleID
                                    pid:(NSNumber* __nullable)pid;
 
@@ -124,12 +139,16 @@
 + (NSUUID*) makeID:(NSString*)musicPlayerIDString;
 
 // BGMMusicPlayer default implementations
-+ (NSArray<id<BGMMusicPlayer>>*) createInstances;
++ (NSArray<id<BGMMusicPlayer>>*) createInstancesWithDefaults:(BGMUserDefaults*)userDefaults;
 @property (readonly) NSImage* __nullable icon;
 @property (readonly) NSUUID* musicPlayerID;
 @property (readonly) NSString* name;
+@property (readonly) NSString* __nullable toolTip;
 @property (readonly) NSString* __nullable bundleID;
 @property NSNumber* __nullable pid;
+@property (readonly) BOOL selected;
+- (void) wasSelected;
+- (void) wasDeselected;
 
 @end
 

BGMApp/BGMApp/Music Players/BGMMusicPlayer.m

@@ -17,16 +17,14 @@
 //  BGMMusicPlayer.m
 //  BGMApp
 //
-//  Copyright © 2016 Kyle Neideck
+//  Copyright © 2016-2019 Kyle Neideck
 //
 
 // Self Include
 #import "BGMMusicPlayer.h"
 
 // PublicUtility Includes
-#undef CoreAudio_ThreadStampMessages
-#define CoreAudio_ThreadStampMessages 0  // Requires C++
-#include "CADebugMacros.h"
+#import "CADebugMacros.h"
 
 
 #pragma clang assume_nonnull begin
@@ -35,17 +33,35 @@
 
 @synthesize musicPlayerID = _musicPlayerID;
 @synthesize name = _name;
+@synthesize toolTip = _toolTip;
 @synthesize bundleID = _bundleID;
 @synthesize pid = _pid;
+@synthesize selected = _selected;
 
 - (instancetype) initWithMusicPlayerID:(NSUUID*)musicPlayerID
                                   name:(NSString*)name
                               bundleID:(NSString* __nullable)bundleID {
-    return [self initWithMusicPlayerID:musicPlayerID name:name bundleID:bundleID pid:nil];
+    return [self initWithMusicPlayerID:musicPlayerID
+                                  name:name
+                               toolTip:nil
+                              bundleID:bundleID
+                                   pid:nil];
 }
 
 - (instancetype) initWithMusicPlayerID:(NSUUID*)musicPlayerID
                                   name:(NSString*)name
+                               toolTip:(NSString*)toolTip
+                              bundleID:(NSString* __nullable)bundleID {
+    return [self initWithMusicPlayerID:musicPlayerID
+                                  name:name
+                               toolTip:toolTip
+                              bundleID:bundleID
+                                   pid:nil];
+}
+
+- (instancetype) initWithMusicPlayerID:(NSUUID*)musicPlayerID
+                                  name:(NSString*)name
+                               toolTip:(NSString* __nullable)toolTip
                               bundleID:(NSString* __nullable)bundleID
                                    pid:(NSNumber* __nullable)pid {
     if ((self = [super init])) {
@@ -56,8 +72,10 @@
         
         _musicPlayerID = musicPlayerID;
         _name = name;
+        _toolTip = toolTip;
         _bundleID = bundleID;
         _pid = pid;
+        _selected = NO;
     }
 
     return self;
@@ -72,8 +90,13 @@
 
 #pragma mark BGMMusicPlayer default implementations
 
-+ (NSArray<id<BGMMusicPlayer>>*) createInstances {
++ (NSArray<id<BGMMusicPlayer>>*) createInstancesWithDefaults:(BGMUserDefaults*)userDefaults {
+    #pragma unused (userDefaults)
+    // TODO: Fix this warning properly.
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wobjc-literal-conversion"
     return @[ [self new] ];
+#pragma clang diagnostic pop
 }
 
 - (NSImage* __nullable) icon {
@@ -84,6 +107,14 @@
     return (!bundlePath ? nil : [[NSWorkspace sharedWorkspace] iconForFile:(NSString*)bundlePath]);
 }
 
+- (void) wasSelected {
+    _selected = YES;
+}
+
+- (void) wasDeselected {
+    _selected = NO;
+}
+
 @end
 
 #pragma clang assume_nonnull end

BGMApp/BGMApp/Music Players/BGMMusicPlayers.h

@@ -17,7 +17,7 @@
 //  BGMMusicPlayers.h
 //  BGMApp
 //
-//  Copyright © 2016 Kyle Neideck
+//  Copyright © 2016, 2019 Kyle Neideck
 //
 //  Holds the music players (i.e. BGMMusicPlayer objects) available in BGMApp. Also keeps track of
 //  which music player is currently selected by the user.
@@ -43,8 +43,8 @@
 // defaultMusicPlayerID is the musicPlayerID (see BGMMusicPlayer.h) of the music player that should be
 // selected by default.
 //
-// The createInstances method of each class in musicPlayerClasses will be called, and the results stored
-// in the musicPlayers property.
+// The createInstancesWithDefaults method of each class in musicPlayerClasses will be called and
+// the results will be stored in the musicPlayers property.
 - (instancetype) initWithAudioDevices:(BGMAudioDeviceManager*)devices
                  defaultMusicPlayerID:(NSUUID*)defaultMusicPlayerID
                    musicPlayerClasses:(NSArray<Class<BGMMusicPlayer>>*)musicPlayerClasses

BGMApp/BGMApp/Music Players/BGMMusicPlayers.mm

@@ -17,7 +17,7 @@
 //  BGMMusicPlayers.mm
 //  BGMApp
 //
-//  Copyright © 2016 Kyle Neideck
+//  Copyright © 2016-2019 Kyle Neideck
 //
 
 // Self include
@@ -33,6 +33,9 @@
 #import "BGMVOX.h"
 #import "BGMDecibel.h"
 #import "BGMHermes.h"
+#import "BGMSwinsian.h"
+#import "BGMMusic.h"
+#import "BGMGooglePlayMusicDesktopPlayer.h"
 
 
 #pragma clang assume_nonnull begin
@@ -46,15 +49,25 @@
 
 - (instancetype) initWithAudioDevices:(BGMAudioDeviceManager*)devices
                          userDefaults:(BGMUserDefaults*)defaults {
+    // The classes handling each music player we support. If you write a new music player class, add
+    // it to this array.
+    NSArray<Class<BGMMusicPlayer>>* mpClasses = @[ [BGMVOX class],
+                                                   [BGMVLC class],
+                                                   [BGMSpotify class],
+                                                   [BGMiTunes class],
+                                                   [BGMDecibel class],
+                                                   [BGMHermes class],
+                                                   [BGMSwinsian class],
+                                                   [BGMMusic class] ];
+
+    // We only support Google Play Music Desktop Player on macOS 10.10 and higher.
+    if (@available(macOS 10.10, *)) {
+        mpClasses = [mpClasses arrayByAddingObject:[BGMGooglePlayMusicDesktopPlayer class]];
+    }
+
     return [self initWithAudioDevices:devices
                  defaultMusicPlayerID:[BGMiTunes sharedMusicPlayerID]
-                   // If you write a new music player class, add it to this array.
-                   musicPlayerClasses:@[ [BGMVOX class],
-                                         [BGMVLC class],
-                                         [BGMSpotify class],
-                                         [BGMiTunes class],
-                                         [BGMDecibel class],
-                                         [BGMHermes class] ]
+                   musicPlayerClasses:mpClasses
                          userDefaults:defaults];
 }
 
@@ -68,11 +81,14 @@
         
         // Init _musicPlayers, an array containing one object for each music player in BGMApp.
         //
-        // Each music player class has a factory method, createInstances, that returns all the instances of that
-        // class BGMApp will use. (Though so far it's always just one instance.)
+        // Each music player class has a factory method, createInstancesWithDefaults, that returns
+        // all the instances of that class BGMApp will use. (Though so far it's always just one
+        // instance.)
         NSMutableArray* musicPlayers = [NSMutableArray new];
         for (Class<BGMMusicPlayer> musicPlayerClass in musicPlayerClasses) {
-            [musicPlayers addObjectsFromArray:[musicPlayerClass createInstances]];
+            NSArray<id<BGMMusicPlayer>>* instances =
+                    [musicPlayerClass createInstancesWithDefaults:userDefaults];
+            [musicPlayers addObjectsFromArray:instances];
         }
         
         _musicPlayers = [NSArray arrayWithArray:musicPlayers];
@@ -130,11 +146,11 @@
 - (void) initSelectedMusicPlayerFromBGMDevice {
     // When the selected music player setting hasn't been stored in user defaults yet, we get the music player
     // bundle ID from the driver and look for the music player with that bundle ID. This is mainly done for
-    // backwards compatability.
+    // backwards compatibility.
     
     NSString* __nullable bundleID =
-        (__bridge_transfer NSString* __nullable)[audioDevices bgmDevice].GetPropertyData_CFString(kBGMMusicPlayerBundleIDAddress);
-    
+        (__bridge_transfer NSString* __nullable)[audioDevices bgmDevice].GetMusicPlayerBundleID();
+
     DebugMsg("BGMMusicPlayers::initSelectedMusicPlayerFromBGMDevice: "
              "Trying to set selected music player by bundle ID (from BGMDriver). bundleID=%s",
              (bundleID ? bundleID.UTF8String : "(null)"));
@@ -204,6 +220,16 @@
              @"BGMMusicPlayers::setSelectedMusicPlayerImpl: Only the music players in the musicPlayers array can be selected. "
               "newSelectedMusicPlayer=%@",
              newSelectedMusicPlayer.name);
+
+    if (_selectedMusicPlayer == newSelectedMusicPlayer) {
+        DebugMsg("BGMMusicPlayers::setSelectedMusicPlayerImpl: %s is already the selected music "
+                 "player.",
+                 _selectedMusicPlayer.name.UTF8String);
+        return;
+    }
+
+    // Tell the current music player (object) a different player has been selected.
+    [_selectedMusicPlayer wasDeselected];
     
     _selectedMusicPlayer = newSelectedMusicPlayer;
     
@@ -215,6 +241,9 @@
     
     // Save the new setting in user defaults.
     userDefaults.selectedMusicPlayerID = _selectedMusicPlayer.musicPlayerID.UUIDString;
+
+    // Tell the music player (object) it's been selected.
+    [_selectedMusicPlayer wasSelected];
 }
 
 - (void) updateBGMDeviceMusicPlayerProperties {
@@ -224,13 +253,11 @@
              @"BGMMusicPlayers::updateBGMDeviceMusicPlayerProperties: Music player has neither bundle ID nor PID");
 
     if (self.selectedMusicPlayer.pid) {
-        [audioDevices bgmDevice].SetPropertyData_CFType(kBGMMusicPlayerProcessIDAddress,
-                                                        (__bridge CFNumberRef)self.selectedMusicPlayer.pid);
+        [audioDevices bgmDevice].SetMusicPlayerProcessID((__bridge CFNumberRef)self.selectedMusicPlayer.pid);
     }
     
     if (self.selectedMusicPlayer.bundleID) {
-        [audioDevices bgmDevice].SetPropertyData_CFString(kBGMMusicPlayerBundleIDAddress,
-                                                          (__bridge CFStringRef)self.selectedMusicPlayer.bundleID);
+        [audioDevices bgmDevice].SetMusicPlayerBundleID((__bridge CFStringRef)self.selectedMusicPlayer.bundleID);
     }
 }
 

BGMApp/BGMApp/Music Players/BGMScriptingBridge.h

@@ -17,7 +17,7 @@
 //  BGMScriptingBridge.h
 //  BGMApp
 //
-//  Copyright © 2016 Kyle Neideck
+//  Copyright © 2016, 2018 Kyle Neideck
 //
 //  A wrapper around Scripting Bridge's SBApplication that tries to avoid ever launching the application.
 //
@@ -29,6 +29,9 @@
 //  unless the music player app is running. That way messages sent while the app is closed are ignored.
 //
 
+// Local Includes
+#import "BGMMusicPlayer.h"
+
 // System Includes
 #import <Cocoa/Cocoa.h>
 #import <ScriptingBridge/ScriptingBridge.h>
@@ -38,12 +41,19 @@
 
 @interface BGMScriptingBridge : NSObject <SBApplicationDelegate>
 
-- (instancetype) initWithBundleID:(NSString*)bundleID;
+// Only keeps a weak ref to musicPlayer.
+- (instancetype) initWithMusicPlayer:(id<BGMMusicPlayer>)musicPlayer;
 
 // If the music player application is running, this property is the Scripting Bridge object representing
 // it. If not, it's set to nil. Used to send Apple events to the music player app.
 @property (readonly) __kindof SBApplication* __nullable application;
 
+// macOS 10.14 requires the user's permission to send Apple Events. If the music player that owns
+// this object (i.e. the one passed to initWithMusicPlayer) is currently the selected music player
+// and the user hasn't already given us permission to send it Apple Events, this method asks the
+// user for permission.
+- (void) ensurePermission;
+
 // SBApplicationDelegate
 
 // On 10.11, SBApplicationDelegate.h declares eventDidFail with a non-null return type, but the docs

BGMApp/BGMApp/Music Players/BGMScriptingBridge.m

@@ -17,31 +17,32 @@
 //  BGMScriptingBridge.m
 //  BGMApp
 //
-//  Copyright © 2016 Kyle Neideck
+//  Copyright © 2016-2019 Kyle Neideck
 //
 
 // Self Include
 #import "BGMScriptingBridge.h"
 
+// Local Includes
+#import "BGM_Utils.h"
+#import "BGMAppWatcher.h"
+
 // PublicUtility Includes
-#undef CoreAudio_ThreadStampMessages
-#define CoreAudio_ThreadStampMessages 0  // Requires C++
-#include "CADebugMacros.h"
+#import "CADebugMacros.h"
 
 
 #pragma clang assume_nonnull begin
 
 @implementation BGMScriptingBridge {
-    NSString* bundleID;
-    // Tokens for the notification observers. We need these to remove the observers in dealloc.
-    id didLaunchToken, didTerminateToken;
+    id<BGMMusicPlayer> __weak _musicPlayer;
+    BGMAppWatcher* appWatcher;
 }
 
 @synthesize application = _application;
 
-- (instancetype) initWithBundleID:(NSString*)inBundleID {
+- (instancetype) initWithMusicPlayer:(id<BGMMusicPlayer>)musicPlayer {
     if ((self = [super init])) {
-        bundleID = inBundleID;
+        _musicPlayer = musicPlayer;
         
         [self initApplication];
     }
@@ -50,13 +51,18 @@
 }
 
 - (void) initApplication {
+    NSString* bundleID = _musicPlayer.bundleID;
+    BGMAssert(bundleID, "Music players need a bundle ID to use ScriptingBridge");
+
+    BGMScriptingBridge* __weak weakSelf = self;
+
     void (^createSBApplication)(void) = ^{
-        _application = [SBApplication applicationWithBundleIdentifier:bundleID];
-        _application.delegate = self;
-    };
-    
-    BOOL (^isAboutThisMusicPlayer)(NSNotification*) = ^(NSNotification* note) {
-        return [[note.userInfo[NSWorkspaceApplicationKey] bundleIdentifier] isEqualToString:bundleID];
+        BGMScriptingBridge* strongSelf = weakSelf;
+        strongSelf->_application = [SBApplication applicationWithBundleIdentifier:bundleID];
+        // TODO: The SBApplication will still keep a strong ref to this object, so we would have to
+        //       make a separate delegate object to avoid the retain cycle. Not currently a problem
+        //       because we only ever create instances that live forever.
+        strongSelf->_application.delegate = strongSelf;
     };
     
     // Add observers that create/destroy the SBApplication when the music player is launched/terminated. We
@@ -67,27 +73,20 @@
     // From the docs for SBApplication's applicationWithBundleIdentifier method:
     //     "For applications that declare themselves to have a dynamic scripting interface, this method will
     //     launch the application if it is not already running."
-    NSNotificationCenter* center = [[NSWorkspace sharedWorkspace] notificationCenter];
-    didLaunchToken = [center addObserverForName:NSWorkspaceDidLaunchApplicationNotification
-                                         object:nil
-                                          queue:nil
-                                     usingBlock:^(NSNotification* note) {
-                                         if (isAboutThisMusicPlayer(note)) {
-                                             DebugMsg("BGMScriptingBridge::initApplication: %s launched",
-                                                      bundleID.UTF8String);
-                                             createSBApplication();
-                                         }
-                                     }];
-    didTerminateToken = [center addObserverForName:NSWorkspaceDidTerminateApplicationNotification
-                                            object:nil
-                                             queue:nil
-                                        usingBlock:^(NSNotification* note) {
-                                            if (isAboutThisMusicPlayer(note)) {
-                                                DebugMsg("BGMScriptingBridge::initApplication: %s terminated",
-                                                         bundleID.UTF8String);
-                                                _application = nil;
-                                            }
-                                        }];
+    appWatcher =
+        [[BGMAppWatcher alloc] initWithBundleID:bundleID
+                                    appLaunched:^{
+                                        DebugMsg("BGMScriptingBridge::initApplication: %s launched",
+                                                 bundleID.UTF8String);
+                                        createSBApplication();
+                                        [weakSelf ensurePermission];
+                                    }
+                                  appTerminated:^{
+                                      BGMScriptingBridge* strongSelf = weakSelf;
+                                      DebugMsg("BGMScriptingBridge::initApplication: %s terminated",
+                                               bundleID.UTF8String);
+                                      strongSelf->_application = nil;
+                                  }];
     
     // Create the SBApplication if the music player is already running.
     if ([NSRunningApplication runningApplicationsWithBundleIdentifier:bundleID].count > 0) {
@@ -95,17 +94,58 @@
     }
 }
 
-- (void) dealloc {
-    // Remove the application launch/termination observers.
-    NSNotificationCenter* center = [NSWorkspace sharedWorkspace].notificationCenter;
-    
-    if (didLaunchToken) {
-        [center removeObserver:didLaunchToken];
-    }
-    
-    if (didTerminateToken) {
-        [center removeObserver:didTerminateToken];
+- (void) ensurePermission {
+    // Skip this check if running on a version of macOS before 10.14. In that case, we don't require
+    // user permission to send Apple Events. Also skip it if compiling on an earlier version.
+#if MAC_OS_X_VERSION_MAX_ALLOWED >= 101400  // MAC_OS_X_VERSION_10_14
+    if (@available(macOS 10.14, *)) {
+        id<BGMMusicPlayer> musicPlayer = _musicPlayer;
+
+        if (!musicPlayer.selected) {
+            DebugMsg("BGMScriptingBridge::ensurePermission: %s not selected. Nothing to do.",
+                     musicPlayer.name.UTF8String);
+            return;
+        }
+
+        if (!musicPlayer.running) {
+            DebugMsg("BGMScriptingBridge::ensurePermission: %s not running. Nothing to do.",
+                     musicPlayer.name.UTF8String);
+            return;
+        }
+
+        // AEDeterminePermissionToAutomateTarget will block if it has to show a dialog to the user
+        // to ask for permission, so dispatch this to make sure it doesn't run on the main thread.
+        dispatch_async(dispatch_get_global_queue(QOS_CLASS_USER_INITIATED, 0), ^{
+            NSAppleEventDescriptor* musicPlayerEventDescriptor =
+                [NSAppleEventDescriptor
+                 descriptorWithBundleIdentifier:(NSString*)musicPlayer.bundleID];
+
+            OSStatus status =
+                AEDeterminePermissionToAutomateTarget(musicPlayerEventDescriptor.aeDesc,
+                                                      typeWildCard,
+                                                      typeWildCard,
+                                                      true);
+
+            DebugMsg("BGMScriptingBridge::ensurePermission: "
+                     "Apple Events permission status for %s: %d",
+                     musicPlayer.name.UTF8String,
+                     status);
+
+            if (status != noErr) {
+                // TODO: If they deny permission, we should grey-out the auto-pause menu item and
+                //       add something to the UI that indicates the problem. Maybe a warning icon
+                //       that shows an explanation when you hover your mouse over it. (We can't just
+                //       ask them again later because the API doesn't support it. They can only fix
+                //       it in System Preferences.)
+                NSLog(@"BGMScriptingBridge::ensurePermission: Permission denied for %@. status=%d",
+                      musicPlayer.name,
+                      status);
+            }
+        });
+    } else {
+        DebugMsg("BGMScriptingBridge::ensurePermission: Not macOS 10.14+. Nothing to do.");
     }
+#endif /* MAC_OS_X_VERSION_MAX_ALLOWED >= 101400 */
 }
 
 #pragma mark SBApplicationDelegate
@@ -120,7 +160,7 @@
     NSString* vars = [NSString stringWithFormat:@"event='%4.4s' error=%@ application=%@",
                          (char*)&(event->descriptorType), error, self.application];
     DebugMsg("BGMScriptingBridge::eventDidFail: Apple event sent to %s failed. %s",
-             bundleID.UTF8String,
+             _musicPlayer.bundleID.UTF8String,
              vars.UTF8String);
 #else
     #pragma unused (event, error)

BGMApp/BGMApp/Music Players/BGMSpotify.m

@@ -17,7 +17,7 @@
 //  BGMSpotify.m
 //  BGMApp
 //
-//  Copyright © 2016 Kyle Neideck
+//  Copyright © 2016-2018 Kyle Neideck
 //
 //  Spotify's AppleScript API looks to have been designed to match iTunes', so this file is basically
 //  just s/iTunes/Spotify/ on BGMiTunes.m
@@ -33,9 +33,7 @@
 #import "BGMScriptingBridge.h"
 
 // PublicUtility Includes
-#undef CoreAudio_ThreadStampMessages
-#define CoreAudio_ThreadStampMessages 0  // Requires C++
-#include "CADebugMacros.h"
+#import "CADebugMacros.h"
 
 
 #pragma clang assume_nonnull begin
@@ -44,12 +42,12 @@
     BGMScriptingBridge* scriptingBridge;
 }
 
-- (id) init {
+- (instancetype) init {
     // If you're copying this class, replace the ID string with a new one generated by uuidgen. (Command line tool.)
     if ((self = [super initWithMusicPlayerID:[BGMMusicPlayerBase makeID:@"EC2A907F-8515-4687-9570-1BF63176E6D8"]
                                         name:@"Spotify"
                                     bundleID:@"com.spotify.client"])) {
-        scriptingBridge = [[BGMScriptingBridge alloc] initWithBundleID:(NSString*)self.bundleID];
+        scriptingBridge = [[BGMScriptingBridge alloc] initWithMusicPlayer:self];
     }
     
     return self;
@@ -59,6 +57,11 @@
     return (SpotifyApplication* __nullable)scriptingBridge.application;
 }
 
+- (void) wasSelected {
+    [super wasSelected];
+    [scriptingBridge ensurePermission];
+}
+
 - (BOOL) isRunning {
     // Note that this will return NO if is self.spotify is nil (i.e. Spotify isn't running).
     return self.spotify.running;

BGMApp/BGMApp/Music Players/BGMSwinsian.h

@@ -14,25 +14,21 @@
 // along with Background Music. If not, see <http://www.gnu.org/licenses/>.
 
 //
-//  AppDelegate.h
+//  BGMSwinsian.h
 //  BGMApp
 //
-//  Copyright © 2016 Kyle Neideck
-//
-//  Sets up and tears down the app.
+//  Copyright © 2018 Kyle Neideck
 //
 
-// System Includes
-#import <Cocoa/Cocoa.h>
+// Superclass/Protocol Import
+#import "BGMMusicPlayer.h"
 
 
-@interface AppDelegate : NSObject <NSApplicationDelegate, NSMenuDelegate>
+#pragma clang assume_nonnull begin
 
-@property (weak) IBOutlet NSMenu* bgmMenu;
-@property (weak) IBOutlet NSView* appVolumeView;
-@property (weak) IBOutlet NSPanel* aboutPanel;
-@property (unsafe_unretained) IBOutlet NSTextView* aboutPanelLicenseView;
-@property (weak) IBOutlet NSMenuItem* autoPauseMenuItemUnwrapped;
+@interface BGMSwinsian : BGMMusicPlayerBase<BGMMusicPlayer>
 
 @end
 
+#pragma clang assume_nonnull end
+

BGMApp/BGMApp/Music Players/BGMSwinsian.m

@@ -0,0 +1,109 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMSwinsian.m
+//  BGMApp
+//
+//  Copyright © 2018 Kyle Neideck
+//
+
+// Self Include
+#import "BGMSwinsian.h"
+
+// Auto-generated Scripting Bridge header
+#import "Swinsian.h"
+
+// Local Includes
+#import "BGMScriptingBridge.h"
+
+// PublicUtility Includes
+#import "CADebugMacros.h"
+
+
+#pragma clang assume_nonnull begin
+
+@implementation BGMSwinsian {
+    BGMScriptingBridge* scriptingBridge;
+}
+
+- (instancetype) init {
+    // If you're copying this class, replace the ID string with a new one generated by uuidgen (the
+    // command line tool).
+    NSUUID* musicPlayerID = [BGMMusicPlayerBase makeID:@"B74D18F6-DFF7-4D88-B719-429CFF98CFFA"];
+
+    if ((self = [super initWithMusicPlayerID:musicPlayerID
+                                        name:@"Swinsian"
+                                    bundleID:@"com.swinsian.Swinsian"])) {
+        scriptingBridge = [[BGMScriptingBridge alloc] initWithMusicPlayer:self];
+    }
+    
+    return self;
+}
+
+- (SwinsianApplication* __nullable) swinsian {
+    return (SwinsianApplication* __nullable)scriptingBridge.application;
+}
+
+- (void) wasSelected {
+    [super wasSelected];
+    [scriptingBridge ensurePermission];
+}
+
+- (BOOL) isRunning {
+    // Note that this will return NO if is self.swinsian is nil (i.e. Swinsian isn't running).
+    return self.swinsian.running;
+}
+
+// isPlaying and isPaused check self.running first just in case Swinsian is closed but self.swinsian
+// hasn't become nil yet. In that case, reading self.swinsian.playerState could make Scripting
+// Bridge open Swinsian.
+
+- (BOOL) isPlaying {
+    return self.running && (self.swinsian.playerState == SwinsianPlayerStatePlaying);
+}
+
+- (BOOL) isPaused {
+    return self.running && (self.swinsian.playerState == SwinsianPlayerStatePaused);
+}
+
+- (BOOL) pause {
+    // isPlaying checks isRunning, so we don't need to check it here and waste an Apple event.
+    BOOL wasPlaying = self.playing;
+    
+    if (wasPlaying) {
+        DebugMsg("BGMSwinsian::pause: Pausing Swinsian");
+        [self.swinsian pause];
+    }
+    
+    return wasPlaying;
+}
+
+- (BOOL) unpause {
+    // isPaused checks isRunning, so we don't need to check it here and waste an Apple event.
+    BOOL wasPaused = self.paused;
+    
+    if (wasPaused) {
+        DebugMsg("BGMSwinsian::unpause: Unpausing Swinsian");
+        [self.swinsian play];
+    }
+    
+    return wasPaused;
+}
+
+@end
+
+#pragma clang assume_nonnull end
+

BGMApp/BGMApp/Music Players/BGMVLC.m

@@ -17,8 +17,8 @@
 //  BGMVLC.m
 //  BGMApp
 //
-//  Copyright © 2016 Kyle Neideck
-//  Portions copyright (C) 2012 Peter Ljunglöf. All rights reserved.
+//  Copyright © 2016-2018 Kyle Neideck
+//  Copyright (C) 2012 Peter Ljunglöf. All rights reserved.
 //
 
 // Self Include
@@ -31,9 +31,7 @@
 #import "BGMScriptingBridge.h"
 
 // PublicUtility Includes
-#undef CoreAudio_ThreadStampMessages
-#define CoreAudio_ThreadStampMessages 0  // Requires C++
-#include "CADebugMacros.h"
+#import "CADebugMacros.h"
 
 
 #pragma clang assume_nonnull begin
@@ -42,11 +40,11 @@
     BGMScriptingBridge* scriptingBridge;
 }
 
-- (id) init {
+- (instancetype) init {
     if ((self = [super initWithMusicPlayerID:[BGMMusicPlayerBase makeID:@"5226F4B9-C740-4045-A273-4B8EABC0E8FC"]
                                         name:@"VLC"
                                     bundleID:@"org.videolan.vlc"])) {
-        scriptingBridge = [[BGMScriptingBridge alloc] initWithBundleID:(NSString*)self.bundleID];
+        scriptingBridge = [[BGMScriptingBridge alloc] initWithMusicPlayer:self];
     }
     
     return self;
@@ -56,6 +54,11 @@
     return (VLCApplication*)scriptingBridge.application;
 }
 
+- (void) wasSelected {
+    [super wasSelected];
+    [scriptingBridge ensurePermission];
+}
+
 - (BOOL) isRunning {
     return self.vlc.running;
 }
@@ -101,7 +104,7 @@
 //
 // VLC's Scripting Bridge interface doesn't seem to have a cleaner way to do this.
 + (void) togglePlay {
-    NSString* src = @"tell application \"VLC\" to play";
+    NSString* src = @"tell application id \"org.videolan.vlc\" to play";
     NSAppleScript* script = [[NSAppleScript alloc] initWithSource:src];
     [script executeAndReturnError:nil];
 }

BGMApp/BGMApp/Music Players/BGMVOX.m

@@ -17,7 +17,7 @@
 //  BGMVOX.m
 //  BGMApp
 //
-//  Copyright © 2016 Kyle Neideck
+//  Copyright © 2016-2018 Kyle Neideck
 //
 
 // Self Include
@@ -30,9 +30,7 @@
 #import "BGMScriptingBridge.h"
 
 // PublicUtility Includes
-#undef CoreAudio_ThreadStampMessages
-#define CoreAudio_ThreadStampMessages 0  // Requires C++
-#include "CADebugMacros.h"
+#import "CADebugMacros.h"
 
 
 #pragma clang assume_nonnull begin
@@ -41,11 +39,11 @@
     BGMScriptingBridge* scriptingBridge;
 }
 
-- (id) init {
+- (instancetype) init {
     if ((self = [super initWithMusicPlayerID:[BGMMusicPlayerBase makeID:@"26498C5D-C18B-4689-8B41-9DA91A78FFAD"]
                                         name:@"VOX"
                                     bundleID:@"com.coppertino.Vox"])) {
-        scriptingBridge = [[BGMScriptingBridge alloc] initWithBundleID:(NSString*)self.bundleID];
+        scriptingBridge = [[BGMScriptingBridge alloc] initWithMusicPlayer:self];
     }
     
     return self;
@@ -55,6 +53,11 @@
     return (VoxApplication*)scriptingBridge.application;
 }
 
+- (void) wasSelected {
+    [super wasSelected];
+    [scriptingBridge ensurePermission];
+}
+
 - (BOOL) isRunning {
     return self.vox.running;
 }

BGMApp/BGMApp/Music Players/BGMiTunes.m

@@ -17,7 +17,7 @@
 //  BGMiTunes.m
 //  BGMApp
 //
-//  Copyright © 2016 Kyle Neideck
+//  Copyright © 2016-2018 Kyle Neideck
 //
 
 // Self Include
@@ -30,9 +30,7 @@
 #import "BGMScriptingBridge.h"
 
 // PublicUtility Includes
-#undef CoreAudio_ThreadStampMessages
-#define CoreAudio_ThreadStampMessages 0  // Requires C++
-#include "CADebugMacros.h"
+#import "CADebugMacros.h"
 
 
 #pragma clang assume_nonnull begin
@@ -47,11 +45,11 @@
     return (NSUUID*)musicPlayerID;
 }
 
-- (id) init {
+- (instancetype) init {
     if ((self = [super initWithMusicPlayerID:[BGMiTunes sharedMusicPlayerID]
                                         name:@"iTunes"
                                     bundleID:@"com.apple.iTunes"])) {
-        scriptingBridge = [[BGMScriptingBridge alloc] initWithBundleID:(NSString* __nonnull)self.bundleID];
+        scriptingBridge = [[BGMScriptingBridge alloc] initWithMusicPlayer:self];
     }
     
     return self;
@@ -61,6 +59,11 @@
     return (iTunesApplication*)scriptingBridge.application;
 }
 
+- (void) wasSelected {
+    [super wasSelected];
+    [scriptingBridge ensurePermission];
+}
+
 - (BOOL) isRunning {
     return self.iTunes.running;
 }

BGMApp/BGMApp/Music Players/GooglePlayMusicDesktopPlayer.js

@@ -0,0 +1,190 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  GooglePlayMusicDesktopPlayer.js
+//  BGMApp
+//
+//  Copyright © 2019 Kyle Neideck
+//
+
+// The specification for GPMDP's API:
+// https://github.com/MarshallOfSound/Google-Play-Music-Desktop-Player-UNOFFICIAL-/blob/master/docs/PlaybackAPI_WebSocket.md
+
+try {
+
+window._log = msg => {
+    window.webkit.messageHandlers.log.postMessage(msg);
+};
+
+// Global JS error handler.
+window.onerror = (msg, url, line, col, error) => {
+    let extra = !col ? '' : '\nColumn: ' + col;
+    extra += !error ? '' : '\nError: ' + error;
+
+    // TODO: I'm not sure this log message is ever actually useful.
+    window._log('Error: ' + msg + '\nURL: ' + url + '\nLine: ' + line + extra);
+
+    window.webkit.messageHandlers.error.postMessage(error);
+};
+
+// Send a JSON message to GPMDP.
+//
+// If we're connecting, this function will return immediately and the message will be sent after we
+// finish connecting. Logs an error and returns if window.connect() hasn't been called yet.
+window._sendJSON = json => {
+    if (window._wsPromise) {
+        window._wsPromise.then(() => {
+            window._sendJSONImmediate(json);
+        }).catch(error => {
+            // TODO: Is there anything else we can do? Retries?
+            window._log('Error sending JSON: ' + JSON.stringify(error));
+        });
+    } else {
+        window._log('Error: No WebSocket promise. Discarding JSON message: ' +
+                    JSON.stringify(json));
+    }
+};
+
+// Send a JSON message to GPMDP, but don't wait if we're in the process of connecting.
+//
+// Logs an error and returns if window.connect() hasn't been called yet. The authCode param is
+// optional and only used to hide the code in log messages.
+window._sendJSONImmediate = (json, authCode) => {
+    let jsonStr = JSON.stringify(json);
+    let jsonStrSanitized = authCode ? jsonStr.replace(authCode, "<private>") : jsonStr;
+
+    if (window._ws) {
+        window._log('Sending JSON: ' + jsonStrSanitized);
+        window._ws.send(jsonStr);
+    } else {
+        window._log('Error: No WebSocket. Discarding JSON message: ' + jsonStrSanitized);
+    }
+};
+
+// permanentAuthCode is optional. If this is the first time they've selected GPMDP, we won't have a
+// permanent code yet.
+window.connect = permanentAuthCode => {
+    // Reset the connection state.
+    window._requestID = 1;
+
+    // Close the existing connection if we're already connected.
+    window.disconnect();
+
+    // Create the new connection.
+    window._ws = new WebSocket('ws://localhost:5672');
+
+    window._ws.onmessage = event => {
+        // Pass the message along to BGMGooglePlayMusicDesktopPlayerConnection.
+        let reply = JSON.parse(event.data);
+        window.webkit.messageHandlers.gpmdp.postMessage(reply);
+    };
+
+    window._wsPromise = new Promise((resolve, reject) => {
+        window._ws.onopen = () => {
+            // Send GPMDP the initial connection message.
+            if (permanentAuthCode) {
+                window._log('Connecting with auth code');
+                window.sendPermanentAuthCode(permanentAuthCode);
+            } else {
+                // Since we don't have an auth code, it will display a four-digit code and reply
+                // telling us to ask the user to type it into Background Music.
+                window._log('Connecting without auth code');
+
+                window._sendJSONImmediate({
+                    'namespace': 'connect',
+                    'method': 'connect',
+                    'arguments': ['Background Music']
+                });
+            }
+        };
+
+        window._ws.onerror = error => {
+            // Report the error to BGMGooglePlayMusicDesktopPlayerConnection.
+            window.webkit.messageHandlers.error.postMessage(error);
+            // Reject the connection promise.
+            reject(error);
+        };
+
+        // Store the function that resolves this promise. We resolve it after we finish
+        // authenticating.
+        window._resolveConnectionPromise = resolve;
+    });
+};
+
+// Close the connection to GPMDP. Does nothing if we aren't connected.
+window.disconnect = () => {
+    if (window._ws) {
+        window._log('Closing WebSocket');
+        window._ws.close();
+        window._ws = null;
+    }
+};
+
+// Send an authentication code to GPMDP. To send a four-digit code (i.e. one entered by the user),
+// call this directly. To send a permanent code received from GPMDP, use
+// window.sendPermanentAuthCode().
+//
+// authCode should be percent-encoded.
+window.sendAuthCode = authCode => {
+    // Percent-decode the auth code string. We pass it percent-encoded just to make sure nothing in
+    // it accidentally gets executed as Javascript.
+    authCode = window.decodeURIComponent(authCode);
+
+    window._sendJSONImmediate({
+        'namespace': 'connect',
+        'method': 'connect',
+        'arguments': ['Background Music', authCode]
+    }, authCode);
+};
+
+// Send a permanent authentication code, received from GPMDP previously, to GPMDP.
+window.sendPermanentAuthCode = permanentAuthCode => {
+    window._log('Sending permanent auth code');
+    window.sendAuthCode(permanentAuthCode);
+    // TODO: If the code is rejected, GPMDP will send us a connect message and we'll show the auth
+    //       code dialog, but accepting the promise here means some messages we send might get
+    //       ignored.
+    window._resolveConnectionPromise();
+};
+
+// Ask GPMDP to send us its current playback state (playing, paused or stopped).
+window.requestPlaybackState = () => {
+    window._sendJSON({
+        'namespace': 'playback',
+        'method': 'getPlaybackState',
+        // We don't send any other types of request, so the ID we send only needs to be unique.
+        'requestID': window._requestID++
+    });
+};
+
+// Tell GPMDP to toggle between playing and paused.
+window.playPause = () => {
+    window._sendJSON({
+        'namespace': 'playback',
+        'method': 'playPause'
+    });
+};
+
+} catch (error) {
+    window.webkit.messageHandlers.log.postMessage('Error: ' + JSON.stringify(error));
+    window.webkit.messageHandlers.log.postMessage(JSON.stringify(error.stack));
+    window.webkit.messageHandlers.error.postMessage(error);
+}
+
+// Return an empty string as returning some types can cause an error when this Javascript is loaded
+// into the WKWebView.
+""
+

BGMApp/BGMApp/Music Players/Music.h

@@ -0,0 +1,545 @@
+/*
+ * Music.h
+ *
+ * Generated with
+ * sdef /System/Applications/Music.app | sdp -fh --basename Music
+ */
+
+#import <AppKit/AppKit.h>
+#import <ScriptingBridge/ScriptingBridge.h>
+
+
+@class MusicApplication, MusicItem, MusicAirPlayDevice, MusicArtwork, MusicEncoder, MusicEQPreset, MusicPlaylist, MusicAudioCDPlaylist, MusicLibraryPlaylist, MusicRadioTunerPlaylist, MusicSource, MusicSubscriptionPlaylist, MusicTrack, MusicAudioCDTrack, MusicFileTrack, MusicSharedTrack, MusicURLTrack, MusicUserPlaylist, MusicFolderPlaylist, MusicVisual, MusicWindow, MusicBrowserWindow, MusicEQWindow, MusicMiniplayerWindow, MusicPlaylistWindow, MusicVideoWindow;
+
+enum MusicEKnd {
+	MusicEKndTrackListing = 'kTrk' /* a basic listing of tracks within a playlist */,
+	MusicEKndAlbumListing = 'kAlb' /* a listing of a playlist grouped by album */,
+	MusicEKndCdInsert = 'kCDi' /* a printout of the playlist for jewel case inserts */
+};
+typedef enum MusicEKnd MusicEKnd;
+
+enum MusicEnum {
+	MusicEnumStandard = 'lwst' /* Standard PostScript error handling */,
+	MusicEnumDetailed = 'lwdt' /* print a detailed report of PostScript errors */
+};
+typedef enum MusicEnum MusicEnum;
+
+enum MusicEPlS {
+	MusicEPlSStopped = 'kPSS',
+	MusicEPlSPlaying = 'kPSP',
+	MusicEPlSPaused = 'kPSp',
+	MusicEPlSFastForwarding = 'kPSF',
+	MusicEPlSRewinding = 'kPSR'
+};
+typedef enum MusicEPlS MusicEPlS;
+
+enum MusicERpt {
+	MusicERptOff = 'kRpO',
+	MusicERptOne = 'kRp1',
+	MusicERptAll = 'kAll'
+};
+typedef enum MusicERpt MusicERpt;
+
+enum MusicEShM {
+	MusicEShMSongs = 'kShS',
+	MusicEShMAlbums = 'kShA',
+	MusicEShMGroupings = 'kShG'
+};
+typedef enum MusicEShM MusicEShM;
+
+enum MusicESrc {
+	MusicESrcLibrary = 'kLib',
+	MusicESrcIPod = 'kPod',
+	MusicESrcAudioCD = 'kACD',
+	MusicESrcMP3CD = 'kMCD',
+	MusicESrcRadioTuner = 'kTun',
+	MusicESrcSharedLibrary = 'kShd',
+	MusicESrcITunesStore = 'kITS',
+	MusicESrcUnknown = 'kUnk'
+};
+typedef enum MusicESrc MusicESrc;
+
+enum MusicESrA {
+	MusicESrAAlbums = 'kSrL' /* albums only */,
+	MusicESrAAll = 'kAll' /* all text fields */,
+	MusicESrAArtists = 'kSrR' /* artists only */,
+	MusicESrAComposers = 'kSrC' /* composers only */,
+	MusicESrADisplayed = 'kSrV' /* visible text fields */,
+	MusicESrASongs = 'kSrS' /* song names only */
+};
+typedef enum MusicESrA MusicESrA;
+
+enum MusicESpK {
+	MusicESpKNone = 'kNon',
+	MusicESpKFolder = 'kSpF',
+	MusicESpKGenius = 'kSpG',
+	MusicESpKLibrary = 'kSpL',
+	MusicESpKMusic = 'kSpZ',
+	MusicESpKPurchasedMusic = 'kSpM'
+};
+typedef enum MusicESpK MusicESpK;
+
+enum MusicEMdK {
+	MusicEMdKSong = 'kMdS' /* music track */,
+	MusicEMdKMusicVideo = 'kVdV' /* music video track */,
+	MusicEMdKUnknown = 'kUnk'
+};
+typedef enum MusicEMdK MusicEMdK;
+
+enum MusicERtK {
+	MusicERtKUser = 'kRtU' /* user-specified rating */,
+	MusicERtKComputed = 'kRtC' /* iTunes-computed rating */
+};
+typedef enum MusicERtK MusicERtK;
+
+enum MusicEAPD {
+	MusicEAPDComputer = 'kAPC',
+	MusicEAPDAirPortExpress = 'kAPX',
+	MusicEAPDAppleTV = 'kAPT',
+	MusicEAPDAirPlayDevice = 'kAPO',
+	MusicEAPDBluetoothDevice = 'kAPB',
+	MusicEAPDHomePod = 'kAPH',
+	MusicEAPDUnknown = 'kAPU'
+};
+typedef enum MusicEAPD MusicEAPD;
+
+enum MusicEClS {
+	MusicEClSUnknown = 'kUnk',
+	MusicEClSPurchased = 'kPur',
+	MusicEClSMatched = 'kMat',
+	MusicEClSUploaded = 'kUpl',
+	MusicEClSIneligible = 'kRej',
+	MusicEClSRemoved = 'kRem',
+	MusicEClSError = 'kErr',
+	MusicEClSDuplicate = 'kDup',
+	MusicEClSSubscription = 'kSub',
+	MusicEClSNoLongerAvailable = 'kRev',
+	MusicEClSNotUploaded = 'kUpP'
+};
+typedef enum MusicEClS MusicEClS;
+
+@protocol MusicGenericMethods
+
+- (void) printPrintDialog:(BOOL)printDialog withProperties:(NSDictionary *)withProperties kind:(MusicEKnd)kind theme:(NSString *)theme;  // Print the specified object(s)
+- (void) close;  // Close an object
+- (void) delete;  // Delete an element from an object
+- (SBObject *) duplicateTo:(SBObject *)to;  // Duplicate one or more object(s)
+- (BOOL) exists;  // Verify if an object exists
+- (void) open;  // Open the specified object(s)
+- (void) save;  // Save the specified object(s)
+- (void) playOnce:(BOOL)once;  // play the current track or the specified track or file.
+- (void) select;  // select the specified object(s)
+
+@end
+
+
+
+/*
+ * iTunes Suite
+ */
+
+// The application program
+@interface MusicApplication : SBApplication
+
+- (SBElementArray<MusicAirPlayDevice *> *) AirPlayDevices;
+- (SBElementArray<MusicBrowserWindow *> *) browserWindows;
+- (SBElementArray<MusicEncoder *> *) encoders;
+- (SBElementArray<MusicEQPreset *> *) EQPresets;
+- (SBElementArray<MusicEQWindow *> *) EQWindows;
+- (SBElementArray<MusicMiniplayerWindow *> *) miniplayerWindows;
+- (SBElementArray<MusicPlaylist *> *) playlists;
+- (SBElementArray<MusicPlaylistWindow *> *) playlistWindows;
+- (SBElementArray<MusicSource *> *) sources;
+- (SBElementArray<MusicTrack *> *) tracks;
+- (SBElementArray<MusicVideoWindow *> *) videoWindows;
+- (SBElementArray<MusicVisual *> *) visuals;
+- (SBElementArray<MusicWindow *> *) windows;
+
+@property (readonly) BOOL AirPlayEnabled;  // is AirPlay currently enabled?
+@property (readonly) BOOL converting;  // is a track currently being converted?
+@property (copy) NSArray<MusicAirPlayDevice *> *currentAirPlayDevices;  // the currently selected AirPlay device(s)
+@property (copy) MusicEncoder *currentEncoder;  // the currently selected encoder (MP3, AIFF, WAV, etc.)
+@property (copy) MusicEQPreset *currentEQPreset;  // the currently selected equalizer preset
+@property (copy, readonly) MusicPlaylist *currentPlaylist;  // the playlist containing the currently targeted track
+@property (copy, readonly) NSString *currentStreamTitle;  // the name of the current song in the playing stream (provided by streaming server)
+@property (copy, readonly) NSString *currentStreamURL;  // the URL of the playing stream or streaming web site (provided by streaming server)
+@property (copy, readonly) MusicTrack *currentTrack;  // the current targeted track
+@property (copy) MusicVisual *currentVisual;  // the currently selected visual plug-in
+@property BOOL EQEnabled;  // is the equalizer enabled?
+@property BOOL fixedIndexing;  // true if all AppleScript track indices should be independent of the play order of the owning playlist.
+@property BOOL frontmost;  // is iTunes the frontmost application?
+@property BOOL fullScreen;  // are visuals displayed using the entire screen?
+@property (copy, readonly) NSString *name;  // the name of the application
+@property BOOL mute;  // has the sound output been muted?
+@property double playerPosition;  // the player’s position within the currently playing track in seconds.
+@property (readonly) MusicEPlS playerState;  // is iTunes stopped, paused, or playing?
+@property (copy, readonly) SBObject *selection;  // the selection visible to the user
+@property BOOL shuffleEnabled;  // are songs played in random order?
+@property MusicEShM shuffleMode;  // the playback shuffle mode
+@property MusicERpt songRepeat;  // the playback repeat mode
+@property NSInteger soundVolume;  // the sound output volume (0 = minimum, 100 = maximum)
+@property (copy, readonly) NSString *version;  // the version of iTunes
+@property BOOL visualsEnabled;  // are visuals currently being displayed?
+
+- (void) printPrintDialog:(BOOL)printDialog withProperties:(NSDictionary *)withProperties kind:(MusicEKnd)kind theme:(NSString *)theme;  // Print the specified object(s)
+- (void) run;  // Run iTunes
+- (void) quit;  // Quit iTunes
+- (MusicTrack *) add:(NSArray<NSURL *> *)x to:(SBObject *)to;  // add one or more files to a playlist
+- (void) backTrack;  // reposition to beginning of current track or go to previous track if already at start of current track
+- (MusicTrack *) convert:(NSArray<SBObject *> *)x;  // convert one or more files or tracks
+- (void) fastForward;  // skip forward in a playing track
+- (void) nextTrack;  // advance to the next track in the current playlist
+- (void) pause;  // pause playback
+- (void) playOnce:(BOOL)once;  // play the current track or the specified track or file.
+- (void) playpause;  // toggle the playing/paused state of the current track
+- (void) previousTrack;  // return to the previous track in the current playlist
+- (void) resume;  // disable fast forward/rewind and resume playback, if playing.
+- (void) rewind;  // skip backwards in a playing track
+- (void) stop;  // stop playback
+- (void) openLocation:(NSString *)x;  // Opens a Music Store or audio stream URL
+
+@end
+
+// an item
+@interface MusicItem : SBObject <MusicGenericMethods>
+
+@property (copy, readonly) SBObject *container;  // the container of the item
+- (NSInteger) id;  // the id of the item
+@property (readonly) NSInteger index;  // The index of the item in internal application order.
+@property (copy) NSString *name;  // the name of the item
+@property (copy, readonly) NSString *persistentID;  // the id of the item as a hexadecimal string. This id does not change over time.
+@property (copy) NSDictionary *properties;  // every property of the item
+
+- (void) download;  // download a cloud track or playlist
+- (void) reveal;  // reveal and select a track or playlist
+
+@end
+
+// an AirPlay device
+@interface MusicAirPlayDevice : MusicItem
+
+@property (readonly) BOOL active;  // is the device currently being played to?
+@property (readonly) BOOL available;  // is the device currently available?
+@property (readonly) MusicEAPD kind;  // the kind of the device
+@property (copy, readonly) NSString *networkAddress;  // the network (MAC) address of the device
+- (BOOL) protected;  // is the device password- or passcode-protected?
+@property BOOL selected;  // is the device currently selected?
+@property (readonly) BOOL supportsAudio;  // does the device support audio playback?
+@property (readonly) BOOL supportsVideo;  // does the device support video playback?
+@property NSInteger soundVolume;  // the output volume for the device (0 = minimum, 100 = maximum)
+
+
+@end
+
+// a piece of art within a track or playlist
+@interface MusicArtwork : MusicItem
+
+@property (copy) NSImage *data;  // data for this artwork, in the form of a picture
+@property (copy) NSString *objectDescription;  // description of artwork as a string
+@property (readonly) BOOL downloaded;  // was this artwork downloaded by iTunes?
+@property (copy, readonly) NSNumber *format;  // the data format for this piece of artwork
+@property NSInteger kind;  // kind or purpose of this piece of artwork
+@property (copy) NSData *rawData;  // data for this artwork, in original format
+
+
+@end
+
+// converts a track to a specific file format
+@interface MusicEncoder : MusicItem
+
+@property (copy, readonly) NSString *format;  // the data format created by the encoder
+
+
+@end
+
+// equalizer preset configuration
+@interface MusicEQPreset : MusicItem
+
+@property double band1;  // the equalizer 32 Hz band level (-12.0 dB to +12.0 dB)
+@property double band2;  // the equalizer 64 Hz band level (-12.0 dB to +12.0 dB)
+@property double band3;  // the equalizer 125 Hz band level (-12.0 dB to +12.0 dB)
+@property double band4;  // the equalizer 250 Hz band level (-12.0 dB to +12.0 dB)
+@property double band5;  // the equalizer 500 Hz band level (-12.0 dB to +12.0 dB)
+@property double band6;  // the equalizer 1 kHz band level (-12.0 dB to +12.0 dB)
+@property double band7;  // the equalizer 2 kHz band level (-12.0 dB to +12.0 dB)
+@property double band8;  // the equalizer 4 kHz band level (-12.0 dB to +12.0 dB)
+@property double band9;  // the equalizer 8 kHz band level (-12.0 dB to +12.0 dB)
+@property double band10;  // the equalizer 16 kHz band level (-12.0 dB to +12.0 dB)
+@property (readonly) BOOL modifiable;  // can this preset be modified?
+@property double preamp;  // the equalizer preamp level (-12.0 dB to +12.0 dB)
+@property BOOL updateTracks;  // should tracks which refer to this preset be updated when the preset is renamed or deleted?
+
+
+@end
+
+// a list of songs/streams
+@interface MusicPlaylist : MusicItem
+
+- (SBElementArray<MusicTrack *> *) tracks;
+- (SBElementArray<MusicArtwork *> *) artworks;
+
+@property (copy) NSString *objectDescription;  // the description of the playlist
+@property BOOL disliked;  // is this playlist disliked?
+@property (readonly) NSInteger duration;  // the total length of all songs (in seconds)
+@property (copy) NSString *name;  // the name of the playlist
+@property BOOL loved;  // is this playlist loved?
+@property (copy, readonly) MusicPlaylist *parent;  // folder which contains this playlist (if any)
+@property (readonly) NSInteger size;  // the total size of all songs (in bytes)
+@property (readonly) MusicESpK specialKind;  // special playlist kind
+@property (copy, readonly) NSString *time;  // the length of all songs in MM:SS format
+@property (readonly) BOOL visible;  // is this playlist visible in the Source list?
+
+- (void) moveTo:(SBObject *)to;  // Move playlist(s) to a new location
+- (MusicTrack *) searchFor:(NSString *)for_ only:(MusicESrA)only;  // search a playlist for tracks matching the search string. Identical to entering search text in the Search field in iTunes.
+
+@end
+
+// a playlist representing an audio CD
+@interface MusicAudioCDPlaylist : MusicPlaylist
+
+- (SBElementArray<MusicAudioCDTrack *> *) audioCDTracks;
+
+@property (copy) NSString *artist;  // the artist of the CD
+@property BOOL compilation;  // is this CD a compilation album?
+@property (copy) NSString *composer;  // the composer of the CD
+@property NSInteger discCount;  // the total number of discs in this CD’s album
+@property NSInteger discNumber;  // the index of this CD disc in the source album
+@property (copy) NSString *genre;  // the genre of the CD
+@property NSInteger year;  // the year the album was recorded/released
+
+
+@end
+
+// the master music library playlist
+@interface MusicLibraryPlaylist : MusicPlaylist
+
+- (SBElementArray<MusicFileTrack *> *) fileTracks;
+- (SBElementArray<MusicURLTrack *> *) URLTracks;
+- (SBElementArray<MusicSharedTrack *> *) sharedTracks;
+
+
+@end
+
+// the radio tuner playlist
+@interface MusicRadioTunerPlaylist : MusicPlaylist
+
+- (SBElementArray<MusicURLTrack *> *) URLTracks;
+
+
+@end
+
+// a music source (music library, CD, device, etc.)
+@interface MusicSource : MusicItem
+
+- (SBElementArray<MusicAudioCDPlaylist *> *) audioCDPlaylists;
+- (SBElementArray<MusicLibraryPlaylist *> *) libraryPlaylists;
+- (SBElementArray<MusicPlaylist *> *) playlists;
+- (SBElementArray<MusicRadioTunerPlaylist *> *) radioTunerPlaylists;
+- (SBElementArray<MusicSubscriptionPlaylist *> *) subscriptionPlaylists;
+- (SBElementArray<MusicUserPlaylist *> *) userPlaylists;
+
+@property (readonly) long long capacity;  // the total size of the source if it has a fixed size
+@property (readonly) long long freeSpace;  // the free space on the source if it has a fixed size
+@property (readonly) MusicESrc kind;
+
+
+@end
+
+// a subscription playlist from Apple Music
+@interface MusicSubscriptionPlaylist : MusicPlaylist
+
+- (SBElementArray<MusicFileTrack *> *) fileTracks;
+- (SBElementArray<MusicURLTrack *> *) URLTracks;
+
+
+@end
+
+// playable audio source
+@interface MusicTrack : MusicItem
+
+- (SBElementArray<MusicArtwork *> *) artworks;
+
+@property (copy) NSString *album;  // the album name of the track
+@property (copy) NSString *albumArtist;  // the album artist of the track
+@property BOOL albumDisliked;  // is the album for this track disliked?
+@property BOOL albumLoved;  // is the album for this track loved?
+@property NSInteger albumRating;  // the rating of the album for this track (0 to 100)
+@property (readonly) MusicERtK albumRatingKind;  // the rating kind of the album rating for this track
+@property (copy) NSString *artist;  // the artist/source of the track
+@property (readonly) NSInteger bitRate;  // the bit rate of the track (in kbps)
+@property double bookmark;  // the bookmark time of the track in seconds
+@property BOOL bookmarkable;  // is the playback position for this track remembered?
+@property NSInteger bpm;  // the tempo of this track in beats per minute
+@property (copy) NSString *category;  // the category of the track
+@property (readonly) MusicEClS cloudStatus;  // the iCloud status of the track
+@property (copy) NSString *comment;  // freeform notes about the track
+@property BOOL compilation;  // is this track from a compilation album?
+@property (copy) NSString *composer;  // the composer of the track
+@property (readonly) NSInteger databaseID;  // the common, unique ID for this track. If two tracks in different playlists have the same database ID, they are sharing the same data.
+@property (copy, readonly) NSDate *dateAdded;  // the date the track was added to the playlist
+@property (copy) NSString *objectDescription;  // the description of the track
+@property NSInteger discCount;  // the total number of discs in the source album
+@property NSInteger discNumber;  // the index of the disc containing this track on the source album
+@property BOOL disliked;  // is this track disliked?
+@property (copy, readonly) NSString *downloaderAppleID;  // the Apple ID of the person who downloaded this track
+@property (copy, readonly) NSString *downloaderName;  // the name of the person who downloaded this track
+@property (readonly) double duration;  // the length of the track in seconds
+@property BOOL enabled;  // is this track checked for playback?
+@property (copy) NSString *episodeID;  // the episode ID of the track
+@property NSInteger episodeNumber;  // the episode number of the track
+@property (copy) NSString *EQ;  // the name of the EQ preset of the track
+@property double finish;  // the stop time of the track in seconds
+@property BOOL gapless;  // is this track from a gapless album?
+@property (copy) NSString *genre;  // the music/audio genre (category) of the track
+@property (copy) NSString *grouping;  // the grouping (piece) of the track. Generally used to denote movements within a classical work.
+@property (copy, readonly) NSString *kind;  // a text description of the track
+@property (copy) NSString *longDescription;
+@property BOOL loved;  // is this track loved?
+@property (copy) NSString *lyrics;  // the lyrics of the track
+@property MusicEMdK mediaKind;  // the media kind of the track
+@property (copy, readonly) NSDate *modificationDate;  // the modification date of the content of this track
+@property (copy) NSString *movement;  // the movement name of the track
+@property NSInteger movementCount;  // the total number of movements in the work
+@property NSInteger movementNumber;  // the index of the movement in the work
+@property NSInteger playedCount;  // number of times this track has been played
+@property (copy) NSDate *playedDate;  // the date and time this track was last played
+@property (copy, readonly) NSString *purchaserAppleID;  // the Apple ID of the person who purchased this track
+@property (copy, readonly) NSString *purchaserName;  // the name of the person who purchased this track
+@property NSInteger rating;  // the rating of this track (0 to 100)
+@property (readonly) MusicERtK ratingKind;  // the rating kind of this track
+@property (copy, readonly) NSDate *releaseDate;  // the release date of this track
+@property (readonly) NSInteger sampleRate;  // the sample rate of the track (in Hz)
+@property NSInteger seasonNumber;  // the season number of the track
+@property BOOL shufflable;  // is this track included when shuffling?
+@property NSInteger skippedCount;  // number of times this track has been skipped
+@property (copy) NSDate *skippedDate;  // the date and time this track was last skipped
+@property (copy) NSString *show;  // the show name of the track
+@property (copy) NSString *sortAlbum;  // override string to use for the track when sorting by album
+@property (copy) NSString *sortArtist;  // override string to use for the track when sorting by artist
+@property (copy) NSString *sortAlbumArtist;  // override string to use for the track when sorting by album artist
+@property (copy) NSString *sortName;  // override string to use for the track when sorting by name
+@property (copy) NSString *sortComposer;  // override string to use for the track when sorting by composer
+@property (copy) NSString *sortShow;  // override string to use for the track when sorting by show name
+@property (readonly) long long size;  // the size of the track (in bytes)
+@property double start;  // the start time of the track in seconds
+@property (copy, readonly) NSString *time;  // the length of the track in MM:SS format
+@property NSInteger trackCount;  // the total number of tracks on the source album
+@property NSInteger trackNumber;  // the index of the track on the source album
+@property BOOL unplayed;  // is this track unplayed?
+@property NSInteger volumeAdjustment;  // relative volume adjustment of the track (-100% to 100%)
+@property (copy) NSString *work;  // the work name of the track
+@property NSInteger year;  // the year the track was recorded/released
+
+
+@end
+
+// a track on an audio CD
+@interface MusicAudioCDTrack : MusicTrack
+
+@property (copy, readonly) NSURL *location;  // the location of the file represented by this track
+
+
+@end
+
+// a track representing an audio file (MP3, AIFF, etc.)
+@interface MusicFileTrack : MusicTrack
+
+@property (copy) NSURL *location;  // the location of the file represented by this track
+
+- (void) refresh;  // update file track information from the current information in the track’s file
+
+@end
+
+// a track residing in a shared library
+@interface MusicSharedTrack : MusicTrack
+
+
+@end
+
+// a track representing a network stream
+@interface MusicURLTrack : MusicTrack
+
+@property (copy) NSString *address;  // the URL for this track
+
+
+@end
+
+// custom playlists created by the user
+@interface MusicUserPlaylist : MusicPlaylist
+
+- (SBElementArray<MusicFileTrack *> *) fileTracks;
+- (SBElementArray<MusicURLTrack *> *) URLTracks;
+- (SBElementArray<MusicSharedTrack *> *) sharedTracks;
+
+@property BOOL shared;  // is this playlist shared?
+@property (readonly) BOOL smart;  // is this a Smart Playlist?
+@property (readonly) BOOL genius;  // is this a Genius Playlist?
+
+
+@end
+
+// a folder that contains other playlists
+@interface MusicFolderPlaylist : MusicUserPlaylist
+
+
+@end
+
+// a visual plug-in
+@interface MusicVisual : MusicItem
+
+
+@end
+
+// any window
+@interface MusicWindow : MusicItem
+
+@property NSRect bounds;  // the boundary rectangle for the window
+@property (readonly) BOOL closeable;  // does the window have a close button?
+@property (readonly) BOOL collapseable;  // does the window have a collapse button?
+@property BOOL collapsed;  // is the window collapsed?
+@property BOOL fullScreen;  // is the window full screen?
+@property NSPoint position;  // the upper left position of the window
+@property (readonly) BOOL resizable;  // is the window resizable?
+@property BOOL visible;  // is the window visible?
+@property (readonly) BOOL zoomable;  // is the window zoomable?
+@property BOOL zoomed;  // is the window zoomed?
+
+
+@end
+
+// the main iTunes window
+@interface MusicBrowserWindow : MusicWindow
+
+@property (copy, readonly) SBObject *selection;  // the selected songs
+@property (copy) MusicPlaylist *view;  // the playlist currently displayed in the window
+
+
+@end
+
+// the iTunes equalizer window
+@interface MusicEQWindow : MusicWindow
+
+
+@end
+
+// the miniplayer window
+@interface MusicMiniplayerWindow : MusicWindow
+
+
+@end
+
+// a sub-window showing a single playlist
+@interface MusicPlaylistWindow : MusicWindow
+
+@property (copy, readonly) SBObject *selection;  // the selected songs
+@property (copy, readonly) MusicPlaylist *view;  // the playlist displayed in the window
+
+
+@end
+
+// the video window
+@interface MusicVideoWindow : MusicWindow
+
+
+@end
+

BGMApp/BGMApp/Music Players/Swinsian.h

@@ -0,0 +1,252 @@
+/*
+ * Swinsian.h
+ *
+ * Generated with
+ * sdef /Applications/Swinsian.app | sdp -fh --basename Swinsian
+ */
+
+#import <AppKit/AppKit.h>
+#import <ScriptingBridge/ScriptingBridge.h>
+
+
+@class SwinsianItem, SwinsianColor, SwinsianWindow, SwinsianApplication, SwinsianPlaylist, SwinsianLibrary, SwinsianTrack, SwinsianLibraryTrack, SwinsianIPodTrack, SwinsianQueue, SwinsianSmartPlaylist, SwinsianNormalPlaylist, SwinsianPlaylistFolder, SwinsianAudioDevice;
+
+enum SwinsianSaveOptions {
+	SwinsianSaveOptionsYes = 'yes ' /* Save the file. */,
+	SwinsianSaveOptionsNo = 'no  ' /* Do not save the file. */,
+	SwinsianSaveOptionsAsk = 'ask ' /* Ask the user whether or not to save the file. */
+};
+typedef enum SwinsianSaveOptions SwinsianSaveOptions;
+
+enum SwinsianPlayerState {
+	SwinsianPlayerStateStopped = 'kPSS',
+	SwinsianPlayerStatePlaying = 'kPSP',
+	SwinsianPlayerStatePaused = 'kPSp'
+};
+typedef enum SwinsianPlayerState SwinsianPlayerState;
+
+@protocol SwinsianGenericMethods
+
+- (void) closeSaving:(SwinsianSaveOptions)saving savingIn:(NSURL *)savingIn;  // Close an object.
+- (void) delete;  // Delete an object.
+- (void) duplicateTo:(SBObject *)to withProperties:(NSDictionary *)withProperties;  // Copy object(s) and put the copies at a new location.
+- (BOOL) exists;  // Verify if an object exists.
+- (void) moveTo:(SBObject *)to;  // Move object(s) to a new location.
+- (void) saveIn:(NSURL *)in_ as:(NSString *)as;  // Save an object.
+
+@end
+
+
+
+/*
+ * Standard Suite
+ */
+
+// A scriptable object.
+@interface SwinsianItem : SBObject <SwinsianGenericMethods>
+
+@property (copy) NSDictionary *properties;  // All of the object's properties.
+
+
+@end
+
+// A color.
+@interface SwinsianColor : SBObject <SwinsianGenericMethods>
+
+
+@end
+
+// A window.
+@interface SwinsianWindow : SBObject <SwinsianGenericMethods>
+
+@property (copy) NSString *name;  // The full title of the window.
+- (NSNumber *) id;  // The unique identifier of the window.
+@property NSRect bounds;  // The bounding rectangle of the window.
+@property (readonly) BOOL closeable;  // Whether the window has a close box.
+@property (readonly) BOOL titled;  // Whether the window has a title bar.
+@property (copy) NSNumber *index;  // The index of the window in the back-to-front window ordering.
+@property (readonly) BOOL floating;  // Whether the window floats.
+@property (readonly) BOOL miniaturizable;  // Whether the window can be miniaturized.
+@property BOOL miniaturized;  // Whether the window is currently miniaturized.
+@property (readonly) BOOL modal;  // Whether the window is the application's current modal window.
+@property (readonly) BOOL resizable;  // Whether the window can be resized.
+@property BOOL visible;  // Whether the window is currently visible.
+@property (readonly) BOOL zoomable;  // Whether the window can be zoomed.
+@property BOOL zoomed;  // Whether the window is currently zoomed.
+@property (copy, readonly) NSArray<SwinsianTrack *> *selection;  // Currently seleted tracks
+
+
+@end
+
+
+
+/*
+ * Swinsian Suite
+ */
+
+// The application
+@interface SwinsianApplication : SBApplication
+
+- (SBElementArray<SwinsianWindow *> *) windows;
+- (SBElementArray<SwinsianPlaylist *> *) playlists;
+- (SBElementArray<SwinsianSmartPlaylist *> *) smartPlaylists;
+- (SBElementArray<SwinsianNormalPlaylist *> *) normalPlaylists;
+- (SBElementArray<SwinsianLibrary *> *) libraries;
+- (SBElementArray<SwinsianTrack *> *) tracks;
+- (SBElementArray<SwinsianAudioDevice *> *) audioDevices;
+
+@property (copy, readonly) NSString *name;  // The name of the application.
+@property (readonly) BOOL frontmost;  // Is this the frontmost (active) application?
+@property (copy, readonly) NSString *version;  // The version of the application.
+@property NSInteger playerPosition;  // the player’s position within the currently playing track in seconds.
+@property (copy, readonly) SwinsianTrack *currentTrack;  // the currently playing track
+@property (copy) NSNumber *soundVolume;  // the volume. (0 minimum, 100 maximum)
+@property (readonly) SwinsianPlayerState playerState;  // are we stopped, paused or still playing?
+@property (copy, readonly) SwinsianQueue *playbackQueue;  // the currently queued tracks
+@property (copy) SwinsianAudioDevice *outputDevice;  // current audio output device
+
+- (void) open:(NSURL *)x;  // Open an object.
+- (void) print:(NSURL *)x;  // Print an object.
+- (void) quitSaving:(SwinsianSaveOptions)saving;  // Quit an application.
+- (void) play;  // begin playing the current playlist
+- (void) pause;  // pause playback
+- (void) nextTrack;  // skip to the next track in the current playlist
+- (void) stop;  // stop playback
+- (NSArray<SwinsianTrack *> *) searchPlaylist:(SwinsianPlaylist *)playlist for:(NSString *)for_;  // search a playlist for tracks matching a string
+- (void) previousTrack;  // skip back to the previous track
+- (void) playpause;  // toggle play/pause
+- (void) addTracks:(NSArray<SwinsianTrack *> *)tracks to:(SwinsianNormalPlaylist *)to;  // add a track to a playlist
+- (void) notify;  // show currently playing track notification
+- (void) rescanTags:(NSArray<SwinsianTrack *> *)x;  // rescan tags on tracks
+- (NSArray<SwinsianTrack *> *) findTrack:(NSString *)x;  // Finds tracks for the given path
+- (void) removeTracks:(NSArray<SwinsianTrack *> *)tracks from:(SwinsianNormalPlaylist *)from;  // remove tracks from a playlist
+
+@end
+
+// generic playlist type, subcasses include smart playlist and normal playlist
+@interface SwinsianPlaylist : SwinsianItem
+
+- (SBElementArray<SwinsianTrack *> *) tracks;
+
+@property (copy) NSString *name;  // the name of the playlist
+@property (readonly) BOOL smart;  // is this a smart playlist
+
+
+@end
+
+@interface SwinsianLibrary : SwinsianItem
+
+- (SBElementArray<SwinsianTrack *> *) tracks;
+
+
+
+@end
+
+// a music track
+@interface SwinsianTrack : SwinsianItem
+
+@property (copy) NSString *album;  // the album of the track
+@property (copy) NSString *artist;  // the artist
+@property (copy) NSString *composer;  // the composer
+@property (copy) NSString *genre;  // the genre
+@property (copy, readonly) NSString *time;  // the length of the track in text format as MM:SS
+@property NSInteger year;  // the year the track was recorded
+@property (copy, readonly) NSDate *dateAdded;  // the date the track was added to the library
+@property (readonly) double duration;  // the length of the track in seconds
+@property (copy, readonly) NSString *location;  // location on disk
+@property (readonly) BOOL iPodTrack;  // TRUE if the track is on an iPod
+@property (copy) NSString *name;  // the title of the track (same as title)
+@property (readonly) NSInteger bitRate;  // the bitrate of the track
+@property (copy, readonly) NSString *kind;  // a text description of the type of file the track is
+@property (copy) NSNumber *rating;  // Track rating. 0-5
+@property NSInteger trackNumber;  // the Track number
+@property (readonly) NSInteger fileSize;  // file size in bytes
+@property (copy, readonly) NSImage *albumArt;  // the album artwork
+@property (copy, readonly) NSString *artFormat;  // the data format for this piece of artwork. text that will be "PNG" or "JPEG". getting the album art property first will mean this information has been retrieved already, otherwise the tags for the file will have to be re-read
+@property (copy) NSNumber *discNumber;  // the disc number
+@property (copy) NSNumber *discCount;  // the total number of discs in the album
+- (NSString *) id;  // uuid
+@property (copy) NSString *albumArtist;  // the album artist
+@property (copy, readonly) NSString *albumArtistOrArtist;  // the album artist of the track, or is none is set, the artist
+@property BOOL compilation;  // compilation flag
+@property (copy) NSString *title;  // track title (the same as name)
+@property (copy) NSString *comment;  // the comment
+@property (copy, readonly) NSDate *dateCreated;  // the date created
+@property (readonly) NSInteger channels;  // audio channel count
+@property (readonly) NSInteger sampleRate;  // audio sample rate
+@property (readonly) NSInteger bitDepth;  // the audio bit depth
+@property (copy) NSDate *lastPlayed;  // date track was last played
+@property (copy) NSString *lyrics;  // track lyrics
+@property (copy, readonly) NSString *path;  // POSIX style path
+@property (copy) NSString *grouping;  // grouping
+@property (copy) NSString *publisher;  // the publisher
+@property (copy) NSString *conductor;  // the conductor
+@property (copy) NSString *objectDescription;  // the description
+@property (copy, readonly) NSString *encoder;  // the encoder
+@property (copy, readonly) NSString *copyright;  // the copyright
+@property (copy) NSString *catalogNumber;  // the catalog number
+@property (copy, readonly) NSDate *dateModified;  // the date modified
+@property NSInteger playCount;  // the play count
+@property (copy) NSNumber *trackCount;  // the total number of tracks in the album
+
+
+@end
+
+@interface SwinsianLibraryTrack : SwinsianTrack
+
+
+
+@end
+
+@interface SwinsianIPodTrack : SwinsianTrack
+
+@property (copy, readonly) NSString *iPodName;  // the name of the iPod this track is on
+
+
+@end
+
+// The playback queue
+@interface SwinsianQueue : SwinsianItem
+
+- (SBElementArray<SwinsianTrack *> *) tracks;
+
+
+
+@end
+
+// a smart playlist
+@interface SwinsianSmartPlaylist : SwinsianPlaylist
+
+
+@end
+
+// a normal, non-smart, playlist
+@interface SwinsianNormalPlaylist : SwinsianPlaylist
+
+- (SBElementArray<SwinsianTrack *> *) tracks;
+
+- (NSString *) id;  // uuid
+
+
+@end
+
+// folder of playlists
+@interface SwinsianPlaylistFolder : SwinsianPlaylist
+
+- (SBElementArray<SwinsianPlaylist *> *) playlists;
+
+- (NSString *) id;  // uuid
+
+
+@end
+
+// an audio output device
+@interface SwinsianAudioDevice : SBObject <SwinsianGenericMethods>
+
+@property (copy, readonly) NSString *name;  // device name
+- (NSString *) id;  // uuid
+- (void) setId: (NSString *) id;
+
+
+@end
+

BGMApp/BGMApp/Music Players/VLC.h

@@ -221,7 +221,7 @@ typedef enum VLCEnum VLCEnum;
 @property NSInteger audioVolume;  // The volume of the current playlist item from 0 to 4, where 4 is 400%
 @property NSInteger currentTime;  // The current time of the current playlist item in seconds.
 @property (readonly) NSInteger durationOfCurrentItem;  // The duration of the current playlist item in seconds.
-@property BOOL fullscreenMode;  // indicates wheter fullscreen is enabled or not
+@property BOOL fullscreenMode;  // indicates whether fullscreen is enabled or not
 @property (readonly) BOOL muted;  // Is VLC currently muted?
 @property (copy, readonly) NSString *nameOfCurrentItem;  // Name of the current playlist item.
 @property (copy, readonly) NSString *pathOfCurrentItem;  // Path to the current playlist item.

BGMApp/BGMApp/Music Players/VOX.h

@@ -37,7 +37,7 @@
 - (void) rewindForwardFast;  // Rewind current track forward fast.
 - (void) rewindBackward;  // Rewind current track backward.
 - (void) rewindBackwardFast;  // Rewind current track backward fast.
-- (void) increasVolume;  // Increas volume.
+- (void) increasVolume;  // Increase volume.
 - (void) decreaseVolume;  // Decrease volume.
 - (void) showHidePlaylist;  // Show/Hide playlist.
 
@@ -62,7 +62,7 @@
 @property (copy, readonly) NSString *album;  // Current track album.
 @property (copy, readonly) NSString *uniqueID;  // Unique identifier for the current track.
 @property double currentTime;  // The current playback position.
-@property (readonly) double totalTime;  // The total time of the currenty playing track.
+@property (readonly) double totalTime;  // The total time of the currently playing track.
 @property double playerVolume;  // Player volume (0.0 to 1.0)
 @property NSInteger repeatState;  // Player repeat state (none = 0, repeat one = 1, repeat all = 2)
 

BGMApp/BGMApp/Preferences/BGMAboutPanel.m

@@ -17,7 +17,7 @@
 //  BGMAboutPanel.m
 //  BGMApp
 //
-//  Copyright © 2016 Kyle Neideck
+//  Copyright © 2016, 2024 Kyle Neideck
 //
 
 // Self Include
@@ -27,8 +27,6 @@
 #import "BGM_Types.h"
 
 // PublicUtility Includes
-#undef CoreAudio_ThreadStampMessages
-#define CoreAudio_ThreadStampMessages 0  // Requires C++
 #include "CADebugMacros.h"
 
 
@@ -37,6 +35,7 @@ NS_ASSUME_NONNULL_BEGIN
 static NSInteger const kVersionLabelTag = 1;
 static NSInteger const kCopyrightLabelTag = 2;
 static NSInteger const kProjectWebsiteLabelTag = 3;
+static NSInteger const kContributorsLabelTag = 4;
 
 @implementation BGMAboutPanel {
     NSPanel* aboutPanel;
@@ -44,6 +43,7 @@ static NSInteger const kProjectWebsiteLabelTag = 3;
     NSTextField* versionLabel;
     NSTextField* copyrightLabel;
     NSTextField* websiteLabel;
+    NSTextField* contributorsLabel;
     
     NSTextView* licenseView;
 }
@@ -55,6 +55,7 @@ static NSInteger const kProjectWebsiteLabelTag = 3;
         versionLabel = [[aboutPanel contentView] viewWithTag:kVersionLabelTag];
         copyrightLabel = [[aboutPanel contentView] viewWithTag:kCopyrightLabelTag];
         websiteLabel = [[aboutPanel contentView] viewWithTag:kProjectWebsiteLabelTag];
+        contributorsLabel = [[aboutPanel contentView] viewWithTag:kContributorsLabelTag];
         
         licenseView = inLicenseView;
         
@@ -85,7 +86,10 @@ static NSInteger const kProjectWebsiteLabelTag = 3;
             [[bundle infoDictionary] objectForKey:@"NSHumanReadableCopyright"];
         
         if (copyrightNotice) {
-            copyrightLabel.stringValue = (NSString*)copyrightNotice;
+            // Remove the part that we replace with a link.
+            copyrightLabel.stringValue =
+                [((NSString*)copyrightNotice) stringByReplacingOccurrencesOfString:contributorsLabel.stringValue
+                                                                        withString:@""];
         }
         
         // Project website link label
@@ -93,10 +97,23 @@ static NSInteger const kProjectWebsiteLabelTag = 3;
         websiteLabel.allowsEditingTextAttributes = YES;
         
         NSString* projectURL = [NSString stringWithUTF8String:kBGMProjectURL];
+        NSFont* linkFont = websiteLabel.font ? websiteLabel.font : [NSFont labelFontOfSize:0.0];
         websiteLabel.attributedStringValue =
             [[NSAttributedString alloc] initWithString:projectURL
                                             attributes:@{ NSLinkAttributeName: projectURL,
-                                                          NSFontAttributeName: websiteLabel.font }];
+                                                          NSFontAttributeName: linkFont }];
+        
+        // Contributors link label
+        // TODO: Proper credits (i.e. in the app instead of just a link)
+        contributorsLabel.selectable = YES;
+        contributorsLabel.allowsEditingTextAttributes = YES;
+        
+        NSString* contributorsURL = [NSString stringWithUTF8String:kBGMContributorsURL];
+        NSFont* cLinkFont = contributorsLabel.font ? contributorsLabel.font : [NSFont labelFontOfSize:0.0];
+        contributorsLabel.attributedStringValue =
+            [[NSAttributedString alloc] initWithString:contributorsLabel.stringValue
+                                            attributes:@{ NSLinkAttributeName: contributorsURL,
+                                                          NSFontAttributeName: cLinkFont }];
         
         // Load the text of the license into the text view
         NSString* __nullable licensePath = [bundle pathForResource:@"LICENSE" ofType:nil];
@@ -112,7 +129,7 @@ static NSInteger const kProjectWebsiteLabelTag = 3;
             licenseStr = @"Error: could not open license file.";
         }
         
-        licenseView.string = licenseStr;
+        licenseView.string = (NSString*)licenseStr;
         
         NSFont* __nullable font = [NSFont fontWithName:@"Andale Mono" size:0.0];
         if (font) {
@@ -123,9 +140,25 @@ static NSInteger const kProjectWebsiteLabelTag = 3;
 
 - (void) show {
     DebugMsg("BGMAboutPanel::showAboutPanel: Opening \"About Background Music\" panel");
-    [NSApp activateIgnoringOtherApps:YES];
+    
+    // We have to make aboutPanel visible before calling [NSApp activateIgnoringOtherApps:YES]
+    // or the app won't be activated the first time (not sure why it only happens the first
+    // time) and aboutPanel won't open. WindowServer logs this explanation:
+    // 0[SetFrontProcessWithInfo]: CPS: Rejecting the request for pid 1234 due to the activation count being 0; launch ts=19302059379458, current time=19314267188375, window count = 0.
     [aboutPanel setIsVisible:YES];
     [aboutPanel makeKeyAndOrderFront:self];
+    
+    // On macOS 14.4, aboutPanel needs "Release When Closed" unchecked in MainMenu.xib. Otherwise,
+    // aboutPanel will never open again if you click the close button.
+    
+    // This is deprecated for NSApplication.activate, but that stops aboutPanel from ever being shown.
+    [NSApp activateIgnoringOtherApps:YES];
+    
+    DebugMsg("BGMAboutPanel::showAboutPanel: Finished opening panel. "
+             "aboutPanel.isVisible %d, aboutPanel.isKeyWindow %d, NSApp.isActive %d",
+             aboutPanel.isVisible,
+             aboutPanel.isKeyWindow,
+             NSApp.isActive);
 }
 
 @end

BGMApp/BGMApp/Preferences/BGMAutoPauseMusicPrefs.mm

@@ -17,7 +17,7 @@
 //  BGMAutoPauseMusicPrefs.mm
 //  BGMApp
 //
-//  Copyright © 2016 Kyle Neideck
+//  Copyright © 2016, 2019 Kyle Neideck
 //
 
 // Self Includes
@@ -69,6 +69,7 @@ static NSInteger const kPrefsMenuAutoPauseHeaderTag = 1;
                                                        action:@selector(handleMusicPlayerChange:)
                                                 keyEquivalent:@""
                                                       atIndex:musicPlayerItemsIndex];
+        menuItem.toolTip = musicPlayer.toolTip;
         
         musicPlayerMenuItems = [musicPlayerMenuItems arrayByAddingObject:menuItem];
         

BGMApp/BGMApp/Preferences/BGMPreferencesMenu.h

@@ -17,7 +17,7 @@
 //  BGMPreferencesMenu.h
 //  BGMApp
 //
-//  Copyright © 2016 Kyle Neideck
+//  Copyright © 2016, 2018, 2019 Kyle Neideck
 //
 //  Handles the preferences menu UI. The user's preference changes are often passed directly to the driver rather
 //  than to other BGMApp classes.
@@ -26,6 +26,7 @@
 // Local Includes
 #import "BGMAudioDeviceManager.h"
 #import "BGMMusicPlayers.h"
+#import "BGMStatusBarItem.h"
 
 // System Includes
 #import <Cocoa/Cocoa.h>
@@ -33,11 +34,12 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-@interface BGMPreferencesMenu : NSObject <NSMenuDelegate>
+@interface BGMPreferencesMenu : NSObject
 
 - (id) initWithBGMMenu:(NSMenu*)inBGMMenu
           audioDevices:(BGMAudioDeviceManager*)inAudioDevices
           musicPlayers:(BGMMusicPlayers*)inMusicPlayers
+         statusBarItem:(BGMStatusBarItem*)inStatusBarItem
             aboutPanel:(NSPanel*)inAboutPanel
  aboutPanelLicenseView:(NSTextView*)inAboutPanelLicenseView;
 

BGMApp/BGMApp/Preferences/BGMPreferencesMenu.mm

@@ -17,7 +17,7 @@
 //  BGMPreferencesMenu.mm
 //  BGMApp
 //
-//  Copyright © 2016 Kyle Neideck
+//  Copyright © 2016, 2018, 2019 Kyle Neideck
 //
 
 // Self Include
@@ -25,7 +25,6 @@
 
 // Local Includes
 #import "BGMAutoPauseMusicPrefs.h"
-#import "BGMOutputDevicePrefs.h"
 #import "BGMAboutPanel.h"
 
 
@@ -33,13 +32,19 @@ NS_ASSUME_NONNULL_BEGIN
 
 // Interface Builder tags
 static NSInteger const kPreferencesMenuItemTag = 1;
-static NSInteger const kAboutPanelMenuItemTag = 3;
+static NSInteger const kBGMIconMenuItemTag     = 2;
+static NSInteger const kVolumeIconMenuItemTag  = 3;
+static NSInteger const kAboutPanelMenuItemTag  = 4;
 
 @implementation BGMPreferencesMenu {
-    // Menu sections
+    // Menu sections/items
     BGMAutoPauseMusicPrefs* autoPauseMusicPrefs;
-    BGMOutputDevicePrefs* outputDevicePrefs;
-    
+    NSMenuItem* bgmIconMenuItem;
+    NSMenuItem* volumeIconMenuItem;
+
+    // The menu item you press to open BGMApp's main menu.
+    BGMStatusBarItem* statusBarItem;
+
     // The About Background Music window
     BGMAboutPanel* aboutPanel;
 }
@@ -47,20 +52,33 @@ static NSInteger const kAboutPanelMenuItemTag = 3;
 - (id) initWithBGMMenu:(NSMenu*)inBGMMenu
           audioDevices:(BGMAudioDeviceManager*)inAudioDevices
           musicPlayers:(BGMMusicPlayers*)inMusicPlayers
+         statusBarItem:(BGMStatusBarItem*)inStatusBarItem
             aboutPanel:(NSPanel*)inAboutPanel
  aboutPanelLicenseView:(NSTextView*)inAboutPanelLicenseView {
     if ((self = [super init])) {
         NSMenu* prefsMenu = [[inBGMMenu itemWithTag:kPreferencesMenuItemTag] submenu];
-        [prefsMenu setDelegate:self];
         
         autoPauseMusicPrefs = [[BGMAutoPauseMusicPrefs alloc] initWithPreferencesMenu:prefsMenu
                                                                          audioDevices:inAudioDevices
                                                                          musicPlayers:inMusicPlayers];
         
-        outputDevicePrefs = [[BGMOutputDevicePrefs alloc] initWithAudioDevices:inAudioDevices];
-        
         aboutPanel = [[BGMAboutPanel alloc] initWithPanel:inAboutPanel licenseView:inAboutPanelLicenseView];
-        
+
+        statusBarItem = inStatusBarItem;
+
+        // Set up the menu items under the "Status Bar Icon" heading.
+        bgmIconMenuItem = [prefsMenu itemWithTag:kBGMIconMenuItemTag];
+        bgmIconMenuItem.state =
+                (statusBarItem.icon == BGMFermataStatusBarIcon) ? NSOnState : NSOffState;
+        [bgmIconMenuItem setTarget:self];
+        [bgmIconMenuItem setAction:@selector(useBGMStatusBarIcon)];
+
+        volumeIconMenuItem = [prefsMenu itemWithTag:kVolumeIconMenuItemTag];
+        volumeIconMenuItem.state =
+                (statusBarItem.icon == BGMVolumeStatusBarIcon) ? NSOnState : NSOffState;
+        [volumeIconMenuItem setTarget:self];
+        [volumeIconMenuItem setAction:@selector(useVolumeStatusBarIcon)];
+
         // Set up the "About Background Music" menu item
         NSMenuItem* aboutMenuItem = [prefsMenu itemWithTag:kAboutPanelMenuItemTag];
         [aboutMenuItem setTarget:aboutPanel];
@@ -70,10 +88,27 @@ static NSInteger const kAboutPanelMenuItemTag = 3;
     return self;
 }
 
-#pragma mark NSMenuDelegate
+- (void) useBGMStatusBarIcon {
+    // Change the icon.
+    statusBarItem.icon = BGMFermataStatusBarIcon;
 
-- (void) menuNeedsUpdate:(NSMenu*)menu {
-    [outputDevicePrefs populatePreferencesMenu:menu];
+    // Select/deselect the menu items.
+    bgmIconMenuItem.state = NSOnState;
+    volumeIconMenuItem.state = NSOffState;
+}
+
+- (void) useVolumeStatusBarIcon {
+    // TODO: Maybe we should show a message that tells the user how to hide the built-in volume
+    //       icon. They probably won't want two status bar items that look the same. Or we might be
+    //       able to automatically hide the built-in icon while BGMApp is running and show it again
+    //       when BGMApp is closed.
+
+    // Change the icon.
+    statusBarItem.icon = BGMVolumeStatusBarIcon;
+
+    // Select/deselect the menu items.
+    bgmIconMenuItem.state = NSOffState;
+    volumeIconMenuItem.state = NSOnState;
 }
 
 @end

BGMApp/BGMApp/Scripting/BGMASApplication.h

@@ -0,0 +1,50 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMASApplication.h
+//  BGMApp
+//
+//  Copyright © 2021 Marcus Wu
+//  Copyright © 2021 Kyle Neideck
+//
+//  An AppleScript class for volume and pan settings for running applications.
+//
+
+
+// Local Includes
+#import "BGMAppVolumesController.h"
+
+// System Includes
+#import <Foundation/Foundation.h>
+#import <Cocoa/Cocoa.h>
+
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface BGMASApplication : NSObject
+
+- (instancetype) initWithApplication:(NSRunningApplication*)app
+                          volumeController:(BGMAppVolumesController*)volumeController
+                     parentSpecifier:(NSScriptObjectSpecifier* __nullable)parentSpecifier
+                               index:(int)i;
+
+@property (readonly) NSString* name;
+@property (readonly) NSString* bundleID;
+@property int volume;
+@property int pan;
+@end
+
+NS_ASSUME_NONNULL_END

BGMApp/BGMApp/Scripting/BGMASApplication.m

@@ -0,0 +1,91 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMASApplication.m
+//  BGMApp
+//
+//  Copyright © 2021 Marcus Wu
+//  Copyright © 2021 Kyle Neideck
+//
+
+// Self Include
+#import "BGMASApplication.h"
+
+// Local Includes
+#import "BGM_Types.h"
+
+@implementation BGMASApplication {
+    NSScriptObjectSpecifier* parentSpecifier;
+    NSRunningApplication *application;
+    BGMAppVolumesController* appVolumesController;
+    int index;
+}
+
+- (instancetype) initWithApplication:(NSRunningApplication*)app
+                          volumeController:(BGMAppVolumesController*)volumeController
+                     parentSpecifier:(NSScriptObjectSpecifier* __nullable)parent
+                               index:(int)i {
+    if ((self = [super init])) {
+        parentSpecifier = parent;
+        application = app;
+        appVolumesController = volumeController;
+        index = i;
+    }
+
+    return self;
+}
+
+- (NSString*) name {
+    return [NSString stringWithFormat:@"%@", [application localizedName]];
+}
+
+- (NSString*) bundleID {
+    return [NSString stringWithFormat:@"%@", [application bundleIdentifier]];
+}
+
+- (int) volume {
+    return [appVolumesController getVolumeAndPanForApp:application].volume;
+}
+
+- (void) setVolume:(int)vol {
+    BGMAppVolumeAndPan volume = {
+        .volume = vol,
+        .pan = kAppPanNoValue
+    };
+    [appVolumesController setVolumeAndPan:volume forApp:application];
+}
+
+- (int) pan {
+    return [appVolumesController getVolumeAndPanForApp:application].pan;
+}
+
+- (void) setPan:(int)pan {
+    BGMAppVolumeAndPan thePan = {
+        .volume = -1,
+        .pan = pan
+    };
+    [appVolumesController setVolumeAndPan:thePan forApp:application];
+}
+
+- (NSScriptObjectSpecifier* __nullable) objectSpecifier {
+    NSScriptClassDescription* parentClassDescription = [parentSpecifier keyClassDescription];
+    return [[NSNameSpecifier alloc] initWithContainerClassDescription:parentClassDescription
+                                                   containerSpecifier:parentSpecifier
+                                                                  key:@"applications"
+                                                                 name:self.name];
+}
+
+@end

BGMApp/BGMApp/Scripting/BGMASOutputDevice.h

@@ -0,0 +1,46 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMASOutputDevice.h
+//  BGMApp
+//
+//  Copyright © 2017 Kyle Neideck
+//
+//  An AppleScript class for the output devices that can be selected in the preferences menu.
+//
+
+// Local Includes
+#import "BGMAudioDeviceManager.h"
+
+// System Includes
+#import <Foundation/Foundation.h>
+
+
+#pragma clang assume_nonnull begin
+
+@interface BGMASOutputDevice : NSObject
+
+- (instancetype) initWithAudioObjectID:(AudioObjectID)objID
+                          audioDevices:(BGMAudioDeviceManager*)devices
+                       parentSpecifier:(NSScriptObjectSpecifier* __nullable)parentSpecifier;
+
+@property (readonly) NSString* name;
+@property BOOL selected;  // is this the device to be used for audio output?
+
+@end
+
+#pragma clang assume_nonnull end
+

BGMApp/BGMApp/Scripting/BGMASOutputDevice.mm

@@ -0,0 +1,83 @@
+// This file is part of Background Music.
+//
+// Background Music is free software: you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation, either version 2 of the
+// License, or (at your option) any later version.
+//
+// Background Music is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Background Music. If not, see <http://www.gnu.org/licenses/>.
+
+//
+//  BGMASOutputDevice.mm
+//  BGMApp
+//
+//  Copyright © 2017 Kyle Neideck
+//
+
+// Self Include
+#import "BGMASOutputDevice.h"
+
+// Local Includes
+#import "BGMAudioDevice.h"
+
+// PublicUtility Includes
+#import "CADebugMacros.h"
+
+
+#pragma clang assume_nonnull begin
+
+@implementation BGMASOutputDevice {
+    NSScriptObjectSpecifier* parentSpecifier;
+    BGMAudioDevice device;
+    BGMAudioDeviceManager* audioDevices;
+}
+
+- (instancetype) initWithAudioObjectID:(AudioObjectID)objID
+                          audioDevices:(BGMAudioDeviceManager*)devices
+                       parentSpecifier:(NSScriptObjectSpecifier* __nullable)parent {
+    if ((self = [super init])) {
+        parentSpecifier = parent;
+        device = objID;
+        audioDevices = devices;
+    }
+
+    return self;
+}
+
+- (NSString*) name {
+    return (NSString*)CFBridgingRelease(device.CopyName());
+}
+
+- (BOOL) selected {
+    return [audioDevices isOutputDevice:device];
+}
+
+- (void) setSelected:(BOOL)selected {
+    if (selected && ![self selected]) {
+        DebugMsg("BGMASOutputDevice::setSelected: A script is setting output device to %s",
+                 [[self name] UTF8String]);
+
+        NSError* err = [audioDevices setOutputDeviceWithID:device revertOnFailure:YES];
+        (void)err;  // TODO: Return an error to the script somehow if this isn't nil. Also, should
+                    //       we return an error if the script tries to set this property to false?     
+    }
+}
+
+- (NSScriptObjectSpecifier* __nullable) objectSpecifier {
+    NSScriptClassDescription* parentClassDescription = [parentSpecifier keyClassDescription];
+    return [[NSNameSpecifier alloc] initWithContainerClassDescription:parentClassDescription
+                                                   containerSpecifier:parentSpecifier
+                                                                  key:@"output devices"
+                                                                 name:self.name];
+}
+
+@end
+
+#pragma clang assume_nonnull end
+