feat(android): play in a foreground MediaSessionService
CI / build (push) Failing after 2m28s

Move ExoPlayer out of the activity into a MediaSessionService so audio keeps
playing when the app is backgrounded, the screen is off, or the task is
swiped away. Media3 provides the media notification, lock-screen and headset
controls, audio focus and noisy-headphone handling.

The UI talks to the service through a MediaController-backed AudioPlayer and
sends title, artist, album and artwork metadata for the notification. Add the
Android 13 notification permission request, the media playback foreground
service permissions, and wake mode for network streaming.
This commit is contained in:
TapTap committed 2026-11-14 21:52:03 +00:00
1 parent 9cdbb3702e
commit b8bbf8d07c
12 files changed
+232 -82

No files matched your search

+2 -1
View File
@@ -28,6 +28,7 @@ The shared module contains the API client, session/cache storage, radio queue, a
- Offline library cache: moods, songs and the last sync revision are stored locally. When the server is unreachable, downloaded tracks still play.
- Original MP3 downloads with progress state, removal and storage usage.
- Session persistence: the login survives app restarts until the token is revoked or expires.
- Android background playback through a Media3 `MediaSessionService`: notification, lock-screen and headset controls, audio focus, and playback that survives the app being backgrounded or the task being swiped away.
## Project layout
@@ -127,7 +128,7 @@ The image build performs one warm-up compile (`desktopTest`, `assembleDebug`, `c
## Known limitations
- Android playback runs inside the app process; a foreground `MediaSessionService` with a notification and lock-screen controls is the next step.
- The media notification exposes play/pause and seeking. Queue actions (skip, add to mood) stay in the app because the mood session and its events belong to the server.
- Desktop playback cannot seek (sequential decoder); pause/resume and skipping work.
- Web downloads are disabled because the browser owns its storage; the app still streams and caches metadata.
- YT Music recommendations are displayed when the server provides them; discovery and downloading are server-side roadmap items.
+1
View File
@@ -61,6 +61,7 @@ kotlin {
implementation("androidx.activity:activity-compose:1.10.1")
implementation("androidx.media3:media3-exoplayer:1.6.1")
implementation("androidx.media3:media3-common:1.6.1")
implementation("androidx.media3:media3-session:1.6.1")
}
val desktopMain by getting {
@@ -2,6 +2,10 @@
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<application
android:allowBackup="true"
@@ -20,5 +24,14 @@
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
<service
android:name=".PlaybackService"
android:exported="true"
android:foregroundServiceType="mediaPlayback">
<intent-filter>
<action android:name="androidx.media3.session.MediaSessionService" />
</intent-filter>
</service>
</application>
</manifest>
@@ -1,76 +0,0 @@
package win.taptap.musicmanager.client
import android.content.Context
import android.net.Uri
import androidx.media3.common.AudioAttributes
import androidx.media3.common.C
import androidx.media3.common.MediaItem
import androidx.media3.common.Player
import androidx.media3.exoplayer.ExoPlayer
import java.io.File
import win.taptap.musicmanager.client.api.Song
import win.taptap.musicmanager.client.playback.AudioPlayer
class AndroidAudioPlayer(context: Context) : AudioPlayer {
private val player = ExoPlayer.Builder(context).build().apply {
setAudioAttributes(
AudioAttributes.Builder()
.setUsage(C.USAGE_MEDIA)
.setContentType(C.AUDIO_CONTENT_TYPE_MUSIC)
.build(),
true,
)
addListener(object : Player.Listener {
override fun onPlaybackStateChanged(playbackState: Int) {
if (playbackState == Player.STATE_ENDED) finished = true
}
})
}
private var finished = false
override fun play(source: String, song: Song, local: Boolean) {
finished = false
val uri = if (local) Uri.fromFile(File(source)) else Uri.parse(source)
player.setMediaItem(MediaItem.fromUri(uri))
player.prepare()
player.play()
}
override fun pause() {
player.pause()
}
override fun resume() {
player.play()
}
override fun stop() {
player.stop()
player.clearMediaItems()
finished = false
}
override fun isPlaying(): Boolean = player.isPlaying
override fun isFinished(): Boolean = finished
override fun positionSeconds(): Double =
player.currentPosition.coerceAtLeast(0L) / 1000.0
override fun durationSeconds(): Double {
val duration = player.duration
return if (duration > 0) duration / 1000.0 else 0.0
}
override val canSeek: Boolean = true
override fun seekTo(seconds: Double) {
player.seekTo((seconds * 1000).toLong().coerceAtLeast(0L))
}
override fun release() {
player.release()
}
}
@@ -1,6 +1,9 @@
package win.taptap.musicmanager.client
import android.Manifest
import android.content.Context
import android.content.pm.PackageManager
import android.os.Build
import androidx.activity.ComponentActivity
import androidx.activity.compose.BackHandler
import androidx.activity.compose.setContent
@@ -17,8 +20,15 @@ class MainActivity : ComponentActivity() {
super.onCreate(savedInstanceState)
AndroidContextHolder.context = applicationContext
enableEdgeToEdge()
requestNotificationPermission()
setContent { App() }
}
private fun requestNotificationPermission() {
if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) return
if (checkSelfPermission(Manifest.permission.POST_NOTIFICATIONS) == PackageManager.PERMISSION_GRANTED) return
requestPermissions(arrayOf(Manifest.permission.POST_NOTIFICATIONS), 1001)
}
}
@Composable
@@ -0,0 +1,127 @@
package win.taptap.musicmanager.client
import android.content.ComponentName
import android.content.Context
import android.net.Uri
import androidx.core.content.ContextCompat
import androidx.media3.common.MediaItem
import androidx.media3.common.MediaMetadata
import androidx.media3.common.Player
import androidx.media3.session.MediaController
import androidx.media3.session.SessionToken
import win.taptap.musicmanager.client.api.Song
import win.taptap.musicmanager.client.playback.AudioPlayer
/**
* Client side of [PlaybackService]. The controller is created asynchronously;
* playback requests made before it connects are queued and executed once.
*/
class MediaControllerAudioPlayer(context: Context) : AudioPlayer {
private val appContext = context.applicationContext
private var controller: MediaController? = null
private var pending: ((MediaController) -> Unit)? = null
private var connected = false
@Volatile private var finished = false
private val future = MediaController.Builder(
appContext,
SessionToken(appContext, ComponentName(appContext, PlaybackService::class.java)),
).buildAsync()
private val listener = object : Player.Listener {
override fun onPlaybackStateChanged(playbackState: Int) {
finished = playbackState == Player.STATE_ENDED
}
}
init {
future.addListener(
{
val sessionController = runCatching { future.get() }.getOrNull()
if (sessionController != null) {
controller = sessionController
sessionController.addListener(listener)
connected = true
pending?.invoke(sessionController)
pending = null
}
},
ContextCompat.getMainExecutor(appContext),
)
}
override fun play(source: String, song: Song, local: Boolean, artworkUri: String?) {
finished = false
withController { controller ->
val uri = if (local) Uri.fromFile(java.io.File(source)) else Uri.parse(source)
val metadata = MediaMetadata.Builder()
.setTitle(song.title)
.setArtist(song.artist)
.setAlbumTitle(song.album)
.setArtworkUri(artworkUri?.let(Uri::parse))
.build()
val item = MediaItem.Builder()
.setUri(uri)
.setMimeType("audio/mpeg")
.setMediaMetadata(metadata)
.build()
controller.setMediaItem(item)
controller.prepare()
controller.play()
}
}
override fun pause() {
withController { it.pause() }
}
override fun resume() {
withController { it.play() }
}
override fun stop() {
finished = false
withController {
it.stop()
it.clearMediaItems()
}
}
override fun isPlaying(): Boolean = controller?.isPlaying == true
override fun isFinished(): Boolean = finished
override fun positionSeconds(): Double =
(controller?.currentPosition ?: 0L).coerceAtLeast(0L) / 1000.0
override fun durationSeconds(): Double {
val duration = controller?.duration ?: 0L
return if (duration > 0) duration / 1000.0 else 0.0
}
override val canSeek: Boolean = true
override fun seekTo(seconds: Double) {
withController { it.seekTo((seconds * 1000).toLong().coerceAtLeast(0L)) }
}
override fun release() {
controller?.release()
MediaController.releaseFuture(future)
controller = null
connected = false
pending = null
}
private fun withController(block: (MediaController) -> Unit) {
val current = controller
if (current != null && connected) {
block(current)
} else {
pending = block
}
}
}
@@ -18,7 +18,7 @@ actual fun defaultServerUrl(): String = "http://10.0.2.2:8080"
actual fun platformStorage(): AppStorage = AndroidStorage(AndroidContextHolder.context)
actual fun createAudioPlayer(): AudioPlayer = AndroidAudioPlayer(AndroidContextHolder.context)
actual fun createAudioPlayer(): AudioPlayer = MediaControllerAudioPlayer(AndroidContextHolder.context)
class AndroidStorage(context: Context) : AppStorage {
@@ -0,0 +1,69 @@
package win.taptap.musicmanager.client
import android.app.PendingIntent
import android.content.Intent
import androidx.media3.common.AudioAttributes
import androidx.media3.common.C
import androidx.media3.exoplayer.ExoPlayer
import androidx.media3.session.MediaSession
import androidx.media3.session.MediaSessionService
/**
* Hosts playback in a foreground service so audio continues when the activity
* is backgrounded, the screen is off, or the task is swiped away.
*
* Media3 publishes the media notification and exposes the session to lock-screen
* controls, Bluetooth/headset buttons and Android Auto.
*/
class PlaybackService : MediaSessionService() {
private var mediaSession: MediaSession? = null
override fun onCreate() {
super.onCreate()
val player = ExoPlayer.Builder(this)
.setAudioAttributes(
AudioAttributes.Builder()
.setUsage(C.USAGE_MEDIA)
.setContentType(C.AUDIO_CONTENT_TYPE_MUSIC)
.build(),
true,
)
.setHandleAudioBecomingNoisy(true)
.build()
.apply {
setWakeMode(C.WAKE_MODE_NETWORK)
}
val sessionActivity = PendingIntent.getActivity(
this,
0,
Intent(this, MainActivity::class.java),
PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
)
mediaSession = MediaSession.Builder(this, player)
.setSessionActivity(sessionActivity)
.build()
}
override fun onGetSession(controllerInfo: MediaSession.ControllerInfo): MediaSession? =
mediaSession
override fun onTaskRemoved(rootIntent: Intent?) {
val player = mediaSession?.player
if (player == null || !player.playWhenReady || player.mediaItemCount == 0) {
stopSelf()
}
}
override fun onDestroy() {
mediaSession?.run {
player.release()
release()
}
mediaSession = null
super.onDestroy()
}
}
@@ -9,7 +9,7 @@ import win.taptap.musicmanager.client.api.Song
* store polls [isFinished] because some backends have no callback support.
*/
interface AudioPlayer {
fun play(source: String, song: Song, local: Boolean)
fun play(source: String, song: Song, local: Boolean, artworkUri: String? = null)
fun pause()
fun resume()
fun stop()
@@ -696,7 +696,12 @@ class AppStore(
private fun startSong(song: Song) {
val localPath = storage.downloadPath(song.id)
finishing = false
player.play(localPath ?: api.streamUrl(song.id), song, localPath != null)
player.play(
source = localPath ?: api.streamUrl(song.id),
song = song,
local = localPath != null,
artworkUri = api.coverUrl(song.albumId),
)
startPolling()
}
@@ -30,7 +30,7 @@ class DesktopAudioPlayer : AudioPlayer {
private var frameRate = 44_100f
private var duration = 0.0
override fun play(source: String, song: Song, local: Boolean) {
override fun play(source: String, song: Song, local: Boolean, artworkUri: String?) {
stop()
finished = false
paused = false
@@ -12,7 +12,7 @@ class WebAudioPlayer : AudioPlayer {
preload = "auto"
}
override fun play(source: String, song: Song, local: Boolean) {
override fun play(source: String, song: Song, local: Boolean, artworkUri: String?) {
audio.src = source
audio.play()
}