Audiogravi^ty

Projects | 2026 | Links: Audiogravity

work in progress Audiogravi^ty v1.0.0
Vladimir Fedotov^©

Audiogravity

Audiogravity

Professional web interface for managing audio services, hardware, and system performance on Linux-based Hi-Fi workstations.

Audiogravity is a self-hosted management platform for audiophiles running Linux audio stacks (MPD, HQPlayer, 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.

Designed for DietPi, Raspberry Pi, Apple 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.

Interface & Tab Overviews

The Audiogravity interface is organized into specialized tabs, each providing focused tools and real-time information for different aspects of your audio system.

1. Profiles

One-click high-level automation scenarios.

Orchestration: Switch complex audio setups instantly. Activating a profile automatically starts necessary services and stops conflicting ones to ensure bit-perfect playback.
Transparency: Each profile tile explicitly shows which services will be started and stopped.
Critical Profiles: Essential configurations that require confirmation before activation or deactivation to prevent system instability.
Dedicated History: Monitor every activation and potential service failure in the synchronized history panel.

2. Services

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

3. Audio Software

Unified package management for audiophile software.

Package Inventory: Manage Shairport Sync, MPD, HQPlayer NAA, UPnP Bridge, and Roon components.
Dry-Run Mode: Simulate installations or updates without making persistent changes to the system.
Architecture Validation: Visual indicators for CPU architecture compatibility (x86_64, armv7/8).
Bulk Operations: One-click “Update All” for all installed packages with available newer versions.

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

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

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

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

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

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

Architecture

audiogravity/
├── backend/          FastAPI (Python 3.13+) — async REST API + SSE
│   ├── core/         Auth, JWT, D-Bus, SSE manager, adaptive monitoring
│   └── modules/      11 feature modules (audio_pipeline, steering, profiles,
│                     services, sysinfo, performance, audio_hw, audio_app_config,
│                     config_validation, packages, push)
│
└── frontend/         Lit 3.0 Web Components — Vite 7 build
    ├── js/
    │   ├── core/     EventBus, AppState, FetchController, auth, API client
    │   └── components/
    │       ├── atoms/      8 base components (badge, switch, sparkline…)
    │       ├── molecules/  19 composite components (cards, tiles, modals…)
    │       └── organisms/  27 page-level components (pipeline, services, admin…)
    └── css/          Design token system — 35+ scoped component stylesheets

Backend stack: FastAPI · dbus-fast · orjson · uvloop · Pydantic v2 · python-jose · passlib · slowapi
Frontend stack: Lit 3.0 · Vite 7 · Storybook 10 · CodeMirror 5 · Stylelint

Project Statistics (v1.0.0)

Layer	Language	Lines (approx.)
Backend	Python	~20,000
Frontend JS	JavaScript (Lit/ES6)	~22,000
Frontend CSS	CSS (design tokens)	~11,000
Scripts	Bash + Python	~3,700
Documentation	Markdown	~21,000
Total		~78,000

120 Lit Web Components across 4 atomic design levels
12 backend modules, ~105 REST endpoints + 1 multiplexed SSE stream
36 scoped CSS files, all lint-clean (Stylelint Phase 3)

Installation

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

2. Architecture Overview

Audiogravity 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

3. Prerequisites

3.1 System Tools

Your system must have these basic utilities installed:

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

3.2 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/.

4. Quick Start

Run the global installer from the project root:

bash install.sh

5. Installation Steps & Options

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

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

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

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

6. Security & Credentials

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

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

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

7. Component Specifics

For deep-dive documentation on each component, please refer to their respective guides:

Backend Installation Guide (Python, venv, sudoers, modules)
Frontend Installation Guide (Node.js, Vite, Nginx, Proxy)

7.1 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"
    )

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

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

10. Uninstallation

10.1 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

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