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/bitgapp/eqMac 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 — Single-maintainer risk — review before adopting

• Last commit 2w ago
• 4 active contributors
• Apache-2.0 licensed
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 94% of recent commits
• ⚠ No CI workflows detected
• ⚠ 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 bitgapp/eqMac repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/bitgapp/eqMac.

What it runs against: a local clone of bitgapp/eqMac — 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 bitgapp/eqMac | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-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 ≤ 46 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of bitgapp/eqMac. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/bitgapp/eqMac.git
#   cd eqMac
#
# 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 bitgapp/eqMac and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-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 "package.json" \\
  && ok "package.json" \\
  || miss "missing critical file: package.json"
test -f "modules/components/src/components.module.ts" \\
  && ok "modules/components/src/components.module.ts" \\
  || miss "missing critical file: modules/components/src/components.module.ts"
test -f ".eslintrc.js" \\
  && ok ".eslintrc.js" \\
  || miss "missing critical file: .eslintrc.js"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f ".nvmrc" \\
  && ok ".nvmrc" \\
  || miss "missing critical file: .nvmrc"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 46 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~16d)"
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/bitgapp/eqMac"
  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).

eqMac is a macOS system-wide audio equalizer and volume mixer built with Swift (backend) and TypeScript/Angular (UI) that intercepts and processes all system audio output through customizable EQ bands, volume boosting, and spatial audio effects. It solves the problem of applying real-time audio processing to any application's output without requiring individual app configuration, supporting advanced features like 10-band fixed EQ, unlimited custom filter banks, spectrum analysis, and per-app volume mixing. Monorepo with Yarn workspaces: modules/ contains reusable components (modules/components/src/animations/fade-in-out.ts visible), ui/ holds the Angular 12 frontend, api/ likely houses backend services, and site/ is the marketing website. Swift backend (318K lines) handles CoreAudio integration and DSP, while TypeScript/Angular UI (239K lines) provides the control interface. Assets/ contains branding (icon.icns, logos, screenshots).

macOS users who want professional-grade audio control over their system (audiophiles, musicians, gamers, hearing-impaired users needing channel separation); contributors are audio engineers and Electron/Swift developers interested in CoreAudio programming and system-level audio manipulation on macOS.

The open-source portion is at v1.3.2 and appears stable for basic features (volume boost, 10-band EQ), but active development has moved to a private fork—the README explicitly states newer releases and Pro features are closed-source. This is a partially-abandoned public codebase with a mature but frozen feature set. The monorepo structure (packages under modules/, api/, ui/, site/) suggests sophisticated architecture, but no visible CI badges, test suites in the file list, or recent commit timestamps indicate status.

Single maintainer (Roman Kisil) with all new work private increases maintenance risk; the Angular 12 stack (published mid-2021) is aging and will face security drift if unmaintained. No test files visible in the top 60 files suggests low automated quality gates. The project depends on closed-source Pro features for revenue, creating an incentive to deprioritize the open-source v1.3.2 codebase. CoreAudio framework changes in newer macOS versions could silently break functionality without CI to catch it.

No active development on this public fork—the codebase is frozen at v1.3.2. The private fork has newer releases with Pro features (Expert EQ, AU hosting, spatial audio, Volume Mixer mentioned in README as Pro features). Open issues on GitHub likely track bugs in the frozen version; roadmap features (input audio source, hotkeys, API, file rendering) remain unimplemented in the public tree.

git clone https://github.com/bitgapp/eqMac.git && cd eqMac && nvm use (installs Node from .nvmrc) && npm install (or yarn install, since workspaces are configured). Then cd ui && npm start to launch the Angular dev server, and build the Swift backend separately using Xcode (not shown in package.json, requires macOS dev setup).

Daily commands: Frontend dev server: nvm use && npm install && npm run lint (linting via ESLint on entire monorepo with .eslintignore, .eslintrc.js config); then cd ui && ng serve (inferred from Angular CLI in devDependencies @angular/cli@12.2.7). Swift backend: open eqMac.xcodeproj in Xcode and build (actual Xcode project not in file list, likely in a non-listed /eqMac subdirectory). No explicit npm start in root package.json suggests multi-step build.

• package.json — Root monorepo configuration defining workspaces (modules, api, site, ui) and build dependencies; essential for understanding project structure and build pipeline
• modules/components/src/components.module.ts — Angular module barrel exporting all shared UI components used across the application; core to component reusability pattern
• .eslintrc.js — Linting configuration enforcing code quality standards across the entire monorepo; required reading for code style compliance
• README.md — Project overview documenting features (Free vs Pro), AutoEQ integration, and status note about v1.3.2 being the open-source version; clarifies scope and maintenance status
• .nvmrc — Node.js version specification ensuring consistent development environment across contributors
• .github/ISSUE_TEMPLATE — Issue templates (bug-report.md, feature-request.md, enhancement.md) defining contribution workflows and reporting standards

• UI Components Module (Angular, SCSS, RxJS) — Renders all interactive controls (sliders, knobs, buttons, dropdowns) with consistent styling and animation
  • Failure mode: If slider component breaks, users cannot adjust EQ bands; audio output remains unchanged
