If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/kyleneideck/BackgroundMusic shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit 3mo ago
• 20 active contributors
• GPL-2.0 licensed
• CI configured
• ⚠ Concentrated ownership — top contributor handles 72% of recent commits
• ⚠ GPL-2.0 is copyleft — check downstream compatibility
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live kyleneideck/BackgroundMusic repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/kyleneideck/BackgroundMusic.

What it runs against: a local clone of kyleneideck/BackgroundMusic — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in kyleneideck/BackgroundMusic | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 106 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of kyleneideck/BackgroundMusic. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/kyleneideck/BackgroundMusic.git
#   cd BackgroundMusic
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of kyleneideck/BackgroundMusic and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "kyleneideck/BackgroundMusic(\\.git)?\\b" \\
  && ok "origin remote is kyleneideck/BackgroundMusic" \\
  || miss "origin remote is not kyleneideck/BackgroundMusic (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-2.0" \\
  || miss "license drift — was GPL-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "BGMApp/BGMApp/BGMAppDelegate.mm" \\
  && ok "BGMApp/BGMApp/BGMAppDelegate.mm" \\
  || miss "missing critical file: BGMApp/BGMApp/BGMAppDelegate.mm"
test -f "BGMApp/BGMApp/BGMAudioDeviceManager.mm" \\
  && ok "BGMApp/BGMApp/BGMAudioDeviceManager.mm" \\
  || miss "missing critical file: BGMApp/BGMApp/BGMAudioDeviceManager.mm"
test -f "BGMApp/BGMApp/BGMAutoPauseMusic.mm" \\
  && ok "BGMApp/BGMApp/BGMAutoPauseMusic.mm" \\
  || miss "missing critical file: BGMApp/BGMApp/BGMAutoPauseMusic.mm"
test -f "BGMApp/BGMApp/BGMAppVolumesController.mm" \\
  && ok "BGMApp/BGMApp/BGMAppVolumesController.mm" \\
  || miss "missing critical file: BGMApp/BGMApp/BGMAppVolumesController.mm"
test -f "BGMApp/BGMApp/BGMXPCListener.mm" \\
  && ok "BGMApp/BGMApp/BGMXPCListener.mm" \\
  || miss "missing critical file: BGMApp/BGMApp/BGMXPCListener.mm"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 106 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~76d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/kyleneideck/BackgroundMusic"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Background Music is a macOS system-level audio utility that intercepts and controls audio streams from all applications, enabling three core features: automatic pause/unpause of music players when other audio plays, per-application volume control (with boost capability), and virtual audio device support for recording system audio. It works by inserting a kernel audio device driver and daemon process that monitors audio activity across the system. Multi-target Xcode workspace (BGM.xcworkspace): BGMApp/ contains the main macOS app and UI code (Objective-C++), core audio device abstraction in BGMAudioDevice.cpp, driver installer and XPC helper (BGMXPCHelper scheme), music player integrations under Music Players/ directory, and system daemon communication via XPC for privilege escalation.

macOS users who want fine-grained control over system audio (musicians, podcasters, streamers), and developers contributing to macOS audio system integration who need reference implementations for CoreAudio driver development and inter-process communication patterns.

Actively developed but pre-1.0: marked as 'alpha' in README, version 0.4.3 is current, has CI/CD pipeline in .github/workflows/build-test-release.yml, but last observable commit activity and issue triage velocity would need GitHub inspection. The codebase is substantial (~1.9M lines across C++/ObjC++) and has public releases, indicating serious maintenance, but alpha status suggests some stability concerns remain.

High: single-maintainer repository (kyleneideck), kernel-level audio driver changes risk system audio breakage across macOS versions, requires elevated privileges for installation (driver loading), and macOS version compatibility is explicitly versioned (10.13+ only). Alpha status means breaking changes are possible; relies on deprecated CoreAudio APIs that Apple may change in new OS releases.

GitHub Actions workflow is configured for build-test-release (build-test-release.yml), indicating CI pipeline is active. The presence of multiple .xcscheme files (Background Music, BGMXPCHelper) suggests ongoing refinement of build targets. README mentions snapshot builds available, suggesting regular integration work, but specific current sprint focus would require checking open PRs and Issues.

git clone https://github.com/kyleneideck/BackgroundMusic.git && cd BackgroundMusic && open BGM.xcworkspace (opens Xcode workspace). Select 'Background Music' scheme, set target to your Mac, and Build (⌘B). Run requires code signing and system extension approval on modern macOS.

Daily commands: Build in Xcode: ⌘B to compile. Requires codesigning and system extension approval. Installation: run the built app, which prompts for admin password to install system audio driver. No dev server; runs as persistent menu bar application after installation.

