Audiogravity - Linux Hi-Fi Streamer & Audio Service Manager

Projects | 2026 | Links: Audiogravity GitHub

Audiogravity is a professional Hi-Fi streamer management platform for Linux. Orchestrate MPD, HQPlayer, Roon, and system performance via a modern web interface on DietPi & Raspberry Pi.

Audiogravity
Audio Device & Streamer Manager

Audiogravity
Audio Device & Streamer Manager

Audiogravity is an advanced audiophile streamer management platform and Audio Device Manager (ADM). It features a professional web interface for orchestrating audio services (MPD, HQPlayer, Roon, minimServer, Jplay), monitoring system performance in real-time, and tuning Linux kernel parameters for bit-perfect playback on high-fidelity workstations.

Audiogravity is a self-hosted management platform for audiophiles running Linux audio stacks (MPD, HQPlayer, minimServer, Jplay, Roon, Shairport-Sync, upmpdcli). It provides real-time monitoring, service orchestration, interactive audio pipeline visualization, and advanced system tuning — all through a modern, responsive web UI and Portable Web App (PWA).

Designed for DietPi, Raspberry Pi, Apple Mac Mini, and any Debian-based Linux system, it bridges the gap between low-level kernel and ALSA configuration and a high-fidelity browser interface accessible from any device.

Key Features

Audio Pipeline Visualization

Interactive Signal Path: Full SVG graph of the Hi-Fi chain — streamer → DAC → amplifier — with pan, zoom, zoom-to-fit, and minimap navigation.
Live Status on Nodes: Playback state (play/pause/stop), Now Playing track info, and active link highlighting directly on the pipeline graph.
Output Steering: Click any pipeline link to switch a service’s ALSA output on the fly — MPD, HQPlayer NAA, and AirPlay supported.
Roon Integration: Zone display, zone transfer, and Roon output auto-discovery from the pipeline UI.
Network View: WiFi signal quality per interface, visible on the pipeline canvas.
Mobile Pipeline: Responsive layout with per-stream steering on small screens.

Audio Service Orchestration

Smart Profiles: One-click activation of complex audio scenarios — orchestrate MPD, Roon, HQPlayer, AirPlay with automatic conflict resolution.
Native D-Bus Control: Direct systemd integration via dbus-fast for instant service state changes and zero-polling monitoring.
Adaptive Monitoring: Telemetry frequency scales automatically (2s → 10s → 30s) based on system activity — 40–60% CPU reduction at idle.

Real-time Monitoring

SSE Telemetry: CPU load, memory, temperature, network and disk I/O streamed via Server-Sent Events.
SVG Sparklines: 60-second rolling history charts for all vital metrics.
Hardware Inventory: Deep ALSA card detection, USB device enumeration, and hardware capability reporting.
Frontend Performance Monitor: SSE traffic rate, active timer count, JS heap pressure — all visible in-browser.

System Tuning

CPU Affinity: Pin audio processes to specific cores to avoid scheduling interference.
Real-Time Scheduling: Configure FIFO/RR policies and priorities (1–99) for bit-perfect, stutter-free playback.
Governor Control: Direct CPU power state management (Performance, Schedutil, Powersave…).
Latency Testing: cyclictest-based tools with histogram reporting to validate RT kernel readiness.
Network Stability: Jitter and packet loss testing with iPerf3 and high-precision ping; iPerf3 service controlled from the UI.

Expert Configuration

Hybrid Config Editor: Modern form UI for common settings + CodeMirror raw editor with syntax highlighting for JSON, INI, XML, and Libconfig.
Validation Engine: Pydantic v2 schema validation, systemd unit existence checks, circular dependency detection, and duplicate service detection — before any change is applied.
Package Management: Install, update, and manage audio software (MPD, Shairport-Sync, HQPlayer, upmpdcli) through a unified interface with real-time SSE log streaming.

Security & Access Control

Dual-Layer Auth: Mandatory X-API-Key header (platform guard) + JWT tokens for Role-Based Access Control (Admin / User / Guest).
mTLS Support: Optional nginx PKI client certificate authentication for network-level access control.
Secure Defaults: Production startup refuses insecure secrets; .env permissions enforced to 600; JWT in sessionStorage (cleared on tab close).
Rate Limiting: slowapi-based rate limiting on authentication routes.

Mobile-First UI