• EQ Engine (Native CoreAudio (inferred)) — Receives frequency/gain values from UI and applies DSP filters to system audio stream in real-time
  • Failure mode: If engine fails, no audio processing occurs; system audio passes through unmodified
• Preset/Profile Manager (localStorage (implied), JSON) — Persists user-configured EQ settings and loads them on demand; supports AutoEQ integration
  • Failure mode: Loss of saved presets; users must reconfigure EQ on each launch
• Volume Mixer (Native CoreAudio (inferred)) — Manages per-device and HDMI volume balancing; Free feature per README
  • Failure mode: Volume controls unresponsive; HDMI device output levels uncontrolled

• User (slider drag) → FlatSlider Component — Mouse/touch event triggers change detection
• FlatSlider Component → EQ Engine — @Output event emits frequency and gain delta; engine updates filter coefficients
• EQ Engine → `` — undefined

Add a new EQ control component

1. Create new component folder with .ts, .html, and .scss files following existing pattern (e.g., modules/components/src/components/my-control/) (modules/components/src/components/flat-slider/flat-slider.component.ts)
2. Implement component class extending Angular Component decorator with @Input/@Output bindings for value and change events (modules/components/src/components/knob/knob.component.ts)
3. Add styling with SCSS following component theming pattern used in existing controls (modules/components/src/components/flat-slider/flat-slider.component.scss)
4. Export new component from modules/components/src/components.module.ts in the declarations and exports arrays (modules/components/src/components.module.ts)

Add a new animation effect

1. Create new animation file in modules/components/src/animations/ (e.g., fade-in-out.ts pattern) (modules/components/src/animations/fade-in-out.ts)
2. Define animation trigger using Angular's animation API with state and transition definitions (modules/components/src/animations/from-top.ts)
3. Export animation from modules/components/src/animations/index.ts barrel file (modules/components/src/animations/index.ts)
4. Import animation in target component and apply via @Component decorator's animations array and HTML template trigger binding (modules/components/src/components/button/button.component.ts)

Add a new UI form input field

1. Review existing input-field component pattern to maintain consistency with validation and theming (modules/components/src/components/input-field/input-field.component.ts)
2. Create new component in modules/components/src/components/[name]/ with TypeScript, HTML template, and styles (modules/components/src/components/checkbox/checkbox.component.ts)
3. Implement FormControl integration and @Input/@Output for form-aware binding patterns (modules/components/src/components/label/label.component.ts)
4. Register component in modules/components/src/components.module.ts declarations and exports (modules/components/src/components.module.ts)

• Angular 12 — Provides component-based architecture, reactive forms, and dependency injection for managing complex audio UI state and real-time slider updates
• TypeScript — Type safety across the UI and audio control layers; critical for preventing runtime errors in audio DSP configurations
• SCSS — Component-scoped styling with variables and mixins supports consistent theming across controls (dark/light mode for promo images)
• macOS native (implied) — System-wide audio processing requires native integration; monorepo structure suggests Electron or similar wrapper around native CoreAudio APIs

• Open-source only v1.3.2 (Free features); Pro features on private fork

  • Why: Maintaining parallel codebases reduces complexity; Free tier is complete for community use
  • Consequence: Contributors cannot access Expert EQ or Spectrum Analyzer code; feature parity documentation required for community PRs

• Monorepo structure with multiple workspaces (modules, api, site, ui)

  • Why: Enables code sharing across platforms (web site, desktop UI, API) and component reusability
  • Consequence: Requires careful dependency management; breaking changes in components affect all consumers

• Component-first UI library with reusable controls (Knob, FlatSlider, etc.)

  • Why: Audio apps require custom interactive controls; abstraction allows consistent behavior
  • Consequence: Adds indirection; debugging slider events requires tracing through animation and event binding layers

• Cross-platform support (macOS-only, noted in README and native icon format)
• Web-based audio processing (system-wide requires native CoreAudio APIs)
• Real-time spectrum visualization in Free tier (Pro feature per README)
• Support for unlimited customizable EQ bands in Free tier (Expert EQ is Pro only)
• Linux or Windows support (macOS-specific system audio APIs)

No explicit Xcode project file in the top 60 (Swift backend build process opaque); likely requires Xcode and CocoaPods/SPM setup not documented here. The project depends on CoreAudio framework (macOS-only, requires macOS 10.14+ signing), but no setup guide visible. Angular 12 is EOL (released mid-2021, support ended May 2022)—npm install may fail or warn on modern Node 18+. nvm is required (.nvmrc present) but not mentioned in README setup steps. Pro features referenced throughout README are in a private fork, so cloning this repo will not give a full working app—backend audio processing may be stubbed out or minimal. No environment variables (.env example) visible for API_URL or auth tokens, suggesting hardcoded endpoints or that api/ requires separate configuration.

