feat: service-owned queue, full player, audio consistency and mood settings
CI / build (push) Successful in 2m40s
CI / play (push) Skipped

- Android Media3 service owns a real timeline: gapless playback, notification
  and headset next/back, 2 s previous rule, queue survives task swipes
- per-track loudness gain via an Android PCM processor and desktop mixer
- optional 0-8 s fade between tracks; full-screen player with quality info
- per-mood offline switch auto-syncs songs on Wi-Fi, three at a time
- dedicated mood settings screen with delete at the bottom
- one-tap add-to-mood in the player; sleep timer can finish the current track
- version 0.4.0
This commit is contained in:
TapTap committed 2026-11-19 16:38:21 +00:00
1 parent 8d7f6a0ccb
commit 1e3dac4e47
26 files changed
+2088 -689

No files matched your search

@@ -2,6 +2,7 @@
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<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" />
@@ -0,0 +1,105 @@
package win.taptap.musicmanager.client
import android.content.Context
import androidx.media3.common.C
import androidx.media3.common.audio.AudioProcessor
import androidx.media3.common.audio.AudioProcessor.AudioFormat
import androidx.media3.common.util.UnstableApi
import androidx.media3.exoplayer.DefaultRenderersFactory
import androidx.media3.exoplayer.audio.AudioSink
import androidx.media3.exoplayer.audio.DefaultAudioSink
import java.nio.ByteBuffer
import java.nio.ByteOrder
import kotlin.math.pow
/**
* Applies the server's per-track loudness gain to 16-bit PCM.
*
* ExoPlayer's own volume is limited to 0..1, so it can only attenuate. Measuring
* tracks against -16 LUFS needs small positive gains on quiet recordings too;
* scaling the PCM samples supports both directions while leaving the hardware
* volume untouched.
*/
@UnstableApi
class GainAudioProcessor : AudioProcessor {
@Volatile
var gain: Float = 1f
private var inputFormat: AudioFormat = AudioFormat.NOT_SET
private var outputFormat: AudioFormat = AudioFormat.NOT_SET
private var buffer: ByteBuffer = AudioProcessor.EMPTY_BUFFER
private var endOfStream = false
override fun configure(inputAudioFormat: AudioFormat): AudioFormat {
if (inputAudioFormat.encoding != C.ENCODING_PCM_16BIT) {
// Float output or compressed passthrough: leave the samples alone.
inputFormat = AudioFormat.NOT_SET
outputFormat = AudioFormat.NOT_SET
return AudioFormat.NOT_SET
}
inputFormat = inputAudioFormat
outputFormat = inputAudioFormat
return outputFormat
}
override fun isActive(): Boolean = inputFormat != AudioFormat.NOT_SET
override fun queueInput(inputBuffer: ByteBuffer) {
val value = gain
val output = ByteBuffer.allocateDirect(inputBuffer.remaining())
.order(ByteOrder.nativeOrder())
while (inputBuffer.remaining() >= 2) {
val sample = inputBuffer.short.toInt()
val scaled = (sample * value).toInt()
.coerceIn(Short.MIN_VALUE.toInt(), Short.MAX_VALUE.toInt())
output.putShort(scaled.toShort())
}
output.flip()
buffer = output
}
override fun queueEndOfStream() {
endOfStream = true
}
override fun getOutput(): ByteBuffer = buffer
override fun isEnded(): Boolean = endOfStream && !buffer.hasRemaining()
override fun flush() {
buffer = AudioProcessor.EMPTY_BUFFER
endOfStream = false
}
override fun reset() {
buffer = AudioProcessor.EMPTY_BUFFER
endOfStream = false
inputFormat = AudioFormat.NOT_SET
outputFormat = AudioFormat.NOT_SET
}
companion object {
fun fromDb(db: Double): Float =
10.0.pow(db / 20.0).toFloat().coerceIn(0f, 4f)
}
}
/** Wires the gain processor into ExoPlayer's audio sink. */
@UnstableApi
class GainRenderersFactory(
context: Context,
private val gainProcessor: GainAudioProcessor,
) : DefaultRenderersFactory(context) {
override fun buildAudioSink(
context: Context,
enableFloatOutput: Boolean,
enableAudioTrackPlaybackParams: Boolean,
): AudioSink = DefaultAudioSink.Builder(context)
.setAudioProcessors(arrayOf(gainProcessor))
// The processor works on 16-bit PCM; forcing float output would bypass it.
.setEnableFloatOutput(false)
.setEnableAudioTrackPlaybackParams(enableAudioTrackPlaybackParams)
.build()
}
@@ -10,8 +10,8 @@ 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
import win.taptap.musicmanager.client.playback.PlaybackTrack
/**
* Client side of [PlaybackService]. The controller is created asynchronously;
@@ -55,43 +55,56 @@ class MediaControllerAudioPlayer(context: Context) : AudioPlayer {
)
}
override fun play(
source: String,
song: Song,
local: Boolean,
artworkUri: String?,
artworkBytes: ByteArray?,
) {
override fun setQueue(tracks: List<PlaybackTrack>, startIndex: Int, startAtSeconds: Double) {
if (tracks.isEmpty()) return
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)
.apply {
if (artworkBytes != null && artworkBytes.isNotEmpty()) {
setArtworkData(
artworkBytes,
MediaMetadata.PICTURE_TYPE_FRONT_COVER,
)
} else {
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()
val items = tracks.map(::mediaItem)
val index = startIndex.coerceIn(tracks.indices)
val positionMs = (startAtSeconds * 1_000).toLong().coerceAtLeast(0L)
withController { current ->
current.setMediaItems(items, index, positionMs)
current.prepare()
current.play()
}
}
override fun appendToQueue(tracks: List<PlaybackTrack>) {
if (tracks.isEmpty()) return
val items = tracks.map(::mediaItem)
withController { current -> current.addMediaItems(items) }
}
override fun moveInQueue(fromIndex: Int, toIndex: Int) {
withController { current -> current.moveMediaItem(fromIndex, toIndex) }
}
override fun removeAt(index: Int) {
withController { current -> current.removeMediaItem(index) }
}
override fun playIndex(index: Int, startAtSeconds: Double) {
finished = false
val positionMs = (startAtSeconds * 1_000).toLong().coerceAtLeast(0L)
withController { current ->
if (index in 0 until current.mediaItemCount) {
current.seekTo(index, positionMs)
current.play()
}
}
}
override fun skipToNext() {
withController { current -> current.seekToNextMediaItem() }
}
override fun skipToPrevious(restartAfterSeconds: Double) {
withController { current -> current.seekToPreviousMediaItem() }
}
override fun currentIndex(): Int = controller?.currentMediaItemIndex ?: 0
override fun queueSize(): Int = controller?.mediaItemCount ?: 0
override fun pause() {
withController { it.pause() }
}
@@ -126,19 +139,26 @@ class MediaControllerAudioPlayer(context: Context) : AudioPlayer {
withController { it.seekTo((seconds * 1000).toLong().coerceAtLeast(0L)) }
}
override fun setSkipCallbacks(onNext: (() -> Unit)?, onPrevious: (() -> Unit)?) {
PlaybackCommands.onNext = onNext
PlaybackCommands.onPrevious = onPrevious
override val supportsCrossfade: Boolean = true
override fun setCrossfadeSeconds(seconds: Int) {
val args = Bundle().apply { putInt(CROSSFADE_SECONDS, seconds.coerceAtLeast(0)) }
withController { current ->
runCatching { current.sendCustomCommand(CROSSFADE_COMMAND, args) }
}
}
override fun scheduleSleepTimer(seconds: Long?): Boolean {
val args = Bundle().apply { putLong(SLEEP_TIMER_SECONDS, seconds ?: 0L) }
val send: (MediaController) -> Boolean = { current ->
runCatching { current.sendCustomCommand(SLEEP_TIMER_COMMAND, args) }.isSuccess
val send: (MediaController) -> Unit = { current ->
runCatching { current.sendCustomCommand(SLEEP_TIMER_COMMAND, args) }
}
val current = controller
if (current != null && connected) return send(current)
synchronized(pending) { pending.addLast { controller -> send(controller) } }
if (current != null && connected) {
send(current)
return true
}
synchronized(pending) { pending.addLast(send) }
return true
}
@@ -150,13 +170,39 @@ class MediaControllerAudioPlayer(context: Context) : AudioPlayer {
synchronized(pending) { pending.clear() }
}
private fun mediaItem(track: PlaybackTrack): MediaItem {
val uri = if (track.local) {
Uri.fromFile(java.io.File(track.source))
} else {
Uri.parse(track.source)
}
val metadata = MediaMetadata.Builder()
.setTitle(track.song.title)
.setArtist(track.song.artist)
.setAlbumTitle(track.song.album)
.setExtras(
Bundle().apply { putDouble(GAIN_DB_KEY, track.gainDb ?: 0.0) },
)
.apply {
if (!track.artworkUri.isNullOrBlank()) {
setArtworkUri(Uri.parse(track.artworkUri))
}
}
.build()
return MediaItem.Builder()
.setUri(uri)
.setMimeType("audio/mpeg")
.setMediaMetadata(metadata)
.build()
}
private fun withController(block: (MediaController) -> Unit) {
val current = controller
if (current != null && connected) {
block(current)
} else {
// The first playback request can be followed immediately by a seek
// (long-form resume). Keep every action, not only the last one.
// The first playback request can be followed immediately by a seek.
// Keep every action, not only the last one.
synchronized(pending) { pending.addLast(block) }
}
}
@@ -2,6 +2,8 @@ package win.taptap.musicmanager.client
import android.content.Context
import android.graphics.BitmapFactory
import android.net.ConnectivityManager
import android.net.NetworkCapabilities
import androidx.compose.ui.graphics.ImageBitmap
import androidx.compose.ui.graphics.asImageBitmap
import io.ktor.client.engine.HttpClientEngine
@@ -21,6 +23,15 @@ actual fun platformStorage(): AppStorage = AndroidStorage(AndroidContextHolder.c
actual fun createAudioPlayer(): AudioPlayer = MediaControllerAudioPlayer(AndroidContextHolder.context)
actual fun isUnmeteredNetwork(): Boolean {
val manager = AndroidContextHolder.context
.getSystemService(ConnectivityManager::class.java) ?: return true
val network = manager.activeNetwork ?: return false
val capabilities = manager.getNetworkCapabilities(network) ?: return false
return capabilities.hasCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET) &&
capabilities.hasCapability(NetworkCapabilities.NET_CAPABILITY_NOT_METERED)
}
class AndroidStorage(context: Context) : AppStorage {
private val root = File(context.filesDir, "audiomanager").apply { mkdirs() }
@@ -1,27 +0,0 @@
package win.taptap.musicmanager.client
/**
* Bridge between the media session in [PlaybackService] and the queue that
* lives in the app's store. Media3 sends headset/Bluetooth next and previous
* here instead of seeking the single-item ExoPlayer.
*/
internal object PlaybackCommands {
@Volatile
var onNext: (() -> Unit)? = null
@Volatile
var onPrevious: (() -> Unit)? = null
/** Returns false when no store is attached, so the default handling applies. */
fun next(): Boolean {
val handler = onNext ?: return false
handler()
return true
}
fun previous(): Boolean {
val handler = onPrevious ?: return false
handler()
return true
}
}
@@ -5,11 +5,10 @@ import android.content.Intent
import android.os.Bundle
import android.os.Handler
import android.os.Looper
import android.view.KeyEvent
import androidx.core.content.IntentCompat
import androidx.media3.common.AudioAttributes
import androidx.media3.common.C
import androidx.media3.common.ForwardingPlayer
import androidx.media3.common.MediaItem
import androidx.media3.common.Player
import androidx.media3.exoplayer.ExoPlayer
import androidx.media3.session.MediaSession
@@ -24,12 +23,22 @@ internal const val SLEEP_TIMER_ACTION = "win.taptap.musicmanager.client.SLEEP_TI
internal const val SLEEP_TIMER_SECONDS = "seconds"
internal val SLEEP_TIMER_COMMAND = SessionCommand(SLEEP_TIMER_ACTION, Bundle.EMPTY)
/** Custom session command that sets the crossfade/fade length. */
internal const val CROSSFADE_ACTION = "win.taptap.musicmanager.client.CROSSFADE"
internal const val CROSSFADE_SECONDS = "seconds"
internal val CROSSFADE_COMMAND = SessionCommand(CROSSFADE_ACTION, Bundle.EMPTY)
/** MediaItem metadata key carrying the server-measured gain in dB. */
internal const val GAIN_DB_KEY = "gainDb"
/**
* 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.
* The queue lives here as a Media3 timeline. That lets the notification,
* headset buttons and Android Auto advance tracks even when the UI process is
* gone, and makes gapless playback possible because ExoPlayer prepares the next
* item ahead of time.
*/
class PlaybackService : MediaSessionService() {
@@ -37,10 +46,42 @@ class PlaybackService : MediaSessionService() {
private val handler = Handler(Looper.getMainLooper())
private val sleepTimer = Runnable { mediaSession?.player?.pause() }
@Volatile private var crossfadeSeconds = 0
@Volatile private var fade = 1f
private val gainProcessor = GainAudioProcessor()
private var player: ExoPlayer? = null
private val fadeLoop = object : Runnable {
override fun run() {
val exo = player ?: return
if (!exo.isPlaying) {
handler.postDelayed(this, FADE_TICK_MS)
return
}
val fadeMs = crossfadeSeconds * 1_000L
if (fadeMs > 0) {
val position = exo.currentPosition.coerceAtLeast(0L)
val duration = exo.duration
val fadeOut = if (duration > 0) {
((duration - position).toFloat() / fadeMs).coerceIn(0f, 1f)
} else {
1f
}
val fadeIn = (position.toFloat() / fadeMs).coerceIn(0f, 1f)
fade = minOf(fadeOut, fadeIn)
} else {
fade = 1f
}
exo.volume = fade.coerceIn(0f, 1f)
handler.postDelayed(this, FADE_TICK_MS)
}
}
override fun onCreate() {
super.onCreate()
val exoPlayer = ExoPlayer.Builder(this)
.setRenderersFactory(GainRenderersFactory(this, gainProcessor))
.setAudioAttributes(
AudioAttributes.Builder()
.setUsage(C.USAGE_MEDIA)
@@ -53,45 +94,48 @@ class PlaybackService : MediaSessionService() {
.apply {
setWakeMode(C.WAKE_MODE_NETWORK)
}
player = exoPlayer
// ExoPlayer holds one item at a time; the queue lives in the app. Advertise
// next/previous so the notification and Android Auto show the buttons and
// route them to the queue instead of seeking inside the single item.
val player = object : ForwardingPlayer(exoPlayer) {
override fun getAvailableCommands(): Player.Commands =
super.getAvailableCommands().buildUpon()
.addAll(
Player.COMMAND_SEEK_TO_NEXT,
Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM,
Player.COMMAND_SEEK_TO_PREVIOUS,
Player.COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM,
)
.build()
override fun isCommandAvailable(command: Int): Boolean =
command == Player.COMMAND_SEEK_TO_NEXT ||
command == Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM ||
command == Player.COMMAND_SEEK_TO_PREVIOUS ||
command == Player.COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM ||
super.isCommandAvailable(command)
override fun seekToNext() {
if (!PlaybackCommands.next()) super.seekToNext()
}
override fun seekToNextMediaItem() {
if (!PlaybackCommands.next()) super.seekToNextMediaItem()
}
// Media3's notification/next/previous map onto the real timeline. The
// only custom rule is Android's usual previous behaviour: after two
// seconds of playback it restarts the current item.
val sessionPlayer = object : ForwardingPlayer(exoPlayer) {
override fun seekToPrevious() {
if (!PlaybackCommands.previous()) super.seekToPrevious()
if (exoPlayer.currentPosition > PREVIOUS_RESTART_MS) {
exoPlayer.seekTo(0)
} else if (exoPlayer.hasPreviousMediaItem()) {
exoPlayer.seekToPreviousMediaItem()
} else {
exoPlayer.seekTo(0)
}
}
override fun seekToPreviousMediaItem() {
if (!PlaybackCommands.previous()) super.seekToPreviousMediaItem()
if (exoPlayer.currentPosition > PREVIOUS_RESTART_MS) {
exoPlayer.seekTo(0)
} else if (exoPlayer.hasPreviousMediaItem()) {
exoPlayer.seekToPreviousMediaItem()
} else {
exoPlayer.seekTo(0)
}
}
}
exoPlayer.addListener(
object : Player.Listener {
override fun onMediaItemTransition(mediaItem: MediaItem?, reason: Int) {
gainProcessor.gain = gainOf(mediaItem)
fade = if (crossfadeSeconds > 0) 0f else 1f
exoPlayer.volume = fade.coerceIn(0f, 1f)
}
override fun onIsPlayingChanged(isPlaying: Boolean) {
handler.removeCallbacks(fadeLoop)
if (isPlaying) handler.post(fadeLoop)
}
},
)
val sessionActivity = PendingIntent.getActivity(
this,
0,
@@ -99,7 +143,7 @@ class PlaybackService : MediaSessionService() {
PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
)
mediaSession = MediaSession.Builder(this, player)
mediaSession = MediaSession.Builder(this, sessionPlayer)
.setSessionActivity(sessionActivity)
.setCallback(object : MediaSession.Callback {
override fun onConnect(
@@ -109,57 +153,37 @@ class PlaybackService : MediaSessionService() {
val commands = MediaSession.ConnectionResult.DEFAULT_SESSION_AND_LIBRARY_COMMANDS
.buildUpon()
.add(SLEEP_TIMER_COMMAND)
.add(CROSSFADE_COMMAND)
.build()
return MediaSession.ConnectionResult.AcceptedResultBuilder(session)
.setAvailableSessionCommands(commands)
.build()
}
/**
* A headset skip must move the app's queue, not seek the one
* item ExoPlayer holds. Returning true consumes the event.
*/
override fun onMediaButtonEvent(
session: MediaSession,
controllerInfo: MediaSession.ControllerInfo,
intent: Intent,
): Boolean {
if (intent.action != Intent.ACTION_MEDIA_BUTTON) return false
val event = IntentCompat.getParcelableExtra(
intent,
Intent.EXTRA_KEY_EVENT,
KeyEvent::class.java,
) ?: return false
return when (event.keyCode) {
KeyEvent.KEYCODE_MEDIA_NEXT -> when (event.action) {
KeyEvent.ACTION_DOWN -> PlaybackCommands.next()
KeyEvent.ACTION_UP -> true
else -> false
}
KeyEvent.KEYCODE_MEDIA_PREVIOUS -> when (event.action) {
KeyEvent.ACTION_DOWN -> PlaybackCommands.previous()
KeyEvent.ACTION_UP -> true
else -> false
}
else -> false
}
}
override fun onCustomCommand(
session: MediaSession,
controller: MediaSession.ControllerInfo,
customCommand: SessionCommand,
args: Bundle,
): ListenableFuture<SessionResult> {
if (customCommand.customAction != SLEEP_TIMER_ACTION) {
return super.onCustomCommand(session, controller, customCommand, args)
}
handler.removeCallbacks(sleepTimer)
val seconds = args.getLong(SLEEP_TIMER_SECONDS, 0L)
if (seconds > 0) {
handler.postDelayed(sleepTimer, seconds * 1_000)
when (customCommand.customAction) {
SLEEP_TIMER_ACTION -> {
handler.removeCallbacks(sleepTimer)
val seconds = args.getLong(SLEEP_TIMER_SECONDS, 0L)
if (seconds > 0) {
handler.postDelayed(sleepTimer, seconds * 1_000)
}
}
CROSSFADE_ACTION -> {
crossfadeSeconds = args.getInt(CROSSFADE_SECONDS, 0).coerceAtLeast(0)
fade = if (crossfadeSeconds > 0) 0f else 1f
exoPlayer.volume = fade.coerceIn(0f, 1f)
handler.removeCallbacks(fadeLoop)
if (exoPlayer.isPlaying) handler.post(fadeLoop)
}
else -> return super.onCustomCommand(session, controller, customCommand, args)
}
return Futures.immediateFuture(SessionResult(SessionResult.RESULT_SUCCESS))
}
@@ -167,6 +191,11 @@ class PlaybackService : MediaSessionService() {
.build()
}
private fun gainOf(item: MediaItem?): Float {
val db = item?.mediaMetadata?.extras?.getDouble(GAIN_DB_KEY, 0.0) ?: 0.0
return GainAudioProcessor.fromDb(db)
}
override fun onGetSession(controllerInfo: MediaSession.ControllerInfo): MediaSession? =
mediaSession
@@ -179,11 +208,18 @@ class PlaybackService : MediaSessionService() {
override fun onDestroy() {
handler.removeCallbacks(sleepTimer)
handler.removeCallbacks(fadeLoop)
mediaSession?.run {
player.release()
release()
}
mediaSession = null
player = null
super.onDestroy()
}
private companion object {
const val PREVIOUS_RESTART_MS = 2_000L
const val FADE_TICK_MS = 100L
}
}