Fluxeroid Radio

• Overview
• Architecture
• Features
• Quick Start
• Project Structure
• Docker Services
• Environment Variables
• Migration from Asteroid

Overview

Fluxeroid is a rewrite of Asteroid Radio using the Fluxion web framework. It provides internet radio streaming with live reactive UI, Icecast/Liquidsoap integration, and PostgreSQL persistence.

Architecture

• Framework: Fluxion (HTML-over-the-wire, SSE, Lattice reactivity)
• Database: PostgreSQL (via fluxion/db-pg)
• Streaming: Icecast2 + Liquidsoap (Docker-managed)
• UI: Server-rendered CLOS components with SSE push updates
• Styling: LASS (dark theme, Asteroid colour scheme)

Features

• Live stream player with now-playing display (SSE-reactive)
• Music library scanning and metadata extraction
• Stream queue management with M3U playlist generation
• Automatic playlist scheduling (time-based rotation)
• User accounts with roles (listener, dj, admin)
• User favorites and listening history
• Track request system
• Listener statistics with GDPR-safe IP hashing
• Geographic listener distribution
• Admin dashboard with service status
• REST API for all operations

Quick Start

;; Start Docker infrastructure
;; $ cd docker && docker compose up -d

;; Load and start
(ql:quickload :fluxeroid)
(fluxeroid:start :port 8080)

;; Stop
(fluxeroid:stop)

Project Structure

src/
  package.lisp          - Package definitions
  config.lisp           - Configuration (env vars + fluxion/config)
  migrations.lisp       - Database schema migrations
  models.lisp           - Data access layer
  library.lisp          - Music library scanning
  stream.lisp           - Queue management, M3U generation
  liquidsoap.lisp       - Liquidsoap telnet control
  icecast.lisp          - Icecast status polling
  scheduler.lisp        - cl-cron playlist rotation
  stats.lisp            - Listener statistics
  playlists.lisp        - Playlist file management
  requests.lisp         - Track request system
  components/
    layout.lisp         - Page shell, nav, footer
    player.lisp         - Stream player (SSE-reactive)
    now-playing.lisp    - Live now-playing display
    library-browser.lisp- Track listing
    admin/
      dashboard.lisp    - System status overview
      queue.lisp        - Stream queue management
      users.lisp        - User management
      stats.lisp        - Listener analytics
  pages.lisp            - Route definitions
  api.lisp              - REST API endpoints
  app.lisp              - Application entry point
static/
  styles.lass           - LASS stylesheet (Asteroid colour scheme)
docker/
  docker-compose.yml    - PostgreSQL + Icecast + Liquidsoap

Docker Services

Service	Port	Purpose
PostgreSQL	5433	Database (host-mapped)
Icecast	8001	Stream distribution
Liquidsoap	1234	Stream source/telnet
Fluxeroid	8080	Web application

Environment Variables

Variable	Default	Description
FLUXEROID_DB_NAME	fluxeroid	PostgreSQL database
FLUXEROID_DB_USER	fluxeroid	Database user
FLUXEROID_DB_PASSWORD	fluxeroid_dev	Database password
FLUXEROID_DB_HOST	localhost	Database host
FLUXEROID_DB_PORT	5433	Database port
FLUXEROID_MUSIC_PATH	app/music	Music library path
FLUXEROID_STREAM_URL	http://localhost:8001	Icecast base URL
FLUXEROID_PORT	8080	Web server port
FLUXEROID_ICECAST_PASS	fluxeroid_admin	Icecast admin pass

Migration from Asteroid

Asteroid (Radiance)	Fluxeroid (Fluxion)
CLIP templates	Spinneret CLOS components
Parenscript JS per page	Fluxion client runtime
JS polling now-playing	SSE push via Lattice cells
Radiance DB abstraction	fluxion/db-pg direct
define-page	defroute + components
define-api (Radiance)	fluxion/api define-api
Session via Radiance	fluxion/session-db
format t debugging	fluxion/log structured
defparameter config	fluxion/config persistent