components_music_AudioPlayerView.bs

import "pkg:/source/api/ApiClient.bs"
import "pkg:/source/api/apiPool.bs"
import "pkg:/source/api/baseRequest.bs"
import "pkg:/source/api/image.bs"
import "pkg:/source/constants/imageSize.bs"
import "pkg:/source/roku_modules/log/LogMixin.brs"
import "pkg:/source/translationKeys.bs"
import "pkg:/source/utils/appWaits.bs"
import "pkg:/source/utils/itemImageUrl.bs"
import "pkg:/source/utils/misc.bs"
import "pkg:/source/utils/tasks.bs"
import "pkg:/source/utils/translate.bs"
import "pkg:/source/utils/voiceTransport.bs"

sub init()
  m.log = new log.Logger("AudioPlayerView")

  m.top.isOptionsAvailable = false
  ' Reaching this screen is where an audio playback start goes (appWaits.leftBehind).
  m.top.isPlaybackScreen = true
  m.isInScrubMode = false
  m.lastRecordedPositionTimestamp = 0
  m.scrubTimestamp = -1
  m.currentBackdropUrl = ""

  m.queueManager = m.global.queueManager
  ' The playback start this screen was opened for (QueueManager.beginPlaybackStart): done when
  ' the first stream loads, failed when it does not or the screen closes first.
  m.playbackStart = m.queueManager.callFunc("takePlaybackStart")
  m.playlistTypeCount = m.queueManager.callFunc("getQueueUniqueTypes").count()

  m.audioPlayer = m.global.audioPlayer
  m.audioPlayer.observeField("state", "audioStateChanged")
  m.audioPlayer.observeField("position", "audioPositionChanged")
  m.audioPlayer.observeField("bufferingStatus", "bufferPositionChanged")

  setupAnimationTasks()
  setupButtons()
  setupInfoNodes()
  setupDataTasks()
  setupScreenSaver()
  applyTheme()

  m.seekPosition.translation = [720 - (m.seekPosition.width / 2), m.seekPosition.translation[1]]

  m.screenSaverTimeout = 0

  m.LoadScreenSaverTimeoutTask.observeField("content", "onScreensaverTimeoutLoaded")
  launchTask(m.LoadScreenSaverTimeoutTask)

  loadButtons()
  pageContentChanged()
  setShuffleIconState()
  setLoopButtonImage()
  ' Set lastFocus for JRScreen lifecycle management
  m.top.lastFocus = m.buttons

  ' Show "Playing <title>" for an audio cast. The launcher set the title before navigating
  ' here; this mount is the stable point (nothing churns after). One-shot: clear it.
  if isValidAndNotEmpty(m.global.deepLinkOpeningTitle)
    displayToast(Substitute(translate(translationKeys.MessagePlayingContent), m.global.deepLinkOpeningTitle), "info")
    m.global.deepLinkOpeningTitle = ""
  end if
end sub

sub applyTheme()
  constants = m.global.constants

  m.seekBar.color = constants.colorBlack + constants.alpha60
  m.bufferPosition.color = constants.colorBackgroundSecondary
  m.playPosition.color = constants.colorSecondary
  m.thumb.blendColor = constants.colorPrimary
end sub

sub onScreensaverTimeoutLoaded()
  data = m.LoadScreenSaverTimeoutTask.content
  m.LoadScreenSaverTimeoutTask.unobserveField("content")
  if isValid(data)
    m.screenSaverTimeout = data
  end if
end sub

sub setupScreenSaver()
  m.screenSaverBackground = m.top.FindNode("screenSaverBackground")

  ' Album Art Screensaver
  m.screenSaverAlbumCover = m.top.FindNode("screenSaverAlbumCover")
  m.screenSaverAlbumAnimation = m.top.findNode("screenSaverAlbumAnimation")
  m.screenSaverAlbumCoverFadeIn = m.top.findNode("screenSaverAlbumCoverFadeIn")

  ' Audio Screensaver
  m.PosterOne = m.top.findNode("PosterOne")
  m.PosterOne.uri = "pkg:/images/branding/logo.png"
  m.BounceAnimation = m.top.findNode("BounceAnimation")
  m.PosterOneFadeIn = m.top.findNode("PosterOneFadeIn")
end sub

sub setupAnimationTasks()
  m.playPositionAnimation = m.top.FindNode("playPositionAnimation")
  m.playPositionAnimationWidth = m.top.FindNode("playPositionAnimationWidth")

  m.bufferPositionAnimation = m.top.FindNode("bufferPositionAnimation")
  m.bufferPositionAnimationWidth = m.top.FindNode("bufferPositionAnimationWidth")
end sub

' Creates tasks to gather data needed to render Scene and play song
sub setupDataTasks()
  ' Song metadata: a new node per run, created at the launch in onAudioStreamLoaded; any run is
  ' released on every track change (pageContentChanged) and in onDestroy.
  m.LoadMetaDataTask = invalid

  ' Load audio stream
  m.LoadAudioStreamTask = CreateObject("roSGNode", "LoadItemsTask")
  m.LoadAudioStreamTask.itemsToLoad = "audioStream"

  m.LoadScreenSaverTimeoutTask = CreateObject("roSGNode", "LoadScreenSaverTimeoutTask")
end sub

