Asteroid Radio - Internet Streaming Implementation

• Overview
• Key Features
  • Live Internet Radio Streaming
  • Music Library Management
  • Web Interface
  • Network Broadcasting
• Architecture Changes
  • Framework Migration
  • Streaming Stack
  • File Structure
• Track Upload Workflow
  • Current Implementation (Manual Upload)
  • File Processing Steps
  • Supported Formats
• Icecast2 Integration
  • Configuration
  • Installation (Ubuntu/Debian)
  • Stream Access
• Liquidsoap Integration
  • Configuration File: asteroid-radio.liq
  • Installation (Ubuntu/Debian)
  • Features
• Network Access
  • Local Development
  • WSL Network Access
  • Internal Network Broadcasting
• Usage Instructions
  • Starting the Radio Station
  • Stopping the Radio Station
  • Adding Music
  • Listening to the Stream
• API Endpoints
  • Track Management
  • Player Control
  • Search and Filter
• Database Schema
  • Tracks Collection
  • Playlists Collection (Future)
• Dependencies
  • Lisp Dependencies (asteroid.asd)
  • System Dependencies
• Development Notes
  • RADIANCE Configuration
  • Database Queries
  • Streaming Considerations
• Future Enhancements
  • Planned Features
  • Technical Improvements
• Troubleshooting
  • Common Issues
  • Debugging
• License

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.

Key Features

Live Internet Radio Streaming

• Continuous MP3 streaming at 128kbps stereo
• Professional audio processing with crossfading and normalization
• Icecast2 streaming server integration
• Liquidsoap audio pipeline for reliable broadcasting

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, and sorting capabilities

Web Interface

• RADIANCE framework with CLIP templating
• Admin dashboard for library management
• Web player with HTML5 audio controls
• Live stream integration with embedded player

Network Broadcasting

• WSL-compatible networking for internal network access
• Professional streaming URLs for media players
• Multi-listener support via Icecast2

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)
• Liquidsoap: Audio processing and streaming pipeline
• RADIANCE: Web server and API (port 8080)
• Database: Track metadata and playlist storage

File Structure

asteroid/
├── asteroid.lisp              # Main server with RADIANCE routes
├── asteroid.asd               # System definition with dependencies
├── asteroid-radio.liq         # Liquidsoap streaming configuration
├── playlist.m3u               # Generated playlist for streaming
├── start-asteroid-radio.sh    # Launch script for all services
├── stop-asteroid-radio.sh     # Stop script for all services
├── template/                  # CLIP HTML templates
│   ├── front-page.chtml       # Main page with live stream
│   ├── admin.chtml            # Admin dashboard
│   └── player.chtml           # Web player interface
├── static/                    # CSS and assets
│   └── asteroid.lass          # LASS stylesheet
└── music/                     # Music library
    ├── incoming/              # Upload staging area
    └── library/               # Processed music files

Track Upload Workflow

Current Implementation (Manual Upload)

1. Copy files to staging: Place MP3/FLAC files in music/incoming/
2. Access admin panel: Navigate to http://[IP]:8080/asteroid/admin
3. Process files: Click "Copy Files from Incoming" button
4. Database update: Files are moved to music/library/ and metadata extracted
5. Automatic playlist: playlist.m3u is regenerated for streaming

File Processing Steps

1. Files copied from music/incoming/ to music/library/
2. Metadata extracted using taglib (title, artist, album, duration, bitrate)
3. Database record created with file path and metadata
4. Playlist file updated for Liquidsoap streaming
5. Files immediately available for on-demand streaming

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
• Mount point: /asteroid.mp3
• Password: b3l0wz3r0 (configured in Liquidsoap)
• Format: MP3 128kbps stereo

Installation (Ubuntu/Debian)

sudo apt update
sudo apt install icecast2
sudo systemctl enable icecast2
sudo systemctl start icecast2

Stream Access

