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

Flag	Description
--pid <PID>	Tap the process with this process ID
--app <NAME>	Tap the first audio process whose name or bundle ID contains NAME (case-insensitive)
--list, -l	Print all active audio processes as a table and exit

Output Format

Flag	Default	Description
--format <fmt>	pcm16	Output format: pcm16 (raw signed 16-bit PCM), wav (streaming RIFF/WAV with header), f32 (raw 32-bit float)
--sample-rate <hz>	16000	Destination sample rate in Hz. Whisper uses 16000; FFmpeg and music apps may prefer 44100 or 48000
--channels <n>	1	1 = mono (down-mixed), 2 = stereo pass-through

Output Destination

Flag	Description
--output <path>, -o <path>	Write audio to a file instead of stdout (e.g. --output recording.wav)
--duration <secs>	Automatically stop after N seconds (e.g. --duration 60)

Audio Processing

Flag	Default	Description
--volume <gain>	1.0	Linear gain multiplier applied before conversion. 2.0 doubles volume; 0.5 halves it
--silence-threshold <rms>	0 (off)	Drop audio chunks whose RMS level is below this value. Prevents silence from being piped to Whisper (which causes hallucination). Try 0.01

Metadata

Flag	Description
--json-info	Print a JSON object to stderr before audio begins: pid, name, bundleID, format, sampleRate, channels, tapSourceSampleRate

Agent & Daemon

Flag	Default	Description
--agent	—	Run as a background permission-anchoring agent (normally started automatically)
--via-agent	—	Connect directly to a running agent without auto-launching one
--agent-socket <path>	/tmp/audia-tap-<uid>.sock	Override the Unix socket path used for agent communication
--timeout <secs>	8.0	How long to wait for the agent socket to appear before giving up

Debugging

Flag	Description
--verbose, -v	Enable verbose debug output on stderr (equivalent to AUDIA_TAP_DEBUG=1)
--quiet, -q	Suppress all informational [audia-tap] stderr messages for clean pipeline integration

Miscellaneous

Flag	Description
--request-permission	Request Audio Capture permission and exit
--chunk-frames <n>	Internal ring-buffer chunk size in frames (default: 4096). Lower values reduce latency; higher values improve throughput
--help, -h	Show the full help message and exit
--version	Print the version string and exit

---

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