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

10 KiB
Raw Blame History

Asteroid Radio - Project Development History

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

—

Last Updated: 2025-10-26