Vertical Sidebar: Collapsible tab navigation with persistent mobile drawer, toggle button, and localStorage state.
Responsive Modals: dvh units and env(safe-area-inset-*) for correct sizing on iOS Safari.
Touch Targets: WCAG 2.1 AA minimum 44px touch targets on interactive elements.
Progressive Web App: Service Worker, installable on iOS/Android, offline fallback page, push notification support.

Tech Stack

Layer	Technology
Backend	Python 3.13 · FastAPI · Uvicorn · uvloop
System integration	dbus-fast (native D-Bus) · systemd · ALSA
Data validation	Pydantic v2 · orjson
Security	JWT HS256 · BCrypt · X-API-Key · mTLS (nginx PKI) · slowapi · WebAuthn (FIDO2 / Passkeys)
Frontend	Lit 3.3 Web Components · Vite 7 · Rollup
UI	CodeMirror 5 · SVG (pipeline graph) · SSE (Server-Sent Events)
PWA	Service Worker · Web Push (VAPID) · installable iOS/Android
Dev tooling	Storybook 10 · Stylelint · Husky 9 · rollup-plugin-visualizer
Target platforms	DietPi · Raspberry Pi · Apple Mac Mini · any Debian-based Linux

Architecture

graph LR
    subgraph CLIENT["Browser / PWA"]
        UI["Lit 3.0 Web Components\n54 components · 3 themes"]
        SSE_C["SSE Client\nAgTimerManager"]
        SW["Service Worker\n(offline / push)"]
    end

    subgraph API["FastAPI Backend"]
        REST["REST API\nX-API-Key + JWT RBAC"]
        SSE_S["SSE Telemetry\nadaptive 2s→10s→30s"]
        MOD["9 Modules\nauth · sysinfo · services\nprofiles · packages\nperformance · audio_hw\naudio_app_config · config_validation"]
    end

    subgraph SYS["Linux System"]
        DBUS["D-Bus / systemd\ndbus-fast"]
        ALSA["ALSA\naudio hardware"]
        CONF["Config Files\naudio-config.json\naudio-topology.json\npackages-config.json"]
    end

    UI -->|"HTTP/REST"| REST
    UI -->|"EventSource"| SSE_S
    SSE_C --> SSE_S
    REST --> MOD
    SSE_S --> MOD
    MOD -->|"native D-Bus"| DBUS
    DBUS -->|"systemd units"| SYS
    MOD -->|"ioctl / procfs"| ALSA
    MOD --> CONF

Audiogravity Frontend Authentication System

Audiogravity frontend authentication

The Audiogravity frontend authentication system is a hybrid solution combining traditional security with modern biometric technologies. It manages user sessions using JWT (JSON Web Tokens) and provides a seamless login experience.

Connection Modes

The frontend offers two primary ways to authenticate:

Username / Password: The standard method using a secure form.
Passkey (Biometrics): Support for WebAuthn (Face ID, Touch ID, or hardware security keys like Yubikey). If a Passkey has been previously registered, the UI automatically displays a simplified “Auto Face ID” panel instead of the standard form.

Session Management (Persistence)

Upon login, the system determines the storage location for the access token (JWT) based on user preferences:

Persistent Session: Stored in localStorage. You remain logged in even after closing the browser.
Temporary Session: Stored in sessionStorage. You are logged out when the tab is closed.
PWA Exception: When the app is running in standalone mode (installed as a PWA), sessions are always persistent to ensure a native app feel.

Initial Check: On page load, the frontend checks for an existing, non-expired JWT. If valid, the user is redirected to the dashboard (index.html).
Authentication Attempt:
- The frontend sends a POST /auth/login request to the backend.
- Mandatory Header: The request must include the X-API-Key to pass the first security layer.
Token Reception: The backend returns a signed JWT, the user role (admin, user, or guest), and the token lifetime.
Passkey Offer: If it’s a first-time password login and the browser is compatible, the user is prompted to register a Passkey for future passwordless logins.
Redirection: The user is redirected to the previously requested URL (saved in redirect_after_login) or the home page.

Roles and UI Adaptation

The frontend adapts its capabilities based on the user’s role:

Admin: Full access, including the system configuration and user management tabs.
User: Standard access to audio profiles and steering.
Guest: Read-only access. The frontend adds a .role-guest CSS class to the body, which hides or disables all modification controls (Save, Delete, Toggle).

Security & Connectivity Monitoring

API Connectivity: The login page performs a real-time health check (/health) to ensure the backend is reachable, displaying a status dot (connected/offline).
API Key Guard: If the X-API-Key is missing from the local configuration, the login form is disabled to prevent unauthorized attempts and inform the user of the configuration error.
Rate Limiting: The system inherits the backend’s rate limiting (default: 5 attempts per minute) to protect against brute-force attacks.