' Setup playback buttons, default to Play button selected
sub setupButtons()
  m.buttons = m.top.findNode("buttons")

  ' Get button references for later use
  m.playButton = m.buttons.findNode("play")
  m.shuffleButton = m.buttons.findNode("shuffle")
  m.repeatButton = m.buttons.findNode("repeat")

  ' If we're playing a mixed playlist, remove the shuffle and repeat buttons
  if m.playlistTypeCount > 1
    if isValid(m.shuffleButton)
      m.buttons.removeChild(m.shuffleButton)
      m.shuffleButton = invalid
    end if

    if isValid(m.repeatButton)
      m.buttons.removeChild(m.repeatButton)
      m.repeatButton = invalid
    end if
  end if

  ' Set default focus to play button (index 1)
  m.buttons.buttonFocused = 1

  ' Center button group horizontally
  m.buttons.callFunc("center")

  ' Observe button selection
  m.buttons.observeField("buttonSelected", "onButtonSelected")
end sub

' Event handler when user selects a button via OK key
sub onButtonSelected()
  buttonIndex = m.buttons.buttonSelected
  button = m.buttons.getChild(buttonIndex)

  if not isValid(button) then return

  if button.id = "play"
    playAction()
  else if button.id = "previous"
    previousClicked()
  else if button.id = "next"
    nextClicked()
  else if button.id = "shuffle"
    shuffleClicked()
  else if button.id = "repeat"
    loopClicked()
  end if
end sub

sub setupInfoNodes()
  m.albumCover = m.top.findNode("albumCover")
  m.albumPlaceholder = m.top.findNode("albumPlaceholder")
  m.albumCover.observeField("loadStatus", "onAlbumCoverLoadStatusChanged")
  m.playPosition = m.top.findNode("playPosition")
  m.bufferPosition = m.top.findNode("bufferPosition")
  m.seekBar = m.top.findNode("seekBar")
  m.thumb = m.top.findNode("thumb")
  m.positionTimestamp = m.top.findNode("positionTimestamp")
  m.seekPosition = m.top.findNode("seekPosition")
  m.seekTimestamp = m.top.findNode("seekTimestamp")
  m.totalLengthTimestamp = m.top.findNode("totalLengthTimestamp")
end sub

sub bufferPositionChanged()
  if m.isInScrubMode then return

  if not isValid(m.audioPlayer.bufferingStatus)
    bufferPositionBarWidth = m.seekBar.width
  else
    bufferPositionBarWidth = m.seekBar.width * m.audioPlayer.bufferingStatus.percentage
  end if

  ' Ensure position bar is never wider than the seek bar
  if bufferPositionBarWidth > m.seekBar.width
    bufferPositionBarWidth = m.seekBar.width
  end if

  ' Use animation to make the display smooth
  m.bufferPositionAnimationWidth.keyValue = [m.bufferPosition.width, bufferPositionBarWidth]
  m.bufferPositionAnimation.control = "start"
end sub

sub audioPositionChanged()
  stopLoadingSpinner()

  if m.audioPlayer.position = 0
    m.playPosition.width = 0
  end if

  if not isValid(m.audioPlayer.position)
    playPositionBarWidth = 0
  else if not isValid(m.songDuration)
    playPositionBarWidth = 0
  else
    songPercentComplete = m.audioPlayer.position / m.songDuration
    playPositionBarWidth = m.seekBar.width * songPercentComplete
  end if

  ' Ensure position bar is never wider than the seek bar
  if playPositionBarWidth > m.seekBar.width
    playPositionBarWidth = m.seekBar.width
  end if

  if not m.isInScrubMode
    moveSeekbarThumb(playPositionBarWidth)
    ' Change the seek position timestamp
    m.seekTimestamp.text = secondsToTimestamp(m.audioPlayer.position, false)
  end if

  ' Use animation to make the display smooth
  m.playPositionAnimationWidth.keyValue = [m.playPosition.width, playPositionBarWidth]
  m.playPositionAnimation.control = "start"

  ' Update displayed position timestamp
  if isValid(m.audioPlayer.position)
    m.lastRecordedPositionTimestamp = m.audioPlayer.position
    m.positionTimestamp.text = secondsToTimestamp(m.audioPlayer.position, false)
  else
    m.lastRecordedPositionTimestamp = 0
    m.positionTimestamp.text = "0:00"
  end if

  ' Only fall into screensaver logic if the user has screensaver enabled in Roku settings
  if m.screenSaverTimeout > 0
    di = CreateObject("roDeviceInfo")
    if di.TimeSinceLastKeypress() >= m.screenSaverTimeout - 2
      if not screenSaverActive()
        startScreenSaver()
      end if
    end if
  end if
end sub

function screenSaverActive() as boolean
  return m.screenSaverBackground.visible or m.screenSaverAlbumCover.opacity > 0 or m.PosterOne.opacity > 0
end function

sub startScreenSaver()
  m.screenSaverBackground.visible = true
  m.top.isOverhangVisible = false

  if m.albumCover.uri = ""
    ' Audio Logo Screensaver
    m.PosterOne.visible = true
    m.PosterOneFadeIn.control = "start"
    m.BounceAnimation.control = "start"
  else
    ' Album Art Screensaver
    m.screenSaverAlbumCoverFadeIn.control = "start"
    m.screenSaverAlbumAnimation.control = "start"
  end if
