glenn
/
asteroid
mirror of https://github.com/glenneth1/asteroid.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: Comprehensive documentation update for October 2025 

- Created PROJECT-HISTORY.org with complete development timeline
- Updated all documentation dates to 2025-10-26
- Added current features: multiple player modes, stream queue control, dynamic URLs
- Updated repository URLs from placeholders to actual GitHub links
- Refreshed feature lists across all docs to reflect current state
- Added PostgreSQL status (configured, ready for migration)
- Updated root README.org with comprehensive current information
- Improved quick start guides and access points
- Enhanced API documentation with complete endpoint list
- Updated all streaming documentation for Docker setup
- Standardized author attribution across all docs
- Incremented docs version to 3.0

All documentation now accurately reflects the current state of the project
with 205+ commits, 3 core contributors, and 2.5 months of active development.
This commit is contained in:
Glenn Thompson 2025-10-26 09:19:21 +03:00 committed by Brian O'Reilly
parent a458a85823
commit f1eb43b325
15 changed files with 682 additions and 237 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

491
README.org
View File

@ -1,35 +1,45 @@
#+TITLE: Asteroid Radio - Internet Streaming Implementation #+TITLE: Asteroid Radio - Internet Radio Streaming Platform
#+AUTHOR: Database Implementation Branch #+AUTHOR: Asteroid Radio Development Team
#+DATE: 2025-09-11 #+DATE: 2025-10-26
* Overview * Overview
This branch implements a complete internet radio streaming system for Asteroid Radio, transforming it from a simple web interface into a fully functional streaming radio station with live broadcasting capabilities. 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.
** Project Links
- *Repository*: https://github.com/fade/asteroid
- *IRC*: #asteroid.music on irc.libera.chat
- *Documentation*: See =docs/= directory for comprehensive guides
* Key Features * Key Features
** Live Internet Radio Streaming ** Live Internet Radio Streaming
- Continuous MP3 streaming at 128kbps stereo - Multiple quality streams: 128kbps MP3, 96kbps AAC, 64kbps MP3
- Professional audio processing with crossfading and normalization - Professional audio processing with crossfading and ReplayGain normalization
- Icecast2 streaming server integration - Icecast2 streaming server integration
- Liquidsoap audio pipeline for reliable broadcasting - Liquidsoap audio pipeline for reliable broadcasting
- Stream queue control for curated programming
** Music Library Management ** Music Library Management
- Database-backed track storage with metadata extraction - Database-backed track storage with metadata extraction
- Support for MP3, FLAC, OGG, and WAV formats - Support for MP3, FLAC, OGG, and WAV formats
- Automatic metadata extraction using taglib - Automatic metadata extraction using taglib
- Track search, filtering, and sorting capabilities - Track search, filtering, sorting, and pagination
- Recursive directory scanning
** Web Interface ** Web Interface
- RADIANCE framework with CLIP templating - RADIANCE framework with CLIP templating
- Admin dashboard for library management - Admin dashboard for library and user management
- Web player with HTML5 audio controls - Multiple player modes: inline, pop-out, and persistent frameset
- Live stream integration with embedded player - Live stream integration with embedded player
- Responsive design for desktop and mobile
- Role-based access control (Admin/DJ/Listener)
** Network Broadcasting ** Network Broadcasting
- WSL-compatible networking for internal network access - Dynamic stream URL detection for multi-environment support
- Professional streaming URLs for media players - Professional streaming URLs for media players
- Multi-listener support via Icecast2 - Multi-listener support via Icecast2
- Docker-based deployment for easy setup
* Architecture Changes * Architecture Changes
@ -40,46 +50,82 @@ This branch implements a complete internet radio streaming system for Asteroid R
- Database abstraction layer for track storage - Database abstraction layer for track storage
** Streaming Stack ** Streaming Stack
- *Icecast2*: Streaming server (port 8000) - *Icecast2*: Streaming server (port 8000) - Docker containerized
- *Liquidsoap*: Audio processing and streaming pipeline - *Liquidsoap*: Audio processing and streaming pipeline - Docker containerized
- *RADIANCE*: Web server and API (port 8080) - *RADIANCE*: Web server and API (port 8080)
- *Database*: Track metadata and playlist storage - *PostgreSQL*: Database backend (configured, ready for migration)
- *Docker Compose*: Container orchestration
** File Structure ** File Structure
#+BEGIN_SRC #+BEGIN_SRC
asteroid/ asteroid/
├── asteroid.lisp # Main server with RADIANCE routes ├── asteroid.lisp # Main server with RADIANCE routes
├── asteroid.asd # System definition with dependencies ├── asteroid.asd # System definition with dependencies
├── asteroid-radio.liq # Liquidsoap streaming configuration ├── stream-control.lisp # Stream queue management
├── playlist.m3u # Generated playlist for streaming ├── user-management.lisp # User administration
├── start-asteroid-radio.sh # Launch script for all services ├── playlist-management.lisp # Playlist operations
├── stop-asteroid-radio.sh # Stop script for all services ├── test-server.sh # Automated test suite
├── docker/ # Docker infrastructure
│ ├── docker-compose.yml # Container orchestration
│ ├── asteroid-radio-docker.liq # Liquidsoap config
│ ├── icecast.xml # Icecast configuration
│ └── music/ # Music library mount
├── template/ # CLIP HTML templates ├── template/ # CLIP HTML templates
│ ├── front-page.chtml # Main page with live stream │ ├── front-page.chtml # Main page with live stream
│ ├── admin.chtml # Admin dashboard │ ├── admin.chtml # Admin dashboard
│ └── player.chtml # Web player interface │ ├── player.chtml # Web player interface
│ └── users.chtml # User management
├── static/ # CSS and assets ├── static/ # CSS and assets
│ └── asteroid.lass # LASS stylesheet │ └── asteroid.lass # LASS stylesheet
└── music/ # Music library ├── docs/ # Comprehensive documentation
├── incoming/ # Upload staging area │ ├── README.org # Documentation index
└── library/ # Processed music files │ ├── PROJECT-OVERVIEW.org # Architecture overview
│ ├── PROJECT-HISTORY.org # Development timeline
│ ├── INSTALLATION.org # Setup guide
│ └── ... # Additional guides
└── music/ # Music library (local dev)
#+END_SRC #+END_SRC
* Track Upload Workflow * Quick Start
** Current Implementation (Manual Upload) ** Docker Installation (Recommended)
1. *Copy files to staging*: Place MP3/FLAC files in =music/incoming/= #+BEGIN_SRC bash
2. *Access admin panel*: Navigate to =http://[IP]:8080/asteroid/admin= # Clone repository
3. *Process files*: Click "Copy Files from Incoming" button git clone https://github.com/fade/asteroid
4. *Database update*: Files are moved to =music/library/= and metadata extracted cd asteroid/docker
5. *Automatic playlist*: =playlist.m3u= is regenerated for streaming
** File Processing Steps # Start all services
1. Files copied from =music/incoming/= to =music/library/= docker compose up -d
2. Metadata extracted using taglib (title, artist, album, duration, bitrate)
3. Database record created with file path and metadata # Verify streams are working
4. Playlist file updated for Liquidsoap streaming curl -I http://localhost:8000/asteroid.mp3
5. Files immediately available for on-demand streaming curl -I http://localhost:8000/asteroid.aac
curl -I http://localhost:8000/asteroid-low.mp3
#+END_SRC
** Access Points
- *Web Interface*: http://localhost:8080/asteroid/
- *Admin Panel*: http://localhost:8080/asteroid/admin
- *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)
- *Icecast Admin*: http://localhost:8000/admin/ (admin/asteroid_admin_2024)
* Music Library Management
** Adding Music
1. *Copy files*: Place MP3/FLAC files in =docker/music/= directory
2. *Access admin panel*: Navigate to =http://localhost:8080/asteroid/admin=
3. *Scan library*: Click "Scan Library" to index new tracks
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 ** Supported Formats
- *MP3*: Primary format, best compatibility - *MP3*: Primary format, best compatibility
@ -90,216 +136,259 @@ asteroid/
* Icecast2 Integration * Icecast2 Integration
** Configuration ** Configuration
- *Server*: localhost:8000 - *Server*: localhost:8000 (Docker container)
- *Mount point*: =/asteroid.mp3= - *Mount points*: =/asteroid.mp3=, =/asteroid.aac=, =/asteroid-low.mp3=
- *Password*: =b3l0wz3r0= (configured in Liquidsoap) - *Password*: =H1tn31EhsyLrfRmo= (configured in Docker setup)
- *Format*: MP3 128kbps stereo - *Formats*: MP3 128kbps, AAC 96kbps, MP3 64kbps
** Docker Setup
Icecast2 runs in a Docker container - no manual installation needed.
** Installation (Ubuntu/Debian)
#+BEGIN_SRC bash #+BEGIN_SRC bash
sudo apt update # Managed via docker-compose
sudo apt install icecast2 cd docker
sudo systemctl enable icecast2 docker compose up -d icecast
sudo systemctl start icecast2
#+END_SRC #+END_SRC
** Stream Access ** Stream Access
- *Direct URL*: =http://[IP]:8000/asteroid.mp3= - *High Quality MP3*: =http://localhost:8000/asteroid.mp3= (128kbps)
- *Admin interface*: =http://[IP]:8000/admin/= - *High Quality AAC*: =http://localhost:8000/asteroid.aac= (96kbps)
- *Statistics*: =http://[IP]:8000/status.xsl= - *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 * Liquidsoap Integration
** Configuration File: =asteroid-radio.liq= ** Docker Configuration
#+BEGIN_SRC liquidsoap Liquidsoap runs in a Docker container with configuration in =docker/asteroid-radio-docker.liq=
#!/usr/bin/liquidsoap
# Set log level for debugging ** Key Features
settings.log.level := 4 - *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
# Create playlist from directory ** Management
radio = playlist(mode="randomize", reload=3600, "/path/to/music/library/")
# Add audio processing
radio = amplify(1.0, radio)
# Fallback with sine wave for debugging
radio = fallback(track_sensitive=false, [radio, sine(440.0)])
# Output to Icecast2
output.icecast(
%mp3(bitrate=128),
host="localhost",
port=8000,
password="b3l0wz3r0",
mount="asteroid.mp3",
name="Asteroid Radio",
description="Music for Hackers - Streaming from the Asteroid",
genre="Electronic/Alternative",
url="http://localhost:8080/asteroid/",
radio
)
#+END_SRC
** Installation (Ubuntu/Debian)
#+BEGIN_SRC bash #+BEGIN_SRC bash
sudo apt update # Start Liquidsoap container
sudo apt install liquidsoap cd docker
docker compose up -d liquidsoap
# View logs
docker compose logs -f liquidsoap
# Restart streaming
docker compose restart liquidsoap
#+END_SRC #+END_SRC
** Features ** Telnet Control
- *Random playlist*: Shuffles music library continuously
- *Auto-reload*: Playlist refreshes every hour
- *Audio processing*: Amplification and normalization
- *Fallback*: Sine tone if no music available (debugging)
- *Metadata*: Station info broadcast to listeners
* Network Access
** Local Development
- *Web Interface*: =http://localhost:8080/asteroid/=
- *Live Stream*: =http://localhost:8000/asteroid.mp3=
- *Admin Panel*: =http://localhost:8080/asteroid/admin=
** WSL Network Access
- *WSL IP*: Check with =ip addr show eth0=
- *Web Interface*: =http://[WSL-IP]:8080/asteroid/=
- *Live Stream*: =http://[WSL-IP]:8000/asteroid.mp3=
** Internal Network Broadcasting
- Services bind to all interfaces (0.0.0.0)
- Accessible from any device on local network
- Compatible with media players (VLC, iTunes, etc.)
* Usage Instructions
** Starting the Radio Station
#+BEGIN_SRC bash #+BEGIN_SRC bash
# Launch all services # Connect to Liquidsoap
./start-asteroid-radio.sh telnet localhost 1234
# Or use netcat for scripting
echo "request.queue" | nc localhost 1234
echo "request.skip" | nc localhost 1234
#+END_SRC #+END_SRC
** Stopping the Radio Station * User Management
#+BEGIN_SRC bash
# Stop all services
./stop-asteroid-radio.sh
#+END_SRC
** Adding Music ** Roles
1. Copy MP3/FLAC files to =music/incoming/= - *Admin*: Full system access, user management, stream control
2. Visit admin panel: =http://[IP]:8080/asteroid/admin= - *DJ*: Content management, playlist creation, library access
3. Click "Copy Files from Incoming" - *Listener*: Basic playback and personal playlists
4. Files are processed and added to streaming playlist
** Listening to the Stream ** Default Credentials
- *Web Browser*: Visit main page for embedded player - Username: =admin=
- *Media Player*: Open =http://[IP]:8000/asteroid.mp3= - Password: =asteroid123=
- *Mobile Apps*: Use internet radio apps with stream URL - ⚠️ 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
- 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
- Audio continues during site navigation
- Seamless listening experience
* API Endpoints * API Endpoints
Asteroid Radio provides a comprehensive REST API with 15+ endpoints.
** Status & Authentication
- =GET /api/asteroid/status= - Server status
- =GET /api/asteroid/auth-status= - Authentication status
- =GET /api/asteroid/icecast-status= - Streaming status
** Track Management ** Track Management
- =GET /api/tracks= - List all tracks with metadata - =GET /api/asteroid/tracks= - List all tracks
- =GET /tracks/{id}/stream= - Stream individual track - =GET /api/asteroid/admin/tracks= - Admin track listing
- =POST /api/scan-library= - Scan and update music library - =POST /api/asteroid/admin/scan-library= - Scan music library
- =POST /api/copy-files= - Process files from incoming directory
** Player Control ** Player Control
- =POST /api/player/play= - Start playback - =GET /api/asteroid/player/status= - Player status
- =POST /api/player/pause= - Pause playback - =POST /api/asteroid/player/play= - Play track
- =POST /api/player/stop= - Stop playback - =POST /api/asteroid/player/pause= - Pause playback
- =GET /api/status= - Get server status - =POST /api/asteroid/player/stop= - Stop playback
- =POST /api/asteroid/player/resume= - Resume playback
** Search and Filter ** Playlist Management
- =GET /api/tracks?search={query}= - Search tracks - =GET /api/asteroid/playlists= - List user playlists
- =GET /api/tracks?sort={field}= - Sort by field - =POST /api/asteroid/playlists/create= - Create playlist
- =GET /api/tracks?artist={name}= - Filter by artist - =GET /api/asteroid/playlists/get= - Get playlist details
- =POST /api/asteroid/playlists/add-track= - Add track to playlist
* Database Schema ** Stream Queue Control (Admin)
- =GET /api/asteroid/stream/queue= - Get broadcast queue
- =POST /api/asteroid/stream/queue/add= - Add track to queue
- =POST /api/asteroid/stream/queue/remove= - Remove from queue
- =POST /api/asteroid/stream/queue/clear= - Clear queue
** Tracks Collection See =docs/API-ENDPOINTS.org= for complete API documentation.
#+BEGIN_SRC lisp
(db:create "tracks" '((title :text)
(artist :text)
(album :text)
(duration :integer)
(file-path :text)
(format :text)
(bitrate :integer)
(added-date :integer)
(play-count :integer)))
#+END_SRC
** Playlists Collection (Future) * Database
#+BEGIN_SRC lisp
(db:create "playlists" '((name :text) ** Current: Radiance DB
(description :text) - File-based database abstraction
(created-date :integer) - Tracks, users, playlists, sessions
(track-ids :text))) - Suitable for development and small deployments
#+END_SRC
** 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 * Dependencies
** Lisp Dependencies (asteroid.asd) ** Lisp Dependencies
- =:radiance= - Web framework - =radiance= - Web framework
- =:r-clip= - Templating system - =r-clip= - CLIP templating
- =:lass= - CSS generation - =lass= - CSS preprocessing
- =:cl-json= - JSON handling - =cl-json= - JSON handling
- =:alexandria= - Utilities - =alexandria= - Common Lisp utilities
- =:local-time= - Time handling - =local-time= - Time handling
- =taglib= - Audio metadata extraction
** System Dependencies ** System Dependencies (Docker)
- =icecast2= - Streaming server - Docker Engine 20.10+
- =liquidsoap= - Audio processing - Docker Compose 2.0+
- =taglib= - Metadata extraction (via audio-streams) - All streaming components containerized
* Development Notes * Testing
** RADIANCE Configuration ** Automated Test Suite
- Domain: "asteroid" #+BEGIN_SRC bash
- Routes use =#@= syntax for URL patterns # Run comprehensive tests
- Database abstraction via =db:= functions ./test-server.sh
- CLIP templates with =data-text= attributes
** Database Queries # Verbose mode
- Use quoted symbols for field names: =(:= '_id id)= ./test-server.sh -v
- RADIANCE returns hash tables with string keys #+END_SRC
- Primary key is "_id" internally, "id" in JSON responses
** Streaming Considerations ** Test Coverage
- MP3 files with spaces in names require playlist.m3u approach - 25+ automated tests
- Liquidsoap fallback prevents stream silence - API endpoint validation
- Icecast2 mount points must match Liquidsoap configuration - HTML page rendering
- Static file serving
- JSON response format
- Authentication flows
* Future Enhancements * Contributing
** Planned Features ** Development Workflow
- Playlist creation and management interface 1. Fork the repository
- Now-playing status tracking and display 2. Create a feature branch
- Direct browser file uploads with progress 3. Make your changes
- Listener statistics and analytics 4. Run test suite
- Scheduled programming and automation 5. Submit pull request
** Technical Improvements ** Community
- WebSocket integration for real-time updates - *IRC*: #asteroid.music on irc.libera.chat
- Advanced audio processing options - *Issues*: GitHub issue tracker
- Multi-bitrate streaming support - *Discussions*: GitHub discussions
- Mobile-responsive interface enhancements
** Core Team
- Brian O'Reilly (Fade) - Project founder
- Glenn Thompson (glenneth) - Core developer
- Luis Pereira - UI/UX
* Troubleshooting * Troubleshooting
** Common Issues ** Docker Issues
- *No audio in stream*: Check Liquidsoap logs, verify MP3 files #+BEGIN_SRC bash
- *Database errors*: Ensure proper field name quoting in queries # Check container status
- *Network access*: Verify WSL IP and firewall settings docker compose ps
- *File upload issues*: Check permissions on music directories
** Debugging # View logs
- Enable Liquidsoap debug logging: =settings.log.level := 4= docker compose logs icecast
- Check Icecast admin interface for stream status docker compose logs liquidsoap
- Monitor RADIANCE logs for web server issues
- Verify database connectivity and collections # 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 Radiance DB file permissions
- Verify database collections exist
- Review application logs
For detailed troubleshooting, see documentation in =docs/= directory.
* License * License
This implementation maintains compatibility with the original Asteroid Radio project license while adding comprehensive streaming capabilities for internet radio broadcasting. See LICENSE file for details.
* Acknowledgments
Built with:
- Common Lisp (SBCL)
- Radiance web framework
- Icecast2 streaming server
- Liquidsoap audio processing
- Docker containerization
Special thanks to all contributors and the Common Lisp community.
---
*Last Updated: 2025-10-26*

2
docs/API-ENDPOINTS.org
View File

@ -1,6 +1,6 @@
#+TITLE: Asteroid Radio - API Endpoints Reference #+TITLE: Asteroid Radio - API Endpoints Reference
#+AUTHOR: Asteroid Radio Development Team #+AUTHOR: Asteroid Radio Development Team
#+DATE: 2025-10-10 #+DATE: 2025-10-26
* Overview * Overview

2
docs/API-REFERENCE.org
View File

@ -1,6 +1,6 @@
#+TITLE: Asteroid Radio - Interface Reference #+TITLE: Asteroid Radio - Interface Reference
#+AUTHOR: Asteroid Radio Development Team #+AUTHOR: Asteroid Radio Development Team
#+DATE: 2025-10-10 #+DATE: 2025-10-26
* Current Interfaces * Current Interfaces

4
docs/DEVELOPMENT.org
View File

@ -1,6 +1,6 @@
#+TITLE: Asteroid Radio - Development Guide #+TITLE: Asteroid Radio - Development Guide
#+AUTHOR: Asteroid Radio Development Team #+AUTHOR: Asteroid Radio Development Team
#+DATE: 2025-10-10 #+DATE: 2025-10-26
* Development Setup * Development Setup
@ -68,7 +68,7 @@ sbcl --load quicklisp.lisp --eval "(quicklisp-quickstart:install)" --quit
*** Clone Repository *** Clone Repository
#+BEGIN_SRC bash #+BEGIN_SRC bash
git clone <repository-url> git clone https://github.com/fade/asteroid
cd asteroid cd asteroid
#+END_SRC #+END_SRC

6
docs/DOCKER-STREAMING.org
View File

@ -1,6 +1,6 @@
#+TITLE: Asteroid Radio - Docker Streaming Setup #+TITLE: Asteroid Radio - Docker Streaming Setup
#+AUTHOR: Docker Team #+AUTHOR: Asteroid Radio Development Team
#+DATE: 2025-10-03 #+DATE: 2025-10-26
* Docker Streaming Overview * Docker Streaming Overview
@ -37,7 +37,7 @@ sudo usermod -a -G docker $USER
** One-Command Setup ** One-Command Setup
#+BEGIN_SRC bash #+BEGIN_SRC bash
# Clone and start # Clone and start
git clone <repository-url> asteroid-radio git clone https://github.com/fade/asteroid asteroid-radio
cd asteroid-radio/docker cd asteroid-radio/docker
docker compose up -d docker compose up -d
#+END_SRC #+END_SRC

12
docs/INSTALLATION.org
View File

@ -1,6 +1,6 @@
#+TITLE: Asteroid Radio - Installation Guide #+TITLE: Asteroid Radio - Installation Guide
#+AUTHOR: Installation Team #+AUTHOR: Asteroid Radio Development Team
#+DATE: 2025-10-03 #+DATE: 2025-10-26
* Installation Overview * Installation Overview
@ -18,8 +18,8 @@ docker info
** One-Command Setup ** One-Command Setup
#+BEGIN_SRC bash #+BEGIN_SRC bash
# Clone and setup (replace with actual repository URL) # Clone and setup
git clone <repository-url> asteroid-radio git clone https://github.com/fade/asteroid asteroid-radio
cd asteroid-radio/docker cd asteroid-radio/docker
docker compose up -d docker compose up -d
#+END_SRC #+END_SRC
@ -201,8 +201,8 @@ sbcl --load quicklisp.lisp --eval "(quicklisp-quickstart:install)" --eval "(ql:a
*** Step 5: Clone and Setup Project *** Step 5: Clone and Setup Project
#+BEGIN_SRC bash #+BEGIN_SRC bash
# Clone repository (replace with actual URL) # Clone repository
git clone <repository-url> /opt/asteroid-radio git clone https://github.com/fade/asteroid /opt/asteroid-radio
cd /opt/asteroid-radio cd /opt/asteroid-radio
# Create required directories # Create required directories

2
docs/PLAYLIST-SYSTEM.org
View File

@ -1,6 +1,6 @@
#+TITLE: Playlist System - Complete (MVP) #+TITLE: Playlist System - Complete (MVP)
#+AUTHOR: Asteroid Radio Development Team #+AUTHOR: Asteroid Radio Development Team
#+DATE: 2025-10-04 #+DATE: 2025-10-26
* Overview * Overview

2
docs/POSTGRESQL-SETUP.org
View File

@ -1,6 +1,6 @@
#+TITLE: PostgreSQL Setup for Asteroid Radio #+TITLE: PostgreSQL Setup for Asteroid Radio
#+AUTHOR: Asteroid Radio Development Team #+AUTHOR: Asteroid Radio Development Team
#+DATE: 2025-10-04 #+DATE: 2025-10-26
* Overview * Overview

343
docs/PROJECT-HISTORY.org Normal file
View File

@ -0,0 +1,343 @@
#+TITLE: Asteroid Radio - Project Development History
#+AUTHOR: Asteroid Radio Development Team
#+DATE: 2025-10-26
#+DESCRIPTION: Comprehensive history of the Asteroid Radio project from inception to present
* Project Overview
Asteroid Radio is a web-based internet radio station 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.
** Technology Stack
- *Backend*: Common Lisp (SBCL), Radiance web framework
- *Streaming*: Icecast2, Liquidsoap
- *Database*: PostgreSQL (configured, ready for migration)
- *Frontend*: HTML5, JavaScript, CLIP templating, LASS (CSS in Lisp)
- *Infrastructure*: Docker, Docker Compose
* Project Timeline
** Phase 1: Project Inception (August 2025)
*** 2025-08-12: Initial Commit
- *Author*: Brian O'Reilly (Fade)
- Project founded and initial repository created
- Basic project structure established
- Core Radiance framework integration begun
** Phase 2: Foundation Building (September - Early October 2025)
*** Core Features Established
- Basic web server setup with Radiance
- Initial music library scanning functionality
- Database integration for track metadata
- Basic authentication system
- Front-end page structure
*** Key Contributors Join
- Glenn Thompson (glenneth) begins major contributions
- Luis Pereira joins for UI/UX improvements
- Collaborative development model established
** Phase 3: Template System & UI Overhaul (October 2025)
*** 2025-10-04 to 2025-10-06: CLIP Template Migration
- *Lead*: Luis Pereira, Glenn Thompson
- Migrated from inline HTML to CLIP templating system
- Established consistent site-wide styling
- Implemented VT323 retro terminal font
- Created reusable template components
*** 2025-10-04 to 2025-10-07: User Management System
- *Lead*: Glenn Thompson
- User profile pages with edit functionality
- Registration and authentication UI
- Role-based access control (admin, DJ, listener)
- User profile management interface
*** 2025-10-05: Navigation Improvements
- *Lead*: Luis Pereira
- Unified navigation bar across all pages
- Improved responsive design
- Better mobile experience
** Phase 4: API Refactoring & Testing (October 8-10, 2025)
*** 2025-10-08: Major API Overhaul
- *Lead*: Glenn Thompson
- Refactored all endpoints to use Radiance's define-api macro
- Standardized JSON API responses
- API-aware authentication (auto-detects API vs web requests)
- Comprehensive automated test suite added
*** 2025-10-08 to 2025-10-09: Frontend JavaScript Updates
- Fixed all frontend code to work with new API endpoints
- Improved error handling
- Better async/await patterns
*** 2025-10-10: Documentation Sprint
- *Lead*: Glenn Thompson
- Major documentation cleanup
- Added comprehensive API documentation
- Created testing guides
- Updated all core documentation files
** Phase 5: Streaming Infrastructure (October 8-14, 2025)
*** 2025-10-08: Liquidsoap DJ Controls
- *Lead*: Glenn Thompson
- Telnet integration with Liquidsoap
- Real-time stream control
- Skip track functionality
- Queue management via telnet commands
*** 2025-10-10: Dynamic Stream URL Support
- *Lead*: Glenn Thompson
- Stream base URL as template variable
- Support for multiple deployment environments
- Preparation for multi-network access
*** 2025-10-14: Stream Queue System
- *Lead*: Brian O'Reilly, Glenn Thompson
- M3U playlist queue management
- Admin UI for queue control
- Add/remove tracks from stream queue
- Real-time queue updates
*** 2025-10-14: Audio Quality Improvements
- ReplayGain volume normalization
- Reduced buffering
- Improved player UI
- Better streaming performance
** Phase 6: Advanced Features (October 12-17, 2025)
*** 2025-10-12: Role-Based Page Flow
- *Lead*: Glenn Thompson
- Intelligent page routing based on user role
- Admin-specific workflows
- DJ control interfaces
- Enhanced user experience
*** 2025-10-13: HTML Partial Hydration
- *Lead*: Luis Pereira
- Now-playing partial component
- Server-side rendering with client updates
- Reduced JavaScript complexity
- Better performance
*** 2025-10-15 to 2025-10-16: Configuration System
- *Lead*: Brian O'Reilly
- Dedicated configuration namespace exploration
- Environment-based configuration
- Improved deployment flexibility
*** 2025-10-16: Comprehensive Documentation Update
- *Lead*: Glenn Thompson
- PROJECT-OVERVIEW updated with all features
- Stream queue and ReplayGain documentation
- Complete feature documentation
*** 2025-10-17: Code Quality Improvements
- *Lead*: Glenn Thompson
- Code consistency refactoring
- Bug fixes (track search query variable)
- Maintainability improvements
- Better code organization
** Phase 7: Player Evolution (October 19-25, 2025)
*** 2025-10-19: Pop-Out Player
- *Lead*: Glenn Thompson
- Standalone pop-out player window
- Independent audio playback
- Queue management improvements
- Multi-window support
*** 2025-10-19: Persistent Audio Player (Frameset)
- *Lead*: Glenn Thompson
- Frameset-based persistent player
- Audio continues during navigation
- Bottom-frame player bar
- Seamless listening experience
*** 2025-10-21: Hybrid Player System
- *Lead*: Glenn Thompson
- Combined frameset and pop-out options
- User preference storage (localStorage)
- Flexible playback modes
- Enhanced user choice
*** 2025-10-24: Dynamic Stream URL Detection
- *Lead*: Glenn Thompson
- Automatic host detection from HTTP headers
- Multi-environment support (localhost, Tailscale, LAN)
- Fixed remote access issues
- No configuration needed for different networks
*** 2025-10-25: Typography Consistency Fix
- *Lead*: Glenn Thompson
- Replaced Courier New with VT323 in persistent player
- Consistent font usage site-wide
- Addressed styling feedback
- Improved visual coherence
* Development Statistics
** Contributors (by commit count)
1. Glenn Thompson (glenneth/Glenneth) - 131+ commits
2. Brian O'Reilly (Fade) - 55+ commits
3. Luis Pereira - 19+ commits
** Total Commits: 205+ commits
** Active Development Period
- Start: August 12, 2025
- Current: October 26, 2025
- Duration: ~2.5 months of active development
* Major Features Implemented
** Core Functionality
- ✅ Music library scanning and metadata extraction
- ✅ PostgreSQL database integration (configured, ready for migration)
- ✅ Track search and filtering
- ✅ Playlist management
- ✅ Stream queue control
- ✅ Live streaming via Icecast/Liquidsoap
** User Management
- ✅ User registration and authentication
- ✅ Role-based access control (Admin, DJ, Listener)
- ✅ User profiles with edit functionality
- ✅ Session management
- ✅ Role-based page flow
** Streaming Features
- ✅ Multiple quality options (AAC 96k, MP3 128k, MP3 64k)
- ✅ ReplayGain volume normalization
- ✅ Live now-playing information
- ✅ Icecast integration
- ✅ Liquidsoap DJ controls
- ✅ Stream queue management
** Player Options
- ✅ Inline web player
- ✅ Pop-out player window
- ✅ Persistent frameset player
- ✅ Hybrid player system
- ✅ Quality selector
- ✅ Auto-reconnect on errors
** API & Integration
- ✅ RESTful JSON API
- ✅ API-aware authentication
- ✅ Comprehensive test suite
- ✅ Telnet integration with Liquidsoap
- ✅ Real-time status updates
** UI/UX
- ✅ Retro terminal aesthetic (VT323 font)
- ✅ Responsive design
- ✅ CLIP templating system
- ✅ LASS CSS preprocessing
- ✅ Consistent navigation
- ✅ HTML partial hydration
** Infrastructure
- ✅ Docker containerization
- ✅ Docker Compose orchestration
- ✅ PostgreSQL database (configured)
- ✅ Multi-environment support
- ✅ Dynamic URL detection
* Technical Milestones
** Architecture Evolution
1. *Initial*: Monolithic HTML generation
2. *Template Migration*: CLIP templating system
3. *API Standardization*: Radiance define-api macros
4. *Component Architecture*: HTML partials and hydration
5. *Multi-Mode Player*: Hybrid player system
** Code Quality Improvements
- Comprehensive test suite
- API refactoring for consistency
- Code organization and maintainability
- Documentation standards
- Consistent error handling
** Performance Optimizations
- ReplayGain normalization
- Reduced buffering
- Efficient database queries
- Parallel music scanning
- Client-side caching
* Current State (October 2025)
** Production Ready Features
- Full music streaming platform
- User management system
- Admin control panel
- DJ controls
- Multiple player modes
- Multi-environment deployment
** Active Development Areas
- Configuration system refinement
- Additional UI improvements
- Performance optimization
- Feature expansion based on user feedback
** Known Issues & Future Work
- PostgreSQL migration (configured, pending data migration)
- Continued UI/UX refinement
- Additional streaming features
- Enhanced playlist functionality
- Mobile app considerations
- Scalability improvements
* Project Philosophy
** Design Principles
- *Hacker Aesthetic*: Terminal-inspired retro design
- *User Choice*: Multiple player modes and options
- *Simplicity*: Clean, focused interface
- *Performance*: Fast, responsive experience
- *Flexibility*: Multi-environment support
** Development Approach
- Collaborative development
- Iterative improvements
- Comprehensive testing
- Documentation-first
- User feedback driven
* Acknowledgments
** Core Team
- *Brian O'Reilly (Fade)*: Project founder, architecture, streaming infrastructure
- *Glenn Thompson (glenneth)*: Major features, API, player systems, documentation
- *Luis Pereira*: UI/UX, templating, frontend improvements
** Technologies
- Radiance web framework
- Icecast streaming server
- Liquidsoap audio processing
- PostgreSQL database
- Common Lisp ecosystem
* Conclusion
Asteroid Radio has evolved from a simple concept into a full-featured internet radio platform in just 2.5 months of active development. The project demonstrates the power of Common Lisp for web development and the collaborative nature of open-source development.
The project continues to evolve with regular improvements, bug fixes, and new features based on user needs and technical requirements.
** Project Links
- Repository: https://github.com/fade/asteroid
- Contributors: https://github.com/fade/asteroid/graphs/contributors
- IRC: #asteroid.music on irc.libera.chat
---
*Last Updated: 2025-10-26*

21
docs/PROJECT-OVERVIEW.org
View File

@ -1,6 +1,6 @@
#+TITLE: Asteroid Radio - Project Overview #+TITLE: Asteroid Radio - Project Overview
#+AUTHOR: Glenn Thompson & Brian O'Reilly (Fade) #+AUTHOR: Glenn Thompson & Brian O'Reilly (Fade)
#+DATE: 2025-10-03 #+DATE: 2025-10-26
* 🎯 Mission * 🎯 Mission
@ -38,7 +38,8 @@ Asteroid Radio is a modern, web-based music streaming platform designed for hack
- **Common Lisp** (SBCL) - Core application language - **Common Lisp** (SBCL) - Core application language
- **Radiance Framework** - Web framework and module system - **Radiance Framework** - Web framework and module system
- **LASS** - CSS preprocessing in Lisp - **LASS** - CSS preprocessing in Lisp
- **PostgreSQL** - Database backend for user accounts and metadata - **PostgreSQL** - Database backend (configured, ready for migration)
- **Radiance DB** - Current database abstraction layer
**Frontend:** **Frontend:**
- **HTML5** with semantic templates - **HTML5** with semantic templates
@ -75,26 +76,32 @@ Asteroid Radio is a modern, web-based music streaming platform designed for hack
## 🚀 Features ## 🚀 Features
### Current Features ### Current Features
- ✅ **User Authentication** - Registration, login, profiles, role-based access - ✅ **User Authentication** - Registration, login, profiles, role-based access (Admin/DJ/Listener)
- ✅ **User Management** - Admin interface for user administration - ✅ **User Management** - Admin interface for user administration
- ✅ **Music Library** - Track management with pagination and search - ✅ **Music Library** - Track management with pagination, search, and filtering
- ✅ **User Playlists** - Create, manage, and play personal music collections - ✅ **User Playlists** - Create, manage, and play personal music collections
- ✅ **Web Player** - Browser-based player with queue management - ✅ **Multiple Player Modes** - Inline, pop-out, and persistent frameset players
- ✅ **Stream Queue Control** - Admin control over broadcast stream queue (M3U-based)
- ✅ **REST API** - Comprehensive JSON API with 15+ endpoints - ✅ **REST API** - Comprehensive JSON API with 15+ endpoints
- ✅ **Music Streaming** - Multiple quality formats (MP3, AAC) - ✅ **Music Streaming** - Multiple quality formats (128k MP3, 96k AAC, 64k MP3)
- ✅ **Rate Limiting** - Anti-abuse protection - ✅ **Rate Limiting** - Anti-abuse protection
- ✅ **Docker Integration** - Icecast2/Liquidsoap streaming infrastructure - ✅ **Docker Integration** - Icecast2/Liquidsoap streaming infrastructure
- ✅ **PostgreSQL Database** - Persistent data storage - ✅ **PostgreSQL Database** - Configured and ready for migration
- ✅ **Liquidsoap DJ Controls** - Telnet interface for live control - ✅ **Liquidsoap DJ Controls** - Telnet interface for live control
- ✅ **Dynamic Stream URLs** - Automatic host detection for multi-environment support
- ✅ **ReplayGain Normalization** - Consistent audio volume across tracks
- ✅ **Responsive Design** - Works on desktop and mobile - ✅ **Responsive Design** - Works on desktop and mobile
- ✅ **Automated Testing** - Comprehensive test suite - ✅ **Automated Testing** - Comprehensive test suite
### Planned Features ### Planned Features
- 🔄 **PostgreSQL Migration** - Full migration from Radiance DB to PostgreSQL
- 🔄 **Enhanced Playlist Management** - Full CRUD operations with PostgreSQL
- 🔄 **Social Features** - Playlist sharing and discovery - 🔄 **Social Features** - Playlist sharing and discovery
- 🔄 **Advanced Search** - Full-text search and filtering - 🔄 **Advanced Search** - Full-text search and filtering
- 🔄 **Mobile App** - Native mobile applications - 🔄 **Mobile App** - Native mobile applications
- 🔄 **WebSocket Support** - Real-time updates - 🔄 **WebSocket Support** - Real-time updates
- 🔄 **Analytics** - Listening statistics and insights - 🔄 **Analytics** - Listening statistics and insights
- 🔄 **Scheduled Programming** - Time-based queue switching
## 🔮 Vision ## 🔮 Vision

22
docs/README.org
View File

@ -1,6 +1,6 @@
#+TITLE: Asteroid Radio - Documentation Index #+TITLE: Asteroid Radio - Documentation Index
#+AUTHOR: Asteroid Radio Development Team #+AUTHOR: Asteroid Radio Development Team
#+DATE: 2025-10-10 #+DATE: 2025-10-26
* Welcome to Asteroid Radio Documentation * Welcome to Asteroid Radio Documentation
@ -19,6 +19,9 @@ For immediate setup, see:
*** [[file:PROJECT-OVERVIEW.org][Project Overview]] *** [[file:PROJECT-OVERVIEW.org][Project Overview]]
Complete overview of Asteroid Radio's architecture, technology stack, and vision. Start here to understand what Asteroid Radio is and how it works. Complete overview of Asteroid Radio's architecture, technology stack, and vision. Start here to understand what Asteroid Radio is and how it works.
*** [[file:PROJECT-HISTORY.org][Project History]]
Comprehensive development history from inception to present, including timeline, milestones, and contributor information.
*** [[file:INSTALLATION.org][Installation Guide]] *** [[file:INSTALLATION.org][Installation Guide]]
Comprehensive installation instructions for multiple operating systems, including system requirements, dependencies, and production deployment considerations. Comprehensive installation instructions for multiple operating systems, including system requirements, dependencies, and production deployment considerations.
@ -58,16 +61,19 @@ Pagination system for efficient browsing of large music libraries.
** What's Working Now ** What's Working Now
- **Web Application**: Full-featured web interface with authentication - **Web Application**: Full-featured web interface with authentication
- **REST API**: JSON API with 15+ endpoints for programmatic access - **REST API**: JSON API with 15+ endpoints for programmatic access
- **User Management**: Registration, login, roles, and profiles - **User Management**: Registration, login, roles (Admin/DJ/Listener), and profiles
- **Music Library**: Track management with pagination and search - **Music Library**: Track management with pagination, search, and filtering
- **Playlists**: User playlists with creation and playback - **Playlists**: User playlists with creation and playback
- **Web Player**: Browser-based audio player with queue management - **Multiple Player Modes**: Inline, pop-out, and persistent frameset players
- **Stream Queue Control**: Admin control over broadcast stream queue
- **Docker Streaming Infrastructure**: Icecast2 + Liquidsoap containers - **Docker Streaming Infrastructure**: Icecast2 + Liquidsoap containers
- **Three Quality Streams**: 128kbps MP3, 96kbps AAC, 64kbps MP3 - **Three Quality Streams**: 128kbps MP3, 96kbps AAC, 64kbps MP3
- **Admin Interface**: Icecast web admin at http://localhost:8000/admin/ - **Admin Interface**: Icecast web admin at http://localhost:8000/admin/
- **Liquidsoap DJ Controls**: Telnet control via localhost:1234 - **Liquidsoap DJ Controls**: Telnet control via localhost:1234
- **Professional Features**: Crossfading, normalization, metadata support - **Professional Features**: Crossfading, ReplayGain normalization, metadata support
- **PostgreSQL Database**: Persistent data storage with full CRUD operations - **PostgreSQL Database**: Configured and ready for migration
- **Dynamic Stream URLs**: Automatic host detection for multi-environment support
- **Responsive Design**: Works on desktop and mobile devices
** Stream URLs (when running) ** Stream URLs (when running)
- **High Quality MP3**: http://localhost:8000/asteroid.mp3 (128kbps) - **High Quality MP3**: http://localhost:8000/asteroid.mp3 (128kbps)
@ -141,5 +147,5 @@ For detailed technical information, see the **[[file:PROJECT-OVERVIEW.org][Proje
--- ---
*Last Updated: 2025-10-10* *Last Updated: 2025-10-26*
*Documentation Version: 2.0* *Documentation Version: 3.0*

6
docs/STREAM-CONTROL.org
View File

@ -1,6 +1,6 @@
#+TITLE: Stream Queue Control System #+TITLE: Stream Queue Control System
#+AUTHOR: Asteroid Radio Team #+AUTHOR: Asteroid Radio Development Team
#+DATE: 2025-10-14 #+DATE: 2025-10-26
* Overview * Overview
@ -140,7 +140,7 @@ If you're working directly in the Lisp REPL:
* File Locations * File Locations
- *Stream Queue File*: =/home/glenn/Projects/Code/asteroid/stream-queue.m3u= - *Stream Queue File*: =stream-queue.m3u= (in project root)
- *Docker Mount*: =/app/stream-queue.m3u= (inside Liquidsoap container) - *Docker Mount*: =/app/stream-queue.m3u= (inside Liquidsoap container)
- *Liquidsoap Config*: =docker/asteroid-radio-docker.liq= - *Liquidsoap Config*: =docker/asteroid-radio-docker.liq=

2
docs/TESTING.org
View File

@ -1,6 +1,6 @@
#+TITLE: Asteroid Radio Testing Guide #+TITLE: Asteroid Radio Testing Guide
#+AUTHOR: Asteroid Radio Development Team #+AUTHOR: Asteroid Radio Development Team
#+DATE: 2025-10-08 #+DATE: 2025-10-26
* Overview * Overview

2
docs/TRACK-PAGINATION-SYSTEM.org
View File

@ -1,6 +1,6 @@
#+TITLE: Track Pagination System - Complete #+TITLE: Track Pagination System - Complete
#+AUTHOR: Asteroid Radio Development Team #+AUTHOR: Asteroid Radio Development Team
#+DATE: 2025-10-04 #+DATE: 2025-10-26
* Overview * Overview

2
docs/USER-MANAGEMENT-SYSTEM.org
View File

@ -1,6 +1,6 @@
#+TITLE: User Management System - Complete #+TITLE: User Management System - Complete
#+AUTHOR: Asteroid Radio Development Team #+AUTHOR: Asteroid Radio Development Team
#+DATE: 2025-10-04 #+DATE: 2025-10-26
* Overview * Overview