Audiogravity Main Navigation and Sidebar Layout Audiogravity frontend navigation

The Audiogravity interface is structured around two main navigation components: the Top Bar and the Main Navigation Tabs.

Top Bar (Header)

The ag-top-bar serves as the persistent global header of the application. It provides critical system information at a glance:

Connection Status: Real-time indicator of the frontend’s connection to the backend API.
System Metrics: Live monitoring of the host system:
- Uptime: Total time since the last system boot.
- CPU & Memory: Color-coded usage percentages (Low, Medium, High activity).
- Temperature: Real-time CPU temperature monitoring.
Global Actions:
- Documentation: Direct access to the internal documentation.
- Logout: Securely ends the session (visible only when authenticated).
- Burger Menu: Controls the configuration drawer on mobile.

The ag-tabs component manages the primary navigation between different application modules. It is designed for maximum flexibility:

Orientation: Can be toggled between Vertical (Sidebar) and Horizontal (Top).
Mobile Experience:
- Supports swipe gestures (edge swipe to open, vertical swipe to switch tabs).
- Features a “molette” mode for fast tab switching.
Dynamic Content:
- Now Playing: Displays real-time metadata (Artist, Title, Service) of the currently active audio stream.
- Badges & Stats: Real-time counters showing active elements (e.g., “2/5 profiles active”).
- Role-based Visibility: Automatically hides the “Admin” tab for non-administrator users.
Connectivity Indicator: A dedicated dot reflects the backend status directly within the logo area.

Audiogravity System Configuration and Theme Settings Drawer Audiogravity frontend configuration

The ag-config-panel is a side drawer (typically opened via the burger menu) that centralizes all user preferences and system settings.

Interface & Experience

Responsiveness: Features a slide-out animation with swipe-to-close support on mobile.
Themes & Styling:
- Dark Mode: Toggles between light and dark visual themes.
- Compact Mode: Reduces UI spacing for professional “pro-audio” layouts.
- Animations: Option to disable micro-animations for performance or accessibility.
- Theme Selector: Curated color palettes (Slate, Gravity, Minimal).

Configuration Management

Persistence: Provides tools to Export and Import the entire system configuration as a JSON file. Includes real-time validation before import.
API Security: Secure entry field for the global X-API-Key with visibility toggling.

Advanced Security (Biometrics)

Face ID / Touch ID: Users can register multiple biometric credentials (Passkeys) for passwordless login directly from this panel.
Device Management: Displays registered devices as interactive chips, allowing individual removal.

Connectivity & Notifications

Push Notifications: One-click subscription to system alerts and push notifications using the VAPID protocol.
System Versions: Live display of current Frontend and Backend versions with deep links to their respective technical documentation and Swagger API reference.

Profiles

Audiogravity Audio Profile Management and Orchestration Tiles Audiogravity profiles laptop and mobile view

The Profiles system is the core of Audiogravity’s audio orchestration. It allows for high-level automation of the entire audio software stack.

High-Level Orchestration

Bit-Perfect Environments: Profiles automatically start necessary services and stop conflicting ones to ensure an optimal playback environment.
Service Dependency: Every profile knows exactly which systemd units it needs to manage.
Critical Profiles: Visual indicators for essential profiles that require additional confirmation before activation or deactivation to prevent system interruption.

Live Feedback & Transparency

Real-time Status: Profile tiles update instantly using SSE (Server-Sent Events) to show transition states (Activating, Deactivating).
Service Impact: Each profile card displays a detailed list of services that will be started or stopped, providing full transparency on the system’s state.
Validation: Configurations are validated against the hardware topology before being applied.

Monitoring & History

Success/Failure Tracking: Detailed toasts and history logs inform the user if specific services failed to start during a profile transition.
History Panel: A dedicated history log records every profile change, providing a trail of the system’s previous states.
Audit Logs: Administrators can audit who activated which profile and when.

Services

The Services system provides granular control and monitoring of individual systemd units that make up the audio stack.

Granular Service Control

Manual Overrides: Users can manually start, stop, or restart any individual service (e.g., MPD, Shairport, Roon Bridge).
Persistence: Services can be enabled or disabled at the system level, ensuring they persist across reboots.
Systemd Integration: Deep integration with the host OS to reflect the true state of every unit (Active, Inactive, Failed, or Reloading).

