## Status

✅ **iOS implementation complete** - See `GrooveAudio (iOS)/` directory
✅ **Android implementation complete** - See `GrooveAudio (Android)/` directory

Both apps are ready to build and run. See the respective directories for implementation details.

---
# 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.