• CoreAudio Audio Unit (AU) Graph — eqMac's entire audio processing pipeline is built on macOS CoreAudio AU graphs; understanding how AU nodes chain filters and DSP effects is critical to modifying the equalizer engine.
• System Audio Interception / Inter-App Audio Routing — eqMac intercepts all macOS system audio output without per-app configuration; this requires kernel-level or HAL-level audio device virtualization, a macOS-specific capability.
• IIR and FIR Filter Design — The EQ bands (10-band fixed, unlimited custom in Pro) are likely implemented as digital filters (Butterworth, Peaking EQ); understanding filter order and Q-factor is essential for audio feature development.
• Monorepo with Yarn Workspaces — eqMac uses Yarn workspaces (modules/*, api, site, ui) to share code across multiple npm packages; understanding workspace dependency resolution prevents circular imports and build failures.
• Real-time Audio DSP and Latency Constraints — Audio processing must run in CoreAudio's real-time render threads with strict latency budgets (typically <10ms); blocking or allocating memory in the render callback will cause audio glitches and dropout.
• Spectrum Analysis and FFT — The Spectrum Analyzer feature (Pro) requires real-time Fast Fourier Transform (FFT) of audio samples; critical for understanding the analyzer module and frequency-domain visualization.
• Angular Material Theme Customization — README mentions 'Fully customize the look and feel of eqMac by changing the User Interface Colors (Pro)'; Angular Material theming (SCSS variables, palette mixins) is the implementation mechanism.

• wwwg/eqMac-reborn — Community fork attempting to revive eqMac development after the official project moved features to a private branch.
• JoseExposito/polychromatic — Similar system-wide macOS utility architecture (peripheral control); demonstrates patterns for building privileged daemon + UI communication.
• kalcaddle/KaiserEQ — Lightweight cross-platform audio equalizer alternative; useful reference for EQ band implementation and DSP patterns.
• jaakkopasanen/AutoEq — Headphone equalization database that eqMac integrates (mentioned in README as Free for Advanced EQ and Pro for Expert EQ); source of preset curves.
• electron/electron — Likely underlying framework for the desktop wrapper (inferred from TypeScript/Angular UI architecture, though not explicitly confirmed in file list).

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 GitHub Actions CI/CD workflow for Angular linting and component builds

The repo has ESLint configured (.eslintrc.js, .eslintignore) and multiple Angular modules (modules/components with breadcrumbs, button, carousel, checkbox components) but no CI pipeline to validate builds on PR. This prevents regression and ensures contributors' code passes lint before merge.

• [ ] Create .github/workflows/ci.yml with Node.js setup and npm install
• [ ] Add lint step running 'npm run lint' against all modules
• [ ] Add Angular build step for modules/components and ui workspace packages
• [ ] Configure workflow to run on pull_request and push to main branch
• [ ] Test workflow passes with existing .eslintrc.js and .nvmrc (v12) configuration

Add unit tests for modules/components with shared test utilities

The modules/components directory contains reusable Angular components (breadcrumbs, button, carousel, checkbox, etc.) but no .spec.ts test files exist. With Angular 12 and Karma/Jasmine available, contributors need test coverage infrastructure to safely modify these shared components used across the monorepo.

• [ ] Create karma.conf.js and test setup for modules/components/src
• [ ] Add breadcrumbs.component.spec.ts testing selector binding and input/output properties
• [ ] Add button.component.spec.ts testing click handlers and disabled state
• [ ] Add carousel.component.spec.ts testing navigation and animation triggers (modules/components/src/animations/)
• [ ] Add checkbox.component.spec.ts testing ngModel binding and change detection
• [ ] Create shared test helper file (modules/components/src/testing/component-test-helper.ts) for common setup logic

Create CONTRIBUTING.md guide with TypeScript/Angular monorepo conventions

CONTRIBUTING.md exists but lacks specific setup instructions for this monorepo structure (yarn workspaces with modules/*, api, site, ui packages). New contributors need clarity on module structure, how to run components in isolation, and conventions for the 12+ Angular modules in modules/ directory.

• [ ] Document yarn workspace setup and how to install/develop individual modules
• [ ] Add section explaining modules/components structure and when to add new components there
• [ ] Include TypeScript configuration details (typescript 4.2.4, tsconfig paths for monorepo)
• [ ] Document how to build and test modules/components in isolation before submitting PR
• [ ] Add ESLint configuration expectations and how to run 'npm run lint' on specific modules
• [ ] Include example PR workflow: create branch, modify component, run tests, submit

• Add TypeScript unit tests for modules/components/src/animations/ (fade-in-out.ts and others); no test files visible in the reusable component library.: Easy: Improves code quality and prevents animation regressions.
• Create a DEVELOPMENT.md guide documenting Swift backend setup (Xcode, CoreAudio framework, build steps) since package.json only covers npm; current README skips native build entirely.: Medium: Reduces onboarding friction for new contributors unfamiliar with macOS native development.
• Migrate Angular Material theme from Angular 12 Material to v14+ or document a migration path; update @angular/material from ^12.2.7 to latest compatible with current Node LTS.: Medium: Reduces security debt and keeps dependencies current; unlocks bug fixes and performance improvements.

Failed to generate security analysis.

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.