Live Telemetry & Metrics

Real-time Monitoring: High-frequency updates of CPU and Memory usage for every active service via SSE.
I/O Tracking: Live monitoring of Network (RX/TX) and Disk (Read/Write) throughput, essential for diagnosing playback issues.
Color-Coded Activity: Metrics are color-coded based on specific thresholds (e.g., High CPU > 20% for DSP) to provide quick visual diagnostics.

Visual History (Sparklines)

Activity Trends: Each service tile features “Sparklines” (mini-graphs) showing the last 30 seconds of activity.
Historical Analysis: Clicking on a metric expands it into a detailed historical graph, pulling up to 30 minutes of data from local storage.
Diagnostics: Trends help identify memory leaks, unexpected CPU spikes, or network congestion that might affect audio quality.

Audiogravity Real-time Service Monitoring and Systemd Control Services tab

services_expand Services tab - expanded view

Real-time monitoring and manual control of individual systemd services.

Status Indicators: Live visual feedback on service state (Active, Inactive, Failed).
Live Metrics: Real-time CPU and Memory usage per service, updated via SSE.
Activity Level Color Coding:
- CPU: LOW (≤5%), MEDIUM (5-20%), HIGH (>20% - typically DSP/upsampling).
- Memory: LOW (≤30MB), MEDIUM (30-100MB), HIGH (>100MB).
- I/O: LOW (≤1MB/s), MEDIUM (1-5MB/s), HIGH (>5MB/s).
Audio Format Reference: Integrated reference for common stream bandwidth (CD Quality ≈1.4MB/s, Hi-Res 24/192 ≈10MB/s).

Audio Software

The Audio Software system manages the installation and lifecycle of third-party audio packages (MPD, Shairport Sync, Roon Bridge, UPnP, LMS, HQPlayer NAA, …).

Audiogravity Audio Software Package Manager and Installer Interface Audio Software tab

Package Lifecycle

Installation & Uninstallation: One-click management of software packages.
Update Management: Integrated version tracking that identifies when a newer version is available on the remote repositories.
Dry-Run Mode: A safety feature allowing users to simulate installations or updates to verify dependencies and scripts without making system changes.

Live Deployment Logs

SSE Stream: Real-time console output during installations and updates, allowing users to monitor progress and debug failures instantly.
Terminal Progress: Visual progress bars mapping internal installation stages to UI feedback.
Audit History: All software changes are recorded in the global history for future reference.

Architecture & Compatibility

Hardware Awareness: Intelligent detection of the host architecture (x86_64, ARMv7, ARMv8) to filter compatible software.
Package Configuration: Advanced JSON-based configuration for specifying installer types (APT, Scripts, DEB) and repository sources.
Import/Export: Ability to backup and restore the entire software configuration, enabling rapid deployment across multiple Audiogravity nodes.

Systemd

Low-level service tuning via systemd “drop-in” overrides.

CPU Affinity: Pin critical audio services to specific CPU cores to minimize context switching and scheduling jitter.
RT Scheduling: Configure Real-Time FIFO policies and priorities (up to 99) for stutter-free processing.
I/O Priority: Ensure audio-related disk/network operations have priority access.
Safe Overrides: Changes are saved as drop-in files, keeping the original vendor service files unmodified.

Audiogravity Systemd Service Tuning and CPU Affinity Configuration Systemd tab

Performance & Optimization

The Performance module provides industrial-grade diagnostic tools and real-time telemetry to ensure the system is tuned for the most demanding audio tasks.

CPU Governor Management

Per-Core Tuning: Granular control over the frequency scaling governor (e.g., Performance, Schedutil, Ondemand) for every logical core.
Boot Persistence: Capability to save governor configurations to disk and generate a dedicated systemd service to re-apply them automatically at boot.
Topology Awareness: Visual grouping of physical cores and logical threads to help users understand the impact of hyper-threading on audio jitter.

Audiogravity System Performance Monitoring and CPU Governor Control Performance tab

High-Resolution Telemetry

Live Thermal Mapping: Real-time temperature tracking mapped to specific cores, allowing for the detection of localized thermal throttling.
Peak Resource Tracking: High-frequency monitoring of CPU spikes and memory pressure with historical peak markers to identify “micro-stutters” that affect audio playback.

Audiogravity High-Resolution Latency Test and Cyclictest Histogram Performance tab - latency test

Integrated Diagnostic Tests