end sub

sub endScreenSaver()
  m.PosterOneFadeIn.control = "pause"
  m.screenSaverAlbumCoverFadeIn.control = "pause"
  m.screenSaverAlbumAnimation.control = "pause"
  m.BounceAnimation.control = "pause"
  m.screenSaverBackground.visible = false
  m.screenSaverAlbumCover.opacity = 0
  m.PosterOne.opacity = 0
  m.top.isOverhangVisible = true
end sub

sub audioStateChanged()
  ' Update play/pause button icon based on audio state
  if isValid(m.playButton)
    if m.audioPlayer.state = "playing"
      m.playButton.icon = "pkg:/images/icons/pause_$$RES$$.png"
    else
      m.playButton.icon = "pkg:/images/icons/play_$$RES$$.png"
    end if
  end if

  ' Song Finished, attempt to move to next song
  if m.audioPlayer.state = "finished"
    ' User has enabled single song loop, play current song again
    if m.audioPlayer.loopMode = "one"
      m.scrubTimestamp = -1
      playAction()
      exitScrubMode()
      return
    end if

    if m.queueManager.callFunc("getPosition") < m.queueManager.callFunc("getCount") - 1
      ' Advance in-place.
      advanceToNextItem()
    else
      ' We are at the end of the song queue

      ' User has enabled loop for entire song queue, move back to first song
      if m.audioPlayer.loopMode = "all"
        m.queueManager.callFunc("setPosition", -1)
        LoadNextSong()
        return
      end if

      ' Queue exhausted: leave the routed /audio view.
      exitAudioPlayback()
    end if
  end if
end sub

' Advance to the next queue item on auto-finish. Audio stays in this routed /audio view
' (reload the stream in place via LoadNextSong). A non-audio next item in a mixed queue leaves
' /audio for the player route: playQueue routes it to /play, which covers /audio, so the
' router suspends it rather than destroying it.
sub advanceToNextItem()
  nextPosition = m.queueManager.callFunc("getPosition") + 1
  if nextPosition > m.queueManager.callFunc("getCount") - 1 then return

  if m.playlistTypeCount > 1
    nextItem = m.queueManager.callFunc("getItemByIndex", nextPosition)
    if m.queueManager.callFunc("getItemType", nextItem) <> "audio"
      m.audioPlayer.control = "stop"
      m.queueManager.callFunc("moveForward")
      m.queueManager.callFunc("playQueue")
      return
    end if
  end if

  LoadNextSong()
end sub

' Leave the routed /audio view, returning to the launching detail (the router resumes the view
' beneath). Stops playback + clears loop first. The physical back key already stops audio in
' onKeyEvent and bubbles to the outlet's goBack, so it does not route through here.
sub exitAudioPlayback()
  m.audioPlayer.control = "stop"
  m.audioPlayer.loopMode = ""
  sgrouter.goBack()
end sub

function playAction() as boolean

  if m.audioPlayer.state = "playing"
    m.audioPlayer.control = "pause"
    if isValid(m.playButton)
      m.playButton.icon = "pkg:/images/icons/play_$$RES$$.png"
    end if
  else if m.audioPlayer.state = "paused"
    m.audioPlayer.control = "resume"
    if isValid(m.playButton)
      m.playButton.icon = "pkg:/images/icons/pause_$$RES$$.png"
    end if
  else if m.audioPlayer.state = "finished"
    m.audioPlayer.control = "play"
    if isValid(m.playButton)
      m.playButton.icon = "pkg:/images/icons/pause_$$RES$$.png"
    end if
  end if

  return true
end function

function previousClicked() as boolean
  currentQueuePosition = m.queueManager.callFunc("getPosition")
  if currentQueuePosition = 0 then return false

  if m.playlistTypeCount > 1
    previousItem = m.queueManager.callFunc("getItemByIndex", currentQueuePosition - 1)
    previousItemType = m.queueManager.callFunc("getItemType", previousItem)

    if previousItemType <> "audio"
      ' A non-audio previous item leaves /audio for the player route (playQueue -> /play,
      ' which covers /audio, so the router suspends it rather than destroying it).
      m.audioPlayer.control = "stop"
      m.queueManager.callFunc("moveBack")
      m.queueManager.callFunc("playQueue")
      return true
    end if
  end if

  exitScrubMode()

  m.lastRecordedPositionTimestamp = 0
  m.positionTimestamp.text = "0:00"

  if m.audioPlayer.state = "playing"
    m.audioPlayer.control = "stop"
  end if

  m.queueManager.callFunc("moveBack")
  pageContentChanged()

  return true
end function

function loopClicked() as boolean
  if m.audioPlayer.loopMode = ""
    m.audioPlayer.loopMode = "all"
  else if m.audioPlayer.loopMode = "all"
    m.audioPlayer.loopMode = "one"
  else
    m.audioPlayer.loopMode = ""
  end if

  setLoopButtonImage()

  return true
end function

