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/roku_modules/log/LogMixin.brs"
import "pkg:/source/translationKeys.bs"
import "pkg:/source/utils/itemImageUrl.bs"
import "pkg:/source/utils/misc.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
  m.isInScrubMode = false
  m.lastRecordedPositionTimestamp = 0
  m.scrubTimestamp = -1
  m.currentBackdropUrl = ""

  m.queueManager = m.global.queueManager
  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")
  m.LoadScreenSaverTimeoutTask.control = "RUN"

  loadButtons()
  pageContentChanged()
  setShuffleIconState()
  setLoopButtonImage()
  ' Set lastFocus for JRScreen lifecycle management
  m.top.lastFocus = m.buttons
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()
  ' Load meta data
  m.LoadMetaDataTask = CreateObject("roSGNode", "LoadItemsTask")
  m.LoadMetaDataTask.itemsToLoad = "metaData"

  ' 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
      m.top.state = "finished"
    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

      ' Return to previous screen
      m.top.state = "finished"
    end if
  end if
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"
      m.audioPlayer.control = "stop"

      m.global.sceneManager.callFunc("clearPreviousScene")
      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"
      m.audioPlayer.control = "stop"

      m.global.sceneManager.callFunc("clearPreviousScene")
      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.control = "STOP"

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

  m.LoadAudioStreamTask.itemId = currentItem.id
  m.LoadAudioStreamTask.observeField("content", "onAudioStreamLoaded")
  m.LoadAudioStreamTask.control = "RUN"
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()
  stopLoadingSpinner()
  data = m.LoadAudioStreamTask.content[0]
  m.LoadAudioStreamTask.unobserveField("content")
  if isValid(data) and data.count() > 0
    ' 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

    ' Set backdrop immediately from available data (will be set once in onMetaDataLoaded if shouldUseMetaTask = true)
    if not shouldUseMetaTask
      ' We have all data, set backdrop now from parent backdrop
      deviceRes = m.global.device.uiResolution
      backdropUri = getItemBackdropUrl(currentItem, { width: deviceRes[0], height: deviceRes[1] })
      if isValidAndNotEmpty(backdropUri)
        m.log.info("Backdrop change (immediate): old=", m.currentBackdropUrl, "new=", backdropUri)
        m.currentBackdropUrl = backdropUri
        m.global.sceneManager.callFunc("setBackgroundImage", backdropUri)
      else
        m.log.info("Backdrop change (immediate): old=", m.currentBackdropUrl, "new=(empty)")
        m.currentBackdropUrl = ""
        m.global.sceneManager.callFunc("setBackgroundImage", "")
      end if
    end if

    ' If we don't have enough data to populate the screen, load metadata (which will also set backdrop)
    if shouldUseMetaTask
      m.LoadMetaDataTask.itemId = currentItem.id
      m.LoadMetaDataTask.observeField("content", "onMetaDataLoaded")
      m.LoadMetaDataTask.control = "RUN"
    else

      ' poster image — prefer album art, fall back to song primary. When neither is
      ' available, clear the URI: the JRPlaceholder behind albumCover surfaces, and the
      ' screensaver activator at startScreenSaver() falls into the audio-logo branch
      ' instead of drifting a fallback glyph around the screen.
      if isValidAndNotEmpty(currentItem.albumId) and isValidAndNotEmpty(currentItem.albumPrimaryImageTag)
        setPosterImage(ImageURL(currentItem.albumId, "Primary", { "maxHeight": 500, "maxWidth": 500, "tag": currentItem.albumPrimaryImageTag }))
      else if isValidAndNotEmpty(currentItem.primaryImageTag)
        setPosterImage(ImageURL(currentItem.id, "Primary", { "maxHeight": 500, "maxWidth": 500, "tag": currentItem.primaryImageTag }))
      else
        setPosterImage("")
      end if

      setScreenTitle(currentItem)
      setOnScreenTextValues(currentItem)
      m.songDuration = currentItem.runTimeTicks / 10000000.0

      ' Update displayed total audio length
      m.totalLengthTimestamp.text = ticksToHuman(currentItem.runTimeTicks)
    end if

    m.audioPlayer.content = data
    m.audioPlayer.control = "none"
    m.audioPlayer.control = "play"
  end if
