Skip to content

README.md

Latest commit

 

History

History
153 lines (113 loc) · 6.92 KB

README.md

File metadata and controls

153 lines (113 loc) · 6.92 KB

FXRoute

FXRoute is a browser-based audio control surface for Linux listening machines.

It is built for mini PCs, desktops, ARM boards, and dedicated stereo boxes that run local playback, EasyEffects DSP, radio, library playback, measurement tools, and optional Spotify desktop control — all remote-controlled from a phone, tablet, or laptop on the local network.

FXRoute measurement graph showing raw and corrected right-channel response

Measure, compare, and turn room-response results into convolver/PEQ corrections directly in the browser.

FXRoute routing and player view FXRoute DSP preset controls
Playback and routing DSP presets and A/B compare
FXRoute PEQ measurement editor FXRoute technical settings
Measurement PEQ editor Technical settings
FXRoute mobile library FXRoute mobile radio tab FXRoute mobile FIR preset editor
Mobile library Mobile radio Mobile PEQ preset

What it does

  • browser UI for desktop and mobile control
  • local music playback with queue, playlists, folder browsing, uploads, ZIP album imports, and media URL imports
  • internet radio with built-in and custom stations
  • lightweight Now Playing cover cue for local tracks when folder or embedded cover art is available
  • Spotify desktop control through playerctl / MPRIS
  • EasyEffects preset switching, PEQ, convolver import/export, output helpers, and A/B compare
  • convolver preset bundles with EasyEffects .irs, REW-friendly .wav impulse copy, preset JSON, and reimport support
  • bundled 30-second 1 kHz stereo FLAC level tone at -12 dBFS for safe level checks
  • global DSP helpers such as limiter, headroom, autogain, bass enhancement, and tone modes
  • practical room/speaker measurement workflow with host microphone capture, calibration files, smoothing, saved runs, PEQ draft transfer, FIR/convolver preset creation, and custom REW-style house curves
  • sample-rate-aware playback handling for local files, radio, Spotify, and Bluetooth handoff cases
  • Bluetooth input visibility/control when the host audio stack supports it
  • optional USB serial amplifier-controller integration for RP2040/ESP32-style MCU input selectors
  • optional local HTTPS/Caddy setup with downloadable local certificate for trusted LAN clients
  • installer support for systemd user service, Flatpak EasyEffects, PipeWire/BlueZ dependencies, firewall comfort rules, and .local LAN naming

Intended setup

FXRoute is meant for a Linux desktop-session audio box, not a fully headless rack server.

Typical setup:

  • small PC or ARM board near DAC, amp, active speakers, headphones, or TV
  • PipeWire-based Linux desktop session
  • EasyEffects running in the same local user session
  • optional Spotify desktop client in the same session
  • control from any browser on the LAN

The user session matters because FXRoute coordinates local audio applications, EasyEffects, MPRIS/playerctl, and PipeWire audio routes. In socket mode, EasyEffects runs as a background service in that session.

Requirements

On supported distros, install.sh installs and configures the required runtime tools such as Python dependencies, mpv, ffmpeg, playerctl, Bluetooth/PipeWire helpers, and service files.

EasyEffects is handled separately: fresh installs can use the installer-managed Flatpak path, while existing native/package-manager EasyEffects installs are accepted when already present.

Tested installer targets so far include:

  • Ubuntu 24.04 and 26.04 on x86_64
  • Manjaro / Arch-family x86_64 systems
  • openSUSE Tumbleweed on x86_64
  • Fedora-family x86_64 systems
  • Armbian 26.2.1 / Ubuntu 24.04 Noble on ARM64 (aarch64, Khadas VIM1S; PipeWire setup may be needed depending on the image)

EasyEffects mode

The installer prefers Flatpak EasyEffects when it installs EasyEffects itself. This is the most reproducible path and normally provides the EasyEffects control socket used by FXRoute for faster preset switching and recovery.

If EasyEffects is already installed through the system package manager or managed manually by the user, FXRoute can use that installation instead. Older native EasyEffects builds may not expose the control socket; in that case FXRoute falls back to EasyEffects CLI control where possible.

Quick start

chmod +x install.sh
./install.sh

The installer creates .env automatically and preserves it on reruns. For manual setup, copy .env.example to .env and adjust at least MUSIC_ROOT when needed. A NAS library can be used by mounting its SMB/Samba share locally, for example under /mnt/music, and setting MUSIC_ROOT=/mnt/music.

Default user service:

  • fxroute.service

Typical URLs:

  • http://localhost:8000
  • http://<host-ip>:8000
  • http://fxroute.local when mDNS is enabled
  • https://<host-ip> or https://fxroute.local when the optional local HTTPS proxy is enabled

Main sections

  • Radio — built-in and custom internet stations
  • Library — local files, folder browsing, playlists, uploads, imports, downloads, and deletion
  • DSP — EasyEffects presets, PEQ, convolver import/export, helpers, A/B compare, and preset creation
  • Measure — practical host-mic measurement, PEQ/FIR tuning, calibration files, and custom house curves
  • Spotify — control a local Spotify desktop client
  • Technical settings — output selection, source state, Bluetooth status, optional amplifier-controller status/control, and local certificate access

Additional notes

Service commands

systemctl --user status fxroute
systemctl --user restart fxroute
journalctl --user -u fxroute -f

Useful EasyEffects checks:

flatpak list --app | grep easyeffects
pgrep -af easyeffects

Manual

See MANUAL.md for the short user manual.

License

See LICENSE.