sub setLoopButtonImage()
  if not isValid(m.repeatButton) then return

  if m.audioPlayer.loopMode = "all"
    ' Repeat all - use repeat.png with active state
    m.repeatButton.icon = "pkg:/images/icons/repeat_$$RES$$.png"
    m.repeatButton.isButtonSelected = true
  else if m.audioPlayer.loopMode = "one"
    ' Repeat one - use repeat-1.png with active state
    m.repeatButton.icon = "pkg:/images/icons/repeat-1_$$RES$$.png"
    m.repeatButton.isButtonSelected = true
  else
    ' Repeat off - use repeat.png without active state
    m.repeatButton.icon = "pkg:/images/icons/repeat_$$RES$$.png"
    m.repeatButton.isButtonSelected = false
  end if
end sub

' Returns false at end-of-queue so callers can distinguish "advanced" from "no-op".
' Side effects (timestamp reset) only fire when an advance actually happens:
' pressing Next on the last track is a no-op, not a partial reset.
function nextClicked() as boolean
  currentQueuePosition = m.queueManager.callFunc("getPosition")
  if currentQueuePosition >= m.queueManager.callFunc("getCount") - 1 then return false

  if m.playlistTypeCount > 1
    nextItem = m.queueManager.callFunc("getItemByIndex", currentQueuePosition + 1)
    nextItemType = m.queueManager.callFunc("getItemType", nextItem)

    if nextItemType <> "audio"
      ' A non-audio next item leaves /audio for the player route (playQueue -> /play, which
      ' covers /audio, so the router suspends it rather than destroying it).
      m.audioPlayer.control = "stop"
      m.queueManager.callFunc("moveForward")
      m.queueManager.callFunc("playQueue")
      return true
    end if
  end if

  exitScrubMode()

  m.lastRecordedPositionTimestamp = 0
  m.positionTimestamp.text = "0:00"

  LoadNextSong()

  return true
end function

sub toggleShuffleEnabled()
  m.queueManager.callFunc("toggleShuffle")
end sub

function findCurrentSongIndex(songList) as integer
  if not isValidAndNotEmpty(songList) then return 0

  for i = 0 to songList.count() - 1
    if songList[i].id = m.queueManager.callFunc("getCurrentItem").id
      return i
    end if
  end for

  return 0
end function

function shuffleClicked() as boolean
  currentSongIndex = findCurrentSongIndex(m.queueManager.callFunc("getUnshuffledQueue"))

  toggleShuffleEnabled()

  if not m.queueManager.callFunc("getIsShuffled")
    ' Shuffle off
    if isValid(m.shuffleButton)
      m.shuffleButton.isButtonSelected = false
    end if
    m.queueManager.callFunc("setPosition", currentSongIndex)
    setTrackNumberDisplay()
    return true
  end if

  ' Shuffle on
  if isValid(m.shuffleButton)
    m.shuffleButton.isButtonSelected = true
  end if
  setTrackNumberDisplay()

  return true
end function

sub setShuffleIconState()
  if not isValid(m.shuffleButton) then return

  if m.queueManager.callFunc("getIsShuffled")
    m.shuffleButton.isButtonSelected = true
  else
    m.shuffleButton.isButtonSelected = false
  end if
end sub

sub setTrackNumberDisplay()
  position = stri(m.queueManager.callFunc("getPosition") + 1).trim()
  count = stri(m.queueManager.callFunc("getCount")).trim()
  setFieldTextValue("numberofsongs", translate(translationKeys.LabelTrack) + " " + translate(translationKeys.Message1Of2, [position, count]))
end sub

sub LoadNextSong()
  if m.audioPlayer.state = "playing"
    m.audioPlayer.control = "stop"
  end if

  exitScrubMode()

  ' Reset playPosition bar without animation
  m.playPosition.width = 0
  m.queueManager.callFunc("moveForward")
  pageContentChanged()
end sub

' Update values on screen when page content changes
sub pageContentChanged()

  m.LoadAudioStreamTask = replaceTask(m.LoadAudioStreamTask, "LoadItemsTask", "content", { itemsToLoad: "audioStream" })
  ' A metadata run still in flight belongs to the song being left. Dropped here, not only when
  ' the next song launches its own, because the next song may not need one: its late delivery
  ' would still be the current node's and paint the old title and artwork over this song.
  m.LoadMetaDataTask = releaseTask(m.LoadMetaDataTask, "content")

  currentItem = m.queueManager.callFunc("getCurrentItem")

  ' Update the queue-derived display NOW (same tick as the position-bar/timestamp reset the
  ' caller did) so the title + "Track X of Y" don't lag behind until the async stream task
  ' returns. onAudioStreamLoaded/onMetaDataLoaded re-apply once the fuller item resolves.
  applyTrackInfo(currentItem)

  m.LoadAudioStreamTask.itemId = currentItem.id
  m.LoadAudioStreamTask.observeField("content", "onAudioStreamLoaded")
  launchTask(m.LoadAudioStreamTask)
end sub

' If we have more than 1 song to play, set initial button states
sub loadButtons()
  if m.queueManager.callFunc("getCount") > 1
    ' Set initial loop/repeat button state
    setLoopButtonImage()
  end if
end sub

