audia-tap

A native, open-source CLI for tapping per-app macOS audio.
The foundational extraction engine behind Audia. Extract raw PCM audio directly from any process and pipe it anywhere.

audia-tap is a standalone Swift CLI that bypasses the macOS system mixer entirely. It uses a native Hardware Abstraction Layer (HAL) tap to hook directly into any running application's process ID (PID), extracting raw 16-bit PCM audio and piping it straight to stdout.

Originally built as the core audio routing engine for Audia, we've open-sourced this fundamental building block for the community. Capture application audio without clunky virtual drivers (like BlackHole). 100% local. Zero virtual routing.

⚡ Features

• Driverless Capture — No BlackHole, Soundflower, or Loopback required. Runs entirely natively.
• App-Specific Targeting — Tap any app by PID or by name with --app. Captures exactly what you want without notifications bleeding into transcription.
• Process Discovery — --list shows every active audio process in a formatted table with bundle IDs and status.
• Multi-Format Output — Raw PCM16, streaming WAV (with header), or Float32 — pipe into anything.
• Configurable DSP — Volume gain, silence gating, sample rate, and channel count — all configurable via flags.
• Sequoia Ready (macOS 15+) — Successfully navigates the strict macOS TCC (Transparency, Consent, and Control) security model using an invisible background agent, ensuring resilient Screen & System Audio Recording permission handling.
• UNIX Philosophy — Does one thing well: pipes raw PCM data to stdout so you can effortlessly pipe it into Whisper, FFmpeg, Parakeet, or any AI model downstream.

🚀 Quick Start

1. Install

Option A — Homebrew Cask (Recommended)

brew tap Bibhav48/tap
brew install --cask audia-tap

Why cask? audia-tap is CLI-first, but ships an .app bundle to satisfy macOS Audio Capture permission anchoring.
The cask installs audia-tap.app and exposes the audia-tap CLI command.

Option B — Build from Source

Clone the repository and install globally. (Requires Xcode command-line tools).

git clone https://github.com/Bibhav48/audia-tap.git
cd audia-tap
./install.sh

Permission Note: On first run, audia-tap will auto-anchor to handle macOS Screen & System Audio Recording permissions.

2. Find your Target PID

Identify the process ID of the application you want to transcribe:

audia-tap --list

This prints a table of every process currently producing (or registered for) audio:

────────────────────────────────────────────────────────────────────
  PID    NAME              BUNDLE ID                      ACTIVE
────────────────────────────────────────────────────────────────────
  471    coreaudiod                                         no
  1234   Safari            com.apple.Safari               ▶ yes
  5678   Spotify           com.spotify.client             ▶ yes
────────────────────────────────────────────────────────────────────
  3 process(es) listed. Use audia-tap --pid <PID> to tap one.
────────────────────────────────────────────────────────────────────

3. Run the Tap

Execute audia-tap with the targeted PID. You can tap by PID directly:

audia-tap --pid 1234

Or by app name (no pgrep needed):

audia-tap --app Safari

You will immediately see raw binary PCM data flowing into your terminal's standard output.

📋 Complete Flag Reference

Target Selection

Output Format

Output Destination

Audio Processing

Metadata

Agent & Daemon

Debugging

Miscellaneous

---

📖 Usage Examples

# List all audio-producing processes
audia-tap --list

# Tap Safari and pipe directly into Whisper
audia-tap --app Safari | python3 Scripts/whisper_demo.py /dev/stdin

# Save Spotify output as a stereo WAV at 44.1 kHz
audia-tap --app Spotify --format wav --sample-rate 44100 --channels 2 --output spotify.wav

# Tap Zoom for 60 seconds, boost quiet audio, suppress silence
audia-tap --app Zoom --volume 1.5 --silence-threshold 0.01 --duration 60

# Inspect stream metadata as JSON before audio begins
audia-tap --pid 1234 --json-info --quiet 2>info.json | python3 my_model.py

# Tap any app with verbose debug output
audia-tap --app Spotify --verbose

# Run quietly without any [audia-tap] status messages
audia-tap --pid 1234 --quiet > my_recording.pcm

# Override the default 16kHz to 48kHz float32 for FFmpeg
audia-tap --pid 1234 --format f32 --sample-rate 48000 | ffmpeg -f f32le -ar 48000 -ac 1 -i - out.mp3

---

🧠 Python AI Integration

The true power of audia-tap lies in piping the audio stream directly into local LLMs. We provide sample scripts in the Scripts/ directory that read the stdout buffer and feed it into AI models in real-time.

Setup Environment (Using uv)

We highly recommend using uv to manage your virtual environment for peak performance.

uv venv
source .venv/bin/activate

Option A: Whisper (OpenAI)

# Install required dependencies
uv pip install openai-whisper numpy

# Run the real-time tap script with your target PID
python3 Scripts/whisper_demo.py <PID>

Option B: Parakeet MLX (Apple Silicon Native)

# Install native dependencies for blazing fast Apple Silicon performance
uv pip install "mlx>=0.19.0" "parakeet-mlx>=1.0.1" numpy soundfile

# Run the script
python3 Scripts/parakeet_mlx_demo.py <PID>

---

🚢 Maintainer Release Flow

audia-tap now has an automated release chain:

1. Create/publish a GitHub release tag like v0.1.1.
2. GitHub Actions builds audia-tap.app, packages audia-tap-0.1.1.dmg, uploads it to that release.
3. If TAP_REPO_TOKEN is configured, CI also updates a tap cask (version + sha256) and pushes it.

Workflow file:

• .github/workflows/release.yml

Optional secrets for tap auto-update:

• TAP_REPO_TOKEN: GitHub token with push access to your tap repository.
• TAP_REPO: optional <owner>/<repo> override for tap repo.
  • Default is ${{ github.repository_owner }}/homebrew-tap.

Local equivalent:

# Build + upload release asset
./Scripts/release_local.sh 0.1.1

# Build + upload + update local tap repo checkout
./Scripts/release_local.sh 0.1.1 /Users/<you>/Projects/homebrew-tap

Production DMG is built with:

• audia-tap.app
• Applications symlink
• README.txt (permission-anchor + CLI path explanation)

🗺️ Roadmap

• Stability: Auto-restarts and headless background daemonization (via --agent)
• Process discovery UX: audia-tap --list to view all active audio processes
• Zero-config mode: Target apps by name (--app "Spotify") instead of PID
• Advanced streaming: Native support for --format wav|f32
• Configurable DSP: --sample-rate, --channels, --volume, --silence-threshold
• Output routing: --output <file> and --duration
• RTP streaming: --rtp <host:port> for network audio routing

---

🤝 Authors

Built with ❤️ by Bibhav Adhikari and Arjav Lamsal.

audia-tap is the open-source audio routing engine extracted from Audia, our upcoming zero-bot AI meeting transcriber for macOS.

⚖️ License

Distributed under the MIT License.