lox-audioserver

Modern TypeScript implementation of the Loxone Audio Server, providing a full functional emulation with extended capabilities and external service bridging.

Core Features

• Radio support backed by TuneIn and Radio Paradise
• Custom radio stream management
• Local music library
  • File storage
  • Shared network drives
• Per-zone recents and favorites
• Per-zone equalizer
• Multi-account Spotify support
• Alert engine
  • Native Loxone alerts
  • Text-to-Speech (TTS), including LoxBerry TTS over MQTT

Audio Inputs

• Spotify Connect
• AirPlay
• Line-in (with optional Shazam track recognition)
• Music Assistant

Audio Outputs

Zones can stream to a range of network and local playback targets:

• Google Cast (Chromecast)
• Sonos
• Snapcast
• Sendspin
• AirPlay
• DLNA / UPnP
• Squeezelite
• Music Assistant
• Spotify Connect

Bridge Providers

To expose unsupported services to Loxone, lox-audioserver introduces bridge providers.

A bridge provider acts as a proxy layer that exposes a non-Spotify service as a virtual Spotify account.
Each bridge maps one external service to one virtual Spotify account, allowing Loxone to list and use multiple unsupported sources side by side without conflicts.

Available Bridge Providers

• Apple Music
• Deezer
• Tidal
• Youtube Music
• Music Assistant

Configuration

All features, inputs, and bridge providers are fully configurable through the Admin UI.

Requirements

• Docker (recommended) — easiest way to run the server without building from source.
• docker-compose (optional) — the repository includes a docker-compose.yml for one-command startup.
• Make sure host ports 7090,7091 and 7095 are available (or adjust host mappings when running the container).
• Network share library support relies on Unix-style mount tooling (e.g., mount.cifs); this is not available on Windows hosts.

Quick Start

The easiest options are docker-compose or docker run.

Recommended: docker-compose (one command)

If you have Docker and docker-compose installed you can use the included docker-compose.yml:

docker compose up -d

This starts a container named lox-audioserver in host network mode, which is the simplest way to allow mDNS/UPnP/Snapcast discovery without extra flags. Because host mode bypasses port publishing, make sure ports 7090, 7091, and 7095 are free on the host. To persist configuration and library data, add a bind mount to the service in docker-compose.yml:

    volumes:
      - ./data:/app/data

If you want to use the Power Manager with gpioset or USB HID relay boards from inside Docker, the container also needs access to the host devices. Expose the relevant /dev/gpiochip* and/or /dev/hidraw* entries, or run the container with elevated device access. Without that, GPIO and CRelay calls can succeed on the host shell but still fail in the container.

For gpioset, configure the chip and the line offset within that chip. On a Raspberry Pi 4, header GPIO22 is typically line 22 on /dev/gpiochip0; the old sysfs-style global number like 534 is not the value gpioset expects.

Shared amp or PSU switching is also supported through groups.powerGroups[]. Set a zone's powerManager.powerGroupId to the shared group id, then configure the group's own powerManager.gpio or powerManager.crelay. The shared output turns on while any member zone is active and turns off after the last member stops.

Quick Docker run

If you prefer docker run, host networking is recommended:

docker run -d \
  --name lox-audioserver \
  --network host \
  -v $(pwd)/data:/app/data \
  ghcr.io/lox-audioserver/lox-audioserver:latest

If you must use bridge networking instead, remove --network host and add port mappings -p 7090:7090 -p 7091:7091 -p 7095:7095.

Run standalone by cloning (no Docker)

If you prefer to run the server directly on the host without Docker, follow these steps. This is a minimal "standalone" run and requires Node.js and npm.

Prerequisites

• Node.js 20 or newer (Docker images and CI build on Node 24)
• npm (comes with Node)
• Ports 7090, 7091 and 7095 available on the host

Step-by-step

1. Clone the repository and change directory:

git clone https://github.com/lox-audioserver/lox-audioserver.git
cd lox-audioserver

2. Create a persistent data folder (used for config, logs, and cache):

mkdir -p data

3. Install dependencies and build:

npm install
npm run build

4. Start the server:

npm start

Configuring

Open the admin UI at http://lox-audioserver-ip:7090 and follow the guided steps. It walks you through adding the Audio Server in Loxone Config, rebooting the Miniserver, pairing, and assigning zones/providers once the MiniServer reconnects.

When the lox-audioserver starts successfully and the Miniserver pairs successfully with the lox-audioserver, the Audio Server icon in Loxone Config turns green.

---

Need help or found a bug? Open an issue in the repository.