Skip to content

README.md

Latest commit

 

History

History
144 lines (113 loc) · 6.1 KB

README.md

File metadata and controls

144 lines (113 loc) · 6.1 KB
Raw

Spectrum

Spectrum is a lighting-control application written in C#. Its desktop frontend and MIDI adapter are Windows-only. The lighting engine, browser controller, simulator, OPC output, orientation inputs, ALSA audio-level capture, and headless host run on Linux. The Linux release also carries a native Madmom runtime; the host feeds it the PCM already captured by ALSA so it does not need to enumerate or open the device a second time.

Installation

The complete desktop application and show audio/MIDI stack currently require a 64-bit Windows computer.

  1. Install Visual Studio Community with the .NET desktop development and Desktop development with C++ workloads.

  2. Install the .NET 10 SDK, Git for Windows, and uv. Install FFmpeg from PowerShell with winget install --id Gyan.FFmpeg -e; Madmom's build and tests require both ffmpeg and ffprobe on PATH.

  3. Clone the repository. A recursive clone is preferred, but the build script also initializes missing submodules:

    git -c core.autocrlf=false clone --recursive https://github.com/campmindshark/spectrum
cd spectrum

  4. Run the checkout-to-artifact build:

    .\build.ps1

The first build needs Internet access. It provisions an isolated CPython 3.11 environment under Madmom/.build-env, compiles the Cython extensions with MSVC, runs the Python and .NET verification suites, and writes these ignored artifacts:

  • artifacts/wheels/: the CPython 3.11 x64 Madmom wheel.
  • artifacts/Spectrum/: the self-contained .NET application and standalone Python runtime.
  • artifacts/Spectrum-win-x64.zip: the portable release directory as an archive.

For a faster developer/CI build that omits the portable application, run .\build.ps1 -SkipPortable. To build only the Python component, run .\Madmom\scripts\build.ps1.

Linux headless host and portable verification

The Spectrum.Host console application runs the engine and browser controller with ALSA audio-level capture and Madmom beat tracking on Linux; MIDI is disabled. The target must provide libasound.so.2 and libstdc++.so.6 with GLIBCXX_3.4.22 or newer; stock Ubuntu 16.04 is too old for the self-contained .NET 10 host. With those libraries and the .NET 10 SDK installed:

dotnet run --project Host/Spectrum.Host.csproj -c Release -- --data-dir ./spectrum-data

Open http://localhost:8080 to use the controller or browser dome simulator. The maintenance page enumerates ALSA capture devices, persists the selected PCM name, shows the live peak level, and reports capture errors. The capture worker retries when an interface is absent or unplugged. When Madmom is selected as the tempo source, it also starts the packaged tracker, streams a mono copy of that PCM to stdin, and reports/retries tracker process failures. --port changes the listener port. Without --data-dir, configuration follows SPECTRUM_DATA_DIR, XDG_CONFIG_HOME/spectrum, then ~/.config/spectrum. Ctrl+C and SIGTERM perform an ordered shutdown and flush pending changes.

The host is not yet at full Linux show-hardware parity: ALSA capture and live Madmom orchestration are implemented and packaged, but they still need physical hardware latency/permission/unplug qualification. MIDI is deliberately deferred. The portable regression suite runs with:

dotnet run --project Tests/Portability/Spectrum.Portability.Tests.csproj -c Release

To reproduce the Linux Madmom wheel and relocatable runtime on an x86-64 Linux host, install build-essential, ffmpeg, and portaudio19-dev, install uv==0.11.26, then run:

bash Madmom/scripts/build.sh \
  --environment-directory artifacts/madmom-linux-build-env \
  --wheel-directory artifacts/wheels/linux-x64 \
  --portable-runtime-directory artifacts/madmom-linux-runtime

The script provisions managed CPython 3.11.15, runs the Madmom suite, checks the four Cython .so modules and PyAudio, runs the DBN tracker against its sample audio through both file and raw-PCM inputs, and repeats the smoke tests after relocating the staged runtime.

To create the same self-contained linux-x64 directory used by CI and tagged releases:

dotnet publish Host/Spectrum.Host.csproj \
  -c Release \
  -r linux-x64 \
  --self-contained true \
  -p:PublishSingleFile=false \
  -o artifacts/Spectrum-linux-x64

The publish directory includes the browser assets, packaged default configuration, license, and a hardened systemd unit with installation notes in deploy/linux/README.md. Tagged releases attach this host as Spectrum-linux-x64.tar.gz alongside the complete Windows desktop archive. The Ubuntu CI job launches the published executable, waits for its HTTP API, persists a setting, sends SIGTERM, and verifies the clean shutdown and saved configuration.

User manual

See the Dome User Manual for desktop setup, browser show controls, maintenance, simulator use, and troubleshooting.

Development and on-site troubleshooting

See the On-playa Development and Troubleshooting Guide for offline build and recovery preparation, architecture, safe development workflows, runtime diagnostics, API checks, hardware-boundary troubleshooting, and common code-change recipes.

For a compact offline reference, see the Spectrum Development Cheat Sheet for magic constants, source locations, runtime invariants, and fast commands.

Dome Simulator

To test out the dome, enable the simulator under the LED Dome tab:

Simulator Settings

When it's working, you should see something like the following:

SDome Simulator