sub onAudioStreamLoaded(event as object)
  ' Before the spinner: an event from a replaced run must not stop the live run's spinner.
  if not isCurrentTaskEvent(event, m.LoadAudioStreamTask) then return
  stopLoadingSpinner()
  data = m.LoadAudioStreamTask.content[0]
  m.LoadAudioStreamTask.unobserveField("content")
  if isValid(data) and data.count() > 0
    appWaits.done(m.playbackStart)
    ' Reset buffer bar without animation
    m.bufferPosition.width = 0

    shouldUseMetaTask = false
    currentItem = m.queueManager.callFunc("getCurrentItem")

    if not isValid(currentItem.runTimeTicks) or currentItem.runTimeTicks = 0
      shouldUseMetaTask = true
    end if

    if not isValidAndNotEmpty(currentItem.albumArtist)
      shouldUseMetaTask = true
    end if

    if not isValidAndNotEmpty(currentItem.name)
      shouldUseMetaTask = true
    end if

    if not isValid(currentItem.artists) or currentItem.artists.count() = 0
      shouldUseMetaTask = true
    end if

    ' If we don't have enough data to populate the screen, load metadata (which also sets the artwork)
    if shouldUseMetaTask
      m.LoadMetaDataTask = replaceTask(m.LoadMetaDataTask, "LoadItemsTask", "content", { itemsToLoad: "metaData" })
      m.LoadMetaDataTask.itemId = currentItem.id
      m.LoadMetaDataTask.observeField("content", "onMetaDataLoaded")
      launchTask(m.LoadMetaDataTask)
    else
      applyItemArtwork(currentItem)
      applyTrackInfo(currentItem)
    end if

    m.audioPlayer.content = data
    m.audioPlayer.control = "none"
    m.audioPlayer.control = "play"
  else
    appWaits.fail(m.playbackStart, "the load found nothing to play")
  end if
end sub

sub onMetaDataLoaded(event as object)
  if not isCurrentTaskEvent(event, m.LoadMetaDataTask) then return
  data = m.LoadMetaDataTask.content[0]
  m.LoadMetaDataTask.unobserveField("content")

  ' A failed fetch publishes [invalid]. The song is already playing, and nothing has set its
  ' artwork yet (the screen still shows the PREVIOUS song's), so use the queue item's own.
  if not isValid(data) or not isValidAndNotEmpty(data.id)
    m.log.warn("song metadata did not load; showing the queue item's own artwork", m.LoadMetaDataTask.itemId)
    currentItem = m.queueManager.callFunc("getCurrentItem")
    ' The user skipped on while it loaded: that song's own load sets its artwork.
    if not isValid(currentItem) or currentItem.id <> m.LoadMetaDataTask.itemId then return
    applyItemArtwork(currentItem)
    return
  end if

  applyItemArtwork(data)
  applyTrackInfo(data)
end sub

' Set the backdrop and poster from a song. getItemBackdropUrl falls back to the parent's
' backdrop (NameGuidPair artist items have no BackdropImageTags). Poster: album art, then the
' song's own primary; with neither, an empty URI surfaces the JRPlaceholder behind albumCover
' and sends startScreenSaver() to the audio-logo branch instead of drifting a fallback glyph.
sub applyItemArtwork(item as object)
  deviceRes = m.global.device.uiResolution
  backdropUri = getItemBackdropUrl(item, { width: deviceRes[0], height: deviceRes[1] })
  if not isValidAndNotEmpty(backdropUri) then backdropUri = ""
  m.log.info("Backdrop change: old=", m.currentBackdropUrl, "new=", backdropUri)
  m.currentBackdropUrl = backdropUri
  m.global.sceneManager.callFunc("setBackgroundImage", backdropUri)

  artSize = imageSize.AUDIO_ART
  if isValidAndNotEmpty(item.albumId) and isValidAndNotEmpty(item.albumPrimaryImageTag)
    setPosterImage(ImageURL(item.albumId, "Primary", { "maxHeight": artSize.height, "maxWidth": artSize.width, "tag": item.albumPrimaryImageTag }))
  else if isValidAndNotEmpty(item.primaryImageTag)
    setPosterImage(ImageURL(item.id, "Primary", { "maxHeight": artSize.height, "maxWidth": artSize.width, "tag": item.primaryImageTag }))
  else
    setPosterImage("")
  end if
end sub

' Set poster image on screen. Empty string clears the URI on both the main album cover
' and the screensaver cover: the JRPlaceholder behind albumCover surfaces, and the
' screensaver activator at startScreenSaver() routes to the audio-logo branch instead
' of drifting a fallback glyph around.
sub setPosterImage(posterURL as dynamic)
  if not isValid(posterURL) then return
  if m.albumCover.uri = posterURL then return
  m.albumCover.uri = posterURL
  m.screenSaverAlbumCover.uri = posterURL
end sub

' Toggle the JRPlaceholder behind albumCover based on the real poster's load state.
' Mirrors the canonical state machine from JRRowItem.bs onPosterLoadStatusChanged,
' but with itemType statically set to "MusicAlbum" in XML (no per-state retyping).
sub onAlbumCoverLoadStatusChanged()
  if m.albumCover.loadStatus = "ready" and m.albumCover.uri <> ""
    m.albumPlaceholder.visible = false
  else if m.albumCover.loadStatus = "failed" and m.albumCover.uri <> ""
    ' Real image failed: clear both URIs so the placeholder shows and the screensaver
    ' gate at startScreenSaver() sees an empty albumCover.uri (audio-logo branch).
    m.albumCover.uri = ""
    m.screenSaverAlbumCover.uri = ""
    m.albumPlaceholder.visible = true
  else
    m.albumPlaceholder.visible = true
  end if
