hydra

Terminal replacement for Loopback — virtual audio devices and routing on macOS, from a ratatui TUI.
Log | Files | Refs | README | LICENSE

TESTING.md (3153B)

      1 # Testing Hydra
      2 
      3 What's been built and verified vs. what needs you (the parts requiring a GUI permission
      4 dialog, `sudo`, or a `coreaudiod` restart can't be done headlessly).
      5 
      6 ## Already verified (no action needed)
      7 
      8 - `cargo build --workspace` — clean, 0 warnings
      9 - `cargo test --workspace` — 19 tests green (wire round-trips, model, theme, manifest, config)
     10 - Device + audio-process **enumeration** against your real hardware (Scarlett 18i20,
     11   built-ins, even the running Loopback Virtual Mic)
     12 - `hydra query --sketchybar|--json|plain` over the live socket
     13 - Config **persistence** round-trip (daemon restores saved routes on startup)
     14 - `Hydra.driver` **builds + signs** (universal, factory symbol exported)
     15 - `Hydra.app` **builds + signs** with the audio-input entitlement
     16 
     17 ## 1. Per-app capture → speakers (no driver, no sudo — start here)
     18 
     19 This is the lowest-risk check: confirms the tap engine + TCC actually work.
     20 
     21 ```sh
     22 cd ~/Dropbox/Projects/Apps/hydra
     23 ./scripts/bundle.sh debug                 # build + ad-hoc-sign Hydra.app
     24 open -a Music                              # or any app; start playback
     25 "./dist/Hydra.app/Contents/MacOS/hydrad" &  # run the SIGNED daemon (not `cargo run` — TCC needs the bundle)
     26 cargo run -p hydra                        # TUI: pick the app, ensure target = "MacBook Pro Speakers" (press o), ⏎
     27 ```
     28 
     29 - macOS should prompt for **Audio Recording** access the first time — approve it.
     30 - Expect: you hear the app through speakers, and the route's peak meter moves.
     31 - If no prompt appears or the meter stays flat: that's the signing/TCC gate — tell me and
     32   I'll dig in (likely needs a free Apple Development cert instead of ad-hoc).
     33 
     34 Stop the daemon when done: `pkill -f Hydra.app`.
     35 
     36 ## 2. The virtual device (driver install — sudo + ~1s audio glitch)
     37 
     38 Makes "Hydra" selectable as an input in other apps (Zoom/OBS/etc). Loopback can stay
     39 installed — no conflict.
     40 
     41 ```sh
     42 ./scripts/build-driver.sh                 # → driver/build/Hydra.driver (already verified to build)
     43 ./scripts/install-driver.sh               # prompts for sudo; restarts coreaudiod
     44 system_profiler SPAudioDataType | grep -i hydra   # confirm "Hydra" appears
     45 ```
     46 
     47 Then in the TUI: pick an app, press `o` until the target is **Hydra**, `⏎`. In another app,
     48 choose **Hydra** as the microphone — it should receive the routed audio.
     49 
     50 Uninstall any time:
     51 ```sh
     52 sudo rm -rf "/Library/Audio/Plug-Ins/HAL/Hydra.driver" && sudo killall coreaudiod
     53 ```
     54 
     55 ## 3. Run as a background agent (optional)
     56 
     57 ```sh
     58 ./scripts/install-agent.sh                # KeepAlive LaunchAgent; routing persists across logins
     59 tail -f /tmp/hydrad.err.log
     60 ```
     61 
     62 ## 4. SketchyBar widget (optional)
     63 
     64 See `scripts/sketchybar/README.md` — add the item to your `sketchybarrc` (remember:
     65 first-added = rightmost).
     66 
     67 ## What I still owe, once the driver's installed
     68 
     69 - **P3**: runtime-dynamic devices (rename, arbitrary channel counts, multiple devices) via
     70   the `devices.json` manifest reader in the driver. Needs the driver installed to test, so
     71   it was deferred to after step 2.
     72 - **P6**: live driver reload without a coreaudiod restart; long-session tap stability.