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

13 KiB
Raw Permalink 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

Phase 8: Docker Deployment & Documentation (October 26 - November 1, 2025)

2025-10-19: User Initialization Retry Logic

  • Lead: Luis Pereira (easilok)
  • Fixed user initialization retry mechanism
  • Improved reliability on startup
  • Better error handling

2025-10-26: Custom Environment Variables for Streams

  • Lead: Luis Pereira (easilok)
  • Added MUSIC_LIBRARY environment variable
  • Added QUEUE_PLAYLIST environment variable
  • Flexible path configuration for Docker deployments

2025-10-26: Docker Setup for Asteroid Application

  • Lead: Luis Pereira (easilok)
  • Created Dockerfile.asteroid for app containerization
  • Added docker-compose.asteroid.yml
  • Radiance configuration for containerized deployment
  • Complete Docker-based deployment solution

2025-10-26: Docker Deployment Documentation

  • Lead: Luis Pereira (easilok)
  • Comprehensive Docker deployment guide in INSTALLATION.org
  • Separate sections for stream services and application
  • Environment variable documentation
  • Build and deployment instructions

2025-10-26: Comprehensive Documentation Update

  • Lead: Glenn Thompson
  • Created PROJECT-HISTORY.org with complete timeline
  • Updated all documentation dates to 2025-10-26
  • Added current features across all docs
  • Updated repository URLs to GitHub
  • Documentation version 3.0

2025-10-28: Documentation Refinements

  • Lead: Glenn Thompson
  • Fixed music directory location (asteroid/music/ not docker/music/)
  • Removed redundant Python/JavaScript examples from API docs
  • Added package manager notes for cross-distribution compatibility
  • Clarified symlink support for music directories

2025-11-01: Documentation Merge and Cleanup

  • Lead: Glenn Thompson
  • Merged upstream Docker deployment documentation
  • Removed obsolete session notes
  • Synchronized with upstream/main
  • Prepared comprehensive documentation PR

Development Statistics

Contributors (by commit count)

  1. Glenn Thompson (glenneth/Glenneth) - 135+ commits
  2. Brian O'Reilly (Fade) - 55+ commits
  3. Luis Pereira (easilok) - 23+ commits

Total Commits: 213+ commits

Active Development Period

  • Start: August 12, 2025
  • Current: November 1, 2025
  • Duration: ~2.75 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 (streams and application)
  • ✅ Docker Compose orchestration
  • ✅ Dockerfile for Asteroid application
  • ✅ Environment variable configuration
  • ✅ 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 (November 2025)

Production Ready Features

  • Full music streaming platform
  • User management system
  • Admin control panel
  • DJ controls
  • Multiple player modes
  • Complete Docker deployment (streams + application)
  • Multi-environment support with dynamic URLs
  • Comprehensive documentation

Active Development Areas

  • PostgreSQL migration (configured, ready for data migration)
  • JavaScript code cleanup and refactoring
  • Additional UI improvements
  • Performance optimization
  • Feature expansion based on user feedback

Recent Achievements

  • ✅ Complete Docker containerization
  • ✅ Environment variable configuration
  • ✅ Comprehensive documentation overhaul
  • ✅ Cross-distribution package manager support
  • ✅ Streamlined deployment process

Known Issues & Future Work

  • PostgreSQL migration (configured, pending data migration)
  • Continued UI/UX refinement
  • Additional streaming features (per design.org)
  • Enhanced playlist functionality
  • Live chat and song requests
  • 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.75 months of active development. The project demonstrates the power of Common Lisp for web development and the collaborative nature of open-source development.

With complete Docker deployment, comprehensive documentation, and a growing feature set, Asteroid Radio is ready for production use while continuing to evolve with regular improvements, bug fixes, and new features based on user needs and technical requirements.

Project Links

—

Last Updated: 2025-11-01