• Direct URL: http://[IP]:8000/asteroid.mp3
• Admin interface: http://[IP]:8000/admin/
• Statistics: http://[IP]:8000/status.xsl

Liquidsoap Integration

Configuration File: asteroid-radio.liq

#!/usr/bin/liquidsoap

# Set log level for debugging
settings.log.level := 4

# Create playlist from directory
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
)

Installation (Ubuntu/Debian)

sudo apt update
sudo apt install liquidsoap

Features

• 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

# Launch all services
./start-asteroid-radio.sh

Stopping the Radio Station

# Stop all services
./stop-asteroid-radio.sh

Adding Music

1. Copy MP3/FLAC files to music/incoming/
2. Visit admin panel: http://[IP]:8080/asteroid/admin
3. Click "Copy Files from Incoming"
4. Files are processed and added to streaming playlist

Listening to the Stream

• Web Browser: Visit main page for embedded player
• Media Player: Open http://[IP]:8000/asteroid.mp3
• Mobile Apps: Use internet radio apps with stream URL

API Endpoints

Track Management

• GET /api/tracks - List all tracks with metadata
• GET /tracks/{id}/stream - Stream individual track
• POST /api/scan-library - Scan and update music library
• POST /api/copy-files - Process files from incoming directory

Player Control

• POST /api/player/play - Start playback
• POST /api/player/pause - Pause playback
• POST /api/player/stop - Stop playback
• GET /api/status - Get server status

Search and Filter

• GET /api/tracks?search={query} - Search tracks
• GET /api/tracks?sort={field} - Sort by field
• GET /api/tracks?artist={name} - Filter by artist

Database Schema

Tracks Collection

(db:create "tracks" '((title :text)
                      (artist :text)
                      (album :text)
                      (duration :integer)
                      (file-path :text)
                      (format :text)
                      (bitrate :integer)
                      (added-date :integer)
                      (play-count :integer)))

Playlists Collection (Future)

(db:create "playlists" '((name :text)
                         (description :text)
                         (created-date :integer)
                         (track-ids :text)))

Dependencies

Lisp Dependencies (asteroid.asd)

• :radiance - Web framework
• :r-clip - Templating system
• :lass - CSS generation
• :cl-json - JSON handling
• :alexandria - Utilities
• :local-time - Time handling

System Dependencies

• icecast2 - Streaming server
• liquidsoap - Audio processing
• taglib - Metadata extraction (via audio-streams)

Development Notes

RADIANCE Configuration

• Domain: "asteroid"
• Routes use #@ syntax for URL patterns
• Database abstraction via db: functions
• CLIP templates with data-text attributes

Database Queries

• Use quoted symbols for field names: (: '_id id)=
• RADIANCE returns hash tables with string keys
• Primary key is "_id" internally, "id" in JSON responses

Streaming Considerations

• MP3 files with spaces in names require playlist.m3u approach
• Liquidsoap fallback prevents stream silence
• Icecast2 mount points must match Liquidsoap configuration

Future Enhancements

Planned Features

• Playlist creation and management interface
• Now-playing status tracking and display
• Direct browser file uploads with progress
• Listener statistics and analytics
• Scheduled programming and automation

Technical Improvements

• WebSocket integration for real-time updates
• Advanced audio processing options
• Multi-bitrate streaming support
• Mobile-responsive interface enhancements

Troubleshooting

Common Issues

• No audio in stream: Check Liquidsoap logs, verify MP3 files
• Database errors: Ensure proper field name quoting in queries
• Network access: Verify WSL IP and firewall settings
• File upload issues: Check permissions on music directories

Debugging

• Enable Liquidsoap debug logging: settings.log.level : 4=
• Check Icecast admin interface for stream status
• Monitor RADIANCE logs for web server issues
• Verify database connectivity and collections

License

This implementation maintains compatibility with the original Asteroid Radio project license while adding comprehensive streaming capabilities for internet radio broadcasting.