end sub

' Set screen's title text to "Artist / Song" when both are available,
' only the song name if no album artist, or empty string to reset the title.
sub setScreenTitle(item as object)
  newTitle = ""
  if isValidAndNotEmpty(item.albumArtist) and isValidAndNotEmpty(item.name)
    newTitle = item.albumArtist + " / " + item.name
  else if isValidAndNotEmpty(item.name)
    newTitle = item.name
  end if

  ' Assign even when empty: resets title when newTitle is ""
  if m.top.overhangTitle <> newTitle
    m.top.overhangTitle = newTitle
  end if
end sub

' Populate on screen text variables
sub setOnScreenTextValues(item as object)
  if m.playlistTypeCount = 1
    setTrackNumberDisplay()
  end if

  artistName = ""
  if isValid(item.artists) and item.artists.count() > 0
    artistName = item.artists[0]
  end if
  setFieldTextValue("artist", artistName)
  setFieldTextValue("song", item.name)
end sub

' Apply the queue-derived now-playing display (track number, title, artist, song, total length)
' from the current item. Called SYNCHRONOUSLY on a track change (pageContentChanged) so these
' update on the same tick as the position-bar/timestamp reset instead of lagging until the async
' stream load returns, and re-applied from the async stream/metadata callbacks once a fuller item
' resolves (idempotent: setFieldTextValue/setScreenTitle no-op when unchanged or invalid). The
' poster/backdrop stay in the async path: image loads are inherently async.
sub applyTrackInfo(item as object)
  if not isValid(item) then return

  setScreenTitle(item)
  setOnScreenTextValues(item)

  if isValid(item.runTimeTicks) and item.runTimeTicks > 0
    m.songDuration = item.runTimeTicks / 10000000.0
    ' Update displayed total audio length
    m.totalLengthTimestamp.text = ticksToHuman(item.runTimeTicks)
  end if
end sub

' processScrubAction: Handles +/- seeking for the audio trickplay bar
'
' @param {integer} seekStep - seconds to move the trickplay position (negative values allowed)
sub processScrubAction(seekStep as integer)
  ' Prepare starting playStart property value
  if m.scrubTimestamp = -1
    m.scrubTimestamp = m.lastRecordedPositionTimestamp
  end if

  ' Don't let seek to go past the end of the song
  if m.scrubTimestamp + seekStep > m.songDuration - 5
    return
  end if

  if seekStep > 0
    ' Move seek forward
    m.scrubTimestamp += seekStep
  else if m.scrubTimestamp >= Abs(seekStep)
    ' If back seek won't go below 0, move seek back
    m.scrubTimestamp += seekStep
  else
    ' Back seek would go below 0, set to 0 directly
    m.scrubTimestamp = 0
  end if

  ' Move the seedbar thumb forward
  songPercentComplete = m.scrubTimestamp / m.songDuration
  playPositionBarWidth = m.seekBar.width * songPercentComplete

  moveSeekbarThumb(playPositionBarWidth)

  ' Change the displayed position timestamp
  m.seekTimestamp.text = secondsToTimestamp(m.scrubTimestamp, false)
end sub

' resetSeekbarThumb: Resets the thumb to the playing position
'
sub resetSeekbarThumb()
  m.scrubTimestamp = -1
  moveSeekbarThumb(m.playPosition.width)
end sub

' moveSeekbarThumb: Positions the thumb on the seekbar
'
' @param {float} playPositionBarWidth - width of the play position bar
sub moveSeekbarThumb(playPositionBarWidth as float)
  ' Center the thumb on the play position bar
  thumbPostionLeft = playPositionBarWidth - 10

  ' Don't let thumb go below 0
  if thumbPostionLeft < 0 then thumbPostionLeft = 0

  ' Don't let thumb go past end of seekbar
  if thumbPostionLeft > m.seekBar.width - 25
    thumbPostionLeft = m.seekBar.width - 25
  end if

  ' Move the thumb
  m.thumb.translation = [thumbPostionLeft, m.thumb.translation[1]]

  ' Move the seek position element so it follows the thumb
  m.seekPosition.translation = [720 + thumbPostionLeft - (m.seekPosition.width / 2), m.seekPosition.translation[1]]
end sub

' exitScrubMode: Moves player out of scrub mode state,  resets back to standard play mode
'
sub exitScrubMode()
  m.buttons.setFocus(true)
  m.thumb.setFocus(false)

  if m.seekPosition.visible
    m.seekPosition.visible = false
  end if

  resetSeekbarThumb()

  m.isInScrubMode = false
  m.thumb.visible = false
end sub

