add streaming and mobile-app instructions
This commit is contained in:
@@ -0,0 +1,517 @@
|
||||
# Groove Audio — Native Mobile Apps
|
||||
|
||||
Instructions for an AI coding agent to build two native apps — one for iOS (Swift/SwiftUI) and one for Android (Kotlin/Jetpack Compose) — that stream lossless audio from the Groove Audio server and display now-playing information.
|
||||
|
||||
---
|
||||
|
||||
## What the server exposes
|
||||
|
||||
| Endpoint | Protocol | Purpose |
|
||||
|---|---|---|
|
||||
| `http://<HOST>:8000/stream.flac` | HTTP chunked (FLAC) | Lossless audio stream |
|
||||
| `http://<HOST>:8180/api/mopidy/rpc` | HTTP JSON-RPC | Mopidy playback control |
|
||||
| `ws://<HOST>:8180/ws/mopidy` | WebSocket | Real-time Mopidy events |
|
||||
| `http://<HOST>:8180/api/snapcast/rpc` | HTTP JSON-RPC | Snapcast zone info |
|
||||
|
||||
**Default LAN host:** `192.168.178.100`
|
||||
|
||||
### Stream authentication
|
||||
The FLAC stream requires HTTP Basic Auth:
|
||||
- Username: `listener`
|
||||
- Password: value of `ICECAST_LISTENER_PASSWORD` in the server's `.env` (default: `groove_listen`)
|
||||
|
||||
The app must pass `Authorization: Basic <base64(listener:password)>` in every HTTP request to the stream URL.
|
||||
|
||||
### Mopidy JSON-RPC quick reference
|
||||
All calls are HTTP POST to `/api/mopidy/rpc` with `Content-Type: application/json`.
|
||||
|
||||
```json
|
||||
// Get current track
|
||||
{"jsonrpc":"2.0","id":1,"method":"core.playback.get_current_track","params":{}}
|
||||
|
||||
// Get playback state (playing/paused/stopped)
|
||||
{"jsonrpc":"2.0","id":2,"method":"core.playback.get_state","params":{}}
|
||||
|
||||
// Get cover art URLs for a list of URIs
|
||||
{"jsonrpc":"2.0","id":3,"method":"core.library.get_images",
|
||||
"params":{"uris":["<track_uri>"]}}
|
||||
|
||||
// Pause / resume / next / previous
|
||||
{"jsonrpc":"2.0","id":4,"method":"core.playback.pause","params":{}}
|
||||
{"jsonrpc":"2.0","id":5,"method":"core.playback.resume","params":{}}
|
||||
{"jsonrpc":"2.0","id":6,"method":"core.playback.next","params":{}}
|
||||
{"jsonrpc":"2.0","id":7,"method":"core.playback.previous","params":{}}
|
||||
|
||||
// Volume (0-100)
|
||||
{"jsonrpc":"2.0","id":8,"method":"core.mixer.get_volume","params":{}}
|
||||
{"jsonrpc":"2.0","id":9,"method":"core.mixer.set_volume","params":{"volume":80}}
|
||||
```
|
||||
|
||||
### Mopidy WebSocket events
|
||||
Connect to `ws://<HOST>:8180/ws/mopidy`. The server pushes JSON event objects whenever playback changes. Listen for:
|
||||
- `event: "track_playback_started"` — new track; contains `tl_track.track`
|
||||
- `event: "track_playback_paused"` / `"track_playback_resumed"`
|
||||
- `event: "volume_changed"` — contains `volume`
|
||||
|
||||
---
|
||||
|
||||
## App requirements (both platforms)
|
||||
|
||||
### Core features
|
||||
1. **Audio streaming** — play the FLAC stream continuously in the background
|
||||
2. **Now-playing screen** — show track title, artist, album, and cover art
|
||||
3. **Transport controls** — play/pause, next, previous
|
||||
4. **Volume slider** — controls Mopidy software mixer volume (not device volume)
|
||||
5. **Background audio** — stream continues when app is backgrounded
|
||||
6. **Lock screen / notification controls** — show now-playing metadata and transport buttons
|
||||
|
||||
### Nice to have
|
||||
- Reconnect automatically when stream drops or server is unreachable
|
||||
- Buffering indicator
|
||||
- Settings screen to configure server host and listener password
|
||||
|
||||
---
|
||||
|
||||
## iOS implementation guide
|
||||
|
||||
### Project setup
|
||||
- SwiftUI app, iOS 16+ deployment target
|
||||
- Add `AVFoundation` and `Combine` frameworks (no additional packages needed)
|
||||
- Enable **Background Modes** capability: check `Audio, AirPlay, and Picture in Picture`
|
||||
- Set `NSAppTransportSecurity > NSAllowsLocalNetworking` to `YES` in Info.plist (for LAN HTTP)
|
||||
- If connecting over the internet via plain HTTP, add the server hostname to `NSExceptionDomains` or use HTTPS (see internet access section)
|
||||
|
||||
### Audio streaming — AVPlayer with authentication
|
||||
|
||||
```swift
|
||||
import AVFoundation
|
||||
|
||||
class StreamPlayer: ObservableObject {
|
||||
private var player: AVPlayer?
|
||||
@Published var isPlaying = false
|
||||
|
||||
func play(host: String, password: String) {
|
||||
let urlString = "http://\(host):8000/stream.flac"
|
||||
guard let url = URL(string: urlString) else { return }
|
||||
|
||||
// AVAsset with custom HTTP headers for Basic Auth
|
||||
let credentials = "listener:\(password)"
|
||||
let encoded = Data(credentials.utf8).base64EncodedString()
|
||||
let asset = AVURLAsset(url: url, options: [
|
||||
"AVURLAssetHTTPHeaderFieldsKey": ["Authorization": "Basic \(encoded)"]
|
||||
])
|
||||
let item = AVPlayerItem(asset: asset)
|
||||
player = AVPlayer(playerItem: item)
|
||||
player?.play()
|
||||
isPlaying = true
|
||||
|
||||
// Configure audio session for background playback
|
||||
try? AVAudioSession.sharedInstance().setCategory(.playback, mode: .default)
|
||||
try? AVAudioSession.sharedInstance().setActive(true)
|
||||
}
|
||||
|
||||
func pause() { player?.pause(); isPlaying = false }
|
||||
func resume() { player?.play(); isPlaying = true }
|
||||
}
|
||||
```
|
||||
|
||||
**Note on FLAC streaming:** `AVPlayer` supports FLAC on iOS 11+. For HTTP-streamed FLAC, set `preferredForwardBufferDuration` on the `AVPlayerItem` (e.g. 10 seconds) to ensure smooth playback. If `AVPlayer` stalls, implement an `AVAssetResourceLoader` delegate to handle HTTP + auth manually and feed raw bytes to the player — this gives full control over reconnection.
|
||||
|
||||
### Now-playing info (Control Center / Lock Screen)
|
||||
|
||||
```swift
|
||||
import MediaPlayer
|
||||
|
||||
func updateNowPlaying(title: String, artist: String, album: String, artwork: UIImage?) {
|
||||
var info = [String: Any]()
|
||||
info[MPMediaItemPropertyTitle] = title
|
||||
info[MPMediaItemPropertyArtist] = artist
|
||||
info[MPMediaItemPropertyAlbumTitle] = album
|
||||
if let img = artwork {
|
||||
info[MPMediaItemPropertyArtwork] =
|
||||
MPMediaItemArtwork(boundsSize: img.size) { _ in img }
|
||||
}
|
||||
info[MPNowPlayingInfoPropertyIsLiveStream] = true
|
||||
MPNowPlayingInfoCenter.default().nowPlayingInfo = info
|
||||
}
|
||||
|
||||
func setupRemoteControls(player: StreamPlayer, mopidy: MopidyClient) {
|
||||
let cc = MPRemoteCommandCenter.shared()
|
||||
cc.playCommand.addTarget { _ in player.resume(); return .success }
|
||||
cc.pauseCommand.addTarget { _ in player.pause(); return .success }
|
||||
cc.nextTrackCommand.addTarget { _ in Task { try? await mopidy.call("core.playback.next") }; return .success }
|
||||
cc.previousTrackCommand.addTarget { _ in Task { try? await mopidy.call("core.playback.previous") }; return .success }
|
||||
}
|
||||
```
|
||||
|
||||
### Mopidy JSON-RPC client
|
||||
|
||||
```swift
|
||||
struct MopidyClient {
|
||||
let baseURL: String // e.g. "http://192.168.178.100:8180"
|
||||
private var nextID = 1
|
||||
|
||||
mutating func call<T: Decodable>(_ method: String, params: [String: Any] = [:]) async throws -> T {
|
||||
let url = URL(string: "\(baseURL)/api/mopidy/rpc")!
|
||||
var req = URLRequest(url: url)
|
||||
req.httpMethod = "POST"
|
||||
req.setValue("application/json", forHTTPHeaderField: "Content-Type")
|
||||
let body: [String: Any] = ["jsonrpc": "2.0", "id": nextID, "method": method, "params": params]
|
||||
req.httpBody = try JSONSerialization.data(withJSONObject: body)
|
||||
nextID += 1
|
||||
let (data, _) = try await URLSession.shared.data(for: req)
|
||||
let wrapper = try JSONDecoder().decode(RPCResponse<T>.self, from: data)
|
||||
return wrapper.result
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### WebSocket for real-time events
|
||||
|
||||
```swift
|
||||
import Foundation
|
||||
|
||||
class MopidyEventStream: NSObject, ObservableObject, URLSessionWebSocketDelegate {
|
||||
private var task: URLSessionWebSocketTask?
|
||||
|
||||
func connect(host: String) {
|
||||
let url = URL(string: "ws://\(host):8180/ws/mopidy")!
|
||||
let session = URLSession(configuration: .default, delegate: self, delegateQueue: nil)
|
||||
task = session.webSocketTask(with: url)
|
||||
task?.resume()
|
||||
receive()
|
||||
}
|
||||
|
||||
private func receive() {
|
||||
task?.receive { [weak self] result in
|
||||
if case .success(.string(let text)) = result,
|
||||
let data = text.data(using: .utf8),
|
||||
let event = try? JSONDecoder().decode(MopidyEvent.self, from: data) {
|
||||
DispatchQueue.main.async { self?.handle(event) }
|
||||
}
|
||||
self?.receive()
|
||||
}
|
||||
}
|
||||
|
||||
private func handle(_ event: MopidyEvent) {
|
||||
// Trigger a fresh core.playback.get_current_track call, update UI
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Suggested iOS project structure
|
||||
|
||||
```
|
||||
GrooveAudio (iOS)/
|
||||
├── App/
|
||||
│ ├── GrooveAudioApp.swift # @main, sets up AVAudioSession
|
||||
│ └── AppSettings.swift # host + password (UserDefaults / Keychain)
|
||||
├── Audio/
|
||||
│ ├── StreamPlayer.swift # AVPlayer wrapper, auth, reconnect
|
||||
│ └── NowPlayingController.swift # MPNowPlayingInfoCenter + MPRemoteCommandCenter
|
||||
├── Mopidy/
|
||||
│ ├── MopidyClient.swift # JSON-RPC HTTP client
|
||||
│ ├── MopidyEventStream.swift # WebSocket event listener
|
||||
│ └── Models.swift # Track, State, RPCResponse, MopidyEvent
|
||||
├── UI/
|
||||
│ ├── NowPlayingView.swift # Main screen: artwork, title, controls
|
||||
│ ├── VolumeView.swift # Slider → core.mixer.set_volume
|
||||
│ └── SettingsView.swift # Host, password, connection status
|
||||
└── Assets/
|
||||
└── placeholder_artwork.png
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Android implementation guide
|
||||
|
||||
### Project setup
|
||||
- Android Studio project, Kotlin, Jetpack Compose UI
|
||||
- Min SDK: 26 (Android 8), target SDK: 35
|
||||
- Add to `app/build.gradle.kts`:
|
||||
|
||||
```kotlin
|
||||
dependencies {
|
||||
// Media3 (ExoPlayer successor — recommended for new projects)
|
||||
implementation("androidx.media3:media3-exoplayer:1.4.1")
|
||||
implementation("androidx.media3:media3-ui:1.4.1")
|
||||
implementation("androidx.media3:media3-session:1.4.1") // MediaSession + notification
|
||||
|
||||
// HTTP + JSON
|
||||
implementation("com.squareup.okhttp3:okhttp:4.12.0")
|
||||
implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.3")
|
||||
|
||||
// Coil for cover art
|
||||
implementation("io.coil-kt:coil-compose:2.7.0")
|
||||
|
||||
// Compose + lifecycle
|
||||
implementation("androidx.lifecycle:lifecycle-viewmodel-compose:2.8.7")
|
||||
implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.8.7")
|
||||
}
|
||||
```
|
||||
|
||||
- Add to `AndroidManifest.xml`:
|
||||
|
||||
```xml
|
||||
<uses-permission android:name="android.permission.INTERNET" />
|
||||
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
|
||||
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
|
||||
|
||||
<!-- Foreground service for background audio -->
|
||||
<service
|
||||
android:name=".audio.GroovePlaybackService"
|
||||
android:foregroundServiceType="mediaPlayback"
|
||||
android:exported="true">
|
||||
<intent-filter>
|
||||
<action android:name="androidx.media3.session.MediaSessionService" />
|
||||
</intent-filter>
|
||||
</service>
|
||||
```
|
||||
|
||||
- If the server uses plain HTTP (not HTTPS), add a network security config that allows cleartext for the server's IP/hostname, or set `android:usesCleartextTraffic="true"` on the `<application>` tag for development.
|
||||
|
||||
### Audio streaming — Media3 ExoPlayer with authentication
|
||||
|
||||
ExoPlayer handles HTTP FLAC streaming natively. Inject the `Authorization` header via a custom `DataSource.Factory`:
|
||||
|
||||
```kotlin
|
||||
import androidx.media3.datasource.okhttp.OkHttpDataSource
|
||||
import androidx.media3.exoplayer.ExoPlayer
|
||||
import androidx.media3.common.MediaItem
|
||||
import okhttp3.OkHttpClient
|
||||
|
||||
fun buildPlayer(context: Context, host: String, password: String): ExoPlayer {
|
||||
val credentials = "listener:$password"
|
||||
val encoded = android.util.Base64.encodeToString(
|
||||
credentials.toByteArray(), android.util.Base64.NO_WRAP
|
||||
)
|
||||
|
||||
val httpClient = OkHttpClient.Builder()
|
||||
.addInterceptor { chain ->
|
||||
chain.proceed(
|
||||
chain.request().newBuilder()
|
||||
.header("Authorization", "Basic $encoded")
|
||||
.build()
|
||||
)
|
||||
}
|
||||
.build()
|
||||
|
||||
val dataSourceFactory = OkHttpDataSource.Factory(httpClient)
|
||||
|
||||
val trackSelector = DefaultTrackSelector(context)
|
||||
val player = ExoPlayer.Builder(context)
|
||||
.setMediaSourceFactory(
|
||||
DefaultMediaSourceFactory(context).setDataSourceFactory(dataSourceFactory)
|
||||
)
|
||||
.build()
|
||||
|
||||
val mediaItem = MediaItem.fromUri("http://$host:8000/stream.flac")
|
||||
player.setMediaItem(mediaItem)
|
||||
player.prepare()
|
||||
player.playWhenReady = true
|
||||
return player
|
||||
}
|
||||
```
|
||||
|
||||
### Background playback — MediaSessionService
|
||||
|
||||
Create a foreground service so audio continues when the app is backgrounded and the notification shows transport controls:
|
||||
|
||||
```kotlin
|
||||
import androidx.media3.session.MediaSessionService
|
||||
import androidx.media3.session.MediaSession
|
||||
|
||||
class GroovePlaybackService : MediaSessionService() {
|
||||
private var mediaSession: MediaSession? = null
|
||||
|
||||
override fun onCreate() {
|
||||
super.onCreate()
|
||||
val prefs = getSharedPreferences("groove", MODE_PRIVATE)
|
||||
val host = prefs.getString("host", "192.168.178.100")!!
|
||||
val password = prefs.getString("password", "groove_listen")!!
|
||||
|
||||
val player = buildPlayer(this, host, password)
|
||||
|
||||
mediaSession = MediaSession.Builder(this, player)
|
||||
.build()
|
||||
}
|
||||
|
||||
override fun onGetSession(controllerInfo: MediaSession.ControllerInfo) = mediaSession
|
||||
|
||||
override fun onDestroy() {
|
||||
mediaSession?.run {
|
||||
player.release()
|
||||
release()
|
||||
mediaSession = null
|
||||
}
|
||||
super.onDestroy()
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Media3's `MediaSessionService` automatically creates a persistent notification with play/pause/next/previous buttons and handles lock screen integration on Android 13+.
|
||||
|
||||
### Now-playing metadata
|
||||
|
||||
Update `MediaItem` metadata so the notification and lock screen show the correct track info:
|
||||
|
||||
```kotlin
|
||||
fun updateNowPlaying(
|
||||
controller: MediaController,
|
||||
title: String,
|
||||
artist: String,
|
||||
album: String,
|
||||
artworkUri: Uri?
|
||||
) {
|
||||
val metadata = MediaMetadata.Builder()
|
||||
.setTitle(title)
|
||||
.setArtist(artist)
|
||||
.setAlbumTitle(album)
|
||||
.setArtworkUri(artworkUri)
|
||||
.setIsPlayable(true)
|
||||
.build()
|
||||
|
||||
val item = controller.currentMediaItem
|
||||
?.buildUpon()
|
||||
?.setMediaMetadata(metadata)
|
||||
?.build()
|
||||
?: return
|
||||
|
||||
controller.replaceMediaItem(0, item)
|
||||
}
|
||||
```
|
||||
|
||||
### Mopidy JSON-RPC client
|
||||
|
||||
```kotlin
|
||||
import kotlinx.serialization.json.*
|
||||
import okhttp3.*
|
||||
import okhttp3.MediaType.Companion.toMediaType
|
||||
import okhttp3.RequestBody.Companion.toRequestBody
|
||||
|
||||
class MopidyClient(private val baseUrl: String) {
|
||||
private val http = OkHttpClient()
|
||||
private val json = Json { ignoreUnknownKeys = true }
|
||||
private val jsonMediaType = "application/json".toMediaType()
|
||||
private var idCounter = 1
|
||||
|
||||
suspend fun call(method: String, params: JsonObject = buildJsonObject {}): JsonElement {
|
||||
val body = buildJsonObject {
|
||||
put("jsonrpc", "2.0")
|
||||
put("id", idCounter++)
|
||||
put("method", method)
|
||||
put("params", params)
|
||||
}.toString().toRequestBody(jsonMediaType)
|
||||
|
||||
val request = Request.Builder()
|
||||
.url("$baseUrl/api/mopidy/rpc")
|
||||
.post(body)
|
||||
.build()
|
||||
|
||||
return withContext(Dispatchers.IO) {
|
||||
http.newCall(request).execute().use { response ->
|
||||
val text = response.body?.string() ?: "{}"
|
||||
json.parseToJsonElement(text)
|
||||
.jsonObject["result"]
|
||||
?: JsonNull
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### WebSocket for real-time events
|
||||
|
||||
```kotlin
|
||||
import okhttp3.*
|
||||
|
||||
class MopidyEventStream(
|
||||
private val host: String,
|
||||
private val onEvent: (JsonObject) -> Unit
|
||||
) {
|
||||
private val client = OkHttpClient()
|
||||
private var ws: WebSocket? = null
|
||||
|
||||
fun connect() {
|
||||
val request = Request.Builder()
|
||||
.url("ws://$host:8180/ws/mopidy")
|
||||
.build()
|
||||
|
||||
ws = client.newWebSocket(request, object : WebSocketListener() {
|
||||
override fun onMessage(webSocket: WebSocket, text: String) {
|
||||
runCatching {
|
||||
val obj = Json.parseToJsonElement(text).jsonObject
|
||||
onEvent(obj)
|
||||
}
|
||||
}
|
||||
|
||||
override fun onFailure(webSocket: WebSocket, t: Throwable, response: Response?) {
|
||||
// Reconnect after delay
|
||||
Thread.sleep(3000)
|
||||
connect()
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
fun disconnect() { ws?.close(1000, null) }
|
||||
}
|
||||
```
|
||||
|
||||
### Suggested Android project structure
|
||||
|
||||
```
|
||||
app/src/main/java/com/groove/audio/
|
||||
├── audio/
|
||||
│ ├── GroovePlaybackService.kt # MediaSessionService (background audio + notification)
|
||||
│ └── PlayerBuilder.kt # ExoPlayer factory with OkHttp + Basic Auth
|
||||
├── mopidy/
|
||||
│ ├── MopidyClient.kt # JSON-RPC over OkHttp
|
||||
│ ├── MopidyEventStream.kt # WebSocket listener with reconnect
|
||||
│ └── Models.kt # Track, State data classes
|
||||
├── ui/
|
||||
│ ├── NowPlayingScreen.kt # Main Compose screen: artwork, title, controls
|
||||
│ ├── VolumeSlider.kt # Slider → core.mixer.set_volume
|
||||
│ └── SettingsScreen.kt # Host, password, connection status
|
||||
├── AppSettings.kt # SharedPreferences / DataStore wrapper
|
||||
└── MainActivity.kt # Entry point, binds to GroovePlaybackService
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Internet access
|
||||
|
||||
The stream server runs on your LAN. To reach it over the internet, choose one approach:
|
||||
|
||||
### Option A — Tailscale (recommended)
|
||||
1. Install Tailscale on the Pi: `curl -fsSL https://tailscale.com/install.sh | sh && sudo tailscale up`
|
||||
2. Install the Tailscale app on iPhone **and** on the Android device
|
||||
3. All devices join the same Tailscale network
|
||||
4. Use the Pi's Tailscale IP (e.g. `100.x.x.x`) as the host in both apps
|
||||
5. No port forwarding, no dynamic DNS, encrypted by default over WireGuard
|
||||
|
||||
This is the simplest and most secure option for both platforms.
|
||||
|
||||
### Option B — Port forwarding
|
||||
1. Forward TCP port `8000` (Icecast stream) on your router to the Pi's LAN IP (`192.168.178.100`)
|
||||
2. Optionally forward port `8180` (web UI / Mopidy API) as well
|
||||
3. Use a dynamic DNS service (DuckDNS, Cloudflare, etc.) if you don't have a static public IP
|
||||
4. Change the default listener password in `.env` before exposing to the internet
|
||||
5. On iOS: add the public hostname to `NSExceptionDomains` in Info.plist (plain HTTP) or configure HTTPS
|
||||
6. On Android: add the public hostname to the network security config for cleartext, or configure HTTPS
|
||||
|
||||
### Option C — Cloudflare Tunnel
|
||||
Cloudflare Tunnels may terminate long-lived unbounded chunked HTTP streams (the FLAC stream). Not recommended for the audio stream; can be used for the Mopidy API endpoint only.
|
||||
|
||||
---
|
||||
|
||||
## Key URLs summary
|
||||
|
||||
| What | LAN URL | Notes |
|
||||
|---|---|---|
|
||||
| FLAC stream | `http://192.168.178.100:8000/stream.flac` | Auth required |
|
||||
| FLAC via nginx | `http://192.168.178.100:8180/stream.flac` | Same stream, single port |
|
||||
| Mopidy RPC | `http://192.168.178.100:8180/api/mopidy/rpc` | No auth |
|
||||
| Mopidy WS | `ws://192.168.178.100:8180/ws/mopidy` | No auth |
|
||||
| Icecast admin | `http://192.168.178.100:8000/admin/` | Admin password from `.env` |
|
||||
|
||||
Replace `192.168.178.100` with the Pi's Tailscale IP when connecting over the internet via Option A.
|
||||
Reference in New Issue
Block a user