audio-routing-docs
/audio-routing-docs
Search and fetch docs for system-level audio routing subsystems (lives BELOW ffmpeg): PipeWire (docs.pipewire.org — pw-cli, pw-dump, pw-link, pw-cat, pw-top, pw-loopback, WirePlumber session manager, PA+JACK compat), JACK Audio Connection Kit (jackaudio.org, jackd/jack_lsp/jack_connect, JACK1 vs JACK2, JackTrip for network audio), Apple Core Audio (developer.apple.com archive — HAL plugins, Aggregate/Multi-Output devices, BlackHole virtual driver), Windows WASAPI (learn.microsoft.com — exclusive vs shared mode, MMDevice, Audio Engine, WDM/KS stack, VB-Cable, VoiceMeeter). Use when the user ask
- Author
- damionrashford ↗
- Repository
- media-os ↗
- Licence
- MIT
- Last repository change
- 17.05.2026
Assessment and security
- Files in this package
- 3
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 17.05.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 1 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/audiodocs.py
What it does and when to use it
Search and fetch docs for system-level audio routing subsystems (lives BELOW ffmpeg): PipeWire (docs.pipewire.org — pw-cli, pw-dump, pw-link, pw-cat, pw-top, pw-loopback, WirePlumber session manager, PA+JACK compat), JACK Audio Connection Kit (jackaudio.org, jackd/jack_lsp/jack_connect, JACK1 vs JACK2, JackTrip for network audio), Apple Core Audio (developer.apple.com archive — HAL plugins, Aggregate/Multi-Output devices, BlackHole virtual driver), Windows WASAPI (learn.microsoft.com — exclusive vs shared mode, MMDevice, Audio Engine, WDM/KS stack, VB-Cable, VoiceMeeter). Use when the user ask
Arguments
/audio-routing-docs [query]
Original author description
Search and fetch docs for system-level audio routing subsystems (lives BELOW ffmpeg): PipeWire (docs.pipewire.org — pw-cli, pw-dump, pw-link, pw-cat, pw-top, pw-loopback, WirePlumber session manager, PA+JACK compat), JACK Audio Connection Kit (jackaudio.org, jackd/jack_lsp/jack_connect, JACK1 vs JACK2, JackTrip for network audio), Apple Core Audio (developer.apple.com archive — HAL plugins, Aggregate/Multi-Output devices, BlackHole virtual driver), Windows WASAPI (learn.microsoft.com — exclusive vs shared mode, MMDevice, Audio Engine, WDM/KS stack, VB-Cable, VoiceMeeter). Use when the user ask
How it works
- Quick start
- When to use
- Step 1 — Know the page catalog
- Step 2 — Search first (default)
- Step 3 — Read one section in full
- Step 4 — Fetch a whole page
- Step 5 — Prime the cache (optional)
- Gotchas
- Examples
- Troubleshooting
SKILL.md preview
---
name: audio-routing-docs
description: >
Search and fetch docs for system-level audio routing subsystems (lives BELOW ffmpeg): PipeWire (docs.pipewire.org — pw-cli, pw-dump, pw-link, pw-cat, pw-top, pw-loopback, WirePlumber session manager, PA+JACK compat), JACK Audio Connection Kit (jackaudio.org, jackd/jack_lsp/jack_connect, JACK1 vs JACK2, JackTrip for network audio), Apple Core Audio (developer.apple.com archive — HAL plugins, Aggregate/Multi-Output devices, BlackHole virtual driver), Windows WASAPI (learn.microsoft.com — exclusive vs shared mode, MMDevice, Audio Engine, WDM/KS stack, VB-Cable, VoiceMeeter). Use when the user asks to look up a PipeWire/JACK/CoreAudio/WASAPI API, verify a system audio routing command, check virtual audio driver setup, or find subsystem docs.
argument-hint: "[query]"
---
# Audio Routing Docs
**Context:** $ARGUMENTS
## Quick start
- **Find a command / API:** → Step 2 (`search --query <term>`)
- **Read the full section for one command:** → Step 3 (`section --page <name> --id <anchor>`)
- **Grab an entire doc page:** → Step 4 (`fetch --page <name>`)
- **Prime the cache for offline use:** → Step 5 (`index`)
- **List all known pages grouped by host:** → Step 1 (`list-pages`)
## When to use
- User asks "what does `pw-link` / `jack_connect` / `SwitchAudioSource` / `svcl.exe` do?"
- Need to verify a subsystem CLI flag before recommending it (anti-hallucination guard).
- Need the canonical URL for a PipeWire man page, JACK API doc, Apple Core Audio archive
page, or Microsoft WASAPI concept page.
- About to write instructions involving virtual drivers (BlackHole, VB-Cable, VoiceMeeter)
and want the real install/config page, not a guess.
This skill is **docs only**. For actual capability (running `pw-link`, installing
BlackHole, flipping Windows default output), use the sibling skills:
`audio-pipewire`, `audio-jack`, `audio-coreaudio`, `audio-wasapi`.
---
## Step 1 — Know the page catalog
The script works only against a curated list of pages across four hosts:
`docs.pipewire.org`, `jackaudio.org`, `developer.apple.com`, `learn.microsoft.com`.
Get the current list:
```bash
uv run ${CLAUDE_SKILL_DIR}/scripts/audiodocs.py list-pages
```
Common picks by question:
| Question | Page |
|---|---|
| "What does `pw-link` accept?" | `pipewire-man-pw-link` |
| "How do I dump the PipeWire graph?" | `pipewire-man-pw-dump` |
| "Where are PipeWire CLIs listed?" | `pipewire-programs` |
| "WirePlumber session manager?" | `wireplumber-home` |
| "What is `jack_lsp`?" | `jack-api` or `jack-stanford` |
| "JackTrip over the internet?" | `jacktrip-docs`, `jacktrip-github` |
| "What is Core Audio / the HAL?" | `coreaudio-overview`, `coreaudio-essentials` |
| "SwitchAudioSource flags?" | `switchaudio-osx` |
| "BlackHole install?" | `blackhole-github` |
| "WASAPI exclusive vs shared?" | `wasapi-exclusive`, `wasapi-overview` |
| "NirSoft svcl.exe flags?" | `wasapi-svcl` |
| "AudioDeviceCmdlets PowerShell?" | `wasapi-audiodevicecmdlets` |
| "VB-Cable / VoiceMeeter install?" | `wasapi-vbcable`, `wasapi-voicemeeter` |
Read [`references/pages.md`](references/pages.md) when you need the full catalog
with one-line descriptions per page.
---
## Step 2 — Search first (default)
When the user names a command, API, or concept, search across all pages:
```bash
uv run ${CLAUDE_SKILL_DIR}/scripts/audiodocs.py search --query "pw-link" --limit 5
```
Scope to one subsystem when you know where it lives (faster, less noise):
```bash
uv run ${CLAUDE_SKILL_DIR}/scripts/audiodocs.py search \
--query "exclusive mode" --page wasapi-exclusive
```
Output for each hit:
```
--- <page>:<line> — <nearest heading>
<canonical URL with #anchor if available>
<snippet with ±3 lines of context>
```
Pass `--format json` for machine-parseable output when chaining.
First run downloads the page (~1–2s). Subsequent runs hit the local cache
(`~/.cache/audio-routing-docs/`) instantly.
---
## Step 3 — Read one section in full
When a search hit points to a specific command/API and you want the full block
(option list + description), use `section`:
```bash
uv run ${CLAUDE_SKILL_DIR}/scripts/audiodocs.py section \
--page pipewire-man-pw-link --id SYNOPSIS
```
`--id` accepts either:
- An anchor id printed in search results as `[§xxxx]`.
- A heading keyword — the script falls back to the first heading matching the string
(case-insensitive).
Output runs from the matching heading down to the next same-or-higher-level heading.
---
## Step 4 — Fetch a whole page
Only when you need to dump the whole page (rare — `search` + `section` are almost
always better):
```bash
uv run ${CLAUDE_SKILL_DIR}/scripts/audiodocs.py fetch --page pipewire-programs
```
Pair with `--format json` for structured handoff.
---
## Step 5 — Prime the cache (optional)
For reliable offline lookups or before a burst of queries:
```bash
uv run ${CLAUDE_SKILL_DIR}/scripts/audiodocs.py index
```
Fetches every known page and stores text-extracted versions in
`~/.cache/audio-routing-docs/`. Override the cache directory with
`AUDIO_ROUTING_DOCS_CACHE=/path/to/dir`.
Clear the cache when upstream docs change:
```bash
uv run ${CLAUDE_SKILL_DIR}/scripts/audiodocs.py clear-cache
```
---
## Gotchas
- **Never recommend a PipeWire/JACK/CoreAudio/WASAPI flag without searching first.**
This skill exists precisely to prevent hallucinated flags. Zero search hits means
the flag is not in that subsystem's official docs — do not claim it works.
- **PipeWire replaced `pipewire-media-session` with WirePlumber.** Old docs and blog
posts still mention `pipewire-media-session`; it is deprecated. Route session-manager
questions to `wireplumber-home`, not the legacy config files.
- **JACK1 vs JACK2 are both "jackd" but behave differently.** JACK1 is C, single-core,
maintenance mode. JACK2 is C++, multicore, adds `jack_control` via D-Bus. On modern
Linux desktops the binary that answers `jackd` is usually PipeWire's libjack shim,
not a real jackd — period size and backends come from PipeWire/WirePlumber, not JACK.
- **Apple's Core Audio docs live at `developer.apple.com/library/archive/...`** —
those are the canonical conceptual docs. The modern path `developer.apple.com/documentation/coreaudio`
covers Swift/Objective-C API references but the archive covers concepts (HAL, Aggregate
Device, AU graph) more fully. Link to the archive for concept questions.
- **BlackHole and Loopback are Apple-Silicon-compatible DriverKit / AudioDriverKit drivers.**
Soundflower is abandoned and won't load on modern macOS — do not recommend it. Route to
`blackhole-github` for installs.
- **WASAPI has no first-party Microsoft CLI.** Everything CLI-shaped (SoundVolumeView,
svcl.exe, AudioDeviceCmdlets, nircmd) is third-party. The Microsoft docs (`wasapi-*`
pages) describe the C/C++ API surface; they do not document the NirSoft/GitHub CLIs.
Cross-check each by searching its own page.
- **Exclusive mode in WASAPI is the bit-perfect path.** Sub-3ms latency needs
`AUDCLNT_STREAMFLAGS_EVENTCALLBACK` + `IAudioClient3::InitializeSharedAudioStream`.
Search on `wasapi-exclusive` and `wasapi-device-formats` for the trade-offs.
- **`audiodevice` is ambiguous on macOS** — at least two tools share the name (npm
package and a Go binary). Always cite the exact upstream repo when recommending it,
or prefer `SwitchAudioSource` (brew install `switchaudio-osx`) which is unambiguous.
- **Cache is keyed by page name only.** Upstream doc edits (new PipeWire release,
new Microsoft revision) are not detected automatically. `clear-cache` + `index`
when you suspect staleness.
- **Anchors in search results use the `[§anchor-id]` sentinel.** Drop the `[§` / `]`
brackets when passing to `section --id`.
- **Text extraction is lossy for complex tables.** If a hit looks truncated, open the
URL printed in the hit header directly for the authoritative view.
- **`learn.microsoft.com` pages include large chrome (nav, breadcrumbs) that the script
strips.** If a search hit has no obvious snippet, the term was in the boilerplate;
try a more specific query or `fetch` the whole page.
---
## Examples
### Example 1 — "What does `pw-link` actually let me do?"
```bash
uv run ${CLAUDE_SKILL_DIR}/scripts/audiodocs.py search --query "pw-link" --limit 3
```
Pick the hit on `pipewire-man-pw-link`, then read the synopsis:
```bash
uv run ${CLAUDE_SKILL_DIR}/scripts/audiodocs.py section \
--page pipewire-man-pw-link --id SYNOPSIS
```
### Example 2 — "What's the difference between JACK exclusive & shared audio on Windows?"
Wrong subsystem — WASAPI has exclusive/shared; JACK does not. Fetch the canonical
doc:
```bash
uv run ${CLAUDE_SKILL_DIR}/scripts/audiodocs.py fetch --page wasapi-exclusive
```
### Example 3 — "What are the CLI flags for `svcl.exe`?"
```bash
uv run ${CLAUDE_SKILL_DIR}/scripts/audiodocs.py search \
--query "SetDefault" --page wasapi-svcl --limit 5
```
(NirSoft's command-line reference lives on `wasapi-svcl`.)
### Example 4 — "Does macOS still support Soundflower?"
```bash
uv run ${CLAUDE_SKILL_DIR}/scripts/audiodocs.py search \
--query "Soundflower" --limit 3
```
Expected result: nothing authoritative — Soundflower is abandoned. Recommend
BlackHole instead; fetch `blackhole-github`.
### Example 5 — "Find the JackTrip server flags."
```bash
uv run ${CLAUDE_SKILL_DIR}/scripts/audiodocs.py search \
--query "server" --page jacktrip-docs --limit 5
```
---
## Troubleshooting
### Error: `unknown page: foo`
**Cause:** The page name isn't in the catalog.
**Fix:** Run `list-pages` to see valid names. Common mistakes: `pipewire` instead of
`pipewire-home`; `jack` instead of `jack-home`; `coreaudio` instead of `coreaudio-overview`.
### Error: `urlopen error [SSL: CERTIFICATE_VERIFY_FAILED]`
**Cause:** System certificate store is out of date (typically macOS with older Python).
**Fix:** Install/update certifi, or run `/Applications/Python\ 3.x/Install\ Certificates.command`.
Do NOT patch the script to disable SSL verification.
### Search returns zero hits
**Cause:** Term isn't on that page, or wrong subsystem.
**Fix:** Drop `--page` to search everywhere; try the sibling subsystem (`wasapi-*`
for Windows, `pipewire-*` for Linux, etc.); try a broader query.
### Results look truncated / tables mangled
**Cause:** Lossy HTML→text extraction on complex tables.
**Fix:** Open the canonical URL printed in the hit header (WebFetch or browser).
### Cache is stale after a subsystem upstream update
**Fix:** `clear-cache` then `index` (or just `fetch --no-cache --page <name>` for one).
---
## Reference docs
- Full annotated page catalog (host-by-host, with what each page covers) →
[`references/pages.md`](references/pages.md).
Files in this package (3)
- SKILL.md 11 KB
- references/pages.md 8 KB
- scripts/audiodocs.py 17 KB
Versions
The database has no other skills named audio-routing-docs.
Database snapshot: 13.11.2026 · package version 8c7393b3fcef (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100audio-pipewire
Route and introspect Linux audio/video/MIDI graphs with PipeWire: pw-cli (interactive object/module control), pw-dump (full graph JSON with --monitor), pw-link (list/create/destroy port links), pw-cat / pw-play / pw-record (playback+record), pw-top (real-time DSP load + xrun… - 100audio-jack
Route professional low-latency audio with JACK Audio Connection Kit (jackaudio.org): jackd server (ALSA/CoreAudio/PortAudio/ASIO backends), jack_control (D-Bus JACK2 config), jack_lsp (list ports/connections), jack_connect/jack_disconnect (manage links), jack_cpu_load,…