' Process key press events
function onKeyEvent(key as string, press as boolean) as boolean

  ' Key bindings for remote control buttons
  if press
    ' If user presses key to turn off screensaver, don't do anything else with it
    if screenSaverActive()
      endScreenSaver()
      return true
    end if

    ' Key Event handler when m.thumb is in focus
    if m.thumb.hasFocus()
      if key = "right"
        m.isInScrubMode = true
        processScrubAction(10)
        return true
      end if

      if key = "left"
        m.isInScrubMode = true
        processScrubAction(-10)
        return true
      end if

      if key = "OK" or key = "play"
        if m.isInScrubMode
          startLoadingSpinner()
          m.isInScrubMode = false
          m.audioPlayer.seek = m.scrubTimestamp
          return true
        end if

        return playAction()
      end if
    end if

    if key = "play"
      return playAction()
    end if

    if key = "up"
      if not m.thumb.visible
        m.thumb.visible = true
      end if
      if not m.seekPosition.visible
        m.seekPosition.visible = true
      end if

      m.thumb.setFocus(true)
      m.buttons.setFocus(false)
      return true
    end if

    if key = "down"
      if m.thumb.visible
        exitScrubMode()
      end if
      return true
    end if

    if key = "back"
      m.audioPlayer.control = "stop"
      m.audioPlayer.loopMode = ""
    else if key = "rewind"
      return previousClicked()
    else if key = "fastforward"
      return nextClicked()
    end if
  end if

  return false
end function

' Stop + tear down without navigating (a deep link arrived while audio plays; the caller
' reroutes to the new content). Stops the audio the same way the back key does
' (onKeyEvent "back" -> control "stop"): the caller's navigation is programmatic, so it
' bypasses that key handler. Not a full onDestroy: the caller then navigates to "/", whose
' clearStackOnResolve closes this view and runs onDestroy (JRScreen.beforeViewClose), and
' running onDestroy twice (it nulls m.audioPlayer) crashes the second pass.
sub teardownForDeepLink()
  if isValid(m.audioPlayer) then m.audioPlayer.control = "stop"
end sub

' onDestroy: Full teardown releasing all resources before component removal
' Called automatically via JRScreen.beforeViewClose when sgRouter permanently closes this view.
sub onDestroy()
  m.log.verbose("onDestroy")
  ' A start still open here never loaded a stream: Back, or a sign-out, before it did.
  appWaits.fail(m.playbackStart, "player closed before its stream loaded")

  ' Unobserve global audioPlayer fields (m.audioPlayer is m.global.audioPlayer: don't destroy it)
  m.audioPlayer.unobserveField("state")
  m.audioPlayer.unobserveField("position")
  m.audioPlayer.unobserveField("bufferingStatus")

  ' Unobserve button observer
  m.buttons.unobserveField("buttonSelected")

  ' Detach every task observer before releasing any task reference. Interleaving
  ' them leaves a window: a handler that reads another task's ref, arriving after
  ' that ref was nulled but before its own observer came off, would dot into
  ' invalid (&hec) - the #733 teardown shape. The metadata node is detached by
  ' releaseTask below in the same call that drops it (it may already be invalid).
  m.LoadAudioStreamTask.unobserveField("content")
  m.LoadScreenSaverTimeoutTask.unobserveField("content")

  ' Stop and release task nodes (observers may already be cleared by their callbacks)
  m.LoadMetaDataTask = releaseTask(m.LoadMetaDataTask, "content")

  m.LoadAudioStreamTask.control = "STOP"
  m.LoadAudioStreamTask = invalid

  m.LoadScreenSaverTimeoutTask.control = "STOP"
  m.LoadScreenSaverTimeoutTask = invalid

  ' Release global node references (nulling local refs only; global nodes are unaffected)
  m.audioPlayer = invalid
  m.queueManager = invalid

  ' Release the placeholder load-status observer before clearing refs
  if isValid(m.albumCover) then m.albumCover.unobserveField("loadStatus")

  ' Clear node references
  m.buttons = invalid
  m.playButton = invalid
  m.shuffleButton = invalid
  m.repeatButton = invalid
  m.albumCover = invalid
  m.albumPlaceholder = invalid
  m.playPosition = invalid
  m.bufferPosition = invalid
  m.seekBar = invalid
  m.thumb = invalid
  m.positionTimestamp = invalid
  m.seekPosition = invalid
  m.seekTimestamp = invalid
  m.totalLengthTimestamp = invalid
  m.playPositionAnimation = invalid
  m.playPositionAnimationWidth = invalid
  m.bufferPositionAnimation = invalid
  m.bufferPositionAnimationWidth = invalid
  m.screenSaverBackground = invalid
  m.screenSaverAlbumCover = invalid
  m.screenSaverAlbumAnimation = invalid
  m.screenSaverAlbumCoverFadeIn = invalid
  m.PosterOne = invalid
  m.BounceAnimation = invalid
  m.PosterOneFadeIn = invalid
end sub

