- Create `docs/API_DOC.md` as an entry point for developer integrations. - Create `docs/REST_API.md` documenting endpoints, authentication, and QR code pairing. - Rename existing `API_DOC.md` to `docs/AIDL_API.md` to standardize documentation structure. - Update `README.md` to include links and descriptions for both API surfaces.
4.5 KiB
Radio App - Remote Control API Documentation
The Radio app provides a REST API to control playback and query information.
Authentication
If authentication is enabled in the app settings, you must include the pairing code in your requests:
- HTTP Headers: Add
X-Remote-Key: YOUR_CODE - Query Parameter: Add
?token=YOUR_CODE(fallback for images and WebSockets)
Pairing via QR Code
Instead of typing the pairing code manually, the client can display a QR code that you confirm by scanning it with the Radio app. This is the recommended flow for desktop browsers and touch devices.
- The client generates a random
clientIdand a randompairKey(32 bytes) and keeps both to itself. - The client calls
POST /api/pair/start?clientId=YOUR_CLIENT_IDwith the headerX-Pair-Key: YOUR_PAIR_KEYto open a short-lived pairing session. - The client calls
GET /api/qr?clientId=YOUR_CLIENT_IDwith the same header to obtain a PNG QR code containingradio-pair:PAIRING_CODE. The pairing code is a one time value of the session – it is not the secret of your Radio app. - Open Settings → Remote Control → Verify with QR Code in the Radio app and scan the displayed code. The app approves that single session.
- The client polls
GET /api/pair/status?clientId=YOUR_CLIENT_IDwith the same header until it returnspaired: true, then stores the returned token and sends it asX-Remote-Keyon all further requests.
The pairing endpoints are exempt from the pairing code check, so they can be called before a client is approved. A session is only readable with its X-Pair-Key, expires after 15 minutes and is dropped as soon as the token was handed out, so knowing a clientId alone is not enough.
Example Usage (JavaScript)
const clientId = crypto.randomUUID();
const pairKey = 'random 32 byte hex string';
const pairHeaders = { 'X-Pair-Key': pairKey };
await fetch('/api/pair/start?clientId=' + encodeURIComponent(clientId), { method: 'POST', headers: pairHeaders });
const qr = await fetch('/api/qr?clientId=' + encodeURIComponent(clientId), { headers: pairHeaders });
document.getElementById('qr').src = URL.createObjectURL(await qr.blob());
const poll = setInterval(async () => {
const res = await fetch('/api/pair/status?clientId=' + encodeURIComponent(clientId), { headers: pairHeaders });
if (!res.ok) return;
const data = await res.json();
if (data.paired && data.token) {
clearInterval(poll);
localStorage.setItem('radio-token', data.token);
}
}, 2000);
API Reference
GET /api/status
Returns current playback status. Recommended for initial state only; use WebSockets for real-time updates.
Response Example:
{
"isPlaying": true,
"playWhenReady": true,
"playbackState": 3,
"currentStationUuid": "fc080549-...",
"metadata": "Artist - Title",
"starred": true
}
WS /api/updates
WebSocket endpoint for real-time status updates. Pushes status objects whenever state or metadata changes.
Example Usage (JavaScript):
const token = '123456'; // From app settings
const socket = new WebSocket('ws://' + location.host + '/api/updates?token=' + encodeURIComponent(token));
socket.onmessage = (event) => {
const status = JSON.parse(event.data);
console.log('Update received:', status);
};
GET /api/stations
Returns all stations in collection.
Response Example:
[
{
"uuid": "fc080549-...",
"name": "Station Name",
"hasImage": true,
"starred": true
}
]
GET /api/image/{uuid}
Returns the image for a specific station. Supports HTTP caching via ETag and If-None-Match.
Response: Image (binary data, JPEG)
GET /api/config
Returns the app version.
Response Example:
{ "version": "15.1" }
GET /api/stream
Returns the actual live audio stream URI of the currently playing radio station.
Response Example:
{ "status": "http://stream-url.example.com/live.mp3" }
POST /api/play/{uuid}
Starts playback of a specific station.
Response Example:
{ "status": "ok" }
POST /api/pause
Pauses current playback.
Response Example:
{ "status": "ok" }
POST /api/resume
Resumes current playback.
Response Example:
{ "status": "ok" }
POST /api/next
Plays the next station.
Response Example:
{ "status": "ok" }
POST /api/prev
Plays the previous station.
Response Example:
{ "status": "ok" }