Latency Test (Cyclictest): Built-in wrapper for the cyclictest utility, providing a visual histogram of interrupt latency. This is the primary tool for verifying that Real-Time (RT) overrides are functioning as intended.
Network Stability (Iperf/Speedtest): Specialized tests to measure network jitter and throughput, ensuring the connection is stable enough for high-bitrate streaming (DSD64/128/256).

Audiogravity Network Stability and Iperf3 Throughput Testing Performance tab - network test

Configuration (audio engine)

The Configuration module is the central management interface for the Audiogravity engine’s logic and hardware mapping.

Audiogravity Audio Engine Configuration and Topology JSON Editor Config tab

Advanced Structural Editor

Pillar-Based Config: Management of the three core configuration files:
- Services: Definitions of systemd units, critical flags, and human-readable labels.
- Profiles: The high-level orchestration logic for one-click scenario switching.
- Topology: The logical map of the system’s hardware and virtual audio ports.
Integrated Validation: Every save request triggers a comprehensive validation pass that categorizes issues into Errors (blocking changes) and Warnings (notifying of non-standard but functional setups).

Port & Hardware Management

Topology Backup: Automatic generation of configuration backups before any structural changes are applied.
Import/Export: Tools to download the entire system logic as a validated JSON bundle for rapid deployment or recovery.

System dashboard

The System module acts as the centralized “Command Center” for host-level monitoring and maintenance.

Audiogravity System Dashboard and Host Health Monitoring System tab

Global Health Overview

Host Metadata: Instant visibility into the Kernel version, Hostname, local IP addresses, and system Uptime.
Partition Monitoring: Visual breakdown of storage usage across all critical mounts (/, /home, /data), preventing service failures due to full disks.
System Actions: Secure, authenticated triggers for Reboot, Shutdown, and a specialized Backend Restart that recycles the Audiogravity service without dropping the OS connection.

Troubleshooting & Logs

Global Log Viewer: Access to system-level logs for auditing boot sequences, hardware driver initialization, and backend crashes.

Audio Pipeline (visualizer)

The Audio Pipeline is a sophisticated, real-time graphical representation of the system’s internal audio signal path.

Audiogravity Interactive Hi-Fi Signal Path and Audio Pipeline Visualization Audio Pipeline tab

High-Performance Topology Map

Infinite Canvas: SVG-based visualization with smooth pan/zoom and a tracking minimap for navigating complex multi-room or multi-service setups.
Live Signal Flow: Dynamic animations (flow keyframes) represent active audio streams. The UI distinguishes between Software Links (dashed lines) and Hardware Links (solid lines).

Interactive Signal Steering

Port-Level Redirection: Users can click on ports to open the “Steering Popover,” allowing for manual redirection of audio signals or manual service starts directly from the visual map.
Network Metadata: Dedicated popovers for network links that display signal strength (RSSI), connection protocols (e.g., 802.11ax), and real-time link latency.

Administration & Security

The Administration module manages global access control and user-level security policies.

Audiogravity Administrative Dashboard and User Access Control Admin tab

RBAC (Role-Based Access Control)

Admin: Unrestricted access to all configuration, system tuning, and user management features.
User: Standard operational access, including profile switching and audio software management.
Guest: Strictly read-only access. The UI is dynamically modified via CSS and API guards to disable all destructive or configuration-level actions.

User Lifecycle Management

Account Controls: Tools to create, disable, or delete users and manage their individual permissions.
Session Policies: Configuration of session persistence (JWT storage in localStorage for permanent login vs sessionStorage for temporary access).
Audit Monitoring: A dedicated performance monitor integrated into the admin view to allow administrators to track system health while managing users.

Configuration files

Audiogravity is driven by three JSON configuration files that fully describe the system — no hardcoded values, no database required.

`audio-config.json`

Central platform configuration with two top-level keys: services and profiles, plus a topology_link that binds the config to the correct host device in the topology graph.

services — declares each managed audio service:

"hqplayer": {
  "critical": true,
  "label": "HQPlayer NAA",
  "systemd_unit": "networkaudiod.service",
  "appconfigfile": "/etc/networkaudiod/networkaudiod.xml"
}

critical: if true, the service requires user confirmation before start/stop
systemd_unit: the exact systemd unit name used for D-Bus control
appconfigfile: path to the application’s own config file, exposed in the Config tab

profiles — named orchestration presets (one-click scenarios):

"roonhd": {
  "name": "Roon HQPlayer",
  "description": "Roon + HQPlayer [Heed-Abacus USB]",
  "start": ["hqplayer", "roon"],
  "stop": ["upmpdcli", "mpd"],
  "critical": true
}

