capacitor-plugin-playlist 0.11.2 → 0.13.0

package/android/src/main/java/org/dwbn/plugins/playlist/service/HandoffForwardingPlayer.kt

@@ -0,0 +1,185 @@
+package org.dwbn.plugins.playlist.service
+
+import android.os.Handler
+import android.os.Looper
+import androidx.annotation.OptIn
+import androidx.media3.common.ForwardingPlayer
+import androidx.media3.common.Player
+import androidx.media3.common.util.UnstableApi
+import org.dwbn.plugins.playlist.handoff.VideoPlayerBridge
+import java.util.concurrent.CopyOnWriteArrayList
+
+/**
+ * Routes the playlist MediaSession to the video ExoPlayer while handoff retain is active and video
+ * is attached; otherwise blocks play during retain-only prewarm (Story 55.6).
+ */
+@OptIn(UnstableApi::class)
+internal class HandoffForwardingPlayer(
+    player: Player,
+    private val retain: () -> Boolean,
+    private val onSkipToNext: (() -> Unit)? = null,
+    private val onSkipToPrevious: (() -> Unit)? = null,
+    private val previousAvailable: (() -> Boolean)? = null,
+    private val nextAvailable: (() -> Boolean)? = null
+) : ForwardingPlayer(player) {
+
+    private val sessionListeners = CopyOnWriteArrayList<Player.Listener>()
+    private val playbackRelay = { dispatchVideoPlaybackToSession() }
+
+    init {
+        VideoPlayerBridge.addPlaybackChangedListener(playbackRelay)
+        if (VideoPlayerBridge.hasActivePlayer()) {
+            playbackRelay()
+        }
+    }
+
+    override fun addListener(listener: Player.Listener) {
+        super.addListener(listener)
+        sessionListeners.addIfAbsent(listener)
+        if (videoPlayer() != null) {
+            playbackRelay()
+        }
+    }
+
+    override fun removeListener(listener: Player.Listener) {
+        super.removeListener(listener)
+        sessionListeners.remove(listener)
+    }
+
+    private fun videoPlayer(): Player? {
+        if (!retain() || !VideoPlayerBridge.hasActivePlayer()) {
+            return null
+        }
+        return VideoPlayerBridge.activePlayer()
+    }
+
+    override fun play() {
+        val video = videoPlayer()
+        if (video != null) {
+            video.play()
+            return
+        }
+        if (MediaNotificationPolicy.shouldIgnoreSessionPlay(retain(), VideoPlayerBridge.hasActivePlayer())) {
+            return
+        }
+        super.play()
+    }
+
+    override fun pause() {
+        videoPlayer()?.pause() ?: super.pause()
+    }
+
+    override fun setPlayWhenReady(playWhenReady: Boolean) {
+        val video = videoPlayer()
+        if (video != null) {
+            video.playWhenReady = playWhenReady
+            return
+        }
+        if (playWhenReady && MediaNotificationPolicy.shouldIgnoreSessionPlay(retain(), VideoPlayerBridge.hasActivePlayer())) {
+            return
+        }
+        super.setPlayWhenReady(playWhenReady)
+    }
+
+    override fun getPlayWhenReady(): Boolean = videoPlayer()?.playWhenReady ?: super.getPlayWhenReady()
+
+    override fun isPlaying(): Boolean {
+        val video = videoPlayer()
+        if (video != null) {
+            return video.playWhenReady && video.playbackState == Player.STATE_READY
+        }
+        return super.isPlaying()
+    }
+
+    override fun getPlaybackState(): Int = videoPlayer()?.playbackState ?: super.getPlaybackState()
+
+    override fun getCurrentPosition(): Long = videoPlayer()?.currentPosition ?: super.getCurrentPosition()
+
+    override fun getContentPosition(): Long = videoPlayer()?.contentPosition ?: super.getContentPosition()
+
+    override fun getDuration(): Long = videoPlayer()?.duration ?: super.getDuration()
+
+    override fun getBufferedPosition(): Long = videoPlayer()?.bufferedPosition ?: super.getBufferedPosition()
+
+    override fun seekTo(positionMs: Long) {
+        videoPlayer()?.seekTo(positionMs) ?: super.seekTo(positionMs)
+    }
+
+    override fun seekTo(windowIndex: Int, positionMs: Long) {
+        videoPlayer()?.seekTo(windowIndex, positionMs) ?: super.seekTo(windowIndex, positionMs)
+    }
+
+    override fun seekToNextMediaItem() {
+        if (videoPlayer() != null) {
+            return
+        }
+        onSkipToNext?.invoke() ?: super.seekToNextMediaItem()
+    }
+
+    override fun seekToPreviousMediaItem() {
+        if (videoPlayer() != null) {
+            return
+        }
+        onSkipToPrevious?.invoke() ?: super.seekToPreviousMediaItem()
+    }
+
+    override fun getAvailableCommands(): Player.Commands {
+        val previous = previousAvailable
+        val next = nextAvailable
+        if (previous == null && next == null) {
+            return super.getAvailableCommands()
+        }
+        val retainActive = retain()
+        val videoAttached = VideoPlayerBridge.hasActivePlayer()
+        return MediaNotificationPolicy.playerCommandsForMediaNotification(
+            super.getAvailableCommands(),
+            MediaNotificationPolicy.mediaNotificationSkipPreviousEnabled(
+                previous?.invoke() ?: false,
+                retainActive,
+                videoAttached
+            ),
+            MediaNotificationPolicy.mediaNotificationSkipNextEnabled(
+                next?.invoke() ?: false,
+                retainActive,
+                videoAttached
+            )
+        )
+    }
+
+    private fun dispatchVideoPlaybackToSession() {
+        val looper = applicationLooperOrNull()
+        if (looper != null && Looper.myLooper() != looper) {
+            Handler(looper).post { dispatchVideoPlaybackToSessionOnLooper() }
+            return
+        }
+        dispatchVideoPlaybackToSessionOnLooper()
+    }
+
+    private fun dispatchVideoPlaybackToSessionOnLooper() {
+        if (videoPlayer() == null) {
+            return
+        }
+        val ready = playWhenReady
+        val state = playbackState
+        val playing = isPlaying
+        val commands = try {
+            availableCommands
+        } catch (_: Throwable) {
+            null
+        }
+        for (listener in sessionListeners) {
+            listener.onPlayWhenReadyChanged(ready, Player.PLAY_WHEN_READY_CHANGE_REASON_USER_REQUEST)
+            listener.onPlaybackStateChanged(state)
+            listener.onIsPlayingChanged(playing)
+            if (commands != null) {
+                listener.onAvailableCommandsChanged(commands)
+            }
+        }
+    }
+
+    private fun applicationLooperOrNull(): Looper? = try {
+        applicationLooper
+    } catch (_: Throwable) {
+        null
+    }
+}