end sub

sub onMetaDataLoaded()
  data = m.LoadMetaDataTask.content[0]
  m.LoadMetaDataTask.unobserveField("content")
  if not isValidAndNotEmpty(data.id) then return

  ' Set backdrop from item or parent backdrop (NameGuidPair artist items have no BackdropImageTags)
  deviceRes = m.global.device.uiResolution
  backdropUri = getItemBackdropUrl(data, { width: deviceRes[0], height: deviceRes[1] })
  if isValidAndNotEmpty(backdropUri)
    m.log.info("Backdrop change (parent): old=", m.currentBackdropUrl, "new=", backdropUri)
    m.currentBackdropUrl = backdropUri
    m.global.sceneManager.callFunc("setBackgroundImage", backdropUri)
  else
    m.log.info("Backdrop change (clear): old=", m.currentBackdropUrl, "new=(empty)")
    m.currentBackdropUrl = ""
    m.global.sceneManager.callFunc("setBackgroundImage", "")
  end if

  ' poster image — prefer album art, fall back to song primary, then placeholder.
  ' Empty string surfaces the JRPlaceholder behind albumCover and gates the screensaver.
  if isValidAndNotEmpty(data.albumId) and isValidAndNotEmpty(data.albumPrimaryImageTag)
    setPosterImage(ImageURL(data.albumId, "Primary", { "maxHeight": 500, "maxWidth": 500, "tag": data.albumPrimaryImageTag }))
  else if isValidAndNotEmpty(data.primaryImageTag)
    setPosterImage(ImageURL(data.id, "Primary", { "maxHeight": 500, "maxWidth": 500, "tag": data.primaryImageTag }))
  else
    setPosterImage("")
  end if

  setScreenTitle(data)
  setOnScreenTextValues(data)

  if data.runTimeTicks > 0
    m.songDuration = data.runTimeTicks / 10000000.0

    ' Update displayed total audio length
    m.totalLengthTimestamp.text = ticksToHuman(data.runTimeTicks)
  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,
' just song name if no album artist, or empty string to reset the title.
sub setScreenTitle(item as object)
  newTitle = ""
  if item.albumArtist <> "" and item.name <> ""
    newTitle = item.albumArtist + " / " + item.name
  else if item.name <> ""
    newTitle = item.name
  end if

  ' Always assign — 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 item.artists.count() > 0
    artistName = item.artists[0]
  end if
  setFieldTextValue("artist", artistName)
  setFieldTextValue("song", item.name)
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

' onDestroy: Full teardown releasing all resources before component removal
' Called automatically by SceneManager.popScene() / clearScenes()
sub onDestroy()
  m.log.verbose("onDestroy")

  ' 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")

  ' Stop and release task nodes (observers may already be cleared by their callbacks)
  m.LoadMetaDataTask.unobserveField("content")
  m.LoadMetaDataTask.control = "STOP"
  m.LoadMetaDataTask = invalid

  m.LoadAudioStreamTask.unobserveField("content")
  m.LoadAudioStreamTask.control = "STOP"
  m.LoadAudioStreamTask = invalid

  m.LoadScreenSaverTimeoutTask.unobserveField("content")
  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) —
'     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 — 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 mode, and pop the scene.
    ' Audio's onStateChange only pops on "finished"; the physical back key gets
    ' the scene pop for free via Roku's OS-default back handling, but voice
    ' transport doesn't, so we pop explicitly.
    m.audioPlayer.control = "stop"
    m.audioPlayer.loopMode = ""
    m.global.sceneManager.callFunc("popScene")
    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()

  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