How cformandoy/bhclient works
Project Type and Purpose
• BlackHole is a macOS virtual audio loopback driver (a CoreAudio HAL plugin) written in C and packaged via Xcode into .driver bundles. It enables zero‑latency audio routing between applications on macOS.
File Structure
• Top‑level code:
• BlackHole.xcodeproj/ – Xcode project files defining build targets for multiple channel‑count drivers (2ch, 16ch, etc.) and architectures (Intel, Apple Silicon).
• BlackHoleTests/ – Test harness (main.c) that uses CoreAudio APIs to validate driver behavior.
• Packaging:
• Installer/ – Shell scripts (create_installer.sh) and HTML templates that build, sign, notarize, and package the driver bundle into a macOS installer package.
• Uninstaller/ – Shell script for removing installed driver bundles.
• Documentation and metadata:
• README.md, CHANGELOG.md, VERSION, LICENSE
• .github/ – CI templates, issue templates, funding info.
• Configuration files (.gitignore, Homebrew formula references in README).
Key Insights from README
• Architecture: an Audio Server Plugin (HAL driver) loaded from /Library/Audio/Plug-Ins/HAL/...
• Build customization via Xcode pre‑processor definitions (kNumber_Of_Channels, kSampleRates, etc.)
• Installer script demonstrates CI/CD flow for building, signing, notarizing, and packaging.
• No kernel extensions—pure HAL plugin.
Main Components
a. Developer Environment
• Xcode IDE & Command‑line (xcodebuild)
• Build scripts (create_installer.sh)
• CI/CD runner (GitHub Actions or similar)
b. Build Artifacts
• .driver bundles for each channel configuration
• Test executable (BlackHoleTests)
• Installer Package (.pkg)
c. Installation Targets
• macOS File System (/Library/Audio/Plug-Ins/HAL/BlackHoleXch.driver)
• Uninstaller script
d. Runtime Components
• CoreAudio HAL subsystem (Audio Server)
• BlackHole virtual audio devices (Original & Mirror)
• Source Application (e.g., DAW, browser)
• Sink Application (e.g., recorder, communication app)
e. External Services/Tools
• Homebrew (optional)
• Notarization & Code Signing services
Relationships and Data Flows
• Build flow: Developer/CI → xcodebuild + preprocessor constants → .driver bundles → create_installer.sh → signed/notarized .pkg
• Install flow: User runs .pkg → .driver placed into HAL directory → CoreAudio loads plugin on start → virtual device becomes available system‑wide
• Audio flow: Source App → CoreAudio → BlackHole driver (loopback logic) → CoreAudio → Sink App
• Uninstall flow: User runs uninstaller script or Homebrew uninstall → driver is removed → CoreAudio no longer exposes device
Architectural Patterns and Design Principles
• Configurability via compile‑time constants for channel count, latency, sample rates, and mirrored devices.
• CI/CD automation for reproducible installer packaging and code signing.
• Test‑driven: Separate test harness that links against CoreAudio to validate functionality.