asteroid/docs/API-REFERENCE.org

#+TITLE: Asteroid Radio - API Reference
#+AUTHOR: Asteroid Radio Development Team
#+DATE: 2025-10-26

* Current Interfaces

Asteroid Radio provides multiple interfaces for different purposes:

1. **REST API** - JSON API for web application and programmatic access (see [[file:API-ENDPOINTS.org][API Endpoints Reference]])
2. **Streaming Endpoints** - Direct audio stream access via Icecast2
3. **Icecast Admin** - Web-based streaming server administration
4. **Liquidsoap Control** - Telnet interface for DJ controls
5. **Docker Management** - Container orchestration and management

** Available Interfaces

*** Streaming Endpoints
- **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)

*** Administrative Interfaces
- **Icecast Admin**: http://localhost:8000/admin/ (admin/asteroid_admin_2024)
- **Liquidsoap Control**: =telnet localhost 1234= (telnet interface)

* Streaming Interface

** Stream Access
All streams are accessible via standard HTTP and can be played in any media player that supports internet radio streams.

*** Testing Stream Connectivity
#+BEGIN_SRC bash
# Test all three streams
curl -I http://localhost:8000/asteroid.mp3     # 128kbps MP3
curl -I http://localhost:8000/asteroid.aac     # 96kbps AAC  
curl -I http://localhost:8000/asteroid-low.mp3 # 64kbps MP3
#+END_SRC

*** Playing Streams
#+BEGIN_SRC bashfutu
# With VLC
vlc http://localhost:8000/asteroid.mp3

# With mpv  
mpv http://localhost:8000/asteroid.aac

# With curl (save to file)
curl http://localhost:8000/asteroid-low.mp3 > stream.mp3
#+END_SRC

* Icecast Admin Interface

** Web Administration
Access the Icecast admin interface at http://localhost:8000/admin/

*** Login Credentials
- **Username**: admin
- **Password**: asteroid_admin_2024

*** Available Functions
- **Stream Status**: View current streams and listener counts
- **Mount Points**: Manage stream mount points  
- **Listener Statistics**: Real-time listener data
- **Server Configuration**: View server settings
- **Log Files**: Access server logs

** Icecast Status XML
Get server status in XML format:
#+BEGIN_SRC bash
curl http://localhost:8000/admin/stats.xml
#+END_SRC

** Stream Statistics  
Get individual stream stats:
#+BEGIN_SRC bash
curl http://localhost:8000/admin/stats.xml?mount=/asteroid.mp3
curl http://localhost:8000/admin/stats.xml?mount=/asteroid.aac
curl http://localhost:8000/admin/stats.xml?mount=/asteroid-low.mp3
#+END_SRC

* Liquidsoap Control Interface

** Telnet Access
Connect to Liquidsoap's telnet interface for real-time control:
#+BEGIN_SRC bash
telnet localhost 1234
#+END_SRC

** Available Commands
Once connected via telnet, you can use these commands:

*** Basic Information
#+BEGIN_SRC
help                    # List all available commands
version                 # Show Liquidsoap version
uptime                  # Show server uptime  
#+END_SRC

*** Source Control  
#+BEGIN_SRC
request.queue           # Show current queue
request.push <uri>      # Add track to queue
request.skip            # Skip current track
#+END_SRC

*** Metadata
#+BEGIN_SRC
request.metadata        # Show current track metadata
request.on_air          # Show what's currently playing
#+END_SRC

*** Volume and Audio
#+BEGIN_SRC
var.get amplify         # Get current amplification level
var.set amplify 1.2     # Set amplification level
#+END_SRC

** Telnet Scripting
You can script Liquidsoap commands:
#+BEGIN_SRC bash
# Get current track info
echo "request.metadata" | nc localhost 1234

# Skip current track
echo "request.skip" | nc localhost 1234

# Check queue status
echo "request.queue" | nc localhost 1234
#+END_SRC

* Docker Container Management

** Container Status
#+BEGIN_SRC bash
# Check running containers
docker compose ps

# View logs
docker compose logs icecast
docker compose logs liquidsoap

# Restart services
docker compose restart
#+END_SRC

** Music Library Management
#+BEGIN_SRC bash
# Add music files (container will detect automatically)
cp ~/path/to/music/*.mp3 docker/music/
cp ~/path/to/music/*.flac docker/music/

# Check what Liquidsoap is seeing
echo "request.queue" | nc localhost 1234
#+END_SRC

* REST API

Asteroid Radio includes a comprehensive REST API built with Radiance's =define-api= framework.

** API Documentation

For complete REST API documentation, see **[[file:API-ENDPOINTS.org][API Endpoints Reference]]**.

The API provides:
- **Authentication & User Management** - Login, registration, user administration
- **Track Management** - Browse and search music library
- **Playlist Operations** - Create, manage, and play playlists
- **Player Control** - Play, pause, stop, resume playback
- **Admin Functions** - Library scanning, system management

** Quick API Examples

#+BEGIN_SRC bash
# Get server status
curl http://localhost:8080/api/asteroid/status

# Get authentication status
curl http://localhost:8080/api/asteroid/auth-status

# Get Icecast streaming status
curl http://localhost:8080/api/asteroid/icecast-status

# Get tracks (requires authentication)
curl -b cookies.txt http://localhost:8080/api/asteroid/tracks
#+END_SRC

See **[[file:API-ENDPOINTS.org][API Endpoints Reference]]** for complete documentation of all 15+ endpoints.

* Getting Help

For support with interfaces and streaming setup:
- Check project documentation and troubleshooting guides
- Review Docker container logs for error messages  
- Join our IRC chat room: **#asteroid.music** on **irc.libera.chat**
- Submit issues with detailed system information

This interface reference covers the streaming infrastructure interfaces. For the REST API, see **[[file:API-ENDPOINTS.org][API Endpoints Reference]]**.