Haptic Muzak

A macOS app that triggers your MacBook’s Taptic Engine (Force Touch trackpad) on detected drum-related moments. By default it runs in auto mode: it watches system Now Playing, downloads a matching track with yt-dlp for analysis, and fires haptics in sync with your player (mirror timing—often YouTube Music in Chrome). You can switch to manual mode to analyze a local file and play it inside the app.

Analysis uses optional Demucs drum stem isolation, Librosa onset detection, and a fast spectral kick/snare/hi-hat classifier (plus Essentia for beat-grid mode).

Documentation

High-level docs live in docs/. On GitHub, open that folder to see this index rendered like the root README, or jump straight from the table below.

Doc	What it covers
docs/README.md	Index — navigation, architecture diagram, links to all pages
Overview	Purpose, requirements, scope
User modes	Auto vs manual, settings
Detection pipeline	Sync modes, analysis, haptics
Integrations	Now Playing, Chrome, downloads, mirror sync
Build and run	Toolchain, Python venv, caches

Edits to those files replace prior text; they are not append-only changelogs.

Requirements

• macOS 13+ (Ventura or later)
• MacBook with Force Touch trackpad (Taptic Engine). On machines without it, the app still runs but no haptics are produced.
• Swift 5.9+ (Xcode 15+)

How to run

cd Haptic-Muzak
swift run HapticMuzak

Or build and run the executable:

swift build
.build/debug/HapticMuzak

How it works

Auto mode (default) — Leave music playing in your player (e.g. YouTube Music in Chrome). The app reads Now Playing metadata, downloads audio for analysis, and aligns haptics to playback. For tighter sync with YouTube Music in Chrome, enable Allow JavaScript from Apple Events (Chrome → View → Developer).

Manual mode — Switch in the window header, then:

1. Pick an audio file – Drag & drop or use “Change…” to open an MP3, M4A, WAV, etc.
2. Choose sync mode
   • Kick drums – Kick-focused transient detection. If Demucs is installed, the app isolates the drum stem first, then runs onset detection on a cleaned percussive track. Swift fallback if Python is not set up.
   • Drums (Smart) – Labeled kick + snare + hi-hat events using Demucs + HPSS + a fast spectral classifier. No tempo “beat grid.”
   • Beats (Essentia) – Exact beat positions (millisecond accuracy) from Essentia RhythmExtractor2013. Free and open source (AGPLv3). Requires pip install essentia in the project venv.
3. Playback – Press play. The Taptic Engine fires at each detected time.

Python setup (Librosa + Essentia)

Use a virtual environment so you don’t hit macOS/Homebrew’s “externally-managed-environment” block:

python3 -m venv Scripts/.venv
Scripts/.venv/bin/pip install -r Scripts/requirements.txt

This installs Librosa (for Kick drums and Drums mode) and Essentia (for Beats mode). Then run the app from the project directory (e.g. swift run). It uses Scripts/.venv/bin/python3 and Scripts/detect_kicks.py when present. The app also searches upward from the executable for Scripts/detect_kicks.py (helpful when launching from Xcode).

Optional: Demucs drum isolation

For the best free drum extraction quality, install Demucs into the same venv:

Scripts/.venv/bin/pip install -r Scripts/requirements-demucs.txt

Then Kick drums and Drums (Smart) will automatically try htdemucs_ft first and cache the extracted drum stem in ~/Library/Caches/HapticMuzak/.

Tips

• For hip-hop with a strong backbeat, Drums (Smart) usually feels better than Kick drums alone.
• For the best results on dense full mixes, install Demucs so the detector can isolate drums before onset analysis.
• For Kick drums, Python + Librosa gives the cleanest transient picks; the Swift fallback is stricter and may miss or merge hits.
• Beats (Essentia) gives a steady metronome-like grid; best when you want haptics on every beat rather than only drum hits.
• Enable System Settings → Trackpad → “Force Click and haptic feedback” (or equivalent).

Project layout

• Sources/HapticMuzak/ – SwiftUI app, playback, haptics, detector glue.
• Scripts/detect_kicks.py – --mode kicks, --mode adt, or --mode essentia; outputs JSON for the app.
• Scripts/requirements.txt – Librosa, soundfile, numpy, essentia.
• Scripts/requirements-demucs.txt – Optional Demucs install for drum stem separation.

License

Use and modify as you like.