Activating a profile atomically starts the listed services and stops the conflicting ones, with automatic conflict resolution.

`audio-topology.json`

Describes the complete Hi-Fi signal chain as a graph of interconnected devices under hifi_topology.devices. Each device has a type (streamer, server, storage, source, converter, amplifier, output, controller, endpoint), its network interfaces, internal services, and physical I/O connectors that map to downstream devices by target_device_id / target_input_id.

Streamer — the Linux host running Audiogravity, with its audio services and ALSA outputs:

"streamer_01": {
  "type": "streamer",
  "internal_services": {
    "mpd":        { "service_type": "player" },
    "upmpdcli":   { "service_type": "controller", "protocol": "upnp", "controls": "mpd" },
    "roonbridge":  { "service_type": "receiver",   "protocol": "raat" },
    "networkaudiod": { "service_type": "processor" }
  },
  "outputs": {
    "usb":    { "target_device_id": "dac_01", "connector": "usb-a",  "system_device_id": "hw:0,0" },
    "toslink": { "target_device_id": "dac_01", "connector": "toslink", "system_device_id": "hw:1,1" }
  }
}

Network server — a remote Roon/HQPlayer core with its own streaming services and NAA output:

"music_server_01": {
  "type": "server",
  "network_outputs": {
    "hqplayer_naa": { "protocol": "naa",  "target_device_id": "streamer_01", "target_service": "networkaudiod" },
    "raat":          { "protocol": "raat", "target_device_id": "streamer_01", "target_service": "roonbridge" }
  }
}

Storage / NAS — declares mount points and UPnP services (MinimServer):

"music_library_01": {
  "type": "storage",
  "internal_services": {
    "nas_nfs":    { "protocol": "nfs",     "mount_point": "/mnt/music" },
    "minim_upnp": { "protocol": "upnp/av", "connection": { "ip": "10.0.0.42", "port": 9791 } }
  }
}

Controller — a mobile device (iPhone) with Jplay as UPnP/OpenHome control point:

"iphone_01": {
  "type": "controller",
  "internal_services": {
    "jplay": {
      "service_type": "control_point",
      "protocols": ["upnp/openhome", "hqp_control"],
      "controls": ["streamer_01.upmpdcli", "music_library_01.minim_upnp"]
    }
  }
}

This file is the sole source of truth for the Audio Pipeline SVG visualization.

graph TB
    subgraph CTL["🎛️ Controller"]
        iphone["iPhone 15 Pro\nJplay · Roon Remote · AirPlay"]
    end

    subgraph NET["🌐 Network"]
        nas["NAS — Synology DS920+\nMinimServer (UPnP/AV) · NFS · SMB"]
        server["Music Server\nRoon Server · HQPlayer Embedded"]
    end

    subgraph STR["🖥️ Streamer — Linux Host (Audiogravity)"]
        mpd["MPD\n(player)"]
        upmpdcli["upmpdcli\n(UPnP renderer)"]
        naa["HQPlayer NAA\n(networkaudiod)"]
        roonbridge["Roon Bridge\n(RAAT)"]
        airplay["Shairport-Sync\n(AirPlay)"]
    end

    subgraph ANA["🎚️ Analog Sources"]
        turntable["Rega Planar 3\n(Turntable)"]
        tuner["Naim NAT 02\n(FM Tuner)"]
        cdp["Naim CDI\n(CD Player)"]
    end

    dac["🔵 Heed Abacus S\n(DAC)"]
    amp["🔊 Naim Nait 2\n(Amplifier)"]
    speakers["Rogers LS3/5a\n(Speakers)"]
    ear["👂 Listener"]

    iphone -->|"UPnP/OpenHome"| upmpdcli
    iphone -->|"HQP control"| server
    iphone -->|"RAAT control"| server
    iphone -->|"AirPlay"| airplay

    nas -->|"NFS mount"| mpd
    nas -->|"UPnP/AV"| upmpdcli

    server -->|"NAA stream"| naa
    server -->|"RAAT stream"| roonbridge

    mpd -->|"controls"| upmpdcli

    STR -->|"USB — hw:0,0"| dac
    STR -->|"Toslink — hw:1,1"| dac

    turntable -->|"RCA — Phono"| amp
    tuner -->|"DIN — Tuner"| amp
    cdp -->|"DIN — Tape"| amp
    dac -->|"RCA→DIN — AUX"| amp

    amp -->|"Banana"| speakers
    speakers -->|"Air"| ear

