README.md
June 11, 2026 · View on GitHub
rtaudio
A hyper-optimized, GPU-accelerated macOS system audio visualizer inspired by Apple's Dynamic Island.
Warning
rtaudio is mostly a PoC and, as such, not under active development. The algorithm is finalized and the app won't receive more features. rtaudio is not really meant to be used as a daily app (although nobody stops you!)
If you'd like a production-ready, polished app you can use right away, consider checking out Halo. It uses rtaudio's DSP engine under the hood, plus a handful of added optimizations.
🌟 Authors
- @zeph (that's me!)
💙 Projects using rtaudio
- Atoll (over 1.7k stars on GitHub!)
📖 Overview
rtaudio is a computationally invisible, real-time macOS system audio visualizer. It drops deep into the macOS hardware stack to capture targeted application audio via kernel-level CoreAudio taps, performs a hardware-accelerated Fast Fourier Transform (FFT) in C++, and renders a buttery-smooth waveform entirely on the GPU using custom Metal fragment shaders.
ℹ️ Info:
rtaudiois not really a "final product" but more of a highly-optimized proof-of-concept for real-time audio visualization on macOS.The app bypasses SwiftUI entirely to avoid
AttributeGraphdiffing overhead. The real magic is how it hands 100% of the UI rendering to the GPU, making it possible to run an accurate remake of Apple's waveform visualizer at near-zero CPU cost—even on battery power at 120Hz.Feel free to include its techniques in your own project (but please give credit!)
⚡ Performance
rtaudio is engineered to be a zero-overhead background utility. It blends seamlessly into your system's idle baseline, making it perfect for "Dynamic Island" style overlays that run constantly on MacBooks without draining the battery.
Benchmarks using "Release" build mode currently show:
- CPU Usage: Effectively hovering around ~4% Wall Clock time while actively rendering at a full 120Hz on ProMotion displays.
- Hardware-Synced Refresh: Leverages optimized
MTKViewdisplay links to perfectly match your active monitor's refresh rate, dropping to 60Hz on external displays to save power. - Zero-Draw Bailout: The Metal draw loop automatically detects audio silence and suspends GPU encoding. When music is paused, GPU usage flatlines to 0.0%.
- Pause when Hidden: Hooks into
NSWindow.occlusionStateto automatically freeze the CoreAudio tap when the visualizer is covered or the screen locks. - Audio Processing: Accelerate (
vDSP) SIMD operations process 1024-sample mono FFTs and peak detection in fractions of a millisecond.
🔧 Features & Tech Stack
Core Features
| Feature | Description |
|---|---|
| Dynamic Island UI | Features Apple's true OLED-black backgrounds and mathematically perfect SDF rendering. |
| Event-Driven Colors | Listens to Apple Music via NSDistributedNotificationCenter to extract dominant artwork colors and dynamically tint the bars. |
| SDF Metal Shaders | Bypasses the CPU for UI rendering. The GPU calculates waveform pixels and animated blurs in parallel using Signed Distance Fields. |
| CoreAudio Tap | Scans NSWorkspace to only tap audio from specific running apps (Apple Music, Spotify). |
Technologies Used
| Component | Technology |
|---|---|
| Audio Capture | CoreAudio (CATap / Aggregate Devices) |
| DSP & FFT | Accelerate / vDSP (C++) |
| Rendering | Metal (MTKView / MSL Shaders / SDFs) |
| State Management | AppKit (NSWindowDelegate occlusion / DisplayLink) |
| Inter-Process | AppleScript / NSDistributedNotificationCenter |
💿 Getting Started
Prerequisites
- macOS 14.2+ (Required for public
AudioHardwareCreateProcessTapsupport) - Xcode 15+
Building & Running
- Clone the repository and open
rtaudio.xcodeprojin Xcode. - Build and Run (
Cmd + R).
Tip: macOS treats kernel-level audio taps exactly like physical microphones. The OS will automatically prompt you for Microphone permissions on the first run. You may need to restart the app after granting permission!
💛 Contributions
Contributions are welcome! Since this project aims for hyper-efficiency:
- Please ensure any UI additions are written as
MSLshaders. Do not introduce SwiftUI or Core Animation layers that require CPU geometry calculation. - Keep audio processing allocations strictly outside of the C++
process()loop to prevent audio dropouts. - Make sure your PR contains all the details needed to know what you're changing and why.
📄 License
This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).
What this means:
- ✅ You can use this project's code (such as the DSP module) to build open source tools.
- ✅ You can modify the project to suit your needs.
- 🛑 If you use this code in a networked service (e.g., a backend server interacting with clients), you must make the source code of that service available to users.
- 🛑 If you distribute a binary that uses this project's code, you must provide the source code for your application.
See LICENSE for more details.