asteroid/docs/API-REFERENCE.org

Asteroid Radio - Interface 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
• Future Development
  • Potential REST API
• Getting Help

Current Interfaces

Asteroid Radio currently operates as a Docker-based streaming platform using Icecast2 and Liquidsoap. The system provides streaming interfaces and control mechanisms rather than a traditional REST API.

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

Future Development

Potential REST API

A REST API may be developed in the future if deemed necessary for:

• Web Interface: Browser-based control panel
• Mobile Applications: Native mobile apps
• Third-party Integration: External service integration
• User Management: Account and playlist management

Such an API would likely be built using the RADIANCE Common Lisp web framework and would provide endpoints for:

• Track and playlist management
• User authentication and profiles
• Streaming control and statistics
• System administration

However, the current Docker streaming setup provides all essential functionality through existing interfaces (Icecast admin, Liquidsoap telnet, and direct stream access).

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 all currently available methods for interacting with Asteroid Radio's streaming infrastructure.

#+END_SRC