mirror of
https://github.com/Michatec/Radio.git
synced 2026-11-17 04:46:53 +01:00
- Define `com.michatec.radio.permission.CONTROL_RADIO` permission in `AndroidManifest.xml` and protect `RadioApiService`. - Add localized string resources for the new IPC permission label and description. - Update AIDL and REST API documentation with permission requirements and WebSocket schemas. - Update bug report template and README links.
194 lines
5.2 KiB
Markdown
194 lines
5.2 KiB
Markdown
# 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.
|
||
|
||
1. The client generates a random `clientId` and a random `pairKey` (32 bytes) and keeps both to itself.
|
||
2. The client calls `POST /api/pair/start?clientId=YOUR_CLIENT_ID` with the header `X-Pair-Key: YOUR_PAIR_KEY` to open a short-lived pairing session.
|
||
3. The client calls `GET /api/qr?clientId=YOUR_CLIENT_ID` with the same header to obtain a PNG QR code containing `radio-pair:YOUR_CLIENT_ID:PAIRING_CODE`. The pairing code is a one-time value of the session – it is **not** the secret of your Radio app.
|
||
4. Open **Settings → Remote Control → Verify with QR Code** in the Radio app and scan the displayed code. The app approves that single session.
|
||
5. The client polls `GET /api/pair/status?clientId=YOUR_CLIENT_ID` with the same header until it returns `paired: true`, then stores the returned token and sends it as `X-Remote-Key` on 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)
|
||
|
||
```js
|
||
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
|
||
|
||
### `POST /api/pair/start?clientId=YOUR_CLIENT_ID`
|
||
Starts a pairing session for the given client ID. Must include header `X-Pair-Key: YOUR_PAIR_KEY`.
|
||
|
||
**Response Example:**
|
||
|
||
```json
|
||
{
|
||
"code": "123456",
|
||
"expiresInSeconds": 900
|
||
}
|
||
```
|
||
|
||
### `GET /api/status`
|
||
Returns current playback status. Recommended for initial state only; use WebSockets for real-time updates.
|
||
|
||
**Response Example:**
|
||
|
||
```json
|
||
{
|
||
"isPlaying": true,
|
||
"playWhenReady": true,
|
||
"playbackState": 3,
|
||
"currentStationUuid": "fc080549-...",
|
||
"metadata": "Artist - Title",
|
||
"starred": true
|
||
}
|
||
```
|
||
|
||
### `WS /api/updates`
|
||
WebSocket endpoint for real-time status and collection updates. Pushes wrapper objects (`{ "type": "status" | "stations", "data": ... }`) whenever playback state, metadata, or stations change.
|
||
|
||
**Response Example (Status Update):**
|
||
|
||
```json
|
||
{
|
||
"type": "status",
|
||
"data": {
|
||
"isPlaying": true,
|
||
"playWhenReady": true,
|
||
"playbackState": 3,
|
||
"currentStationUuid": "fc080549-...",
|
||
"metadata": "Artist - Title",
|
||
"starred": true
|
||
}
|
||
}
|
||
```
|
||
|
||
**Example Usage (JavaScript):**
|
||
|
||
```js
|
||
const token = '123456'; // From app settings or QR pairing
|
||
const socket = new WebSocket('ws://' + location.host + '/api/updates?token=' + encodeURIComponent(token));
|
||
socket.onmessage = (event) => {
|
||
const message = JSON.parse(event.data);
|
||
if (message.type === 'status') {
|
||
console.log('Status update:', message.data);
|
||
} else if (message.type === 'stations') {
|
||
console.log('Stations update:', message.data);
|
||
}
|
||
};
|
||
```
|
||
|
||
### `GET /api/stations`
|
||
Returns all stations in the collection.
|
||
|
||
**Response Example:**
|
||
|
||
```json
|
||
[
|
||
{
|
||
"uuid": "fc080549-...",
|
||
"name": "Station Name",
|
||
"hasImage": true,
|
||
"starred": true,
|
||
"lastModified": 1700000000000
|
||
}
|
||
]
|
||
```
|
||
|
||
### `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:**
|
||
|
||
```json
|
||
{ "version": "15.1" }
|
||
```
|
||
|
||
### `GET /api/stream`
|
||
Returns the actual live audio stream URI of the currently playing radio station.
|
||
|
||
**Response Example:**
|
||
|
||
```json
|
||
{ "status": "http://stream-url.example.com/live.mp3" }
|
||
```
|
||
|
||
### `POST /api/play/{uuid}`
|
||
Starts playback of a specific station.
|
||
|
||
**Response Example:**
|
||
|
||
```json
|
||
{ "status": "ok" }
|
||
```
|
||
|
||
### `POST /api/pause`
|
||
Pauses current playback.
|
||
|
||
**Response Example:**
|
||
|
||
```json
|
||
{ "status": "ok" }
|
||
```
|
||
|
||
### `POST /api/resume`
|
||
Resumes current playback.
|
||
|
||
**Response Example:**
|
||
|
||
```json
|
||
{ "status": "ok" }
|
||
```
|
||
|
||
### `POST /api/next`
|
||
Plays the next station.
|
||
|
||
**Response Example:**
|
||
|
||
```json
|
||
{ "status": "ok" }
|
||
```
|
||
|
||
### `POST /api/prev`
|
||
Plays the previous station.
|
||
|
||
**Response Example:**
|
||
|
||
```json
|
||
{ "status": "ok" }
|
||
```
|