`packages-config.json`

Software catalog for the Audio Software tab. Each entry under packages defines how to install, update, and identify a piece of audio software:

"upmpdcli": {
  "label": "UPnP Bridge",
  "description": "UPnP/DLNA front-end for MPD",
  "package_name": "upmpdcli",
  "service_id": "upmpdcli",
  "installer_type": "apt_repo",
  "installer_config": {
    "gpg_key_url": "https://www.lesbonscomptes.com/pages/lesbonscomptes.gpg",
    "gpg_key_path": "/usr/share/keyrings/lesbonscomptes.gpg",
    "repo_line": "deb [signed-by=...] http://www.lesbonscomptes.com/upmpdcli/downloads/debian/ trixie main",
    "sources_list_path": "/etc/apt/sources.list.d/upmpdcli.list"
  },
  "arch_support": ["amd64", "arm64", "armhf"]
}

Four installer_type strategies are supported:

Type	Description
`apt_simple`	Standard `apt install` (MPD, Shairport-Sync)
`apt_deb`	Direct `.deb` download with regex version auto-detection (HQPlayer NAA)
`apt_repo`	Third-party apt repository with GPG key setup (upmpdcli)
`script`	Vendor install script with custom uninstall commands (Roon Bridge, Roon Server)
`dummy`	No-op installer for testing the installation workflow

arch_support lists compatible architectures (amd64, arm64, armhf, all) — the UI renders a visual compatibility badge per package.

Installation

Principle

Audiogravity uses an orchestrated installation process. The top-level install.sh script acts as a master controller that:

Validates global prerequisites.
Coordinates configuration shared between components (like API ports and keys).
Triggers specialized sub-installers for the Backend and Frontend.

Architecture Overview

Audiogravity follows a separated backend/frontend architecture connected via API. The Web Layer is highly flexible, supporting local servers (Nginx, Lighttpd) or a decoupled “External Proxy” mode for advanced security (TLS/mTLS).

flowchart TD
    subgraph Browser["User Browser"]
        UI[Audiogravity Web Interface]
    end

    subgraph Server["Linux Server (DietPi/Debian)"]
        subgraph WebLayer["Web Layer (Flexible)"]
            Proxy[Optional Nginx Proxy \n TLS / mTLS]
            WebServer[Nginx / Lighttpd \n / Standalone Python]
        end

        subgraph BackendLayer["Backend API (Python/FastAPI)"]
            API[API Server \n port 8000]
            Auth[JWT Auth \n Module]
            SysInfo[System Info \n Modules]
            SvcMgmt[Service Mgmt \n Modules]
        end

        subgraph SystemLayer["Operating System"]
            Systemd[(Systemd)]
            AudioSvcs[Audio Services \n Roon, HQPlayer, MPD...]
            Pkgs[Package Mgr \n APT/Scripts]
        end
    end

    UI -.->|HTTPS / mTLS| Proxy
    Proxy -.->|HTTP Proxy| WebServer
    UI -->|HTTP / WebSocket| WebServer
    WebServer -->|API Proxy / Direct| API
    WebServer -->|Static Files| WebServer

    API --- Auth
    API --- SysInfo
    API --- SvcMgmt

    SvcMgmt -->|D-Bus / Subprocess| Systemd
    Systemd -->|Manage| AudioSvcs
    SvcMgmt -->|Run| Pkgs

Prerequisites

System Tools

Your system must have these basic utilities installed:

bash, curl, sed, grep, awk
hostname, systemctl (for service management)

Privileges

The script should ideally be run with sudo privileges.

Backend: Needs sudo to configure sudoers.d and systemd services.
Frontend: Needs sudo to configure web servers (Nginx/Lighttpd) and write to /var/www/.

Quick Start

Run the global installer from the project root:

bash install.sh

Installation Steps & Options

The installer is interactive and will guide you through several choices:

Selection

You can choose to install:

Backend only: If you only need the API.
Frontend only: If the API is already running elsewhere.
Both (Recommended): For a full, integrated installation on a single machine.

Configuration

API Port: The port the backend will listen on (default 8000).
Backend Host/IP: (If installing Frontend) Tells the web UI where the API is located.
Skip Build: (If installing Frontend) Option to use existing pre-built assets (from _site/ directory). This is useful to avoid installing Node.js/npm on the production machine; you can build on your development machine and copy the files.

Interactive Defaults

