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

17 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

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

Phase 9: Production Launch & Feature Expansion (November - December 2025)

Early November: Template & Deployment Stabilization

  • Lead: Glenn Thompson, Brian O'Reilly
  • Changed template extension to match CLIP documentation (.ctml)
  • Updated all template paths in calling code
  • Refactored for Lispy improvements (templates, strings, error handling)
  • Deployment and post-deployment fixes
  • Fixed redirection when navigating between frameset views
  • Stream quality persistence in local storage
  • Security: Removed hardcoded admin credentials from login page
  • Stream service containers locked to localhost access

Mid-November: Password Management & Data Model Refactoring

  • Lead: Glenn Thompson, Luis Pereira
  • Password management and listener count fixes
  • Database schema bug fixes from upstream merge
  • User database methods moved to data-model
  • Admin button visibility restricted to admin accounts
  • Profile password change fixes
  • Playlist creation fixes on frontend

Late November: Recently Played & MusicBrainz Integration

  • Lead: Glenn Thompson
  • Recently played tracks feature with MusicBrainz integration
  • Favicon and asteroid.png graphics added to front page
  • User activate/deactivate routes
  • User role update routes
  • Track name clickable with external link icon
  • Audio player color matched to app panels
  • Blinking live cursor added

Late November: Spectrum Analyzer & Parenscript Conversion

  • Lead: Glenn Thompson
  • Real-time spectrum analyzer using Web Audio API
  • Parenscript (Lisp-to-JavaScript) implementation
  • Spectrum analyzer theming and visualization styles
  • Monotone theme and dynamic border color
  • HTML entity decoding fixes in now playing titles
  • JavaScript converted to Parenscript with stream fixes

Early December: PostgreSQL Integration & Database Work

  • Lead: Brian O'Reilly, Glenn Thompson
  • PostgreSQL interface integration (i-postmodern)
  • Users table case sensitivity fixes
  • Database credentials sourced from environment
  • M3U files moved to dedicated playlists directory
  • Database creation script corrections
  • User dump/restore to CSV functionality

Mid-December: Player Improvements & Listener Statistics

  • Lead: Glenn Thompson / Cascade
  • Wedged player fix with reconnect button and volume preservation
  • Status page for frameset mode with navigation fixes
  • Listener statistics feature with geo stats collection
  • City-level tracking in geo stats
  • Expandable city breakdown in admin view
  • Liquidsoap/Icecast controls added
  • Library scan fixes

Mid-December: Shuffle Mount & Channel Selector

  • Lead: Glenn Thompson
  • Shuffle stream mount with separate recently-played tracking
  • Channel/quality selector separation
  • Dynamic playlist phase names
  • Dynamic channel name updates
  • Playlist crossfade transitions
  • New playlists in support of variety

Late December: Playlist Scheduler & User Features

  • Lead: Glenn Thompson
  • Automatic playlist scheduler with cl-cron
  • Admin UI for playlist scheduler with server time display
  • Database persistence for playlist schedule
  • Track favorites feature with star button
  • Listening history tracking
  • Listening activity chart on profile page
  • Avatar upload functionality
  • Track requests and profile enhancements

Late December: Custom Playlists & Rate Limiting

  • Lead: Glenn Thompson, Luis Pereira
  • Custom user playlists with submission and admin review
  • YP directory listings for internet-radio.com and xiph.org
  • Rate limiting macros for define-page and define-api
  • Bigger rate limits for now-playing API routes
  • Favorites sync between front page and frame player via postMessage
  • Listening history refactored to data-model
  • Timestamp normalization for PostgreSQL compatibility

December 31: Version 1.0 & Operations

  • Lead: Brian O'Reilly
  • Declared "Version 1.0" milestone
  • TODO.org updated to reflect production launch
  • Operations procedures instituted
  • Repository cleanup of interstitial files

Development Statistics

Contributors (by commit count)

  1. Glenn Thompson (glenneth/Glenneth) - 354 commits
  2. Brian O'Reilly (Fade) - 148 commits
  3. Luis Pereira (easilok) - 109 commits

Total Commits: 614 commits

Pull Requests Merged: 88

  1. Glenn Thompson (glenneth1) - 59 PRs
  2. Luis Pereira (easilok) - 26 PRs
  3. Brian O'Reilly (fade) - 3 PRs

Active Development Period

  • Start: August 12, 2025
  • Current: January 26, 2026
  • Duration: ~5.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 (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

Phase 10: Documentation Overhaul (January 2026)

2026-01-26: Comprehensive Documentation Update

  • Lead: Glenn Thompson / Cascade
  • Major documentation alignment with current codebase
  • Standardized all API endpoint references to `/api/asteroid/` base path
  • Updated UI route documentation to reflect root `/` mounting
  • Corrected template file extensions from `.chtml` to `.ctml`
  • Fixed Docker music library paths (`music/library/` standardization)
  • Updated stream queue file location to `playlists/stream-queue.m3u`
  • Expanded API-ENDPOINTS.org with playlist management, stream control, and admin APIs
  • Updated all metadata dates to 2026-01-26
  • Bumped documentation version to 3.1
  • Author metadata standardization (Glenn → Glenn Thompson where applicable)

Current State (January 2026)

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 (January 2026)

  • Complete documentation overhaul aligning docs with codebase
  • API endpoint standardization (`/api/asteroid/` base path)
  • Docker deployment fully documented
  • Documentation version 3.1 released
  • All metadata updated and consistent

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 over 5+ 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: 2026-01-26