6 changed files with 238 additions and 284 deletions
--- a/README.org
+++ b/README.org
@ -1,12 +1,10 @@
 #+TITLE: Asteroid Radio - Internet Radio Streaming Platform
 #+AUTHOR: Asteroid Radio Development Team
-#+DATE: 2026-03-05
+#+DATE: 2026-01-26
 * Overview
-Asteroid Radio is a complete internet radio streaming platform built entirely in Common Lisp. It combines the [[https://shirakumo.github.io/radiance/][Radiance]] web framework with an in-process audio streaming pipeline powered by [[https://shirakumo.github.io/harmony/][Harmony]], [[https://shirakumo.github.io/cl-mixed/][cl-mixed]], and a custom streaming server called *CL-Streamer*. Everything runs in a single SBCL process — audio decoding, mixing, encoding, HTTP streaming, metadata, playlist scheduling, and the web frontend.
+Asteroid Radio is a complete internet radio streaming platform built with Common Lisp, featuring a hacker-themed terminal aesthetic. The project combines the Radiance web framework with Icecast/Liquidsoap streaming infrastructure to create a full-featured music streaming platform with live broadcasting capabilities.
 No external streaming services are required. The only external dependency is PostgreSQL for persistent data.
 ** Project Links
 - *Repository*: https://github.com/fade/asteroid
@ -16,229 +14,188 @@ No external streaming services are required. The only external dependency is Pos
 * Key Features
 ** Live Internet Radio Streaming
- Dual-format simultaneous output: 128kbps MP3 + 128kbps AAC
+- Multiple quality streams: 128kbps MP3, 96kbps AAC, 64kbps MP3
- Real-time audio decoding via Harmony (FLAC, MP3 via cl-mixed backends)
+- Professional audio processing with crossfading and ReplayGain normalization
- Crossfade between tracks (3s overlap, configurable fade-in/fade-out)
+- Icecast2 streaming server integration
- ICY metadata protocol for now-playing information in media players
+- Liquidsoap audio pipeline for reliable broadcasting
- Burst-on-connect for instant playback start (~4s of buffered audio)
+- Stream queue control for curated programming
 ** CL-Streamer — The Audio Pipeline
 CL-Streamer is Asteroid Radio's own native Common Lisp audio streaming server, written from scratch as part of this project. It provides HTTP audio streaming with ICY metadata, dual-format encoding (MP3 + AAC), and real-time audio processing — replacing what previously required separate Icecast and Liquidsoap Docker containers. It lives in the =cl-streamer/= directory and is loaded as an ASDF system within the Asteroid Radio process. See =cl-streamer/README.org= for full technical details.
 Key components:
 - *streaming-drain* — custom Harmony drain that intercepts mixed audio and feeds it to encoders instead of a sound card
 - *MP3 encoder* — LAME via CFFI (=lame-ffi.lisp=)
 - *AAC encoder* — FDK-AAC via a C shim that avoids SBCL signal handler conflicts (=fdkaac-shim.c=, =fdkaac-ffi.lisp=)
 - *Broadcast buffer* — single-producer multi-consumer ring buffer per mount point; never blocks the encoder
 - *ICY metadata* — SHOUTcast-compatible metadata interleaved in the stream
 - *HTTP server* — usocket-based, serves =/asteroid.mp3= and =/asteroid.aac= directly
 ** Playlist Scheduling
 - Cron-based playlist scheduler with configurable time slots (=playlist-scheduler.lisp=)
 - M3U playlist files with =#EXTINF= metadata (=playlists/= directory)
 - Playback state persistence — saves current track/playlist position to disk (=.playback-state.lisp=)
 - Automatic resume from saved state on restart
 - Sequential playback with crossfade transitions
 ** Music Library Management
 - Database-backed track storage with metadata extraction
- Support for MP3 and FLAC formats (decoded by cl-mixed backends)
+- Support for MP3, FLAC, OGG, and WAV formats
- Automatic metadata extraction using [[https://github.com/psilord/taglib][taglib]] (artist, title, album)
+- Automatic metadata extraction using taglib
 - Track search, filtering, sorting, and pagination
 - Recursive directory scanning
 ** Web Interface
- Radiance framework with CLIP templating
+- RADIANCE framework with CLIP templating
- Admin dashboard with stream status, listener stats, and library management
+- Admin dashboard for library and user management
 - Multiple player modes: inline, pop-out, and persistent frameset
- Live stream integration with embedded HTML5 audio player
+- Live stream integration with embedded player
 - Responsive design for desktop and mobile
 - Role-based access control (Admin/DJ/Listener)
 - ParenScript-generated JavaScript (=parenscript/= directory)
 - LASS-generated CSS (=static/asteroid.lass=)
-** Listener Statistics
+** Network Broadcasting
- In-process listener tracking (no external polling needed)
+- Dynamic stream URL detection for multi-environment support
- Geo IP lookup with caching (=listener-stats.lisp=)
+- Professional streaming URLs for media players
- Per-mount and aggregate listener counts
+- Multi-listener support via Icecast2
- GDPR-compliant IP hashing and data retention
+- Docker-based deployment for easy setup
-* Architecture
+* Architecture Changes
-#+BEGIN_EXAMPLE
+** Framework Migration
-┌──────────────────────────────────────────────────────────────┐
+- Migrated from Hunchentoot to RADIANCE web framework
-│                    SBCL Process                               │
+- Implemented proper domain routing (=/asteroid/=)
-│                                                               │
+- CLIP templating system for dynamic content
-│  ┌───────────┐   ┌──────────────┐   ┌───────────────────┐   │
+- Database abstraction layer for track storage
 │  │ Harmony    │──▶│ streaming-   │──▶│ MP3 Encoder       │   │
 │  │ (decode,   │   │ drain        │   │ (LAME FFI)        │──▶│ /asteroid.mp3
 │  │  crossfade,│   │ (float→s16   │   └───────────────────┘   │
 │  │  mix)      │   │  conversion) │   ┌───────────────────┐   │
 │  └───────────┘   └──────────────┘──▶│ AAC Encoder        │   │
 │       ▲                              │ (FDK-AAC C shim)   │──▶│ /asteroid.aac
 │       │                              └───────────────────┘   │
 │  ┌───────────┐                       ┌───────────────────┐   │
 │  │ Playlist   │   ICY metadata ────▶│ CL-Streamer        │   │
 │  │ Scheduler  │   Listener stats ◀──│ HTTP Server         │   │
 │  │ (cl-cron)  │                      │ (usocket)           │   │
 │  └───────────┘                       └───────────────────┘   │
 │       │                                                       │
 │  ┌───────────┐   ┌──────────────┐   ┌───────────────────┐   │
 │  │ Radiance   │──▶│ Admin        │   │ PostgreSQL         │   │
 │  │ Web Server │   │ Dashboard    │   │ (external)         │   │
 │  │ (port 8080)│   │ + Player UI  │   │                    │   │
 │  └───────────┘   └──────────────┘   └───────────────────┘   │
 └──────────────────────────────────────────────────────────────┘
 #+END_EXAMPLE
-** How Audio Flows
+** Streaming Stack
-
+- *Icecast2*: Streaming server (port 8000) - Docker containerized
-1. *Decode* — Harmony loads a FLAC or MP3 file via cl-mixed-flac or cl-mixed-mpg123
+- *Liquidsoap*: Audio processing and streaming pipeline - Docker containerized
-2. *Mix* — during crossfade, two voices play simultaneously through Harmony's mixer
+- *RADIANCE*: Web server and API (port 8080)
-3. *Drain* — the custom =streaming-drain= reads interleaved float samples from the pack buffer
+- *PostgreSQL*: Database backend (configured, ready for migration)
-4. *Convert* — floats are converted to signed 16-bit PCM via CFFI
+- *Docker Compose*: Container orchestration
 5. *Encode* — PCM is fed to LAME (MP3) and FDK-AAC (AAC) encoders in parallel
 6. *Buffer* — encoded bytes are written to per-mount broadcast ring buffers
 7. *Serve* — HTTP clients read from their position in the ring buffer with ICY metadata interleaving
 ** File Structure
 #+BEGIN_SRC
 asteroid/
-├── asteroid.lisp              # Main server, Radiance routes, API endpoints
+├── asteroid.lisp              # Main server with RADIANCE routes
-├── asteroid.asd               # ASDF system definition
+├── asteroid.asd               # System definition with dependencies
 ├── stream-harmony.lisp        # Harmony/CL-Streamer integration, playback state
 ├── playlist-scheduler.lisp    # Cron-based playlist scheduling
 ├── stream-control.lisp        # Stream queue management
 ├── listener-stats.lisp        # Listener statistics and geo IP
 ├── user-management.lisp       # User administration
 ├── playlist-management.lisp   # Playlist operations
-├── user-playlists.lisp        # User playlist features
+├── test-server.sh             # Automated test suite
-├── user-profile.lisp          # User profile management
+├── docker/                    # Docker infrastructure
-├── track-requests.lisp        # Track request system
+│   ├── docker-compose.yml     # Container orchestration
-├── auth-routes.lisp           # Authentication routes
+│   ├── asteroid-radio-docker.liq  # Liquidsoap config
-├── database.lisp              # Database schema and helpers
+│   ├── icecast.xml            # Icecast configuration
-├── Makefile                   # Build: compiles SBCL image
+│   └── music/                 # Music library mount
 ├── cl-streamer/               # Audio streaming subsystem
 │   ├── cl-streamer.asd        # ASDF system definition
 │   ├── harmony-backend.lisp   # Harmony integration, crossfade, play-list/play-file
 │   ├── stream-server.lisp     # HTTP streaming server (usocket)
 │   ├── buffer.lisp            # Broadcast ring buffer
 │   ├── encoder.lisp           # MP3 encoder (LAME FFI)
 │   ├── aac-encoder.lisp       # AAC encoder with frame accumulation
 │   ├── lame-ffi.lisp          # CFFI bindings for libmp3lame
 │   ├── fdkaac-ffi.lisp        # CFFI bindings for FDK-AAC (via shim)
 │   ├── fdkaac-shim.c          # C shim for FDK-AAC (avoids SBCL signal conflicts)
 │   ├── libfdkaac-shim.so      # Compiled shim shared library
 │   ├── icy-protocol.lisp      # ICY metadata encoding
 │   └── README.org             # Full CL-Streamer documentation
 ├── playlists/                 # M3U playlist files for the scheduler
 ├── template/                  # CLIP HTML templates
-├── parenscript/               # ParenScript JavaScript sources
+│   ├── front-page.ctml        # Main page with live stream
-├── static/                    # CSS (LASS) and assets
+│   ├── admin.ctml             # Admin dashboard
-├── migrations/                # PostgreSQL schema migrations
+│   ├── player.ctml            # Web player interface
-├── docker/                    # Docker config (PostgreSQL only)
+│   └── users.ctml             # User management
 ├── static/                    # CSS and assets
 │   └── asteroid.lass          # LASS stylesheet
 ├── docs/                      # Comprehensive documentation
-└── music/                     # Music library symlink
+│   ├── README.org             # Documentation index
 │   ├── PROJECT-OVERVIEW.org   # Architecture overview
 │   ├── PROJECT-HISTORY.org    # Development timeline
 │   ├── INSTALLATION.org       # Setup guide
 │   └── ...                    # Additional guides
 └── music/                     # Music library (local dev)
 #+END_SRC
 * Quick Start
-** Prerequisites
+** Docker Installation (Recommended)
 - *SBCL* — Steel Bank Common Lisp
 - *Quicklisp* — with Ultralisp distribution (for Harmony, cl-mixed)
 - *PostgreSQL* — running instance (Docker or native)
 - *System libraries*: =libmp3lame=, =libfdk-aac=, =libflac=, =libmpg123=, =libtagc=
 ** Building the FDK-AAC Shim
 CL-Streamer uses a thin C shim to call FDK-AAC, avoiding SBCL signal handler conflicts that cause recursive SIGSEGV when calling FDK-AAC directly via CFFI. The compiled =libfdkaac-shim.so= is included in the repository, but if you need to rebuild it (e.g. after updating =libfdk-aac=):
 #+BEGIN_SRC bash
 cd cl-streamer
 gcc -shared -fPIC -o libfdkaac-shim.so fdkaac-shim.c -lfdk-aac
 #+END_SRC
 The shim is loaded automatically at ASDF system load time from the =cl-streamer/= directory — no installation or =LD_LIBRARY_PATH= configuration needed.
 ** Build and Run
 #+BEGIN_SRC bash
 # Clone repository
 git clone https://github.com/fade/asteroid
-cd asteroid
+cd asteroid/docker
-# Start PostgreSQL (if using Docker)
+# Start all services
-cd docker && docker compose up -d postgres && cd ..
+docker compose up -d
-# Build the SBCL image
+# Verify streams are working
-make
+curl -I http://localhost:8000/asteroid.mp3
-
+curl -I http://localhost:8000/asteroid.aac
-# Run (set ASTEROID_STREAM_URL to the stream server address)
+curl -I http://localhost:8000/asteroid-low.mp3
 ASTEROID_STREAM_URL=http://localhost:8000 ./asteroid
 #+END_SRC
 On startup, Asteroid will:
 1. Start the Radiance web server on port 8080
 2. Start the CL-Streamer HTTP server on port 8000
 3. Initialise the Harmony audio pipeline with MP3 + AAC encoders
 4. Connect to PostgreSQL and load the playlist schedule
 5. Resume playback from saved state (if =.playback-state.lisp= exists)
 6. Begin streaming audio on =/asteroid.mp3= and =/asteroid.aac=
 ** Access Points
 - *Web Interface*: http://localhost:8080/
 - *Admin Panel*: http://localhost:8080/admin
- *MP3 Stream*: http://localhost:8000/asteroid.mp3 (128kbps)
+- *High Quality MP3*: http://localhost:8000/asteroid.mp3 (128kbps)
- *AAC Stream*: http://localhost:8000/asteroid.aac (128kbps)
+- *High Quality AAC*: http://localhost:8000/asteroid.aac (96kbps)
-
+- *Low Quality MP3*: http://localhost:8000/asteroid-low.mp3 (64kbps)
-* Playlist Scheduling
+- *Icecast Admin*: http://localhost:8000/admin/ (admin/asteroid_admin_2024)
 Playlists are M3U files in the =playlists/= directory. The scheduler (=playlist-scheduler.lisp=) uses =cl-cron= to switch playlists at configured times.
 ** Schedule Configuration
 The schedule is stored in the database and loaded on startup. Example schedule:
 | Time (UTC) | Playlist               | Description                    |
 |------------+------------------------+--------------------------------|
 | 00:00      | midnight-ambient.m3u   | Deep, dark ambient             |
 | 06:00      | morning-drift.m3u      | Lighter, awakening ambient     |
 | 12:00      | afternoon-orbit.m3u    | Mid-energy floating ambient    |
 | 13:00      | underworld-and-friends | Techno, electro, progressive   |
 | 18:00      | evening-descent.m3u    | Winding down transitional      |
 ** M3U Format
 Playlists use =#EXTINF= metadata and =/app/music/= prefixed paths (rewritten to local library path at load time):
 #+BEGIN_SRC
 #EXTM3U
 #PLAYLIST:Underworld & Friends
 #EXTINF:-1,Underworld - Born Slippy (Nuxx)
 /app/music/Underworld - Second Toughest In The Infants (flac)/Second Toughest In The Infants (CD2)/01 Born Slippy (Nuxx).flac
 #EXTINF:-1,Orbital - Halcyon + On + On
 /app/music/Orbital/1993 - Orbital - Orbital 2 (Brown Album - TRUCD2, 828 386.2)/00. Halcyon + On + On.mp3
 #+END_SRC
 ** Playback State Persistence
 The current track and playlist position are saved to =.playback-state.lisp= periodically. On restart, playback resumes from the saved position rather than restarting the playlist from the beginning.
 * Music Library Management
 ** Adding Music
-1. Place MP3/FLAC files in the music library directory (symlinked from =music/library/=)
+1. *Copy files*: Place MP3/FLAC files in =docker/music/= directory
-2. Navigate to the admin panel at =http://localhost:8080/admin=
+2. *Access admin panel*: Navigate to =http://localhost:8080/admin=
-3. Click "Scan Library" to index new tracks
+3. *Scan library*: Click "Scan Library" to index new tracks
-4. Metadata (artist, title, album) is automatically extracted via taglib
+4. *Metadata extraction*: Track information automatically extracted
 5. *Stream queue*: Optionally add tracks to broadcast queue
 ** Library Scanning
 1. Recursive directory scanning of music folder
 2. Metadata extracted using taglib (title, artist, album, duration)
 3. Database records created with file paths and metadata
 4. Tracks immediately available for playback and streaming
 5. Supports nested folder structures
 ** Supported Formats
- *FLAC* — decoded by cl-mixed-flac (via libflac)
+- *MP3*: Primary format, best compatibility
- *MP3* — decoded by cl-mixed-mpg123 (via libmpg123)
+- *FLAC*: Lossless audio, high quality
 - *OGG*: Open source format
 - *WAV*: Uncompressed audio
-** Path Mapping
+* Icecast2 Integration
-In Docker deployments, music paths use =/app/music/= prefix. In local development, =music/library/= is a symlink to the actual music directory. The M3U playlist loader rewrites paths accordingly.
+
 ** Configuration
 - *Server*: localhost:8000 (Docker container)
 - *Mount points*: =/asteroid.mp3=, =/asteroid.aac=, =/asteroid-low.mp3=
 - *Password*: =H1tn31EhsyLrfRmo= (configured in Docker setup)
 - *Formats*: MP3 128kbps, AAC 96kbps, MP3 64kbps
 ** Docker Setup
 Icecast2 runs in a Docker container - no manual installation needed.
 #+BEGIN_SRC bash
 # Managed via docker-compose
 cd docker
 docker compose up -d icecast
 #+END_SRC
 ** Stream Access
 - *High Quality MP3*: =http://localhost:8000/asteroid.mp3= (128kbps)
 - *High Quality AAC*: =http://localhost:8000/asteroid.aac= (96kbps)
 - *Low Quality MP3*: =http://localhost:8000/asteroid-low.mp3= (64kbps)
 - *Admin interface*: =http://localhost:8000/admin/= (admin/asteroid_admin_2024)
 - *Statistics*: =http://localhost:8000/status.xsl=
 * Liquidsoap Integration
 ** Docker Configuration
 Liquidsoap runs in a Docker container with configuration in =docker/asteroid-radio-docker.liq=
 ** Key Features
 - *Multiple outputs*: Generates 3 simultaneous streams (MP3 128k, AAC 96k, MP3 64k)
 - *Audio processing*: Crossfading, normalization, ReplayGain
 - *Stream queue*: Reads from M3U playlist for curated programming
 - *Telnet control*: Remote control interface on port 1234
 - *Metadata*: Broadcasts track information to listeners
 ** Management
 #+BEGIN_SRC bash
 # Start Liquidsoap container
 cd docker
 docker compose up -d liquidsoap
 # View logs
 docker compose logs -f liquidsoap
 # Restart streaming
 docker compose restart liquidsoap
 #+END_SRC
 ** Telnet Control
 #+BEGIN_SRC bash
 # Connect to Liquidsoap
 telnet localhost 1234
 # Or use netcat for scripting
 echo "request.queue" | nc localhost 1234
 echo "request.skip" | nc localhost 1234
 #+END_SRC
 * User Management
 ** Roles
- *Admin*: Full system access, user management, stream control, skip tracks
+- *Admin*: Full system access, user management, stream control
 - *DJ*: Content management, playlist creation, library access
 - *Listener*: Basic playback and personal playlists
@ -247,15 +204,23 @@ In Docker deployments, music paths use =/app/music/= prefix. In local developmen
 - Password: =asteroid123=
 - ⚠️ Change default password after first login
 ** User Administration
 - Create/manage users via admin panel
 - Role-based access control
 - User profiles and preferences
 - Session management
 * Player Modes
 ** Inline Player
 - Embedded in web pages
- HTML5 audio with stream auto-reconnect
+- Standard HTML5 audio controls
 - Queue management
 ** Pop-Out Player
 - Standalone player window
 - Independent from main browser window
 - Persistent across page navigation
 ** Frameset Player
 - Bottom-frame persistent player
@ -264,16 +229,25 @@ In Docker deployments, music paths use =/app/music/= prefix. In local developmen
 * API Endpoints
-** Status & Streaming
+Asteroid Radio provides a comprehensive REST API with 90+ endpoints.
 ** Status & Authentication
 - =GET /api/asteroid/status= - Server status
- =GET /api/asteroid/icecast-status= - Stream status (now-playing, listeners; name kept for frontend compatibility)
+- =GET /api/asteroid/auth-status= - Authentication status
- =POST /api/asteroid/stream/skip= - Skip current track (admin)
+- =GET /api/asteroid/icecast-status= - Streaming status
 ** Track Management
 - =GET /api/asteroid/tracks= - List all tracks
 - =GET /api/asteroid/admin/tracks= - Admin track listing
 - =POST /api/asteroid/admin/scan-library= - Scan music library
 ** Player Control
 - =GET /api/asteroid/player/status= - Player status
 - =POST /api/asteroid/player/play= - Play track
 - =POST /api/asteroid/player/pause= - Pause playback
 - =POST /api/asteroid/player/stop= - Stop playback
 - =POST /api/asteroid/player/resume= - Resume playback
 ** Playlist Management
 - =GET /api/asteroid/playlists= - List user playlists
 - =POST /api/asteroid/playlists/create= - Create playlist
@ -290,52 +264,49 @@ See =docs/API-ENDPOINTS.org= for complete API documentation.
 * Database
-** PostgreSQL
+** Current: Radiance DB
- Primary database for tracks, users, playlists, sessions, schedule, listener stats
+- File-based database abstraction
- Docker container or native installation
+- Tracks, users, playlists, sessions
- Schema managed via migrations in =migrations/= directory
+- Suitable for development and small deployments
- Connection configured in =config/radiance-postgres.lisp=
+
- See =docs/POSTGRESQL-SETUP.org= for setup details
+** PostgreSQL (Configured)
 - Docker container ready
 - Full schema defined
 - Migration pending
 - See =docs/POSTGRESQL-SETUP.org= for details
 * Documentation
 Comprehensive documentation available in the =docs/= directory:
 - *README.org* - Documentation index
 - *PROJECT-OVERVIEW.org* - Architecture and features
 - *PROJECT-HISTORY.org* - Development timeline and milestones
 - *INSTALLATION.org* - Complete installation guide
 - *DEVELOPMENT.org* - Developer setup and guidelines
 - *DOCKER-STREAMING.org* - Docker streaming infrastructure
 - *API-ENDPOINTS.org* - REST API reference
 - *STREAM-CONTROL.org* - Stream queue management
 - *USER-MANAGEMENT-SYSTEM.org* - User administration
 - *PLAYLIST-SYSTEM.org* - Playlist functionality
 - *TESTING.org* - Automated testing guide
 - *POSTGRESQL-SETUP.org* - Database setup
 * Dependencies
 ** Lisp Dependencies
 - =radiance= - Web framework
 - =harmony= - Audio framework (decode, mix, effects)
 - =cl-mixed= / =cl-mixed-flac= / =cl-mixed-mpg123= - Low-level audio mixing and decoding
 - =r-clip= - CLIP templating
 - =lass= - CSS preprocessing
 - =parenscript= - Lisp-to-JavaScript compiler
 - =cl-json= - JSON handling
 - =alexandria= - Common Lisp utilities
 - =bordeaux-threads= - Portable threading
 - =local-time= - Time handling
 - =taglib= - Audio metadata extraction
 - =cl-cron= - Cron-style job scheduling
 - =cffi= - C foreign function interface
 - =usocket= - Socket networking
 - =i-postmodern= - PostgreSQL interface (Radiance)
 - =ironclad= - Cryptographic hashing (passwords, IP hashing)
 - =log4cl= - Logging
 - =slynk= - Sly/SLIME interactive development
-** System Libraries
+** System Dependencies (Docker)
- =libmp3lame= - MP3 encoding (LAME)
+- Docker Engine 20.10+
- =libfdk-aac= - AAC encoding (FDK-AAC, accessed via C shim)
+- Docker Compose 2.0+
- =libflac= - FLAC decoding
+- All streaming components containerized
 - =libmpg123= - MP3 decoding
 - =libtagc= - Audio metadata reading (taglib C bindings)
 ** Infrastructure
 - *PostgreSQL* - only external service required
 - *Docker* - optional, for running PostgreSQL
 * Resource Usage
 Running on a single SBCL process:
 - *RAM*: ~320MB RSS (real-time audio decode + dual MP3/AAC encode)
 - *CPU*: ~8% total (Harmony thread is ~5%)
 - *Threads*: ~18
 * Testing
@ -365,9 +336,6 @@ Running on a single SBCL process:
 4. Run test suite
 5. Submit pull request
 ** Interactive Development
 Asteroid starts a Slynk server on port 4009. Connect from Emacs/Sly for live REPL access to the running system — inspect streams, modify playlists, debug audio issues without restarting.
 ** Community
 - *IRC*: #asteroid.music on irc.libera.chat
 - *Issues*: GitHub issue tracker
@ -380,45 +348,32 @@ Asteroid starts a Slynk server on port 4009. Connect from Emacs/Sly for live REP
 * Troubleshooting
-** Stream Not Playing
+** Docker Issues
- Check that the process is running and CL-Streamer started (look for "CL-Streamer started on port 8000" in logs)
+#+BEGIN_SRC bash
- Test stream URLs: =curl -I http://localhost:8000/asteroid.mp3=
+# Check container status
- Check for audio file errors in the log (missing files, unsupported formats)
+docker compose ps
 - Verify music library symlink: =ls -la music/library/=
-** SBCL Pathname Issues
+# View logs
-File paths containing square brackets (e.g. =[WEB FLAC]=) can cause =SIMPLE-ARRAY CHARACTER= errors because SBCL's =pathname= function interprets brackets as wildcard patterns. CL-Streamer uses =sb-ext:parse-native-namestring= to avoid this.
+docker compose logs icecast
 docker compose logs liquidsoap
 # Restart services
 docker compose restart
 #+END_SRC
 ** Stream Not Playing
 - Verify containers are running
 - Check music files exist in =docker/music/=
 - Test stream URLs with curl
 - Review Liquidsoap logs
 ** Database Issues
- Check PostgreSQL is running: =docker compose ps= (if using Docker)
+- Check Radiance DB file permissions
- Verify connection in =config/radiance-postgres.lisp=
+- Verify database collections exist
- Review application logs for connection errors
+- Review application logs
 ** Playback State
 - Saved to =.playback-state.lisp= in the project root
 - Delete this file to force a fresh start from the scheduled playlist
 - Check logs for "Resuming after track..." on startup
 For detailed troubleshooting, see documentation in =docs/= directory.
 * Documentation
 Comprehensive documentation available in the =docs/= directory:
 - *README.org* - Documentation index
 - *PROJECT-OVERVIEW.org* - Architecture and features
 - *PROJECT-HISTORY.org* - Development timeline and milestones
 - *INSTALLATION.org* - Complete installation guide
 - *DEVELOPMENT.org* - Developer setup and guidelines
 - *API-ENDPOINTS.org* - REST API reference
 - *STREAM-CONTROL.org* - Stream queue management
 - *USER-MANAGEMENT-SYSTEM.org* - User administration
 - *PLAYLIST-SYSTEM.org* - Playlist functionality
 - *TESTING.org* - Automated testing guide
 - *POSTGRESQL-SETUP.org* - Database setup
 See also =cl-streamer/README.org= for CL-Streamer technical documentation.
 * License
 See LICENSE file for details.
@ -426,14 +381,13 @@ See LICENSE file for details.
 * Acknowledgments
 Built with:
- [[https://www.sbcl.org/][SBCL]] (Steel Bank Common Lisp)
+- Common Lisp (SBCL)
- [[https://shirakumo.github.io/radiance/][Radiance]] web framework (Shinmera)
+- Radiance web framework
- [[https://shirakumo.github.io/harmony/][Harmony]] audio framework (Shinmera)
+- Icecast2 streaming server
- [[https://shirakumo.github.io/cl-mixed/][cl-mixed]] audio mixing library (Shinmera)
+- Liquidsoap audio processing
- [[https://lame.sourceforge.io/][LAME]] MP3 encoder
+- Docker containerization
 - [[https://github.com/mstorsjo/fdk-aac][FDK-AAC]] AAC encoder
-Special thanks to Yukari Hafner (Shinmera) for Harmony, cl-mixed, and Radiance, and to the Common Lisp community.
+Special thanks to all contributors and the Common Lisp community.
 * Credits
@ -442,4 +396,4 @@ Special thanks to Yukari Hafner (Shinmera) for Harmony, cl-mixed, and Radiance,
 ---
-*Last Updated: 2026-03-05*
+*Last Updated: 2026-01-26*
--- a/playlists/afternoon-orbit.m3u
+++ b/playlists/afternoon-orbit.m3u
@ -6,7 +6,7 @@
 #DESCRIPTION:Mid-energy floating ambient for the afternoon hours (12:00-18:00)
 #EXTINF:-1,Boards of Canada - Kid for Today
-/app/music/Boards of Canada/In a Beautiful Place Out in the Country/01 - Kid for Today.mp3
+/app/music/Boards of Canada/In a Beautiful Place Out in the Country/01 Kid for Today.flac
 #EXTINF:-1,Orbital - Halcyon + On + On
 /app/music/Orbital/1993 - Orbital - Orbital 2 (Brown Album - TRUCD2, 828 386.2)/00. Halcyon + On + On.mp3
 #EXTINF:-1,Four Tet - Parallel 1
@ -18,23 +18,23 @@
 #EXTINF:-1,Plaid - Sun Electric - Tee (Plaid Mix)
 /app/music/Plaid - Stem Sell (Plaid Remixes) [2021] (WEB - FLAC - Lossless)/17-Sun_Electric-Tee_(Plaid_Mix).flac
 #EXTINF:-1,The Orb - Little Fluffy Clouds
-/app/music/The Orb/1991 - The Orb's Adventures Beyond the Ultraworld (Double Album)/01 Little Fluffy Clouds.mp3
+/app/music/The Orb/1991 - The Orb's Adventures Beyond the Ultraworld (Double Album)/05 Little Fluffy Clouds.flac
 #EXTINF:-1,Labradford - S
 /app/music/Labradford/1997 - Mi Media Naranja/1 S.flac
-#EXTINF:-1,Drexciya - Bubble Chamber
+#EXTINF:-1,Drexciya - Bubble Metropolis
-/app/music/Drexciya/2013 - Journey Of The Deep Sea Dweller III/12. Drexciya - Bubble Chamber.mp3
+/app/music/Drexciya/2013 - Journey Of The Deep Sea Dweller III/01 Bubble Metropolis.flac
 #EXTINF:-1,Clark - Spring But Dark
 /app/music/Clark - Death Peak (2017) [FLAC]/01 - Spring But Dark.flac
 #EXTINF:-1,Tycho - Rings
 /app/music/Tycho - Epoch (Deluxe Version) (2019) [WEB FLAC16-44.1]/09 - Rings.flac
 #EXTINF:-1,Boards of Canada - Amo Bishop Roden
-/app/music/Boards of Canada/In a Beautiful Place Out in the Country/02 - Amo Bishop Roden.mp3
+/app/music/Boards of Canada/In a Beautiful Place Out in the Country/02 Amo Bishop Roden.flac
 #EXTINF:-1,FSOL - Sol 7
 /app/music/The Future Sound of London - Environment Six (2016 - WEB - FLAC)/07 - Sol 7.flac
 #EXTINF:-1,Aphex Twin - CHEETAHT7b
 /app/music/Aphex Twin (2016) Cheetah EP [WEB] [FLAC]/Cheetah EP-002-Aphex Twin-CHEETAHT7b.flac
 #EXTINF:-1,Model 500 - Digital Solutions
-/app/music/Model 500/2015 - Digital Solutions/08-model_500-digital_solutions.flac
+/app/music/Model 500/2015 - Digital Solutions/01 Digital Solutions.flac
 #EXTINF:-1,Proem - Winter Wolves
 /app/music/Proem - 2018 Modern Rope (WEB)/01. Winter Wolves.flac
 #EXTINF:-1,Four Tet - Parallel 8
@ -46,7 +46,7 @@
 #EXTINF:-1,Kiasmos - Thrown
 /app/music/Kiasmos/2014 - Kiasmos/05 - Thrown.flac
 #EXTINF:-1,The Orb - Supernova at the End of the Universe
-/app/music/The Orb/1991 - The Orb's Adventures Beyond the Ultraworld (Double Album)/03 Supernova at the End of the Universe.mp3
+/app/music/The Orb/1991 - The Orb's Adventures Beyond the Ultraworld (Double Album)/08 Supernova at the End of the Universe.flac
 #EXTINF:-1,arovane - komposition no. 1
 /app/music/arovane - Wirkung (2020) [WEB FLAC16]/17. arovane - komposition no. 1.flac
 #EXTINF:-1,Orbital - Lush 3-1
@ -56,11 +56,11 @@
 #EXTINF:-1,Clark - Absence (Bibio Remix)
 /app/music/Clark - Feast Beast (2013) [24 Bit WEB FLAC] [16-44]/1.12. Clark - Absence (Bibio Remix).flac
 #EXTINF:-1,Drexciya - Aqua Worm Hole
-/app/music/Drexciya/2013 - Journey Of The Deep Sea Dweller III/11. Drexciya - Aqua Worm Hole.mp3
+/app/music/Drexciya/2013 - Journey Of The Deep Sea Dweller III/03 Aqua Worm Hole.flac
 #EXTINF:-1,FSOL - Electric Pastrol
 /app/music/The Future Sound of London - Environment Six (2016 - WEB - FLAC)/16 - Electric Pastrol.flac
 #EXTINF:-1,Vector Lovers - Capsule For One
-/app/music/Vector Lovers/2005 - Capsule For One/11 - Capsule For One.mp3
+/app/music/Vector Lovers/2005 - Capsule For One/01 - Capsule For One.flac
 #EXTINF:-1,Plaid - Ricardo Tobar - After The Movie (Plaid Remix)
 /app/music/Plaid - Stem Sell (Plaid Remixes) [2021] (WEB - FLAC - Lossless)/21-Ricardo_Tobar-After_The_Movie_(Plaid_Remix).flac
 #EXTINF:-1,Aphex Twin - CHEETA2 ms800
@ -74,6 +74,6 @@
 #EXTINF:-1,FSOL - Beyond the Field of Vision
 /app/music/The Future Sound of London - Environment Six (2016 - WEB - FLAC)/19 - Beyond the Field of Vision.flac
 #EXTINF:-1,Underworld - Cowgirl
-/app/music/Underworld - Second Toughest In The Infants (flac)/Second Toughest In The Infants (CD1)/01 Juanita , Kiteless , To Dream Of Love.flac
+/app/music/Underworld - Second Toughest In The Infants (flac)/01 - Juanita - Kiteless - To Dream Of Love.flac
 #EXTINF:-1,Underworld - Everything, Everything
 /app/music/Underworld - Everything, Everything (2000 - CD - FLAC)/01 - Juanita-Kiteless.flac
--- a/playlists/evening-descent.m3u
+++ b/playlists/evening-descent.m3u
@ -50,7 +50,7 @@
 #EXTINF:-1,Kiasmos - Burnt
 /app/music/Kiasmos/2014 - Kiasmos/08 - Burnt.flac
 #EXTINF:-1,Johann Johannsson - The Theory of Everything
-/app/music/Johann Johannsson - The Theory of Everything (2014) [FLAC]/24 - The Theory Of Everything.flac
+/app/music/Johann Johannsson - The Theory of Everything (2014) [FLAC]/24 - The Theory of Everything.flac
 #EXTINF:-1,Tangerine Dream - Pantha Rhei
 /app/music/Tangerine Dream - Ambient Monkeys (flac)/11 Tangerine Dream - Pantha Rhei.flac
 #EXTINF:-1,Biosphere - Stordjupta
@ -62,7 +62,7 @@
 #EXTINF:-1,Proem - Kids That Hate Live Things
 /app/music/Proem - Until Here for Years (n5md, 2019) flac/11 - Kids That Hate Live Things.flac
 #EXTINF:-1,Brian Eno - I'm Hardly Me
-/app/music/Brian Eno/2022 - ForeverAndEverNoMore/08 I’m Hardly Me.flac
+/app/music/Brian Eno/2022 - ForeverAndEverNoMore/08 I'm Hardly Me.flac
 #EXTINF:-1,Labradford - P
 /app/music/Labradford/1997 - Mi Media Naranja/7 P.flac
 #EXTINF:-1,Tim Hecker - Starting Over Again
@ -78,4 +78,4 @@
 #EXTINF:-1,Biosphere - Tomorrow Then We Will Attend
 /app/music/Biosphere - Departed Glories (2016) - FLAC WEB/15 - Tomorrow Then We Will Attend.flac
 #EXTINF:-1,Tape Loop Orchestra - The Word On My Lips Is Your Name
-/app/music/Tape Loop Orchestra/2012 - The Word On My Lips Is Your Name/Disc 1 - The Word On My Lips Is Your Name/01 - The Word On My Lips Is Your Name.flac
+/app/music/Tape Loop Orchestra/2012 - The Word On My Lips Is Your Name/01 - The Word On My Lips Is Your Name.flac
--- a/playlists/midnight-ambient.m3u
+++ b/playlists/midnight-ambient.m3u
@ -51,8 +51,8 @@
 /app/music/Pye Corner Audio/2019 - Hollow Earth (WEB, #GBX032 DL)/09 - Subterranean Lakes.mp3
 #EXTINF:-1,Labradford - WR
 /app/music/Labradford/1997 - Mi Media Naranja/3 WR.flac
-#EXTINF:-1,Bark Psychosis - The Loom
+#EXTINF:-1,Bark Psychosis - Hex
-/app/music/Bark Psychosis/1994 - Hex/01 - bark psychosis - the loom.mp3
+/app/music/Bark Psychosis/1994 - Hex/01 The Loom.flac
 #EXTINF:-1,Biosphere - Turned To Stone
 /app/music/Biosphere - The Petrified Forest (2017) - CD FLAC/03. Biosphere - Turned To Stone.flac
 #EXTINF:-1,Tim Hecker - Winter's Coming
@ -79,7 +79,7 @@
 /app/music/Tim Hecker - The North Water Original Score (2021 - WEB - FLAC)/Tim Hecker - The North Water (Original Score) - 14 Twinkle In The Wasteland.flac
 #EXTINF:-1,Locrian - Heavy Water
 /app/music/Locrian - Infinite Dissolution (2015) - WEB FLAC/08 - Heavy Water.flac
-#EXTINF:-1,Tape Loop Orchestra - Reel One
+#EXTINF:-1,Tape Loop Orchestra - 1953 Culture Festival
-/app/music/Tape Loop Orchestra/2009 - 1953 Culture Festival/01 Tape Loop Orchestra - Chapter 1   Reel One.mp3
+/app/music/Tape Loop Orchestra/2009 - 1953 Culture Festival/01 - 1953 Culture Festival.flac
 #EXTINF:-1,Underworld - Everything, Everything
 /app/music/Underworld - Everything, Everything (2000 - CD - FLAC)/01 - Juanita-Kiteless.flac
--- a/playlists/morning-drift.m3u
+++ b/playlists/morning-drift.m3u
@ -71,8 +71,8 @@
 /app/music/The Future Sound of London - Environment Six (2016 - WEB - FLAC)/15 - Imagined Friends.flac
 #EXTINF:-1,Biosphere - Lysbotn
 /app/music/Biosphere - The Senja Recordings (2019) [FLAC]/11 - Lysbotn.flac
-#EXTINF:-1,Boards of Canada - Kid for Today
+#EXTINF:-1,Boards of Canada - In a Beautiful Place Out in the Country
-/app/music/Boards of Canada/In a Beautiful Place Out in the Country/01 - Kid for Today.mp3
+/app/music/Boards of Canada/In a Beautiful Place Out in the Country/01 Kid for Today.flac
 #EXTINF:-1,Brian Eno - Making Gardens Out of Silence
 /app/music/Brian Eno/2022 - ForeverAndEverNoMore/10 Making Gardens Out of Silence.flac
 #EXTINF:-1,Tangerine Dream - Virtue Is Its Own Reward
--- a/playlists/underworld-and-friends.m3u
+++ b/playlists/underworld-and-friends.m3u
@ -23,8 +23,8 @@
 /app/music/The Other People Place/2017 - Lifestyles Of The Laptop Café/A1 - Eye Contact.flac
 #EXTINF:-1,Boxcutter - Arecibo Message
 /app/music/Boxcutter - Arecibo Message (2009) [FLAC]/03 - Boxcutter - Arecibo Message.flac
-#EXTINF:-1,Drexciya - Bubble Chamber
+#EXTINF:-1,Drexciya - Bubble Metropolis
-/app/music/Drexciya/2013 - Journey Of The Deep Sea Dweller III/12. Drexciya - Bubble Chamber.mp3
+/app/music/Drexciya/2013 - Journey Of The Deep Sea Dweller III/01 Bubble Metropolis.flac
 #EXTINF:-1,Orbital - Monsters Exist
 /app/music/Orbital - Monsters Exist (PledgeMusic Deluxe) (2018) (WEB) [FLAC]/01 - Monsters Exist.flac
 #EXTINF:-1,Underworld - Push Upstairs
@ -44,7 +44,7 @@
 #EXTINF:-1,The Other People Place - Moonlight Rendezvous
 /app/music/The Other People Place/2017 - Lifestyles Of The Laptop Café/B1 - Moonlight Rendezvous.flac
 #EXTINF:-1,Model 500 - Digital Solutions
-/app/music/Model 500/2015 - Digital Solutions/08-model_500-digital_solutions.flac
+/app/music/Model 500/2015 - Digital Solutions/01 Digital Solutions.flac
 #EXTINF:-1,Orbital - P.H.U.K
 /app/music/Orbital - Monsters Exist (PledgeMusic Deluxe) (2018) (WEB) [FLAC]/04 - P.H.U.K.flac
 #EXTINF:-1,Underworld - Pearls Girl
@ -56,7 +56,7 @@
 #EXTINF:-1,Boxcutter - SpaceBass
 /app/music/Boxcutter - Arecibo Message (2009) [FLAC]/04 - Boxcutter - SpaceBass.flac
 #EXTINF:-1,Drexciya - Aqua Worm Hole
-/app/music/Drexciya/2013 - Journey Of The Deep Sea Dweller III/11. Drexciya - Aqua Worm Hole.mp3
+/app/music/Drexciya/2013 - Journey Of The Deep Sea Dweller III/03 Aqua Worm Hole.flac
 #EXTINF:-1,Dopplereffekt - Mandelbrot Set
 /app/music/Dopplereffekt/2017 - Cellular Automata/07. Mandelbrot Set.flac
 #EXTINF:-1,Underworld - Cups