asteroid/docs/API-REFERENCE.org

Asteroid Radio - API Reference

• Current Interfaces
  • Available Interfaces
    • Streaming Endpoints
    • Administrative Interfaces
• Streaming Interface
  • Stream Access
    • Testing Stream Connectivity
    • Playing Streams
• Icecast Admin Interface
  • Web Administration
    • Login Credentials
    • Available Functions
  • Icecast Status XML
  • Stream Statistics
• Liquidsoap Control Interface
  • Telnet Access
  • Available Commands
    • Basic Information
    • Source Control
    • Metadata
    • Volume and Audio
  • Telnet Scripting
• Docker Container Management
  • Container Status
  • Music Library Management
• REST API
  • API Documentation
  • Quick API Examples
• Getting Help

Current Interfaces

Asteroid Radio provides multiple interfaces for different purposes:

1. REST API - JSON API for web application and programmatic access (see 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

# 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

Playing Streams

# 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

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:

curl http://localhost:8000/admin/stats.xml

Stream Statistics

Get individual stream stats:

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

Liquidsoap Control Interface

Telnet Access

Connect to Liquidsoap's telnet interface for real-time control:

telnet localhost 1234

Available Commands

Once connected via telnet, you can use these commands:

Basic Information

help                    # List all available commands
version                 # Show Liquidsoap version
uptime                  # Show server uptime

Source Control

request.queue           # Show current queue
request.push <uri>      # Add track to queue
request.skip            # Skip current track

Metadata

request.metadata        # Show current track metadata
request.on_air          # Show what's currently playing

Volume and Audio

var.get amplify         # Get current amplification level
var.set amplify 1.2     # Set amplification level

Telnet Scripting

You can script Liquidsoap commands:

# 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

Docker Container Management

Container Status

# Check running containers
docker compose ps

# View logs
docker compose logs icecast
docker compose logs liquidsoap

# Restart services
docker compose restart

Music Library Management

# 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

REST API

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

API Documentation

For complete REST API documentation, see 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

# 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

See 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 API Endpoints Reference.