hydra

lib.rs (8971B)

---

 //! Shared wire protocol for Hydra: the only crate both the daemon (`hydrad`) and the
 //! TUI/query binary (`hydra`) depend on. Deliberately has **zero** macOS / CoreAudio
 //! dependencies so the TUI can never accidentally link the audio engine.
 //!
 //! Transport is newline-delimited JSON (NDJSON) over a Unix-domain socket: one serde
 //! value per line, hand-debuggable with `nc`.
 
 use serde::{Deserialize, Serialize};
 use std::io::{self, BufRead, Write};
 use std::path::PathBuf;
 
 /// Bumped when the wire format changes incompatibly.
 pub const PROTOCOL_VERSION: u32 = 1;
 
 /// `~/Library/Application Support/hydra` on macOS. The daemon keeps its socket, config,
 /// and theme here. Falls back to `/tmp/hydra` if the data dir can't be resolved.
 pub fn runtime_dir() -> PathBuf {
     let mut p = dirs::data_dir().unwrap_or_else(|| PathBuf::from("/tmp"));
     p.push("hydra");
     p
 }
 
 /// Path to the daemon's control socket.
 pub fn socket_path() -> PathBuf {
     let mut p = runtime_dir();
     p.push("hydrad.sock");
     p
 }
 
 // ── Request / response ────────────────────────────────────────────────────────
 
 /// A request from a client (TUI or `hydra query`) to the daemon.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub enum Command {
     /// Liveness check.
     Ping,
     /// Fetch the current routing snapshot.
     GetState,
     /// Enumerate the host's audio devices (hardware + virtual).
     ListDevices,
     /// Enumerate processes currently producing audio (capture targets).
     ListApps,
     /// Start monitoring one process's audio to an output device (P1).
     /// `output_uid = None` means the system default output.
     StartMonitor { pid: i32, output_uid: Option<String>, gain: f32 },
     /// Combine several processes' audio into a single route to one output (the Loopback
     /// "combine sources" feature). `output_uid = None` means the system default output.
     StartCombined { pids: Vec<i32>, output_uid: Option<String>, gain: f32 },
     /// Route a hardware INPUT device (mic / line-in, by UID) to an output. No tap/TCC.
     StartInput { input_uid: String, output_uid: Option<String>, gain: f32 },
     /// Tear down a route by id.
     StopRoute { id: String },
     /// Live-adjust a route's gain (linear, 0.0..~2.0).
     SetGain { id: String, gain: f32 },
     /// Live mute/unmute a route.
     SetMute { id: String, muted: bool },
     /// Rename the Hydra virtual device. Writes the driver manifest
     /// (/Library/Application Support/hydra/devices.json); the new name takes effect on the
     /// next coreaudiod restart (the driver reads the manifest at load).
     SetDeviceName { name: String },
     /// List saved preset names.
     ListPresets,
     /// Save the current routing setup as a named preset (replaces one of the same name).
     SavePreset { name: String },
     /// Replace all live routes with the named preset's routes. Apps not currently running
     /// are skipped (same as restore-on-startup).
     ApplyPreset { name: String },
     /// Delete a saved preset by name.
     DeletePreset { name: String },
     /// Start recording a route's audio to a WAV file. `path = None` ⇒ daemon picks a
     /// timestamped file in ~/Music/Hydra.
     StartRecording { id: String, path: Option<String> },
     /// Stop recording a route; reply carries the file path + duration.
     StopRecording { id: String },
     /// Opt this connection into the server-push event stream (state deltas, meters).
     Subscribe,
     /// Ask the daemon to exit.
     Shutdown,
 }
 
 /// The daemon's reply to a [`Command`].
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub enum Response {
     Pong { version: u32 },
     State(StateSnapshot),
     Devices(Vec<AudioDevice>),
     Apps(Vec<AudioApp>),
     /// A route was created; carries its assigned id.
     RouteStarted { id: String },
     /// Saved preset names.
     Presets(Vec<String>),
     /// A preset was applied; carries how many of its routes were (re)established.
     PresetApplied { restored: usize, total: usize },
     /// Recording started; carries the file path being written.
     RecordingStarted { path: String },
     /// Recording stopped; carries the file path + sample-frames written.
     RecordingStopped { path: String, frames: u64 },
     Ok,
     Error(String),
 }
 
 /// A host audio device (hardware or virtual), as seen by CoreAudio.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct AudioDevice {
     pub uid: String,
     pub name: String,
     pub input_channels: u32,
     pub output_channels: u32,
     pub is_default_output: bool,
 }
 
 /// A process currently registered with CoreAudio as an audio producer.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct AudioApp {
     pub pid: i32,
     pub name: String,
     pub bundle_id: Option<String>,
     /// Sort/priority rank: 0 = foreground Dock app, 1 = menu-bar/background app,
     /// 2 = plain process (system daemons, helpers). Lower = more likely a real target.
     #[serde(default)]
     pub kind: u8,
 }
 
 /// Server-initiated push messages (only sent after [`Command::Subscribe`]).
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub enum Event {
     StateChanged(StateSnapshot),
 }
 
 // ── Snapshot types ────────────────────────────────────────────────────────────
 
 /// A read-only view of the daemon's routing state, safe to render or print.
 #[derive(Debug, Clone, Default, Serialize, Deserialize)]
 pub struct StateSnapshot {
     pub daemon_version: String,
     pub devices: Vec<DeviceSummary>,
     pub routes: Vec<RouteSummary>,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct DeviceSummary {
     pub uid: String,
     pub name: String,
     pub channels: u32,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct RouteSummary {
     pub id: String,
     /// Display label, e.g. "Swinsian → Scarlett 18i20".
     pub target: String,
     pub source_count: usize,
     pub active: bool,
     /// Linear gain (1.0 = unity).
     pub gain: f32,
     pub muted: bool,
     /// Most recent peak level (0.0..~1.0) for metering.
     pub peak: f32,
     /// Whether this route is currently being recorded to a file.
     #[serde(default)]
     pub recording: bool,
 }
 
 // ── NDJSON framing ────────────────────────────────────────────────────────────
 
 fn invalid_data<E: std::fmt::Display>(e: E) -> io::Error {
     io::Error::new(io::ErrorKind::InvalidData, e.to_string())
 }
 
 /// Serialize `msg` as a single JSON line and flush it to `w`.
 pub fn write_msg<W: Write, T: Serialize>(w: &mut W, msg: &T) -> io::Result<()> {
     let mut line = serde_json::to_vec(msg).map_err(invalid_data)?;
     line.push(b'\n');
     w.write_all(&line)?;
     w.flush()
 }
 
 /// Read one JSON line from `r`. Returns `Ok(None)` on clean EOF.
 pub fn read_msg<R: BufRead, T: for<'de> Deserialize<'de>>(r: &mut R) -> io::Result<Option<T>> {
     let mut line = String::new();
     if r.read_line(&mut line)? == 0 {
         return Ok(None);
     }
     let trimmed = line.trim_end();
     if trimmed.is_empty() {
         return Ok(None);
     }
     serde_json::from_str(trimmed).map(Some).map_err(invalid_data)
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
     use std::io::BufReader;
 
     #[test]
     fn command_round_trips() {
         let mut buf = Vec::new();
         write_msg(&mut buf, &Command::Ping).unwrap();
         let mut r = BufReader::new(&buf[..]);
         let got: Option<Command> = read_msg(&mut r).unwrap();
         assert!(matches!(got, Some(Command::Ping)));
     }
 
     #[test]
     fn snapshot_round_trips() {
         let snap = StateSnapshot {
             daemon_version: "0.1.0".into(),
             devices: vec![DeviceSummary { uid: "hydra:main".into(), name: "Main".into(), channels: 16 }],
             routes: vec![RouteSummary {
                 id: "r1".into(),
                 target: "hydra:main".into(),
                 source_count: 2,
                 active: true,
                 gain: 1.0,
                 muted: false,
                 peak: 0.0,
                 recording: false,
             }],
         };
         let mut buf = Vec::new();
         write_msg(&mut buf, &Response::State(snap)).unwrap();
         let mut r = BufReader::new(&buf[..]);
         let got: Option<Response> = read_msg(&mut r).unwrap();
         match got {
             Some(Response::State(s)) => {
                 assert_eq!(s.devices.len(), 1);
                 assert_eq!(s.routes[0].source_count, 2);
             }
             other => panic!("unexpected: {other:?}"),
         }
     }
 
     #[test]
     fn eof_returns_none() {
         let mut r = BufReader::new(&b""[..]);
         let got: Option<Command> = read_msg(&mut r).unwrap();
         assert!(got.is_none());
     }
 }