1  #+TITLE: Asteroid Radio - API Reference
  2  #+AUTHOR: Asteroid Radio Development Team
  3  #+DATE: 2025-10-26
  4  
  5  * Current Interfaces
  6  
  7  Asteroid Radio provides multiple interfaces for different purposes:
  8  
  9  1. **REST API** - JSON API for web application and programmatic access (see [[file:API-ENDPOINTS.org][API Endpoints Reference]])
 10  2. **Streaming Endpoints** - Direct audio stream access via Icecast2
 11  3. **Icecast Admin** - Web-based streaming server administration
 12  4. **Liquidsoap Control** - Telnet interface for DJ controls
 13  5. **Docker Management** - Container orchestration and management
 14  
 15  ** Available Interfaces
 16  
 17  *** Streaming Endpoints
 18  - **High Quality MP3**: http://localhost:8000/asteroid.mp3 (128kbps)
 19  - **High Quality AAC**: http://localhost:8000/asteroid.aac (96kbps) 
 20  - **Low Quality MP3**: http://localhost:8000/asteroid-low.mp3 (64kbps)
 21  
 22  *** Administrative Interfaces
 23  - **Icecast Admin**: http://localhost:8000/admin/ (admin/asteroid_admin_2024)
 24  - **Liquidsoap Control**: =telnet localhost 1234= (telnet interface)
 25  
 26  * Streaming Interface
 27  
 28  ** Stream Access
 29  All streams are accessible via standard HTTP and can be played in any media player that supports internet radio streams.
 30  
 31  *** Testing Stream Connectivity
 32  #+BEGIN_SRC bash
 33  # Test all three streams
 34  curl -I http://localhost:8000/asteroid.mp3     # 128kbps MP3
 35  curl -I http://localhost:8000/asteroid.aac     # 96kbps AAC  
 36  curl -I http://localhost:8000/asteroid-low.mp3 # 64kbps MP3
 37  #+END_SRC
 38  
 39  *** Playing Streams
 40  #+BEGIN_SRC bashfutu
 41  # With VLC
 42  vlc http://localhost:8000/asteroid.mp3
 43  
 44  # With mpv  
 45  mpv http://localhost:8000/asteroid.aac
 46  
 47  # With curl (save to file)
 48  curl http://localhost:8000/asteroid-low.mp3 > stream.mp3
 49  #+END_SRC
 50  
 51  * Icecast Admin Interface
 52  
 53  ** Web Administration
 54  Access the Icecast admin interface at http://localhost:8000/admin/
 55  
 56  *** Login Credentials
 57  - **Username**: admin
 58  - **Password**: asteroid_admin_2024
 59  
 60  *** Available Functions
 61  - **Stream Status**: View current streams and listener counts
 62  - **Mount Points**: Manage stream mount points  
 63  - **Listener Statistics**: Real-time listener data
 64  - **Server Configuration**: View server settings
 65  - **Log Files**: Access server logs
 66  
 67  ** Icecast Status XML
 68  Get server status in XML format:
 69  #+BEGIN_SRC bash
 70  curl http://localhost:8000/admin/stats.xml
 71  #+END_SRC
 72  
 73  ** Stream Statistics  
 74  Get individual stream stats:
 75  #+BEGIN_SRC bash
 76  curl http://localhost:8000/admin/stats.xml?mount=/asteroid.mp3
 77  curl http://localhost:8000/admin/stats.xml?mount=/asteroid.aac
 78  curl http://localhost:8000/admin/stats.xml?mount=/asteroid-low.mp3
 79  #+END_SRC
 80  
 81  * Liquidsoap Control Interface
 82  
 83  ** Telnet Access
 84  Connect to Liquidsoap's telnet interface for real-time control:
 85  #+BEGIN_SRC bash
 86  telnet localhost 1234
 87  #+END_SRC
 88  
 89  ** Available Commands
 90  Once connected via telnet, you can use these commands:
 91  
 92  *** Basic Information
 93  #+BEGIN_SRC
 94  help                    # List all available commands
 95  version                 # Show Liquidsoap version
 96  uptime                  # Show server uptime  
 97  #+END_SRC
 98  
 99  *** Source Control  
100  #+BEGIN_SRC
101  request.queue           # Show current queue
102  request.push <uri>      # Add track to queue
103  request.skip            # Skip current track
104  #+END_SRC
105  
106  *** Metadata
107  #+BEGIN_SRC
108  request.metadata        # Show current track metadata
109  request.on_air          # Show what's currently playing
110  #+END_SRC
111  
112  *** Volume and Audio
113  #+BEGIN_SRC
114  var.get amplify         # Get current amplification level
115  var.set amplify 1.2     # Set amplification level
116  #+END_SRC
117  
118  ** Telnet Scripting
119  You can script Liquidsoap commands:
120  #+BEGIN_SRC bash
121  # Get current track info
122  echo "request.metadata" | nc localhost 1234
123  
124  # Skip current track
125  echo "request.skip" | nc localhost 1234
126  
127  # Check queue status
128  echo "request.queue" | nc localhost 1234
129  #+END_SRC
130  
131  * Docker Container Management
132  
133  ** Container Status
134  #+BEGIN_SRC bash
135  # Check running containers
136  docker compose ps
137  
138  # View logs
139  docker compose logs icecast
140  docker compose logs liquidsoap
141  
142  # Restart services
143  docker compose restart
144  #+END_SRC
145  
146  ** Music Library Management
147  #+BEGIN_SRC bash
148  # Add music files (container will detect automatically)
149  cp ~/path/to/music/*.mp3 docker/music/
150  cp ~/path/to/music/*.flac docker/music/
151  
152  # Check what Liquidsoap is seeing
153  echo "request.queue" | nc localhost 1234
154  #+END_SRC
155  
156  * REST API
157  
158  Asteroid Radio includes a comprehensive REST API built with Radiance's =define-api= framework.
159  
160  ** API Documentation
161  
162  For complete REST API documentation, see **[[file:API-ENDPOINTS.org][API Endpoints Reference]]**.
163  
164  The API provides:
165  - **Authentication & User Management** - Login, registration, user administration
166  - **Track Management** - Browse and search music library
167  - **Playlist Operations** - Create, manage, and play playlists
168  - **Player Control** - Play, pause, stop, resume playback
169  - **Admin Functions** - Library scanning, system management
170  
171  ** Quick API Examples
172  
173  #+BEGIN_SRC bash
174  # Get server status
175  curl http://localhost:8080/api/asteroid/status
176  
177  # Get authentication status
178  curl http://localhost:8080/api/asteroid/auth-status
179  
180  # Get Icecast streaming status
181  curl http://localhost:8080/api/asteroid/icecast-status
182  
183  # Get tracks (requires authentication)
184  curl -b cookies.txt http://localhost:8080/api/asteroid/tracks
185  #+END_SRC
186  
187  See **[[file:API-ENDPOINTS.org][API Endpoints Reference]]** for complete documentation of all 15+ endpoints.
188  
189  * Getting Help
190  
191  For support with interfaces and streaming setup:
192  - Check project documentation and troubleshooting guides
193  - Review Docker container logs for error messages  
194  - Join our IRC chat room: **#asteroid.music** on **irc.libera.chat**
195  - Submit issues with detailed system information
196  
197  This interface reference covers the streaming infrastructure interfaces. For the REST API, see **[[file:API-ENDPOINTS.org][API Endpoints Reference]]**.