• BGMApp/BGMApp/BGMAppDelegate.mm — Main application entry point and lifecycle manager; initializes audio devices, XPC listener, and UI components that enable all core features.
• BGMApp/BGMApp/BGMAudioDeviceManager.mm — Central manager for audio device lifecycle and control; orchestrates communication between the virtual BGM device and real output devices.
• BGMApp/BGMApp/BGMAutoPauseMusic.mm — Core auto-pause logic that detects when non-music audio plays and triggers pause/unpause on supported music players.
• BGMApp/BGMApp/BGMAppVolumesController.mm — Handles per-application volume control; manages volume sliders in UI and communicates volume changes to audio engine.
• BGMApp/BGMApp/BGMXPCListener.mm — XPC service listener that handles privileged audio operations and inter-process communication between user app and system daemon.
• BGMApp/BGMApp/BGMBackgroundMusicDevice.cpp — Virtual audio device implementation; core of audio routing system that captures and mixes system audio.
• BGMApp/BGMApp/BGMPlayThrough.cpp — Real-time audio passthrough engine; enables recording system audio by managing audio unit graphs and buffer handling.

Add Support for a New Music Player

1. Create a new player adapter class inheriting from BGMMusicPlayer protocol in Music Players folder (BGMApp/BGMApp/Music Players/BGMMusicPlayer.m)
2. Implement play(), pause(), and isPlaying() methods using AppleScript or native APIs (BGMApp/BGMApp/Music Players/BGMSpotify.m)
3. Register the new player in the factory array in BGMMusicPlayers.mm (BGMApp/BGMApp/Music Players/BGMMusicPlayers.mm)
4. Add test integration to verify auto-pause triggers correctly when that player is active (BGMApp/BGMApp/BGMAutoPauseMusic.mm)

Add a New Menu Item or UI Control

1. Define the menu item or control in the XIB file or create a new view controller (BGMApp/BGMApp/Base.lproj/MainMenu.xib)
2. Create an associated .mm or .m file that implements the controller/handler for the new control (BGMApp/BGMApp/BGMOutputVolumeMenuItem.mm)
3. Wire the control to BGMAppDelegate or relevant manager (e.g., BGMAudioDeviceManager) to handle state changes (BGMApp/BGMApp/BGMAppDelegate.mm)
4. Store any persistent state in BGMUserDefaults.m if the preference should be remembered (BGMApp/BGMApp/BGMUserDefaults.m)

Modify Audio Device Control or Detection Logic

1. Locate the relevant device property or control method in BGMAudioDevice.cpp (BGMApp/BGMApp/BGMAudioDevice.cpp)
2. If syncing is needed between virtual and physical devices, update BGMDeviceControlSync.cpp (BGMApp/BGMApp/BGMDeviceControlSync.cpp)
3. Update BGMAudioDeviceManager to call the new method and notify listeners (BGMApp/BGMApp/BGMAudioDeviceManager.mm)
4. Test that real-time audio passthrough in BGMPlayThrough.cpp is not disrupted (BGMApp/BGMApp/BGMPlayThrough.cpp)

Adjust Auto-Pause Behavior or Audio Detection

1. Review the auto-pause state machine and trigger conditions in BGMAutoPauseMusic.mm (BGMApp/BGMApp/BGMAutoPauseMusic.mm)
2. If detection logic changes, update BGMAppWatcher.m to monitor the right applications (BGMApp/BGMApp/BGMAppWatcher.m)
3. If volume thresholds matter, check BGMVolumeChangeListener.cpp for level detection (BGMApp/BGMApp/BGMVolumeChangeListener.cpp)
4. Test pause/unpause calls to the registered music players (BGMApp/BGMApp/Music Players/BGMMusicPlayers.mm)

• CoreAudio / Audio Units — Provides low-latency, real-time access to system audio streams for capture and passthrough; required for recording system audio and virtual device implementation.
• Objective-C / C++ — Necessary for CoreAudio integration (C++ preferred for real-time safety), Cocoa UI (Objective-C), and AppleScript integration via scripting bridge.
• XPC (Inter-Process Communication) — Enables privileged audio operations (device control) in a separate helper process for security and stability; keeps UI process isolated.
• AppleScript / Scripting Bridge — Only practical way to control third-party music players (Spotify, iTunes) without modifying them; avoids dependency injection.
• Cocoa / NSMenu — undefined

