Audio Routing Docs

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:

uv run ${CLAUDE_SKILL_DIR}/scripts/audiodocs.py list-pages

Common picks by question:

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

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

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

Reference docs

• Full annotated page catalog (host-by-host, with what each page covers) → references/pages.md.