PROJECT-OVERVIEW.org
1 #+TITLE: Asteroid Radio - Project Overview 2 #+AUTHOR: Glenn Thompson & Brian O'Reilly (Fade) 3 #+DATE: 2025-10-26 4 5 * 🎯 Mission 6 7 Asteroid Radio is a modern, web-based music streaming platform designed for hackers and music enthusiasts. Built with Common Lisp and the Radiance web framework, it combines the power of functional programming with contemporary web technologies. 8 9 * 🏗️ Architecture 10 11 ** Core Components 12 13 #+BEGIN_EXAMPLE 14 ┌─────────────────────────────────────────────────────────────┐ 15 │ Asteroid Radio Platform │ 16 ├─────────────────────────────────────────────────────────────┤ 17 │ Web Application Layer (Common Lisp + Radiance) │ 18 │ ├── Authentication & User Management │ 19 │ ├── Music Library Management │ 20 │ ├── Web Player Interface │ 21 │ └── API Endpoints │ 22 ├─────────────────────────────────────────────────────────────┤ 23 │ Streaming Infrastructure (Docker) │ 24 │ ├── Icecast2 (Streaming Server) │ 25 │ ├── Liquidsoap (Audio Processing) │ 26 │ └── Multiple Format Support (AAC, MP3) │ 27 ├─────────────────────────────────────────────────────────────┤ 28 │ Data Layer │ 29 │ ├── PostgreSQL Database (via Radiance) │ 30 │ ├── User Accounts & Profiles │ 31 │ └── Music Metadata │ 32 └─────────────────────────────────────────────────────────────┘ 33 ``` 34 35 ### Technology Stack 36 37 **Backend:** 38 - **Common Lisp** (SBCL) - Core application language 39 - **Radiance Framework** - Web framework and module system 40 - **LASS** - CSS preprocessing in Lisp 41 - **PostgreSQL** - Database backend (configured, ready for migration) 42 - **Radiance DB** - Current database abstraction layer 43 44 **Frontend:** 45 - **HTML5** with semantic templates 46 - **CSS3** with dark hacker theme 47 - **JavaScript** for interactive features 48 - **VT323 Font** for retro terminal aesthetic 49 50 **Streaming:** 51 - **Docker Compose** - Container orchestration 52 - **Icecast2** - HTTP streaming server 53 - **Liquidsoap** - Audio processing and encoding 54 - **Multiple Formats** - AAC 96kbps, MP3 128kbps/64kbps 55 56 **Development & Testing:** 57 - **Make** - Build system 58 - **Python** - Performance analysis tools 59 - **Bash** - Testing and deployment scripts 60 61 ## 🎨 Design Philosophy 62 63 ### Visual Theme 64 - **Dark terminal aesthetic** - Black background with colored text 65 - **Hacker-friendly** - Monospace fonts and terminal-inspired UI 66 - **Color scheme** - Black → Blue-grey → Cyan → Blue progression 67 - **Minimalist** - Clean, functional interface without clutter 68 69 ### Technical Principles 70 - **Functional programming** - Leveraging Lisp's strengths 71 - **Modular architecture** - Radiance's interface system 72 - **Performance first** - Sub-1% CPU usage for web app 73 - **Self-contained** - Minimal external dependencies 74 - **Docker-ready** - Containerized streaming infrastructure 75 76 ## 🚀 Features 77 78 ### Current Features 79 - ✅ **User Authentication** - Registration, login, profiles, role-based access (Admin/DJ/Listener) 80 - ✅ **User Management** - Admin interface for user administration 81 - ✅ **Music Library** - Track management with pagination, search, and filtering 82 - ✅ **User Playlists** - Create, manage, and play personal music collections 83 - ✅ **Multiple Player Modes** - Inline, pop-out, and persistent frameset players 84 - ✅ **Stream Queue Control** - Admin control over broadcast stream queue (M3U-based) 85 - ✅ **REST API** - Comprehensive JSON API with 15+ endpoints 86 - ✅ **Music Streaming** - Multiple quality formats (128k MP3, 96k AAC, 64k MP3) 87 - ✅ **Rate Limiting** - Anti-abuse protection 88 - ✅ **Docker Integration** - Icecast2/Liquidsoap streaming infrastructure 89 - ✅ **PostgreSQL Database** - Configured and ready for migration 90 - ✅ **Liquidsoap DJ Controls** - Telnet interface for live control 91 - ✅ **Dynamic Stream URLs** - Automatic host detection for multi-environment support 92 - ✅ **ReplayGain Normalization** - Consistent audio volume across tracks 93 - ✅ **Responsive Design** - Works on desktop and mobile 94 - ✅ **Automated Testing** - Comprehensive test suite 95 96 ### Planned Features 97 - 🔄 **PostgreSQL Migration** - Full migration from Radiance DB to PostgreSQL 98 - 🔄 **Enhanced Playlist Management** - Full CRUD operations with PostgreSQL 99 - 🔄 **Social Features** - Playlist sharing and discovery 100 - 🔄 **Advanced Search** - Full-text search and filtering 101 - 🔄 **Mobile App** - Native mobile applications 102 - 🔄 **WebSocket Support** - Real-time updates 103 - 🔄 **Analytics** - Listening statistics and insights 104 - 🔄 **Scheduled Programming** - Time-based queue switching 105 106 107 ## 🔮 Vision 108 109 Asteroid Radio is the premier streaming platform for **Asteroid Music** - the perfect soundtrack for developers, hackers, and anyone who spends hours deep in code. Our mission is to curate and deliver music that enhances focus, creativity, and the flow state that every programmer knows. 110 111 **What is Asteroid Music?** 112 - **Focus-Enhancing** - Ambient, electronic, and instrumental tracks that don't distract 113 - **Coding-Optimized** - Rhythms and textures that complement the mental rhythm of programming 114 - **Hacker Culture** - Music that resonates with the developer mindset and aesthetic 115 - **Flow State** - Carefully selected tracks that help maintain deep concentration 116 117 **Platform Features:** 118 - **Multi-Format Streaming** - High-quality AAC, MP3 128k, and MP3 64k streams 119 - **User Community** - Accounts, playlists, and sharing among fellow developers 120 - **Developer-Friendly** - Built with Common Lisp, fully hackable and extensible 121 - **Professional Quality** - Crossfading, normalization, metadata, and telnet control 122 - **Always-On Broadcasting** - Continuous streams perfect for long coding sessions 123 124 Asteroid Radio isn't just another music platform - it's the soundtrack to the hacker lifestyle, designed by hackers for hackers who understand that the right music can make the difference between good code and great code.