Requires valid Developer ID certificate for codesigning (build fails silently without it); system extension (audio driver) must be approved in System Settings > Security & Privacy on Big Sur+, blocking first-run installation; CoreAudio APIs are thread-unsafe in real-time audio contexts (BGMPlayThroughRTLogger.cpp exists to avoid logging in RT threads); macOS 10.13-13 compatibility requires conditional compilation for AudioObjectGetPropertyData calls; XPC communication with elevated helper requires entitlements in both BGMApp-Debug.entitlements and helper plist files.

• CoreAudio Driver Architecture (IOAudio) — Background Music implements a virtual audio driver; understanding IOKit audio device registration and property callbacks is essential to modify the core audio handling in BGMBackgroundMusicDevice.cpp and BGMDeviceControlSync.cpp
• XPC (XPC Services) Privilege Escalation — The app uses XPC to communicate with a helper running as root to load kernel drivers; necessary to understand the security boundary between BGMApp and BGMXPCHelper when modifying privileged operations
• Audio Unit (AU) Plugin Architecture — Background Music intercepts audio at the Audio Unit level; understanding plugin lifecycle, I/O handling, and render callbacks is needed to modify BGMPlayThrough.cpp (playthrough device chain)
• Real-Time Audio Thread Safety — macOS audio callbacks run on real-time threads where blocking, allocation, and logging are forbidden; BGMPlayThroughRTLogger.cpp exists to work around this—critical when modifying audio path code
• AppleScript/NSAppleScript Music Player Control — Auto-pause feature controls music players (Spotify, iTunes) via AppleScript; understanding BGMAutoPauseMusic.mm's script generation and event handling is needed to add new player support
• Aggregate Audio Devices — Recording system audio with a microphone requires combining Background Music device with input via aggregate device; users need this for streaming, docs exist in README but code support in BGMAudioDevice.cpp

• Awesome-Volume-Control/SoundFlower — Predecessor macOS audio routing utility; Background Music partially revives and modernizes this project with per-app volume control
• mixxx/mixxx — Open-source DJ software that also implements per-app audio mixing; reference for real-time audio processing patterns
• elanlevine/AudioSwitch — Lightweight macOS audio output switcher; similar CoreAudio API usage patterns for device enumeration
• tombonez/noisecut — macOS noise suppression built on background audio device approach; shows alternative use of same virtual device mechanism

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for BGMAudioDevice and BGMAudioDeviceManager classes

The core audio device management classes (BGMAudioDevice.cpp/h and BGMAudioDeviceManager.mm) lack visible unit test coverage. Given that Background Music manipulates macOS audio devices at a low level, comprehensive unit tests would prevent regressions in device enumeration, property updates, and control synchronization. This is especially critical since audio device handling is error-prone and affects all users.

• [ ] Create a new test target in BGMApp.xcodeproj for unit tests
• [ ] Write tests for BGMAudioDevice initialization, property getters/setters, and device comparisons
• [ ] Write tests for BGMAudioDeviceManager device discovery, preferred device selection (BGMPreferredOutputDevices.mm), and device change notifications
• [ ] Add tests for BGMDeviceControlSync.cpp to verify control synchronization between devices
• [ ] Integrate tests into .github/workflows/build-test-release.yml CI pipeline

Add comprehensive logging and error handling documentation for BGMXPCListener and privileged helper communication

The BGMXPCListener.mm and XPC helper communication layer are critical security and stability components, but there's no visible documentation on troubleshooting XPC failures, helper installation issues, or debugging inter-process communication. New contributors investigating issues with the helper installer or permission errors would benefit from a dedicated troubleshooting guide with specific error codes and solutions.

• [ ] Create a new TROUBLESHOOTING_XPC.md file documenting common XPC helper failures and their solutions
• [ ] Add inline code documentation to BGMXPCListener.mm explaining the XPC connection lifecycle and error cases
• [ ] Document the privileged helper installation process (referencing the build setup) and validation steps
• [ ] Add a section to the main README linking to XPC troubleshooting for users experiencing 'helper not installed' errors
• [ ] Include examples of enabling debug logging (BGMDebugLoggingMenuItem.m) to diagnose XPC issues

Refactor BGMAppVolumesController to separate UI logic from audio control logic

BGMAppVolumesController.mm appears to handle both the UI table view management and the underlying app volume control logic. This tight coupling makes it harder to test volume logic independently and maintain the code. Splitting this into a data model class (app volumes state/management) and a view controller (UI updates) would follow standard iOS/macOS MVC patterns and improve testability.

• [ ] Create a new BGMAppVolumesModel class to encapsulate app volume storage, persistence, and change notifications (separate from BGMAppVolumes.m)
• [ ] Migrate volume tracking and KVO observation from BGMAppVolumesController into BGMAppVolumesModel
• [ ] Refactor BGMAppVolumesController.mm to use BGMAppVolumesModel as a data source, focusing only on table view delegate/datasource methods
• [ ] Add unit tests for BGMAppVolumesModel volume operations independent of UI
• [ ] Update BGMAppDelegate.mm and other references to use the new architecture

