asteroid/README.org

#+TITLE: Asteroid Radio - Internet Radio Streaming Platform
#+AUTHOR: Asteroid Radio Development Team
#+DATE: 2025-10-26

* Overview

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

** Live Internet Radio Streaming
- Multiple quality streams: 128kbps MP3, 96kbps AAC, 64kbps MP3
- Professional audio processing with crossfading and ReplayGain normalization
- Icecast2 streaming server integration
- Liquidsoap audio pipeline for reliable broadcasting
- Stream queue control for curated programming

** Music Library Management
- Database-backed track storage with metadata extraction
- Support for MP3, FLAC, OGG, and WAV formats
- Automatic metadata extraction using taglib
- Track search, filtering, sorting, and pagination
- Recursive directory scanning

** Web Interface
- RADIANCE framework with CLIP templating
- Admin dashboard for library and user management
- Multiple player modes: inline, pop-out, and persistent frameset
- Live stream integration with embedded player
- Responsive design for desktop and mobile
- Role-based access control (Admin/DJ/Listener)

** Network Broadcasting
- Dynamic stream URL detection for multi-environment support
- Professional streaming URLs for media players
- Multi-listener support via Icecast2
- Docker-based deployment for easy setup

* Architecture Changes

** Framework Migration
- Migrated from Hunchentoot to RADIANCE web framework
- Implemented proper domain routing (=/asteroid/=)
- CLIP templating system for dynamic content
- Database abstraction layer for track storage

** Streaming Stack
- *Icecast2*: Streaming server (port 8000) - Docker containerized
- *Liquidsoap*: Audio processing and streaming pipeline - Docker containerized
- *RADIANCE*: Web server and API (port 8080)
- *PostgreSQL*: Database backend (configured, ready for migration)
- *Docker Compose*: Container orchestration

** File Structure
#+BEGIN_SRC
asteroid/
├── asteroid.lisp              # Main server with RADIANCE routes
├── asteroid.asd               # System definition with dependencies
├── stream-control.lisp        # Stream queue management
├── user-management.lisp       # User administration
├── playlist-management.lisp   # Playlist operations
├── 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
│   ├── front-page.chtml       # Main page with live stream
│   ├── admin.chtml            # Admin dashboard
│   ├── player.chtml           # Web player interface
│   └── users.chtml            # User management
├── static/                    # CSS and assets
│   └── asteroid.lass          # LASS stylesheet
├── docs/                      # Comprehensive documentation
│   ├── 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

** Docker Installation (Recommended)
#+BEGIN_SRC bash
# Clone repository
git clone https://github.com/fade/asteroid
cd asteroid/docker

# Start all services
docker compose up -d

# Verify streams are working
curl -I http://localhost:8000/asteroid.mp3
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
- *MP3*: Primary format, best compatibility
- *FLAC*: Lossless audio, high quality
- *OGG*: Open source format
- *WAV*: Uncompressed audio

* Icecast2 Integration

** 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
- *DJ*: Content management, playlist creation, library access
- *Listener*: Basic playback and personal playlists

** Default Credentials
- Username: =admin=
- 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
- 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

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
- =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
- =GET /api/asteroid/playlists/get= - Get playlist details
- =POST /api/asteroid/playlists/add-track= - Add track to playlist

** 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

See =docs/API-ENDPOINTS.org= for complete API documentation.

* Database

** Current: Radiance DB
- File-based database abstraction
- Tracks, users, playlists, sessions
- Suitable for development and small deployments

** 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
- =r-clip= - CLIP templating
- =lass= - CSS preprocessing
- =cl-json= - JSON handling
- =alexandria= - Common Lisp utilities
- =local-time= - Time handling
- =taglib= - Audio metadata extraction

** System Dependencies (Docker)
- Docker Engine 20.10+
- Docker Compose 2.0+
- All streaming components containerized

* Testing

** Automated Test Suite
#+BEGIN_SRC bash
# Run comprehensive tests
./test-server.sh

# Verbose mode
./test-server.sh -v
#+END_SRC

** Test Coverage
- 25+ automated tests
- API endpoint validation
- HTML page rendering
- Static file serving
- JSON response format
- Authentication flows

* Contributing

** Development Workflow
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run test suite
5. Submit pull request

** Community
- *IRC*: #asteroid.music on irc.libera.chat
- *Issues*: GitHub issue tracker
- *Discussions*: GitHub discussions

** Core Team
- Brian O'Reilly (Fade) - Project founder
- Glenn Thompson (glenneth) - Core developer
- Luis Pereira - UI/UX

* Troubleshooting

** Docker Issues
#+BEGIN_SRC bash
# Check container status
docker compose ps

# View logs
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 Radiance DB file permissions
- Verify database collections exist
- Review application logs

For detailed troubleshooting, see documentation in =docs/= directory.

* License

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*