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

6.8 KiB
Raw Blame History

Asteroid Radio - Project Overview

🎯 Mission

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.

🏗️ Architecture

Core Components

#+BEGIN_EXAMPLE ┌─────────────────────────────────────────────────────────────┐ │ Asteroid Radio Platform │ ├─────────────────────────────────────────────────────────────┤ │ Web Application Layer (Common Lisp + Radiance) │ │ ├── Authentication & User Management │ │ ├── Music Library Management │ │ ├── Web Player Interface │ │ └── API Endpoints │ ├─────────────────────────────────────────────────────────────┤ │ Streaming Infrastructure (Docker) │ │ ├── Icecast2 (Streaming Server) │ │ ├── Liquidsoap (Audio Processing) │ │ └── Multiple Format Support (AAC, MP3) │ ├─────────────────────────────────────────────────────────────┤ │ Data Layer │ │ ├── PostgreSQL Database (via Radiance) │ │ ├── User Accounts & Profiles │ │ └── Music Metadata │ └─────────────────────────────────────────────────────────────┘ ```

### Technology Stack

Backend:

  • Common Lisp (SBCL) - Core application language
  • Radiance Framework - Web framework and module system
  • LASS - CSS preprocessing in Lisp
  • PostgreSQL - Database backend (configured, ready for migration)
  • Radiance DB - Current database abstraction layer

Frontend:

  • HTML5 with semantic templates
  • CSS3 with dark hacker theme
  • JavaScript for interactive features
  • VT323 Font for retro terminal aesthetic

Streaming:

  • Docker Compose - Container orchestration
  • Icecast2 - HTTP streaming server
  • Liquidsoap - Audio processing and encoding
  • Multiple Formats - AAC 96kbps, MP3 128kbps/64kbps

Development & Testing:

  • Make - Build system
  • Python - Performance analysis tools
  • Bash - Testing and deployment scripts

## 🎨 Design Philosophy

### Visual Theme

  • Dark terminal aesthetic - Black background with colored text
  • Hacker-friendly - Monospace fonts and terminal-inspired UI
  • Color scheme - Black → Blue-grey → Cyan → Blue progression
  • Minimalist - Clean, functional interface without clutter

### Technical Principles

  • Functional programming - Leveraging Lisp's strengths
  • Modular architecture - Radiance's interface system
  • Performance first - Sub-1% CPU usage for web app
  • Self-contained - Minimal external dependencies
  • Docker-ready - Containerized streaming infrastructure

## 🚀 Features

### Current Features

  • ✅ User Authentication - Registration, login, profiles, role-based access (Admin/DJ/Listener)
  • ✅ User Management - Admin interface for user administration
  • ✅ Music Library - Track management with pagination, search, and filtering
  • ✅ User Playlists - Create, manage, and play personal music collections
  • ✅ Multiple Player Modes - Inline, pop-out, and persistent frameset players
  • ✅ Stream Queue Control - Admin control over broadcast stream queue (M3U-based)
  • ✅ REST API - Comprehensive JSON API with 15+ endpoints
  • ✅ Music Streaming - Multiple quality formats (128k MP3, 96k AAC, 64k MP3)
  • ✅ Rate Limiting - Anti-abuse protection
  • ✅ Docker Integration - Icecast2/Liquidsoap streaming infrastructure
  • ✅ PostgreSQL Database - Configured and ready for migration
  • ✅ Liquidsoap DJ Controls - Telnet interface for live control
  • ✅ Dynamic Stream URLs - Automatic host detection for multi-environment support
  • ✅ ReplayGain Normalization - Consistent audio volume across tracks
  • ✅ Responsive Design - Works on desktop and mobile
  • ✅ Automated Testing - Comprehensive test suite

### Planned Features

  • 🔄 PostgreSQL Migration - Full migration from Radiance DB to PostgreSQL
  • 🔄 Enhanced Playlist Management - Full CRUD operations with PostgreSQL
  • 🔄 Social Features - Playlist sharing and discovery
  • 🔄 Advanced Search - Full-text search and filtering
  • 🔄 Mobile App - Native mobile applications
  • 🔄 WebSocket Support - Real-time updates
  • 🔄 Analytics - Listening statistics and insights
  • 🔄 Scheduled Programming - Time-based queue switching

## 🔮 Vision

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.

What is Asteroid Music?

  • Focus-Enhancing - Ambient, electronic, and instrumental tracks that don't distract
  • Coding-Optimized - Rhythms and textures that complement the mental rhythm of programming
  • Hacker Culture - Music that resonates with the developer mindset and aesthetic
  • Flow State - Carefully selected tracks that help maintain deep concentration

Platform Features:

  • Multi-Format Streaming - High-quality AAC, MP3 128k, and MP3 64k streams
  • User Community - Accounts, playlists, and sharing among fellow developers
  • Developer-Friendly - Built with Common Lisp, fully hackable and extensible
  • Professional Quality - Crossfading, normalization, metadata, and telnet control
  • Always-On Broadcasting - Continuous streams perfect for long coding sessions

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.