• Add unit tests for BGMAudioDevice.cpp by mocking CoreAudio C APIs—currently no XCTest files visible in the repo despite complex device state management
• Document the XPC protocol interface between BGMApp and BGMXPCHelper (no .h file visible defining method signatures)—would help contributors understand privilege escalation flow
• Add Spotify pausing support retry logic with exponential backoff, since music player AppleScript commands can fail transiently during app startup (observed in BGMAutoPauseMusic.mm but no retry loop)

• Medium · XPC Service Security — BGMApp/BGMApp/BGMXPCListener.mm, BGMApp/BGMApp.xcodeproj/xcshareddata/xcschemes/BGMXPCHelper.xcscheme. The codebase includes XPC (inter-process communication) components (BGMXPCListener.mm, BGMXPCHelper.xcscheme) which are used for privileged operations. XPC services can be vulnerable to privilege escalation if not properly validated. The presence of BGMXPCHelper suggests elevated privilege operations that require careful input validation and entitlement verification. Fix: 1. Implement strict input validation for all XPC messages. 2. Verify XPC caller entitlements before processing requests. 3. Use code signing and entitlements properly. 4. Minimize privileges required by XPC helper. 5. Consider using NSXPCConnection with proper entitlements validation.
• Medium · Privileged Audio Device Access — BGMApp/BGMApp/BGMAudioDevice.cpp, BGMApp/BGMApp/BGMAudioDeviceManager.mm, BGMApp/BGMApp/BGMBackgroundMusicDevice.cpp. The application directly accesses audio devices and system audio controls (BGMAudioDevice.cpp, BGMAudioDeviceManager.mm, BGMBackgroundMusicDevice.h). Direct manipulation of Core Audio APIs requires careful handling to prevent unauthorized audio capture or manipulation. There's potential for privilege escalation if the device manager isn't properly restricted. Fix: 1. Ensure proper entitlements are declared in .entitlements files. 2. Validate all audio device operations. 3. Implement proper error handling for device access failures. 4. Use sandbox restrictions where possible. 5. Log all privileged audio operations for auditing.
• Medium · Potential Path Traversal in App Watching — BGMApp/BGMApp/BGMAppWatcher.h, BGMApp/BGMApp/BGMAppWatcher.m. The BGMAppWatcher component monitors applications and their behavior. If file paths or application identifiers are not properly validated, there could be path traversal vulnerabilities or access to unauthorized application data. Fix: 1. Validate all application paths and identifiers. 2. Use canonical path resolution. 3. Implement whitelist-based access controls. 4. Avoid constructing paths from user-controllable input. 5. Use secure APIs for application enumeration (LSCopyApplicationURLsForBundleIdentifier, etc.).
• Low · Debug Logging in Production — BGMApp/BGMApp/BGMDebugLoggingMenuItem.h, BGMApp/BGMApp/BGMDebugLoggingMenuItem.m, BGMApp/BGMApp/BGMPlayThroughRTLogger.cpp. The presence of BGMDebugLoggingMenuItem.h/m suggests debug logging functionality is available in the UI. If debug logging is enabled in production builds, it could expose sensitive information about audio streams, application behavior, or system configuration. Fix: 1. Ensure debug logging is disabled in release builds. 2. Implement conditional compilation for debug features. 3. Use environment variables to control debug output. 4. Sanitize debug output to exclude sensitive data. 5. Document what information debug mode exposes.
• Low · Insecure User Defaults Storage — BGMApp/BGMApp/BGMUserDefaults.h, BGMApp/BGMApp/BGMUserDefaults.m. BGMUserDefaults uses macOS UserDefaults for storing application preferences. If sensitive configuration data (like preferred devices, volume settings) is stored here, it could be accessible to other applications or users with access to the user's home directory. Fix: 1. Don't store sensitive data in UserDefaults. 2. Use Keychain for sensitive information if needed. 3. Apply proper file permissions to UserDefaults storage. 4. Validate UserDefaults values on read to prevent injection. 5. Document what data is stored and its sensitivity level.
• Low · Missing Entitlements Documentation — BGMApp/BGMApp/BGMApp-Debug.entitlements, BGMApp/BGMApp. The application uses two entitlements files (BGMApp-Debug.entitlements and BGMApp.entitlements) but the specific entitlements and their justification are not visible in the provided structure. This makes it difficult to verify least privilege principle is followed. Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.