' handleTransport: Roku voice transport handler. Called from source/main.bs when an
' roInputEvent with info.type = "transport" arrives and AudioPlayerView is the active scene.
'
' Returns { status: "<code>" } per roInput.EventResponse(). Status codes mirror video.
'
' JellyRock-specific behaviors (audio has no continuous trickplay, no media segments):
'   - "forward"/"rewind" are discrete 10s seeks.
'   - "replay" seeks backward by playbackInstantReplaySeconds (same setting as video),
'     which matches the Roku platform spec; users wanting loop control use the "loop" command.
'   - "skip" advances to the next track.
'
' See https://github.com/rokudev/dev-doc, file docs/DEVELOPER/media-playback/voice-controls/transport-controls.md
function handleTransport(evt as object) as object
  if not isValid(evt) or not isValid(evt.command) then return { status: "unhandled" }
  cmd = LCase(evt.command)
  m.log.info("voice transport", cmd)

  if cmd = "play" or cmd = "resume"
    if m.audioPlayer.state = "paused"
      m.audioPlayer.control = "resume"
      return { status: "success" }
    end if
    if m.audioPlayer.state = "playing" then return { status: "error.redundant" }
    m.audioPlayer.control = "play"
    return { status: "success" }
  end if

  if cmd = "pause"
    if m.audioPlayer.state = "paused" then return { status: "error.redundant" }
    m.audioPlayer.control = "pause"
    return { status: "success" }
  end if

  if cmd = "stop"
    ' Mirror back-key behavior: stop playback, clear loop, and leave the routed /audio view.
    ' The physical back key bubbles to the outlet's goBack; voice transport doesn't, so we exit
    ' explicitly.
    exitAudioPlayback()
    return { status: "success" }
  end if

  if cmd = "ok"
    ' No idle "open menu" equivalent for audio: the player is its own menu.
    return { status: "unhandled" }
  end if

  if cmd = "forward" then return audioSeekRelative(10)
  if cmd = "rewind" then return audioSeekRelative(-10)
  if cmd = "startover" then return audioSeekTo(0)

  if cmd = "replay"
    return audioSeekRelative(-voiceTransport.resolveInstantReplaySeconds(m.global.user.settings.playbackInstantReplaySeconds))
  end if

  if cmd = "seek" then return handleAudioVoiceSeek(evt)

  if cmd = "next" or cmd = "skip" then return audioNextTrack()

  ' Remote-control additions. "previous" reuses the on-screen previous-button path; "seekto" is an
  ' ABSOLUTE seek (Jellyfin Playstate Seek carries an absolute position, unlike voice's relative
  ' "seek"); "playpause" toggles by current transport state.
  if cmd = "previous"
    if not isValid(m.queueManager) then return { status: "error.generic" }
    if not previousClicked() then return { status: "error.generic" }
    return { status: "success" }
  end if

  if cmd = "seekto"
    if not isValid(evt.position) then return { status: "error.generic" }
    return audioSeekTo(evt.position)
  end if

  if cmd = "playpause"
    if m.audioPlayer.state = "playing"
      m.audioPlayer.control = "pause"
      return { status: "success" }
    end if
    if m.audioPlayer.state = "paused"
      m.audioPlayer.control = "resume"
    else
      m.audioPlayer.control = "play"
    end if
    return { status: "success" }
  end if

  if cmd = "nowplaying" then return announceAudioNowPlaying()

  if cmd = "shuffle"
    if not isValid(m.shuffleButton) then return { status: "error.generic" }
    shuffleClicked()
    return { status: "success" }
  end if

  if cmd = "loop"
    if not isValid(m.repeatButton) then return { status: "error.generic" }
    loopClicked()
    return { status: "success" }
  end if

  if cmd = "like" then return setAudioFavorite(true)
  if cmd = "dislike" then return setAudioFavorite(false)

  return { status: "unhandled" }
end function

function audioSeekRelative(deltaSeconds as integer) as object
  if not isValid(m.audioPlayer) or not isValid(m.audioPlayer.position) then return { status: "error.generic" }
  return audioSeekTo(m.audioPlayer.position + deltaSeconds)
end function

' 5s end-slack (vs 30s for video): songs are short, and we still want the seek to
' land before the track auto-advances to the next.
function audioSeekTo(targetSeconds as float) as object
  if not isValid(m.audioPlayer) then return { status: "error.generic" }
  result = voiceTransport.computeSeekStatus(targetSeconds, m.songDuration, 5)
  m.audioPlayer.seek = result.clamped
  return { status: result.status }
end function

function handleAudioVoiceSeek(evt as object) as object
  parsed = voiceTransport.parseSeekDelta(evt)
  if not parsed.valid then return { status: "error.generic" }
  return audioSeekRelative(parsed.delta)
end function

function audioNextTrack() as object
  if not isValid(m.queueManager) then return { status: "error.generic" }
  if not nextClicked() then return { status: "error.generic" }
  return { status: "success" }
end function

' Returns the metadata in the response: main.bs's transport dispatcher does the
' roAppManager call on the MAIN thread (roAppManager isn't creatable on render).
function announceAudioNowPlaying() as object
  if not isValid(m.queueManager) then return { status: "error.generic" }
  item = m.queueManager.callFunc("getCurrentItem")
  if not isValid(item) or not isValid(item.name) or item.name = "" then return { status: "error.generic" }
  return {
    status: "success",
    nowPlaying: {
      title: item.name,
      contentType: item.type ?? "audio"
    }
  }
end function

function setAudioFavorite(isLike as boolean) as object
  if not isValid(m.queueManager) then return { status: "error.generic" }
  item = m.queueManager.callFunc("getCurrentItem")
  if not isValid(item) or not isValid(item.id) or item.id = "" then return { status: "error.generic" }
  itemId = item.id
  if isLike
    SubmitSideEffect(GetApi().BuildMarkFavoriteRequest(itemId))
  else
    SubmitSideEffect(GetApi().BuildUnmarkFavoriteRequest(itemId))
  end if
  return { status: "success" }
end function