Audiogravi^ty

Projects | 2026 | Links: Audiogravi^ty

Audiogravi^ty v1.2.0

Audiogravi^ty

Audiogravi^ty

Audiogravi^ty - Audio Device Manager, is an audiophile streamer management platform with 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 Hi-Fi workstations.

Audiogravi^ty 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.12 · FastAPI · Uvicorn · uvloop
System integration	dbus-fast (native D-Bus) · systemd · ALSA
Data validation	Pydantic v2 (`__slots__`) · orjson
Security	JWT HS256 · BCrypt · X-API-Key · mTLS (nginx PKI) · slowapi
Frontend	Lit 3.0 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 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 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 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.

1. 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).

2. 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.

3. 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.

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, …).

AudioSoftware Audio Software tab

1. 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.

2. 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.

3. 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.

Systemd Systemd tab

Performance

High-end optimization and latency validation.

CPU Governor: Direct control over frequency scaling policies (e.g., Performance, Schedutil).
Latency Testing: Integrated cyclictest tools with histogram reporting to validate kernel real-time performance.
Network Stability: Throughput and jitter testing to ensure stable streaming conditions.
Boot Persistence: Save optimized settings to a dedicated systemd service for automatic application at startup.

Performance tab

audiogravity_performance_test_latence Performance tab - latency test

audiogravity_performance_test_network Performance tab - network test

Config

Safe and intuitive configuration editing.

Hybrid Editor: Choose between a user-friendly UI Form Mode and a syntax-highlighted Expert Mode (CodeMirror).
Audio Output Discovery: Displays the currently active ALSA device directly on each service’s configuration tile.
Automatic Backups: Every change creates a versioned backup, allowing for instant rollback.
Safe Apply: Automatically restarts the modified service after saving to apply changes immediately.

Config Config tab

System

Centralized vital metrics and hardware inventory.

Vitals Dashboard: Real-time monitoring of CPU load, temperature, memory, and network/disk throughput.
Hardware discovery: Comprehensive list of detected audio cards, USB interfaces, and subdevices.
Event Log: Live stream of system events and SSE messages for deep diagnostic visibility.

System System tab

Audio Pipeline

Interactive visualization of the Hi-Fi signal chain.

Interactive Graph: Full SVG visualization of the path from Controller (Remote) → Server (Core) → Streamer (Local) → Physical Output (DAC/Amp).
Live Signal Path: Animated particles and glowing links indicate active audio streams.
Output Steering: On mobile, provides direct per-stream steering between different physical outputs (USB, Optical, etc.).
Status Integration: Displays playback state and “Now Playing” metadata directly on the graph nodes.

AudioPipeline Audio Pipeline tab

Admin

Access control and platform security.

RBAC: Role-Based Access Control with Admin (Full access), User (Functional access), and Guest (Read-only) roles.
Persistence Toggle: Choose between persistent (localStorage) or session-based (sessionStorage) authentication storage.
Security Defaults: Enforced password policies and session protection.

Admin Admin tab

Configuration files

Audiogravi^ty 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 Audiogravi^ty, 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

Audiogravi^ty 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

Audiogravi^ty follows a separated backend/frontend architecture connected via API.

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

    subgraph Server["Linux Server (DietPi/Debian)"]
        subgraph WebLayer["Web Layer (Flexible)"]
            WebServer["Nginx / Lighttpd<br/>/ Standalone Python"]
        end

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

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

    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)

Audiogravi^ty 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).

Audiogravity

Key Features

Audio Pipeline Visualization

Audio Service Orchestration

Real-time Monitoring

System Tuning

Expert Configuration

Security & Access Control

Mobile-First UI

Tech Stack

Architecture

Audiogravity Frontend Authentication System

Connection Modes

Session Management (Persistence)

Login Lifecycle

Roles and UI Adaptation

Security & Connectivity Monitoring

Navigation & Layout

Top Bar (Header)

Main Navigation Tabs (Sidebar)

Configuration Panel (Burger Menu)

Interface & Experience

Configuration Management

Advanced Security (Biometrics)

Connectivity & Notifications

Profiles

High-Level Orchestration

Live Feedback & Transparency

Monitoring & History

Services

1. Granular Service Control

2. Live Telemetry & Metrics

3. Visual History (Sparklines)

Audio Software

1. Package Lifecycle

2. Live Deployment Logs

3. Architecture & Compatibility

Systemd

Performance

Config

System

Audio Pipeline

Admin

Configuration files

audio-config.json

audio-topology.json

packages-config.json

Installation

Principle

Architecture Overview

Prerequisites

System Tools

Privileges

Quick Start

Installation Steps & Options

Selection

Configuration

Interactive Defaults

Security & Credentials

API Key

JWT Secrets

Administrative User

Push Notifications (Web Push / VAPID)

VAPID Keys

Testing

API Endpoints

Sending from Python

Development Tools & Quality

Useful Post-Install Commands

Check Status

View Logs

Uninstallation

Complete Removal

Troubleshooting

License

Acknowledgments

Templates (for web app):

Error

Audiogravi^ty

`audio-config.json`

`audio-topology.json`

`packages-config.json`