# horuse/splitwave architecture

> Architecture diagram of the GitHub repository horuse/splitwave, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/horuse/splitwave
- Repository: https://github.com/horuse/splitwave

## Overview

1. **Overall shape**
   Splitwave is a desktop audio router built as a **Svelte frontend + Tauri shell + Rust audio engine**. The UI lets users assemble an audio graph, while the Rust side owns all real audio I/O, DSP, recording, and OS-specific integration.

2. **Frontend boundary**
   The `src/` tree is the presentation layer: SvelteKit routes for the main editor, pipeline detail pages, preview, and virtual-device management. The UI is organized by feature modules such as `flow`, `audio`, `pipeline`, `overlay`, `updater`, and `error`, with shared components and icons underneath `src/lib/components`.

3. **Graph editor and state**
   The `flow` module is the visual node editor. It renders inputs, effects, and outputs as nodes, supports undo/redo and snapshot history, and drives the user-facing model of the audio pipeline. The `pipeline` module holds the typed state model and the generated Rust-backed TypeScript types used by the editor.

4. **Frontend-to-backend contract**
   The app uses Tauri commands as the bridge between UI and engine. Shared pipeline types are generated from Rust (`ts-rs`-style generated files in `src/lib/modules/pipeline/generated`), so the frontend and backend agree on node kinds, effect parameters, and recording formats.

5. **Rust application core**
   `src-tauri/src/` is the runtime backend. `main.rs` and `lib.rs` boot the Tauri app, `commands.rs` exposes callable operations to the frontend, `state.rs` stores application state, and `error.rs` centralizes error propagation back to the UI.

6. **Audio engine pipeline**
   The heart of the system is `src-tauri/src/audio/pipeline/` and `engine.rs`. Audio flows through a DAG-based pipeline where sources are normalized, resampled, processed by effects, and delivered to outputs. Supporting modules handle timing/clocking, worker execution, meters, signal representation, and file reading.

7. **Inputs and capture sources**
   Input acquisition is split by source type and platform:
   - `capture/` handles system and per-app capture
   - `device/` handles microphone and speaker device enumeration
   - `system_audio/` and `virtual_device/` manage OS-specific capture/loopback sources
   - `input_bridge.rs` and `playback.rs` connect captured audio into the processing graph  
   The backend supports microphones, system audio, per-app capture, file input, and virtual-device loopback as first-class sources.

8. **Effects and metering**
   Effects live in `audio/effects/` and are implemented in Rust as DSP modules: gain, mute, balance, EQ, compressor, delay, limiter, noise gate/suppressor, reverb, saturator, LUFS/level metering, and waveform analysis. These are applied inside the pipeline, not in the UI, so the editor only configures them.

9. **Outputs and encoders**
   The output side supports speaker/device playback, virtual-device output, and file recording. `audio/encoders/` contains format-specific writers for WAV, FLAC, AIFF, MP3, Opus, and AAC; these are fed by the processed stream when the graph terminates in a recording node.

10. **Platform-specific audio boundaries**
   The backend is heavily OS-conditioned:
   - **macOS:** CoreAudio/HAL for device enumeration, ScreenCaptureKit for system/app capture, `cpal` for device I/O, and a custom AudioServerPlugin virtual driver.
   - **Linux:** PipeWire for device I/O, capture, playback, and null-sink virtual devices.
   - **Windows:** WASAPI via `cpal`, plus Windows APIs for loopback/process capture and endpoint volume. Virtual devices are not available.

11. **Native macOS support code**
   `src-tauri/native/` contains Swift and C++ support code used only on macOS. Swift is used for ScreenCaptureKit bridging and AAC encoding support, while `virtual_driver/` implements the AudioServerPlugin driver that makes virtual devices appear system-wide.

12. **Packaging and build-time integration**
   The repository is packaged as a Tauri desktop app across macOS, Linux, and Windows. `build.rs` coordinates native build steps, including the macOS Swift/static-library pieces. The CI/release workflows and Tauri config files split the app into platform-specific installers and capabilities.

13. **Important data flow for diagrams**
   The main runtime path is: **OS audio sources or file input → backend capture/device layer → pipeline DAG → effects/meters → output device / virtual device / recorder encoder**. The UI only configures and monitors this path; it does not process audio itself.

14. **Cross-cutting concerns**
   A few modules cut across the whole app: `audio/volume` controls device volume, `audio/permission` handles platform permission checks, `audio/resample` and `audio/clock` keep streams aligned, and the `error`/`updater`/`app_info` modules provide app-wide UX support. These are secondary to the audio graph but important for completeness.

