177 lines
5.0 KiB
Org Mode
177 lines
5.0 KiB
Org Mode
#+TITLE: Asteroid Radio - Interface Reference
|
|
#+AUTHOR: Interface Team
|
|
#+DATE: 2025-10-03
|
|
|
|
* 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
|
|
#+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
|
|
|
|
* 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
|