feat: require custom CONTROL_RADIO permission for RadioApiService

- 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.
This commit is contained in:
Michatec committed 2026-11-16 13:39:31 +01:00
1 parent 2d52ae5cee
commit 2895e0905d
16 files changed
+119 -42

No files matched your search

+7 -9
View File
@@ -23,16 +23,14 @@ A clear and concise description of what you expected to happen.
**Screenshots**
If applicable, add screenshots to help explain your problem.
**Desktop (please complete the following information):**
- OS: [e.g. iOS]
- Browser [e.g. chrome, safari]
- Version [e.g. 22]
**Device & OS:**
- Device: [e.g. Google Pixel 8, Android TV, Chromecast with Google TV]
- OS / Android Version: [e.g. Android 14, Android TV 12]
- Radio App Version: [e.g. 15.2]
**Smartphone (please complete the following information):**
- Device: [e.g. iPhone6]
- OS: [e.g. iOS8.1]
- Browser [e.g. stock browser, safari]
- Version [e.g. 22]
**Web Remote Control (if applicable):**
- OS: [e.g. Windows 11, macOS, Linux]
- Browser: [e.g. Chrome 122, Firefox 123]
**Additional context**
Add any other context about the problem here.
+9 -8
View File
@@ -9,8 +9,8 @@
### ℹ️ About Radio
**Radio is an application with a minimalist approach to listening to radio over the Internet.** <br>
**Radio only offers a basic search option, and it imports audio streaming links when you tap them in a web browser.** <br>
**Radio 15.1+ features support for Android TV and Google Cast, along with a Web Control interface and a developer API.** <br>
**Pull request are welcome at any time.**<br>
**Radio 15.1+ features support for Android TV and Google Cast, along with a Web Control interface and a developer API.** <br>
**Pull requests are welcome at any time.**<br>
**Radio is free software. It is released under the [GPLv3 open source license](https://opensource.org/licenses/GPL-3.0).**
</div>
@@ -49,8 +49,8 @@ Since the developers of this app do not agree to this requirement, this app will
<details>
<summary>💡 Frequent Questions</summary>
<br>
Q: How can I add a radio station
A: There are three ways to add a radio station to Radio: Use Search, add playlist file address (M3U, PLS), enter a raw stream address. The last way will not support the update feature.
Q: How can I add a radio station?
A: There are three ways to add a radio station to Radio: Use Search, add a playlist file address (M3U, PLS), or enter a raw stream address. The last way will not support the update feature.
-------------------------------------------------------------------------
@@ -60,8 +60,8 @@ A: The update feature will try to fetch the current stream address of a station
-------------------------------------------------------------------------
Q: Where do the radio station search results come from?
A: Radio searches the [radio-browser.info](http://www.radio-browser.info/) online database.
You can help out the radio-browser.info community by [adding the missing station](http://www.radio-browser.info/gui/#!/add) to their database.
A: Radio searches the [radio-browser.info](https://www.radio-browser.info/) online database.
You can help out the radio-browser.info community by [adding the missing station](https://www.radio-browser.info/add) to their database.
</details>
----------------------------------------
@@ -115,6 +115,7 @@ Starting with version **15.2**, Radio exposes an AIDL-based API (`com.michatec.r
- **Package:** `com.michatec.radio`
- **Service:** `com.michatec.radio.api.RadioApiService`
- **AIDL Interface:** `com.michatec.radio.api.IRadioApi`
- **Permission:** `com.michatec.radio.permission.CONTROL_RADIO`
**Available features:**
- Play, pause, stop and check playback state
@@ -157,7 +158,7 @@ When **Edit Stations** is enabled:
**General TV** Controls:
- Press **0** or **DEL** to remove the selected radio station
- Press **1** or **SPACE** to make the selected radio station favourite
- Press **1** or **SPACE** to make the selected radio station favorite
- Press **2** or **PLUS** to reorder the selected radio station
</details>
@@ -167,7 +168,7 @@ When **Edit Stations** is enabled:
<details>
<summary>📜️ Credit</summary>
- [Radio Browser](http://www.radio-browser.info/) for providing the radio station database
- [Radio Browser](https://www.radio-browser.info/) for providing the radio station database
- [AndroidX Leanback](https://developer.android.com/jetpack/androidx/releases/leanback) for providing the Android TV UI components
- Michatec for developing the app and maintaining the project
+8 -1
View File
@@ -23,6 +23,13 @@
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" />
<!-- CUSTOM IPC PERMISSION FOR AIDL API -->
<permission
android:name="com.michatec.radio.permission.CONTROL_RADIO"
android:label="@string/permission_control_radio_label"
android:description="@string/permission_control_radio_description"
android:protectionLevel="normal" />
<attribution
android:tag="MediaPlayback"
android:label="@string/app_name" />
@@ -168,7 +175,7 @@
android:name=".api.RadioApiService"
android:enabled="true"
android:exported="true"
tools:ignore="ExportedService">
android:permission="com.michatec.radio.permission.CONTROL_RADIO">
<intent-filter>
<action android:name="com.michatec.radio.api.RadioApiService" />
</intent-filter>
+3
View File
@@ -1,5 +1,8 @@
<?xml version="1.0" encoding="utf-8"?>
<resources>
<!-- Permissions -->
<string name="permission_control_radio_label">Styr Radio-afspilning</string>
<string name="permission_control_radio_description">Tillader programmer at styre Radio-afspilning, læse stationslister og modtage afspilningsstatus via IPC.</string>
<!-- Appnavn -->
<!-- Tilgængelighedsbeskrivelser -->
<string name="descr_app_icon">App-ikon i form af en gammel radio</string>
+4
View File
@@ -1,6 +1,10 @@
<?xml version="1.0" encoding="utf-8"?>
<resources>
<!-- App Name -->
<!-- Permissions -->
<string name="permission_control_radio_label">Radio-Wiedergabe steuern</string>
<string name="permission_control_radio_description">Ermöglicht Apps die Steuerung der Radio-Wiedergabe, das Auslesen von Senderlisten und den Empfang des Wiedergabestatus über IPC.</string>
<!-- Accessibility Descriptions -->
<string name="descr_app_icon">App-Symbol in der Form eines alten Radios</string>
<string name="descr_card_small_play_button">Start/Stopp</string>
+3
View File
@@ -1,5 +1,8 @@
<?xml version="1.0" encoding="utf-8"?>
<resources>
<!-- Permissions -->
<string name="permission_control_radio_label">Έλεγχος αναπαραγωγής Radio</string>
<string name="permission_control_radio_description">Επιτρέπει σε εφαρμογές να ελέγχουν την αναπαραγωγή, να διαβάζουν λίστες σταθμών και να λαμβάνουν κατάσταση αναπαραγωγής μέσω IPC.</string>
<!-- App Name -->
<!-- Accessibility Descriptions -->
<string name="descr_app_icon">Εικονίδιο εφαρμογής που απεικονίζει παλιό ραδιόφωνο</string>
+3
View File
@@ -1,5 +1,8 @@
<?xml version="1.0" encoding="utf-8"?>
<resources>
<!-- Permissions -->
<string name="permission_control_radio_label">Contrôler la lecture Radio</string>
<string name="permission_control_radio_description">Permet aux applications de contrôler la lecture Radio, de lire la liste des stations et de recevoir l\état de lecture via IPC.</string>
<!-- Nom de l'application -->
<!-- Descriptions d'accessibilité -->
<string name="descr_app_icon">Icône de lapplication en forme dancienne radio</string>
+3
View File
@@ -1,5 +1,8 @@
<?xml version="1.0" encoding="utf-8"?>
<resources>
<!-- Permissions -->
<string name="permission_control_radio_label">Radioの再生を制御</string>
<string name="permission_control_radio_description">アプリがIPCを介してRadioの再生を制御し、局リストを読み取り、再生状態を受信できるようにします。</string>
<!-- アプリ名 -->
<!-- アクセシビリティの説明 -->
<string name="descr_app_icon">昔のラジオの形をしたアプリアイコン</string>
+3
View File
@@ -1,5 +1,8 @@
<?xml version="1.0" encoding="utf-8"?>
<resources>
<!-- Permissions -->
<string name="permission_control_radio_label">Radio-afspelen bedienen</string>
<string name="permission_control_radio_description">Stelt apps in staat om het afspelen van Radio te bedienen, zenderlijsten te lezen en de afspeelstatus via IPC te ontvangen.</string>
<!-- App Name -->
<!-- Accessibility Descriptions -->
<string name="descr_app_icon">App icoon die een oude radio afbeeld</string>
+3
View File
@@ -1,5 +1,8 @@
<?xml version="1.0" encoding="utf-8"?>
<resources>
<!-- Permissions -->
<string name="permission_control_radio_label">Sterowanie odtwarzaniem Radio</string>
<string name="permission_control_radio_description">Zezwala aplikacjom na sterowanie odtwarzaniem Radio, odczytywanie list stacji i odbieranie stanu odtwarzania przez IPC.</string>
<!-- App Name -->
<!-- Accessibility Descriptions -->
<string name="descr_app_icon">Ikona aplikacji przedstawiająca stare radio</string>
+3
View File
@@ -1,5 +1,8 @@
<?xml version="1.0" encoding="utf-8"?>
<resources>
<!-- Permissions -->
<string name="permission_control_radio_label">Управление воспроизведением Radio</string>
<string name="permission_control_radio_description">Позволяет приложениям управлять воспроизведением Radio, читать списки станций и получать статус воспроизведения через IPC.</string>
<!-- App Name -->
<!-- Accessibility Descriptions -->
<string name="descr_app_icon">Значок приложения с изображением старого радио</string>
+3
View File
@@ -1,5 +1,8 @@
<?xml version="1.0" encoding="utf-8"?>
<resources>
<!-- Permissions -->
<string name="permission_control_radio_label">Керування відтворенням Radio</string>
<string name="permission_control_radio_description">Дозволяє програмам керувати відтворенням Radio, читати списки станцій та отримувати статус відтворення через IPC.</string>
<!-- App Name -->
<!-- Accessibility Descriptions -->
<string name="descr_app_icon">Значок застосунку із зображенням старого радіо</string>
+4
View File
@@ -4,6 +4,10 @@
<string name="app_version_name" translatable="false">\"Blue\"</string>
<string name="app_name" translatable="false">Radio</string>
<!-- Permissions -->
<string name="permission_control_radio_label">Control Radio playback</string>
<string name="permission_control_radio_description">Allows applications to control Radio playback, read station lists, and receive playback status via IPC.</string>
<!-- Accessibility Descriptions -->
<string name="descr_app_icon">App icon depicting an old radio</string>
<string name="descr_card_small_play_button">Play/stop</string>
+21 -17
View File
@@ -9,6 +9,7 @@ This documentation describes the Android Interface Definition Language (AIDL) AP
- **Package Name:** `com.michatec.radio`
- **Service Class:** `com.michatec.radio.api.RadioApiService`
- **AIDL Interface:** `com.michatec.radio.api.IRadioApi`
- **Permission:** `com.michatec.radio.permission.CONTROL_RADIO`
---
@@ -34,19 +35,19 @@ interface IRadioApi {
### Method Summary
| Method | Return Type | Description |
|:---------------------------------|:------------|:----------------------------------------------------------------------|
| `play()` | `void` | Resumes or starts audio playback. |
| `pause()` | `void` | Pauses audio playback. |
| `stop()` | `void` | Stops audio playback and releases player resources. |
| `isPlaying()` | `boolean` | Returns `true` if audio is currently playing, `false` otherwise. |
| `getCurrentStationName()` | `String` | Returns the display name of the currently active radio station. |
| `getCurrentMetadata()` | `String` | Returns current track metadata/artist info (if available). |
| `playStationByUuid(String uuid)` | `void` | Switches to and plays the radio station matching the specified UUID. |
| `getSavedStationsJson()` | `String` | Returns a JSON array string containing all saved radio stations. |
| `getFavoriteStationsJson()` | `String` | Returns a JSON array string containing all starred/favorite stations. |
| `getCurrentStationImage()` | `byte[]` | Returns raw image bytes of the currently active station cover art. |
| `getStationImageByUuid(String)` | `byte[]` | Returns raw image bytes for the station cover art matching the UUID. |
| Method | Return Type | Description |
|:-------------------------------------|:------------|:----------------------------------------------------------------------|
| `play()` | `void` | Resumes or starts audio playback. |
| `pause()` | `void` | Pauses audio playback. |
| `stop()` | `void` | Stops audio playback and releases player resources. |
| `isPlaying()` | `boolean` | Returns `true` if audio is currently playing, `false` otherwise. |
| `getCurrentStationName()` | `String` | Returns the display name of the currently active radio station. |
| `getCurrentMetadata()` | `String` | Returns current track metadata/artist info (if available). |
| `playStationByUuid(String uuid)` | `void` | Switches to and plays the radio station matching the specified UUID. |
| `getSavedStationsJson()` | `String` | Returns a JSON array string containing all saved radio stations. |
| `getFavoriteStationsJson()` | `String` | Returns a JSON array string containing all starred/favorite stations. |
| `getCurrentStationImage()` | `byte[]` | Returns raw image bytes of the currently active station cover art. |
| `getStationImageByUuid(String uuid)` | `byte[]` | Returns raw image bytes for the station cover art matching the UUID. |
---
@@ -55,16 +56,19 @@ interface IRadioApi {
To control the Radio app from another Android application, follow these steps:
### 1. Declare Required Permission & Queries in `AndroidManifest.xml`
In your client application's `src/main/AndroidManifest.xml`, declare the custom permission required to bind to `RadioApiService`. If targeting Android 11 (API 30) or higher, also include a `<queries>` declaration to ensure package visibility:
In your client application's `src/main/AndroidManifest.xml`, declare the custom permission `com.michatec.radio.permission.CONTROL_RADIO`. If targeting Android 11 (API 30) or higher, also include a `<queries>` declaration to ensure package visibility:
```xml
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<!-- Custom permission required to interact with RadioApiService via IPC -->
<uses-permission android:name="com.michatec.radio.permission.CONTROL_RADIO" />
<!-- Package visibility for Android 11+ (API 30+) -->
<queries>
<package android:name="com.michatec.radio" />
<intent>
<action android:name="com.michatec.radio.api.IRadioApi" />
<action android:name="com.michatec.radio.api.RadioApiService" />
</intent>
</queries>
@@ -251,12 +255,12 @@ class MyActivity : AppCompatActivity() {
radioController.connect()
// Example: Play button click
findViewById<Button>(id.btnPlay).setOnClickListener {
findViewById<Button>(R.id.btnPlay).setOnClickListener {
radioController.play()
}
// Example: Fetch and log all saved stations & cover image
findViewById<Button>(id.btnFetchStations).setOnClickListener {
findViewById<Button>(R.id.btnFetchStations).setOnClickListener {
val savedStations = radioController.getSavedStations()
val favoriteStations = radioController.getFavoriteStations()
val currentImageBytes = radioController.getCurrentStationImage()
+2
View File
@@ -36,6 +36,7 @@ Starting with version **15.2**, Radio provides an AIDL interface that allows ext
- **Package:** `com.michatec.radio`
- **Service:** `com.michatec.radio.api.RadioApiService`
- **Interface:** `com.michatec.radio.api.IRadioApi`
- **Permission:** `com.michatec.radio.permission.CONTROL_RADIO`
**Features:**
- Play, pause and stop playback
@@ -44,6 +45,7 @@ Starting with version **15.2**, Radio provides an AIDL interface that allows ext
- Access track metadata
- Switch stations using their UUID
- Retrieve saved and favorite stations as JSON
- Retrieve current station cover image and station image by UUID
**Documentation:** [AIDL API Documentation](AIDL_API.md)
+40 -7
View File
@@ -15,7 +15,7 @@ Instead of typing the pairing code manually, the client can display a QR code th
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:PAIRING_CODE`. The pairing code is a one time value of the session – it is **not** the secret of your Radio app.
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.
@@ -45,6 +45,18 @@ const poll = setInterval(async () => {
## 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.
@@ -62,21 +74,41 @@ Returns current playback status. Recommended for initial state only; use WebSock
```
### `WS /api/updates`
WebSocket endpoint for real-time status updates. Pushes status objects whenever state or metadata changes.
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
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 status = JSON.parse(event.data);
console.log('Update received:', status);
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 collection.
Returns all stations in the collection.
**Response Example:**
@@ -86,7 +118,8 @@ Returns all stations in collection.
"uuid": "fc080549-...",
"name": "Station Name",
"hasImage": true,
"starred": true
"starred": true,
"lastModified": 1700000000000
}
]
```