Main entry points: [`src-tauri/src/audio/pipeline`](https://github.com/horuse/splitwave/tree/main/src-tauri/src/audio/pipeline) (Pipeline DAG), [`src/routes`](https://github.com/horuse/splitwave/tree/main/src/routes) (App routes), [`src-tauri/src/audio`](https://github.com/horuse/splitwave/tree/main/src-tauri/src/audio) (Platform backends), [`src-tauri/src/commands.rs`](https://github.com/horuse/splitwave/blob/main/src-tauri/src/commands.rs) (Commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Svelte UI"]
  node_routes["App routes<br/>svelte routes"]
  node_flow["Flow editor<br/>graph UI"]
  node_pipeline_ui["Pipeline model<br/>typed state"]
  node_audio_ui["Audio UI<br/>audio controls"]
  node_overlay["Overlays<br/>ui layer"]
  node_updater["Updater<br/>update UX"]
  node_error_ui["Error UX<br/>error handling"]
end

subgraph group_backend["Tauri Rust"]
  node_tauri_main["Tauri app<br/>startup<br/>[main.rs]"]
  node_tauri_state["App state<br/>runtime state<br/>[state.rs]"]
  node_commands["Commands<br/>Tauri bridge<br/>[commands.rs]"]
  node_audio_engine["Audio engine<br/>engine core<br/>[engine.rs]"]
  node_pipeline_core["Pipeline DAG<br/>audio graph"]
  node_capture["Capture<br/>sources"]
  node_device_io["Device I/O<br/>device layer"]
  node_system_audio["System audio<br/>platform capture"]
  node_virtual_device["Virtual device<br/>loopback output"]
  node_effects["DSP effects<br/>signal processing"]
  node_encoders["Encoders<br/>recording output"]
  node_platform_io["Platform backends<br/>os adapters"]
end

subgraph group_native["Native support"]
  node_native_support["Native support<br/>Swift/C++"]
end

subgraph group_build["Packaging"]
  node_build_packaging["Build & packaging<br/>build config<br/>[build.rs]"]
end

node_routes -->|"renders"| node_flow
node_routes -->|"shows"| node_audio_ui
node_routes -->|"uses"| node_overlay
node_routes -->|"shows"| node_updater
node_routes -->|"shows"| node_error_ui
node_flow -->|"binds"| node_pipeline_ui
node_flow -->|"calls"| node_commands
node_audio_ui -->|"calls"| node_commands
node_error_ui -.->|"listens to"| node_commands
node_tauri_main -->|"initializes"| node_tauri_state
node_tauri_main -->|"registers"| node_commands
node_commands -->|"controls"| node_audio_engine
node_audio_engine -->|"runs"| node_pipeline_core
node_pipeline_core -->|"ingests"| node_capture
node_pipeline_core -->|"plays to"| node_device_io
node_pipeline_core -->|"captures"| node_system_audio
node_pipeline_core -->|"routes to"| node_virtual_device
node_pipeline_core -->|"applies"| node_effects
node_pipeline_core -->|"records via"| node_encoders
node_platform_io -.->|"implements"| node_capture
node_platform_io -.->|"implements"| node_device_io
node_platform_io -.->|"implements"| node_system_audio
node_platform_io -.->|"implements"| node_virtual_device
node_platform_io -.->|"supports"| node_encoders
node_native_support -.->|"bridges"| node_system_audio
node_native_support -.->|"drives"| node_virtual_device
node_build_packaging -.->|"packages"| node_tauri_main
node_build_packaging -.->|"compiles"| node_native_support

click node_routes "https://github.com/horuse/splitwave/tree/main/src/routes"
click node_flow "https://github.com/horuse/splitwave/tree/main/src/lib/modules/flow"
click node_pipeline_ui "https://github.com/horuse/splitwave/tree/main/src/lib/modules/pipeline"
click node_audio_ui "https://github.com/horuse/splitwave/tree/main/src/lib/modules/audio"
click node_overlay "https://github.com/horuse/splitwave/tree/main/src/lib/modules/overlay"
click node_updater "https://github.com/horuse/splitwave/tree/main/src/lib/modules/updater"
click node_error_ui "https://github.com/horuse/splitwave/tree/main/src/lib/modules/error"
click node_tauri_main "https://github.com/horuse/splitwave/blob/main/src-tauri/src/main.rs"
click node_tauri_state "https://github.com/horuse/splitwave/blob/main/src-tauri/src/state.rs"
click node_commands "https://github.com/horuse/splitwave/blob/main/src-tauri/src/commands.rs"
click node_audio_engine "https://github.com/horuse/splitwave/blob/main/src-tauri/src/audio/engine.rs"
click node_pipeline_core "https://github.com/horuse/splitwave/tree/main/src-tauri/src/audio/pipeline"
click node_capture "https://github.com/horuse/splitwave/tree/main/src-tauri/src/audio/capture"
click node_device_io "https://github.com/horuse/splitwave/tree/main/src-tauri/src/audio/device"
click node_system_audio "https://github.com/horuse/splitwave/tree/main/src-tauri/src/audio/system_audio"
click node_virtual_device "https://github.com/horuse/splitwave/tree/main/src-tauri/src/audio/virtual_device"
click node_effects "https://github.com/horuse/splitwave/tree/main/src-tauri/src/audio/effects"
click node_encoders "https://github.com/horuse/splitwave/tree/main/src-tauri/src/audio/encoders"
click node_platform_io "https://github.com/horuse/splitwave/tree/main/src-tauri/src/audio"
click node_native_support "https://github.com/horuse/splitwave/tree/main/src-tauri/native"
click node_build_packaging "https://github.com/horuse/splitwave/blob/main/src-tauri/build.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_routes,node_flow,node_pipeline_ui,node_audio_ui,node_overlay,node_updater,node_error_ui toneBlue
class node_tauri_main,node_tauri_state,node_commands,node_audio_engine,node_pipeline_core,node_capture,node_device_io,node_system_audio,node_virtual_device,node_effects,node_encoders,node_platform_io toneAmber
class node_native_support toneMint
class node_build_packaging toneRose
```

## Components

### Svelte UI

Presentation layer for editing, monitoring, and app UX.

- [App routes](https://github.com/horuse/splitwave/tree/main/src/routes): svelte routes · Top-level pages for the main editor, pipeline detail, preview, and virtual-device management. · `src/routes`
- [Flow editor](https://github.com/horuse/splitwave/tree/main/src/lib/modules/flow): graph UI · Visual node editor with inputs, effects, outputs, undo/redo, and snapshot history. · `src/lib/modules/flow`
- [Pipeline model](https://github.com/horuse/splitwave/tree/main/src/lib/modules/pipeline): typed state · Frontend pipeline state and generated Rust-backed types shared with the backend. · `src/lib/modules/pipeline`
- [Audio UI](https://github.com/horuse/splitwave/tree/main/src/lib/modules/audio): audio controls · Frontend audio status, activation, runtime controls, and device-related UI. · `src/lib/modules/audio`
- [Overlays](https://github.com/horuse/splitwave/tree/main/src/lib/modules/overlay): ui layer · Reusable modal, menu, tooltip, context, and popover infrastructure. · `src/lib/modules/overlay`
- [Updater](https://github.com/horuse/splitwave/tree/main/src/lib/modules/updater): update UX · Update notifications and related frontend state/methods. · `src/lib/modules/updater`
- [Error UX](https://github.com/horuse/splitwave/tree/main/src/lib/modules/error): error handling · Frontend error initialization, state, and modal presentation. · `src/lib/modules/error`

### Tauri Rust

Runtime backend for commands, audio engine, and OS integration.

- [Tauri app](https://github.com/horuse/splitwave/blob/main/src-tauri/src/main.rs): startup · App entrypoints and bootstrap for the desktop shell. · `src-tauri/src/main.rs`
- [App state](https://github.com/horuse/splitwave/blob/main/src-tauri/src/state.rs): runtime state · Shared backend state stored for commands and engine coordination. · `src-tauri/src/state.rs`
- [Commands](https://github.com/horuse/splitwave/blob/main/src-tauri/src/commands.rs): Tauri bridge · Callable operations exposed from Rust to the frontend. · `src-tauri/src/commands.rs`
- [Audio engine](https://github.com/horuse/splitwave/blob/main/src-tauri/src/audio/engine.rs): engine core · Core Rust runtime that owns routing, scheduling, and stream execution. · `src-tauri/src/audio/engine.rs`
- [Pipeline DAG](https://github.com/horuse/splitwave/tree/main/src-tauri/src/audio/pipeline): audio graph · Graph execution, signal representation, worker execution, meters, and file reading. · `src-tauri/src/audio/pipeline`
- [Capture](https://github.com/horuse/splitwave/tree/main/src-tauri/src/audio/capture): sources · System, per-app, file, and device input acquisition across platforms. · `src-tauri/src/audio/capture`
- [Device I/O](https://github.com/horuse/splitwave/tree/main/src-tauri/src/audio/device): device layer · Mic/speaker enumeration and playback/device plumbing. · `src-tauri/src/audio/device`
- [System audio](https://github.com/horuse/splitwave/tree/main/src-tauri/src/audio/system_audio): platform capture · OS-specific loopback and system-audio capture integration. · `src-tauri/src/audio/system_audio`
- [Virtual device](https://github.com/horuse/splitwave/tree/main/src-tauri/src/audio/virtual_device): loopback output · OS-specific virtual-device support for routing audio back into the system. · `src-tauri/src/audio/virtual_device`
- [DSP effects](https://github.com/horuse/splitwave/tree/main/src-tauri/src/audio/effects): signal processing · Gain, mute, EQ, compressor, delay, limiter, gating, reverb, saturator, and analysis modules. · `src-tauri/src/audio/effects`
- [Encoders](https://github.com/horuse/splitwave/tree/main/src-tauri/src/audio/encoders): recording output · Format-specific writers for recording and exported audio files. · `src-tauri/src/audio/encoders`
- [Platform backends](https://github.com/horuse/splitwave/tree/main/src-tauri/src/audio): os adapters · macOS, Linux, and Windows-specific implementation modules for capture, output, volume, and permissions. · `src-tauri/src/audio`

### Native support

macOS-only Swift/C++ bridge and driver support.

- [Native support](https://github.com/horuse/splitwave/tree/main/src-tauri/native): Swift/C++ · macOS bridging code and the system virtual-driver implementation. · `src-tauri/native`

### Packaging

Build, capability, and release integration.

- [Build & packaging](https://github.com/horuse/splitwave/blob/main/src-tauri/build.rs): build config · Build script, Tauri configs, capabilities, and release workflows. · `src-tauri/build.rs`

## Connections

- App routes → Flow editor: renders · Main editor routes host the flow editor and related pages.
- App routes → Audio UI: shows · Routes include audio status and control surfaces.
- App routes → Overlays: uses · Pages rely on overlay primitives for dialogs and menus.
- App routes → Updater: shows · App routes surface update prompts and banners.
- App routes → Error UX: shows · Routes present global error UI.
- Flow editor → Pipeline model: binds · The editor consumes the typed pipeline model and generated node data.
- Flow editor → Commands: calls · Editor actions are persisted and executed through backend commands.
- Audio UI → Commands: calls · Audio controls drive backend actions via Tauri commands.
- Error UX → Commands: listens to · Error state is populated from backend command failures.
- Tauri app → App state: initializes · App bootstrap creates shared runtime state.
- Tauri app → Commands: registers · Startup wires commands into the shell.
- Commands → Audio engine: controls · Commands steer the engine and expose audio operations.
- Audio engine → Pipeline DAG: runs · Engine execution is centered on the pipeline DAG and workers.
- Pipeline DAG → Capture: ingests · The graph consumes audio from capture sources.
- Pipeline DAG → Device I/O: plays to · Processed audio is delivered to device outputs.
- Pipeline DAG → System audio: captures · System audio feeds into the pipeline through platform-specific sources.
- Pipeline DAG → Virtual device: routes to · The graph can terminate in virtual-device outputs.
- Pipeline DAG → DSP effects: applies · DSP modules are applied inside the pipeline.
- Pipeline DAG → Encoders: records via · Recording outputs are encoded by format writers.
- Platform backends → Capture: implements · Platform modules specialize source capture and device access.
- Platform backends → Device I/O: implements · Platform modules provide device enumeration and playback backends.
- Platform backends → System audio: implements · OS-specific system-audio capture is selected per platform.
- Platform backends → Virtual device: implements · Virtual-device support varies by platform.
- Platform backends → Encoders: supports · Platform code may contribute to codec and audio I/O support.
- Native support → System audio: bridges · macOS native code bridges ScreenCaptureKit and related APIs.
- Native support → Virtual device: drives · Native support includes the macOS audio driver for virtual devices.
- Build & packaging → Tauri app: packages · Build and release tooling assemble the desktop shell.
- Build & packaging → Native support: compiles · Build scripts coordinate Swift and C++ native pieces.