package/android/src/main/java/org/dwbn/plugins/playlist/service/MediaNotificationPolicy.kt

@@ -0,0 +1,253 @@
+package org.dwbn.plugins.playlist.service
+
+import android.content.Intent
+import android.os.Build
+import androidx.annotation.OptIn
+import androidx.media3.common.C
+import androidx.media3.common.Player
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.session.DefaultMediaNotificationProvider
+
+/**
+ * Pure notification / focus / video-handoff decisions for Stories 55.5–55.6.
+ * [MediaService], [org.dwbn.plugins.playlist.playlist.AudioPlaylistHandler] and
+ * [org.dwbn.plugins.playlist.RmxAudioPlayer] call these so JVM tests can cover the I/O matrix
+ * without a device.
+ */
+@OptIn(UnstableApi::class)
+object MediaNotificationPolicy {
+    const val HANDLE_AUDIO_FOCUS = true
+
+    /** FGS start blocked by notification permission or related security policy. */
+    @JvmStatic
+    fun isForegroundStartSecurityBlocked(error: Throwable): Boolean = error is SecurityException
+
+    @JvmStatic
+    fun isForegroundStartNotAllowedFromBackground(error: Throwable): Boolean =
+        Build.VERSION.SDK_INT >= Build.VERSION_CODES.S &&
+            error is android.app.ForegroundServiceStartNotAllowedException
+
+    /** Distinct from the video plugin session (`org.dwbn.video`); Media3 forbids two empty IDs. */
+    const val MEDIA_SESSION_ID = "org.dwbn.playlist"
+
+    /**
+     * [MediaService.promoteToForeground] must not call [android.app.Service.startForeground]
+     * (Android 12+ forbids restarting FGS from the background after video).
+     * FGS starts at the beginning of [MediaService.onCreate] so the startForegroundService
+     * timeout cannot fire while ExoPlayer / MediaSession are built. Media3 then replaces that
+     * notification; [MediaService.onStartCommand] must not post the title-only placeholder again.
+     */
+    const val ALLOW_START_FOREGROUND_ON_PROMOTE = false
+
+    /** Title-only FGS placeholder is only allowed before the session exists (onCreate start). */
+    const val ALLOW_TITLE_ONLY_NOTIFICATION_AFTER_SESSION = false
+
+    /** Show Media3's session notification before playback is ready so FGS starts within the timeout. */
+    const val SHOW_NOTIFICATION_WHEN_IDLE =
+        androidx.media3.session.MediaSessionService.SHOW_NOTIFICATION_FOR_IDLE_PLAYER_ALWAYS
+
+    val mediaNotificationProviderClass: Class<out DefaultMediaNotificationProvider>
+        get() = DefaultMediaNotificationProvider::class.java
+
+    @JvmStatic
+    fun shouldStartForegroundOnPromote(): Boolean = ALLOW_START_FOREGROUND_ON_PROMOTE
+
+    /** A second [android.content.Context.startForegroundService] while onCreate is still running trips the FGS timeout. */
+    @JvmStatic
+    fun shouldStartForegroundService(serviceAlreadyCreated: Boolean): Boolean = !serviceAlreadyCreated
+
+    @JvmStatic
+    fun shouldRequestLegacyAudioFocus(): Boolean = false
+
+    @JvmStatic
+    fun shouldLoadRemoteArtwork(artworkUri: String?): Boolean = !artworkUri.isNullOrEmpty()
+
+    @JvmStatic
+    fun hasNoLargeArtwork(artworkData: ByteArray?, artworkUri: String?): Boolean =
+        (artworkData == null || artworkData.isEmpty()) && !shouldLoadRemoteArtwork(artworkUri)
+
+    @JvmStatic
+    fun shouldSkipEndForeground(videoHandoffForegroundRetain: Boolean): Boolean =
+        videoHandoffForegroundRetain
+
+    /**
+     * Pause even when buffering / [androidx.media3.common.Player.isPlaying] is false so Media3
+     * [handleAudioFocus] abandons. Teaching-sequence video may call prepare while not playing.
+     */
+    @JvmStatic
+    fun shouldPauseForVideoHandoff(isPlaying: Boolean): Boolean = true
+
+    /** Teaching-sequence path has no prewarm — retain must start on prepare. */
+    @JvmStatic
+    fun shouldRetainForegroundOnPrepare(): Boolean = true
+
+    /**
+     * Media3 caps [androidx.media3.session.MediaSessionService.setForegroundServiceTimeoutMs]
+     * at 10 minutes, so [MediaService.onUpdateNotificationAsync] must force
+     * `startInForegroundRequired=true` while retain is set.
+     */
+    @JvmStatic
+    fun shouldForceNotificationForeground(videoHandoffForegroundRetain: Boolean): Boolean =
+        videoHandoffForegroundRetain
+
+    @JvmStatic
+    fun startInForegroundRequired(
+        videoHandoffForegroundRetain: Boolean,
+        media3Requested: Boolean
+    ): Boolean = media3Requested || shouldForceNotificationForeground(videoHandoffForegroundRetain)
+
+    /** MediaSession / notification play must not start audible audio while retain is set and video is absent. */
+    @JvmStatic
+    fun shouldIgnoreSessionPlay(videoHandoffForegroundRetain: Boolean): Boolean =
+        shouldIgnoreSessionPlay(videoHandoffForegroundRetain, videoHandoffPlayerAttached = false)
+
+    @JvmStatic
+    fun shouldIgnoreSessionPlay(
+        videoHandoffForegroundRetain: Boolean,
+        videoHandoffPlayerAttached: Boolean
+    ): Boolean = videoHandoffForegroundRetain && !videoHandoffPlayerAttached
+
+    @JvmStatic
+    fun shouldDelegateNotificationToVideo(
+        videoHandoffForegroundRetain: Boolean,
+        videoHandoffPlayerAttached: Boolean
+    ): Boolean = videoHandoffForegroundRetain && videoHandoffPlayerAttached
+
+    @JvmStatic
+    fun mediaNotificationSkipPreviousEnabled(
+        previousAvailable: Boolean,
+        videoHandoffForegroundRetain: Boolean,
+        videoHandoffPlayerAttached: Boolean
+    ): Boolean {
+        if (shouldDelegateNotificationToVideo(videoHandoffForegroundRetain, videoHandoffPlayerAttached)) {
+            return false
+        }
+        return mediaNotificationSkipPreviousEnabled(previousAvailable)
+    }
+
+    @JvmStatic
+    fun mediaNotificationSkipNextEnabled(
+        nextAvailable: Boolean,
+        videoHandoffForegroundRetain: Boolean,
+        videoHandoffPlayerAttached: Boolean
+    ): Boolean {
+        if (shouldDelegateNotificationToVideo(videoHandoffForegroundRetain, videoHandoffPlayerAttached)) {
+            return false
+        }
+        return mediaNotificationSkipNextEnabled(nextAvailable)
+    }
+
+    /** Android audible resume stays play then seek (not seek then play). */
+    @JvmStatic
+    fun shouldPlayThenSeekOnResume(): Boolean = true
+
+    /**
+     * `{ resumed: true }` only for in-place audible resume while FGS is already up.
+     * Prewarm, paused exit, and missing FGS all return false so JS may `playTrackById`.
+     */
+    @JvmStatic
+    fun shouldReportInPlaceResumed(
+        prewarm: Boolean,
+        play: Boolean,
+        retain: Boolean,
+        serviceInForeground: Boolean
+    ): Boolean = !prewarm && play && retain && serviceInForeground
+
+    /** [org.dwbn.plugins.playlist.RmxAudioPlayer.getLastKnownPositionSec] is the handoff snapshot. */
+    @JvmStatic
+    fun lastKnownPositionSec(handoffPositionSec: Float): Float = handoffPositionSec
+
+    /**
+     * Failed in-place resume must not last-resort [org.dwbn.plugins.playlist.manager.PlaylistManager.beginPlayback]
+     * (Android 12+ forbids starting FGS from the background after video). JS may play/seek.
+     */
+    @JvmStatic
+    fun shouldBeginPlaybackWhenInPlaceUnavailable(): Boolean = false
+
+    /** Teaching-sequence retain starts on prepare — [org.dwbn.plugins.playlist.RmxAudioPlayer] must call this. */
+    @JvmStatic
+    fun applyForegroundRetainOnPrepare(setRetain: Runnable) {
+        if (shouldRetainForegroundOnPrepare()) {
+            setRetain.run()
+        }
+    }
+
+    /** Miss-path audible resume must not [org.dwbn.plugins.playlist.manager.PlaylistManager.beginPlayback]. */
+    @JvmStatic
+    fun applyBeginPlaybackWhenInPlaceUnavailable(beginPlayback: Runnable) {
+        if (shouldBeginPlaybackWhenInPlaceUnavailable()) {
+            beginPlayback.run()
+        }
+    }
+
+    /**
+     * [org.dwbn.plugins.playlist.manager.PlaylistManager] player listener must call this when
+     * [androidx.media3.common.Player.Listener.onPlayWhenReadyChanged] fires.
+     */
+    @JvmStatic
+    fun applyRetainPlayWhenReadyGuard(
+        playWhenReady: Boolean,
+        videoHandoffForegroundRetain: Boolean,
+        videoHandoffPlayerAttached: Boolean,
+        pausePlayer: Runnable
+    ) {
+        if (playWhenReady &&
+            shouldIgnoreSessionPlay(videoHandoffForegroundRetain, videoHandoffPlayerAttached)
+        ) {
+            pausePlayer.run()
+        }
+    }
+
+    @JvmStatic
+    fun sessionLaunchIntentFlags(): Int =
+        Intent.FLAG_ACTIVITY_REORDER_TO_FRONT or Intent.FLAG_ACTIVITY_SINGLE_TOP
+
+    @JvmStatic
+    fun shouldOverwriteMedia3NotificationOnStartCommand(): Boolean = false
+
+    @JvmStatic
+    fun shouldAllowTitleOnlyNotificationAfterSession(): Boolean =
+        ALLOW_TITLE_ONLY_NOTIFICATION_AFTER_SESSION
+
+    /** CPU + Wi-Fi lock while playing, as PlaylistCore's WifiLock and ExoMedia's partial wake lock did. */
+    const val WAKE_MODE = C.WAKE_MODE_NETWORK
+
+    /** `setOptions({ options: { icon } })` names an app drawable; fall back to the platform play glyph. */
+    @JvmStatic
+    fun smallIconRes(resolvedIconRes: Int): Int =
+        if (resolvedIconRes != 0) resolvedIconRes else android.R.drawable.ic_media_play
+
+    /** Mirrors [org.dwbn.plugins.playlist.manager.PlaylistManager.isPreviousAvailable] for JVM tests. */
+    @JvmStatic
+    fun mediaNotificationSkipPreviousEnabled(previousAvailable: Boolean): Boolean = previousAvailable
+
+    /** Mirrors [org.dwbn.plugins.playlist.manager.PlaylistManager.isNextAvailable] for JVM tests. */
+    @JvmStatic
+    fun mediaNotificationSkipNextEnabled(nextAvailable: Boolean): Boolean = nextAvailable
+
+    /**
+     * Starts from Media3 default / wrapped player commands so metadata and play-pause stay
+     * available. Skip is added or removed from that set — never replace it with a tiny list.
+     */
+    @JvmStatic
+    fun playerCommandsForMediaNotification(
+        base: Player.Commands,
+        previousAvailable: Boolean,
+        nextAvailable: Boolean
+    ): Player.Commands {
+        val builder = base.buildUpon().add(Player.COMMAND_PLAY_PAUSE)
+        if (mediaNotificationSkipPreviousEnabled(previousAvailable)) {
+            builder.add(Player.COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM)
+        } else {
+            builder.remove(Player.COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM)
+            builder.remove(Player.COMMAND_SEEK_TO_PREVIOUS)
+        }
+        if (mediaNotificationSkipNextEnabled(nextAvailable)) {
+            builder.add(Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM)
+        } else {
+            builder.remove(Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM)
+            builder.remove(Player.COMMAND_SEEK_TO_NEXT)
+        }
+        return builder.build()
+    }
+}