asteroid/docs

Asteroid Radio - Documentation Index

• Welcome to Asteroid Radio Documentation
• Quick Start
• Documentation Structure
  • Core Documentation
    • Project Overview
    • Installation Guide
    • Docker Streaming Setup
  • Development & Integration
    • Development Guide
    • API Endpoints Reference
    • Interface Reference
    • Testing Guide
  • Feature Documentation
    • PostgreSQL Setup
    • Playlist System
    • User Management
    • Track Pagination
• Current System Status
  • What's Working Now
  • Stream URLs (when running)
• Getting Started
  • New Users
  • Developers
  • System Administrators
• Support & Community
  • Getting Help
  • Contributing
• About Asteroid Music
• Technical Architecture

Welcome to Asteroid Radio Documentation

Asteroid Radio is a modern internet radio platform designed for developers and music enthusiasts who want to run their own radio stations streaming Asteroid Music - the perfect soundtrack for coding and hacking sessions.

Quick Start

For immediate setup, see:

1. Installation Guide - Get Asteroid Radio running
2. Docker Streaming Setup - Docker-based streaming infrastructure

Documentation Structure

Core Documentation

Project Overview

Complete overview of Asteroid Radio's architecture, technology stack, and vision. Start here to understand what Asteroid Radio is and how it works.

Installation Guide

Comprehensive installation instructions for multiple operating systems, including system requirements, dependencies, and production deployment considerations.

Docker Streaming Setup

Complete guide to the Docker-based streaming infrastructure using Icecast2 and Liquidsoap. Includes container configuration, management scripts, and troubleshooting.

Development & Integration

Development Guide

Development environment setup, contributing guidelines, coding standards, and debugging procedures for developers working on Asteroid Radio.

API Endpoints Reference

Complete documentation of all REST API endpoints including authentication, tracks, playlists, player control, and admin functions.

Interface Reference

Documentation of streaming endpoints, Icecast admin interface, Liquidsoap telnet control, and Docker management commands.

Testing Guide

Automated testing suite documentation, test script usage, and manual testing procedures.

Feature Documentation

PostgreSQL Setup

Database configuration, schema design, and migration guide for PostgreSQL backend.

Playlist System

User playlist functionality including creation, management, and playback features.

User Management

User administration system with role management, authentication, and access control.

Track Pagination

Pagination system for efficient browsing of large music libraries.

Current System Status

What's Working Now

• Web Application: Full-featured web interface with authentication
• REST API: JSON API with 15+ endpoints for programmatic access
• User Management: Registration, login, roles, and profiles
• Music Library: Track management with pagination and search
• Playlists: User playlists with creation and playback
• Web Player: Browser-based audio player with queue management
• Docker Streaming Infrastructure: Icecast2 + Liquidsoap containers
• Three Quality Streams: 128kbps MP3, 96kbps AAC, 64kbps MP3
• Admin Interface: Icecast web admin at http://localhost:8000/admin/
• Liquidsoap DJ Controls: Telnet control via localhost:1234
• Professional Features: Crossfading, normalization, metadata support
• PostgreSQL Database: Persistent data storage with full CRUD operations

Stream URLs (when running)

• High Quality MP3: http://localhost:8000/asteroid.mp3 (128kbps)
• High Quality AAC: http://localhost:8000/asteroid.aac (96kbps)
• Low Quality MP3: http://localhost:8000/asteroid-low.mp3 (64kbps)

Getting Started

New Users

1. Read the Project Overview to understand Asteroid Radio
2. Follow the Installation Guide for your operating system
3. Set up streaming with the Docker Guide

Developers

1. Review the Development Guide for setup procedures
2. Check the API Endpoints Reference for REST API documentation
3. Review the Interface Reference for streaming controls
4. See Testing Guide for automated testing
5. Join our IRC channel: #asteroid.music on irc.libera.chat

System Administrators

1. Follow the Installation Guide production deployment section
2. Review Docker Streaming Setup for container management
3. Monitor system resources and streaming performance

Support & Community

Getting Help

• Documentation: Start with the relevant guide above
• IRC Chat: Join #asteroid.music on irc.libera.chat
• Issues: Submit detailed bug reports with system information
• Logs: Check Docker container logs for troubleshooting

Contributing

• Review the Development Guide for contribution guidelines
• Follow coding standards and testing procedures
• Submit pull requests with clear descriptions

About Asteroid Music

Asteroid Radio streams Asteroid Music - a carefully curated genre designed for developers:

• Focus-Enhancing: Ambient, electronic, and instrumental tracks
• Coding-Optimized: Rhythms that complement programming flow
• Hacker Culture: Music that resonates with developer aesthetics
• Flow State: Tracks selected to maintain deep concentration

This isn't just background music - it's the soundtrack to the hacker lifestyle, designed by hackers for hackers who understand that the right music can elevate your code.

Technical Architecture

Asteroid Radio uses a modern, containerized architecture:

┌─────────────────────────────────────────────────────────────┐
│                    Asteroid Radio Platform                  │
├─────────────────────────────────────────────────────────────┤
│  Streaming Infrastructure (Docker)                         │
│  ├── Icecast2 (HTTP Streaming Server)                     │
│  ├── Liquidsoap (Audio Processing Pipeline)               │
│  └── Multiple Format Support (AAC, MP3)                   │
├─────────────────────────────────────────────────────────────┤
│  Control Interfaces                                        │
│  ├── Icecast Admin Web Interface                          │
│  ├── Liquidsoap Telnet Control                            │
│  └── Docker Container Management                          │
└─────────────────────────────────────────────────────────────┘

For detailed technical information, see the Project Overview.

—

Last Updated: 2025-10-10 Documentation Version: 2.0