Audio Routing Docs

Audio Routing Docs

Context: $ARGUMENTS

Quick start

• Find a command / API: → Step 2 (search --query )
• Read the full section for one command: → Step 3 (section --page --id )
• Grab an entire doc page: → Step 4 (fetch --page )
• 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:

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:

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):

uv run ${CLAUDE_SKILL_DIR}/scripts/audiodocs.py search \
  --query "exclusive mode" --page wasapi-exclusive

Output for each hit:

--- : — 

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:

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):

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:

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:

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?"

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:

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:

uv run ${CLAUDE_SKILL_DIR}/scripts/audiodocs.py fetch --page wasapi-exclusive

Example 3 — "What are the CLI flags for svcl.exe?"

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?"

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

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 for one).

---

Reference docs

• Full annotated page catalog (host-by-host, with what each page covers) →

[references/pages.md](references/pages.md).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: damionrashford
• Source: damionrashford/media-os
• License: MIT
• Homepage: https://damionrashford.github.io/media-os/

Install and usage instructions live in the source repository linked above.