# cformandoy/bhclient architecture

> Architecture diagram of the GitHub repository cformandoy/bhclient, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cformandoy/bhclient
- Repository: https://github.com/cformandoy/bhclient

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Build-Time Components"
        DevCI["Developer / CI Runner"]:::ci
        XcodeIDE["Xcode IDE & xcodebuild"]:::build
        subgraph "Xcode Project"
            PBX["project.pbxproj"]:::build
            WS["project.xcworkspace"]:::build
            Scheme["BlackHole.xcscheme"]:::build
        end
        subgraph "Driver Source"
            BHc["BlackHole.c"]:::build
            BHP["BlackHole.plist"]:::build
            BHicns["BlackHole.icns"]:::build
        end
        TestHarness["BlackHoleTests/main.c"]:::build
        DevCI --> XcodeIDE
        XcodeIDE --> PBX
        XcodeIDE --> BHc
        XcodeIDE --> TestHarness
    end

    subgraph "Build Artifacts"
        Artifact[".driver bundles (2ch,16ch,64ch,...)"]:::build
        XcodeIDE --> Artifact
        TestHarness --> Artifact
    end

    subgraph "Packaging"
        CreateInstaller["create_installer.sh"]:::packaging
        WelcomeHTML["welcome.html"]:::packaging
        ConclusionHTML["conclusion.html"]:::packaging
        RequirementsXML["requirements.xml"]:::packaging
        PreInstallScr["scripts/preinstall"]:::packaging
        PostInstallScr["scripts/postinstall"]:::packaging
        Artifact --> CreateInstaller
        CreateInstaller --> WelcomeHTML
        CreateInstaller --> ConclusionHTML
        CreateInstaller --> RequirementsXML
        CreateInstaller --> PreInstallScr
        CreateInstaller --> PostInstallScr
        CreateInstaller --> SignedPkg["Signed & Notarized .pkg"]:::packaging
    end

    Uninstaller["create_uninstaller.sh"]:::packaging
    UninstallerPost["Scripts/postinstall"]:::packaging
    Uninstaller --> UninstallerPost

    Homebrew["Homebrew (optional)"]:::ci

    subgraph "File System"
        HALDir["/Library/Audio/Plug-Ins/HAL/"]:::fs
    end

    SignedPkg -->|Install| HALDir
    Uninstaller -->|Uninstall| HALDir
    Homebrew -->|Alternate install| HALDir

    subgraph "Runtime (macOS Kernel & HAL)"
        CoreAudio["CoreAudio HAL Subsystem"]:::runtime
        BHDriver["BlackHole Driver Bundle"]:::runtime
        HALDir --> CoreAudio
        CoreAudio --> BHDriver
    end

    subgraph "Audio Data Flow"
        SourceApp["Source Application"]:::app
        SinkApp["Sink Application"]:::app
        SourceApp --> CoreAudio
        CoreAudio --> BHDriver
        BHDriver --> CoreAudio
        CoreAudio --> SinkApp
    end

    subgraph "Documentation & Metadata"
        README["README.md"]:::doc
        Changelog["CHANGELOG.md"]:::doc
        License["LICENSE"]:::doc
        Version["VERSION"]:::doc
        Gitignore[".gitignore"]:::doc
        GitHubDir[".github/"]:::doc
    end

    classDef build fill:#ACE,stroke:#333,stroke-width:1px;
    classDef packaging fill:#7FCEFF,stroke:#333,stroke-width:1px;
    classDef fs fill:#8FBC8F,stroke:#333,stroke-width:1px;
    classDef runtime fill:#FFB347,stroke:#333,stroke-width:1px;
    classDef app fill:#D3D3D3,stroke:#333,stroke-width:1px;
    classDef ci fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef doc fill:#CCCCCC,stroke:#333,stroke-width:1px;

    click BHc "https://github.com/cformandoy/bhclient/blob/master/BlackHole/BlackHole.c"
    click BHP "https://github.com/cformandoy/bhclient/blob/master/BlackHole/BlackHole.plist"
    click BHicns "https://github.com/cformandoy/bhclient/blob/master/BlackHole/BlackHole.icns"
    click PBX "https://github.com/cformandoy/bhclient/blob/master/BlackHole.xcodeproj/project.pbxproj"
    click WS "https://github.com/cformandoy/bhclient/tree/master/BlackHole.xcodeproj/project.xcworkspace/"
    click Scheme "https://github.com/cformandoy/bhclient/blob/master/BlackHole.xcodeproj/xcshareddata/xcschemes/BlackHole.xcscheme"
    click TestHarness "https://github.com/cformandoy/bhclient/blob/master/BlackHoleTests/main.c"
    click CreateInstaller "https://github.com/cformandoy/bhclient/blob/master/Installer/create_installer.sh"
    click WelcomeHTML "https://github.com/cformandoy/bhclient/blob/master/Installer/welcome.html"
    click ConclusionHTML "https://github.com/cformandoy/bhclient/blob/master/Installer/conclusion.html"
    click RequirementsXML "https://github.com/cformandoy/bhclient/blob/master/Installer/requirements.xml"
    click PreInstallScr "https://github.com/cformandoy/bhclient/tree/master/Installer/scripts/preinstall"
    click PostInstallScr "https://github.com/cformandoy/bhclient/tree/master/Installer/scripts/postinstall"
    click Uninstaller "https://github.com/cformandoy/bhclient/blob/master/Uninstaller/create_uninstaller.sh"
    click UninstallerPost "https://github.com/cformandoy/bhclient/tree/master/Uninstaller/Scripts/postinstall"
    click GitHubDir "https://github.com/cformandoy/bhclient/tree/master/.github/"
    click README "https://github.com/cformandoy/bhclient/blob/master/README.md"
    click Changelog "https://github.com/cformandoy/bhclient/blob/master/CHANGELOG.md"
    click License "https://github.com/cformandoy/bhclient/tree/master/LICENSE"
    click Version "https://github.com/cformandoy/bhclient/tree/master/VERSION"
    click Gitignore "https://github.com/cformandoy/bhclient/blob/master/.gitignore"
```