When the installer asks a question, the value inside brackets [] is the default value.

If you simply press ENTER without typing anything, the default value is used.
Example: Enter backend API port [8000]: → Pressing ENTER will use 8000.
For Yes/No questions like (y/N), the capital letter indicates the default. (y/N) defaults to No, while (Y/n) would default to Yes.

Security & Credentials

API Key

The installer automatically coordinates the API Key:

It is generated/stored in backend/.env.
It is automatically detected and injected into the Frontend configuration during the process.

JWT Secrets

Secure JWT secrets are generated during the backend phase. You should save the API Key displayed at the end of the backend installation for manual administration if needed.

Administrative User

At the end of the backend phase, the script will prompt you to create the first Admin User.

Important: You will be locked out of the web interface if you do not create this user.

Push Notifications (Web Push / VAPID)

Audiogravity supports Web Push notifications via the VAPID protocol. The Service Worker (frontend/public/sw.js) handles incoming push events.

Requirement: Push notifications require HTTPS. They will not work over plain HTTP.

VAPID Keys

VAPID keys are generated during installation and stored in backend/.env:

VAPID_PRIVATE_KEY=...
VAPID_PUBLIC_KEY=...

To regenerate them manually:

cd backend
venv/bin/python -c "from py_vapid import Vapid; v = Vapid(); v.generate_keys(); print(v.private_key, v.public_key)"

Testing

# Send a test notification from the backend
cd backend
venv/bin/python test_push_manual.py

Or open the browser test page:

https://<your-host>/test-push-subscription.html

Log in with your credentials.
Click Subscribe.
Click Send Test.

API Endpoints

Endpoint	Auth	Description
`GET /push/vapid-public-key`	API Key	Retrieve the VAPID public key
`POST /push/subscribe`	JWT	Subscribe a device to push notifications
`POST /push/send`	JWT	Send a push notification
`GET /push/subscribers`	JWT	List active subscribers

Sending from Python

from modules.push.service import get_push_service

async def send_alert():
    push_service = get_push_service()
    await push_service.send_notification(
        title="Alert",
        message="CPU temperature at 85°C",
        url="/index.html#system"
    )

Development Tools & Quality

The repository includes tooling for frontend development quality:

.vscode/settings.json — VSCode workspace settings: Stylelint enabled, CSS native validation disabled, auto-fix on save configured. Requires the stylelint.vscode-stylelint extension.
.github/workflows/css-lint.yml — CI workflow that runs npm run lint:css on every push or pull request (compatible with GitHub and Gitea CI).
Husky pre-commit hook (frontend/.husky/pre-commit) — Automatically runs Stylelint on staged CSS files before each commit. Configured via lint-staged in frontend/package.json.

These tools are active after running npm install in the frontend/ directory. The git hooks path is configured automatically via the prepare script.

Useful Post-Install Commands

Check Status

# Backend
sudo systemctl status audiogravity-backend

# Frontend (depending on your choice)
sudo systemctl status nginx
# OR
sudo systemctl status lighttpd
# OR
sudo systemctl status audiogravity-frontend

View Logs

# Backend logs
sudo journalctl -u audiogravity-backend -f

# Web server logs (example for Nginx)
sudo journalctl -u nginx -f

Uninstallation

Complete Removal

# Stop services
sudo systemctl stop audiogravity-backend
# Stop web server (depends on selection)
sudo systemctl stop nginx

# Disable services
sudo systemctl disable audiogravity-backend

# Remove backend
sudo rm -f /etc/systemd/system/audiogravity-backend.service
sudo rm -f /etc/sudoers.d/audiogravity-backend
sudo rm -rf /etc/audiogravity
rm -rf audiogravity/backend/venv
rm -f audiogravity/backend/.env

# Remove frontend
sudo rm -f /etc/nginx/sites-enabled/audiogravity
sudo rm -f /etc/nginx/sites-available/audiogravity
sudo rm -rf /var/www/audiogravity-frontend

# Reload systemd
sudo systemctl daemon-reload

Troubleshooting

Missing Tools: If the script fails early, ensure you have common Unix tools installed (apt install curl sed grep).
Permission Denied: Ensure you are running with sudo.
Port Conflict: If port 8000 or 80 is already in use, the installer will warn you or failed services won’t start.

License

Acknowledgments

Built for the audiophile community on DietPi and Raspberry Pi who demand precise, low-latency control over their Hi-Fi systems.

Developed with the assistance of Claude.ai (Anthropic).