chore(docs): update code docs

Author: jellyrock[bot]

docs/components_ItemDetails.bs.html

@@ -1343,15 +1343,32 @@
       SetUpAudioOptions(allStreams)
       updateOptionsButtonVisibility()
     else if item.type <> "Series" and item.type <> "Season" and item.type <> "Person" and item.type <> "BoxSet" and item.type <> "MusicArtist" and item.type <> "MusicAlbum" and item.type <> "Playlist"
-      if m.top.selectedVideoStreamId = "" and isValidAndNotEmpty(item.mediaSourceId)
+      mediaSources = invalid
+      if isValid(item.mediaSourcesData) and isValidAndNotEmpty(item.mediaSourcesData.mediaSources)
+        mediaSources = item.mediaSourcesData.mediaSources
+      end if
+
+      ' Select best video source based on device capabilities instead of always using first
+      if m.top.selectedVideoStreamId = "" and isValid(mediaSources) and mediaSources.Count() > 0
+        bestSourceIndex = findBestVideoSource(mediaSources)
+        m.top.selectedVideoStreamId = mediaSources[bestSourceIndex].Id ?? item.mediaSourceId
+      else if m.top.selectedVideoStreamId = "" and isValidAndNotEmpty(item.mediaSourceId)
         m.top.selectedVideoStreamId = item.mediaSourceId
       end if
 
+      ' Use the selected source's MediaStreams (not always mediaSources[0])
       allStreams = []
-      mediaSources = invalid
-      if isValid(item.mediaSourcesData) and isValidAndNotEmpty(item.mediaSourcesData.mediaSources)
-        mediaSources = item.mediaSourcesData.mediaSources
-        if isValid(mediaSources[0].MediaStreams)
+      if isValid(mediaSources)
+        for each source in mediaSources
+          if source.Id = m.top.selectedVideoStreamId
+            if isValid(source.MediaStreams)
+              allStreams = source.MediaStreams
+            end if
+            exit for
+          end if
+        end for
+        ' Fallback to first source if selected source not found
+        if allStreams.Count() = 0 and isValid(mediaSources[0]) and isValid(mediaSources[0].MediaStreams)
           allStreams = mediaSources[0].MediaStreams
         end if
       end if

docs/components_ItemGrid_LoadVideoContentTask.bs.html

@@ -50,6 +50,7 @@
 
   id = m.top.itemId
   mediaSourceId = invalid
+  if m.top.mediaSourceId <> "" then mediaSourceId = m.top.mediaSourceId
   audio_stream_idx = m.top.selectedAudioStreamIndex
   forceTranscoding = m.top.forceTranscoding
   bypassDoviPreservation = m.top.bypassDoviPreservation
@@ -92,14 +93,33 @@
     mediaSources = meta.mediaSourcesData.mediaSources
   end if
 
+  ' Select best video source if no specific source was requested
+  if not isValid(mediaSourceId) and isValid(mediaSources) and mediaSources.Count() > 1
+    bestSourceIndex = findBestVideoSource(mediaSources)
+    mediaSourceId = mediaSources[bestSourceIndex].Id
+    m.log.info("Auto-selected video source", "index", bestSourceIndex, "mediaSourceId", mediaSourceId)
+  end if
+
   ' Re-determine audio stream index if no manual selection was made
   ' Task field = 0 means no manual selection (default value)
   ' Task field > 0 means user manually selected from MovieDetails/TVListDetails - preserve it
   if m.top.selectedAudioStreamIndex = 0
-    if isValid(mediaSources) and isValid(mediaSources[0].MediaStreams)
+    ' Use the selected source's MediaStreams for audio selection when available
+    selectedSourceStreams = invalid
+    if isValid(mediaSourceId) and isValid(mediaSources)
+      for each source in mediaSources
+        if source.Id = mediaSourceId and isValid(source.MediaStreams)
+          selectedSourceStreams = source.MediaStreams
+          exit for
+        end if
+      end for
+    end if
+    if isValid(selectedSourceStreams)
       ' Resolve playDefaultAudioTrack setting (JellyRock override or web client)
       playDefault = resolvePlayDefaultAudioTrack(userSettings, userSession.config)
-
+      audio_stream_idx = findBestAudioStreamIndex(selectedSourceStreams, playDefault, userSession.config.audioLanguagePreference)
+    else if isValid(mediaSources) and isValid(mediaSources[0].MediaStreams)
+      playDefault = resolvePlayDefaultAudioTrack(userSettings, userSession.config)
       audio_stream_idx = findBestAudioStreamIndex(mediaSources[0].MediaStreams, playDefault, userSession.config.audioLanguagePreference)
     else
       ' MediaStreams not available - keep existing behavior of using 0
@@ -218,8 +238,9 @@
 
   ' Determine final subtitle_idx BEFORE calling ItemPostPlaybackInfo to avoid duplicate API calls.
   ' defaultSubtitleTrackFromVid() only needs meta and audio_stream_idx, both available at this point.
+  ' Pass mediaSourceId so subtitle selection uses the correct source's streams (not always mediaSources[0]).
   if subtitle_idx = SubtitleSelection.notset
-    subtitle_idx = defaultSubtitleTrackFromVid(meta, audio_stream_idx)
+    subtitle_idx = defaultSubtitleTrackFromVid(meta, audio_stream_idx, mediaSourceId)
   end if
 
   ' PlayStart requires the time to be in seconds

docs/components_manager_ViewCreator.bs.html

@@ -24,6 +24,7 @@
   m.view.observeField("selectPlaybackInfoPressed", "onSelectPlaybackInfoPressed")
   m.view.observeField("selectSubtitlePressed", "onSelectSubtitlePressed")
   m.view.observeField("selectAudioPressed", "onSelectAudioPressed")
+  m.view.observeField("selectVideoSourcePressed", "onSelectVideoSourcePressed")
 
   mediaSourceId = m.global.queueManager.callFunc("getCurrentItem").mediaSourceId
 
@@ -127,6 +128,39 @@
   sceneManager.observeField("returnData", "onSelectionMade")
 end sub
 
+' onSelectVideoSourcePressed: Display video source selection dialog
+'
+sub onSelectVideoSourcePressed()
+  videoSourceData = {
+    data: []
+  }
+
+  if not isValid(m.view.fullVideoSourceData) then return
+
+  hasMultipleSources = m.view.fullVideoSourceData.Count() > 1
+
+  for each source in m.view.fullVideoSourceData
+    sourceItem = {
+      "Index": source.Id,
+      "IsExternal": false,
+      "Track": {
+        "description": formatVideoSourceTitle(source, hasMultipleSources)
+      },
+      "Type": "videosourceselection"
+    }
+
+    if m.view.mediaSourceId = source.Id
+      sourceItem.selected = true
+    end if
+
+    videoSourceData.data.push(sourceItem)
+  end for
+
+  sceneManager = m.global.sceneManager
+  sceneManager.callFunc("radioDialog", tr("Select Video Source"), videoSourceData)
+  sceneManager.observeField("returnData", "onSelectionMade")
+end sub
+
 ' User has selected something from the radioDialog popup
 sub onSelectionMade()
   sceneManager = m.global.sceneManager
@@ -144,6 +178,11 @@
     processAudioSelection()
     return
   end if
+
+  if LCase(sceneManager.returnData.type) = "videosourceselection"
+    processVideoSourceSelection()
+    return
+  end if
 end sub
 
 
@@ -159,6 +198,19 @@
   end if
 end sub
 
+' processVideoSourceSelection: Video source selection handler
+' Triggers video reload with the new MediaSource ID
+sub processVideoSourceSelection()
+  selectedSource = m.global.sceneManager.returnData
+
+  if isValid(selectedSource) and isValid(selectedSource.index)
+    ' Only trigger reload if source actually changed
+    if selectedSource.index <> m.view.mediaSourceId
+      m.view.mediaSourceId = selectedSource.index
+    end if
+  end if
+end sub
+
 sub processSubtitleSelection()
   m.selectedSubtitle = m.global.sceneManager.returnData
 

docs/components_video_OSD.bs.html

@@ -69,6 +69,13 @@
   ' Cache item reference for use in display methods
   m.itemData = item
 
+  ' Preserve the original item name from the first load.
+  ' Source-switch reloads fetch metadata for an alternate version whose name
+  ' may include year/edition suffixes (e.g., "Dracula (1931) [Colorized]").
+  if not isValidAndNotEmpty(m.originalItemName)
+    m.originalItemName = item.name
+  end if
+
   itemType = item.type
 
   ' Determine isMovie/isSeries flags for ratings display settings.
@@ -107,6 +114,13 @@
 
   ' Stream counts - read pre-computed values from item node
   m.top.numAudioStreams = item.audioStreamCount
+  ' Only update video source count from meta if it's higher than the current value.
+  ' During a source-switch reload, the reloaded meta represents a single MediaSource
+  ' and hasMultipleVideoSources will be false, but the original source list is still valid.
+  metaVideoSources = item.hasMultipleVideoSources ? 2 : 1
+  if metaVideoSources > m.top.numVideoSources
+    m.top.numVideoSources = metaVideoSources
+  end if
 
   ' Runtime — for TvChannel, use the currently-airing program's runtime if available
   runTimeTicks = item.runTimeTicks
@@ -149,6 +163,10 @@
 
   ' Remove these buttons as needed
 
+  ' Video Sources - hide for single source or live TV
+  if m.top.numVideoSources < 2 or m.itemData.type = "TvChannel"
+    m.buttonMenuLeft.removeChild(m.buttonMenuLeft.findNode("showVideoSourceMenu"))
+  end if
   ' Audio Track
   if m.top.numAudioStreams < 2
     m.buttonMenuLeft.removeChild(m.buttonMenuLeft.findNode("showAudioMenu"))
@@ -208,7 +226,15 @@
   if item.type = "TvChannel" and isValid(item.currentProgram) and isValidAndNotEmpty(item.currentProgram.name)
     m.videoTitle.text = item.currentProgram.name
   else
-    m.videoTitle.text = item.name
+    ' Use preserved original name (m.originalItemName) to avoid alternate version names
+    ' that may include year/edition suffixes (e.g., "Dracula (1931) [Colorized]").
+    ' Falls back to item.name on first load before the original is cached.
+    title = m.originalItemName ?? item.name
+    ' Append active video source tag when multiple sources exist (e.g., "[B&W]")
+    if isValidAndNotEmpty(m.top.videoSourceTag)
+      title += " " + m.top.videoSourceTag
+    end if
+    m.videoTitle.text = title
   end if
 end sub
 

docs/components_video_VideoPlayerView.bs.html

@@ -8,6 +8,7 @@
 import "pkg:/source/utils/misc.bs"
 import "pkg:/source/utils/queueBackdropHelper.bs"
 import "pkg:/source/utils/session.bs"
+import "pkg:/source/utils/streamSelection.bs"
 import "pkg:/source/utils/trickplay.bs"
 
 ' Child index for position label in Roku's built-in trickPlayBar component.
@@ -37,6 +38,9 @@
   m.LoadMetaDataTask.itemId = m.currentItem.id
   m.LoadMetaDataTask.itemType = m.currentItem.type
   m.LoadMetaDataTask.selectedAudioStreamIndex = m.currentItem.selectedAudioStreamIndex
+  if isValidAndNotEmpty(m.currentItem.mediaSourceId)
+    m.LoadMetaDataTask.mediaSourceId = m.currentItem.mediaSourceId
+  end if
   m.LoadMetaDataTask.observeField("content", "onVideoContentLoaded")
   m.LoadMetaDataTask.control = "RUN"
 
@@ -282,6 +286,12 @@
   m.top.selectAudioPressed = true
 end sub
 
+' handleShowVideoSourceMenuAction: Handles action to show video source selection menu
+'
+sub handleShowVideoSourceMenuAction()
+  m.top.selectVideoSourcePressed = true
+end sub
+
 ' handleShowVideoInfoPopupAction: Handles action to show video info popup
 '
 sub handleShowVideoInfoPopupAction()
@@ -328,6 +338,11 @@
     return
   end if
 
+  if action = "showvideosourcemenu"
+    handleShowVideoSourceMenuAction()
+    return
+  end if
+
   if action = "showvideoinfopopup"
     handleShowVideoInfoPopupAction()
     return
@@ -496,6 +511,39 @@
   m.LoadMetaDataTask.control = "RUN"
 end sub
 
+' onVideoSourceChange: Handles video source switching from OSD
+' Saves position, stops playback, re-selects audio for the new source's streams,
+' and reloads video content with the new MediaSource ID.
+sub onVideoSourceChange()
+  newSourceId = m.top.mediaSourceId
+  if not isValidAndNotEmpty(newSourceId) then return
+
+  ' Save the current video position
+  m.global.queueManager.callFunc("setTopStartingPoint", int(m.top.position) * 10000000&)
+
+  m.top.control = "stop"
+
+  ' Re-determine best audio stream for the new source's MediaStreams
+  audioStreamIdx = 0
+  if isValid(m.top.fullVideoSourceData)
+    for each source in m.top.fullVideoSourceData
+      if source.Id = newSourceId and isValid(source.MediaStreams)
+        localUser = m.global.user
+        playDefault = resolvePlayDefaultAudioTrack(localUser.settings, localUser.config)
+        audioStreamIdx = findBestAudioStreamIndex(source.MediaStreams, playDefault, localUser.config.audioLanguagePreference)
+        exit for
+      end if
+    end for
+  end if
+
+  m.LoadMetaDataTask.selectedSubtitleIndex = -2 ' Reset to auto-detect for new source
+  m.LoadMetaDataTask.selectedAudioStreamIndex = audioStreamIdx
+  m.LoadMetaDataTask.itemId = m.currentItem.id
+  m.LoadMetaDataTask.mediaSourceId = newSourceId
+  m.LoadMetaDataTask.observeField("content", "onVideoContentLoaded")
+  m.LoadMetaDataTask.control = "RUN"
+end sub
+
 sub onPlaybackErrorDialogClosed(msg)
   sourceNode = msg.getRoSGNode()
   sourceNode.unobserveField("buttonSelected")
@@ -550,7 +598,6 @@
   m.top.PlaySessionId = videoContent[0].PlaySessionId
   m.top.videoId = videoContent[0].id
   m.top.container = videoContent[0].container
-  m.top.mediaSourceId = videoContent[0].mediaSourceId
   m.top.fullSubtitleData = videoContent[0].fullSubtitleData
   m.top.fullAudioData = videoContent[0].fullAudioData
   m.top.audioIndex = videoContent[0].audioIndex
@@ -561,12 +608,47 @@
   m.top.doviDirectPlayFallbackAvailable = isValid(videoContent[0].doviDirectPlayFallbackAvailable) and videoContent[0].doviDirectPlayFallbackAvailable
   m.top.transcodeAvailable = isValid(videoContent[0].transcodeAvailable) and videoContent[0].transcodeAvailable
 
+  ' Unobserve mediaSourceId before setting to prevent observer loop
+  m.top.unobserveField("mediaSourceId")
+  m.top.mediaSourceId = videoContent[0].mediaSourceId
+  m.top.observeField("mediaSourceId", "onVideoSourceChange")
+
   ' Reset retry flags so subsequent reloads (audio/subtitle changes) use fresh evaluation.
   m.LoadMetaDataTask.bypassDoviPreservation = false
   m.LoadMetaDataTask.forceTranscoding = false
 
   ' Pass JellyfinBaseItem node to OSD for typed field access
   if isValid(videoContent[0].meta)
+    ' Populate video source data for OSD source switching.
+    ' Only update if the new metadata has more sources than what we already have —
+    ' a source-switch reload fetches metadata for a single MediaSource ID,
+    ' which loses the parent item's full source list.
+    if isValid(videoContent[0].meta.mediaSourcesData) and isValidAndNotEmpty(videoContent[0].meta.mediaSourcesData.mediaSources)
+      newSources = videoContent[0].meta.mediaSourcesData.mediaSources
+      existingCount = 0
+      if isValid(m.top.fullVideoSourceData) then existingCount = m.top.fullVideoSourceData.Count()
+      if newSources.Count() >= existingCount
+        m.top.fullVideoSourceData = newSources
+      end if
+    end if
+    ' Pre-set video source count on OSD BEFORE itemData triggers onItemDataChanged().
+    ' A source-switch reload returns metadata for a single MediaSource, so
+    ' hasMultipleVideoSources would be false. Override with the preserved count
+    ' so setButtonStates() keeps the video source button.
+    if isValid(m.top.fullVideoSourceData) and m.top.fullVideoSourceData.Count() > 1
+      m.osd.numVideoSources = m.top.fullVideoSourceData.Count()
+      ' Set the active source's name tag for the OSD title (e.g., "[B&W]", "[Colorized]")
+      currentSourceId = videoContent[0].mediaSourceId
+      m.osd.videoSourceTag = ""
+      for each source in m.top.fullVideoSourceData
+        if source.Id = currentSourceId and isValidAndNotEmpty(source.Name)
+          m.osd.videoSourceTag = source.Name
+          exit for
+        end if
+      end for
+    else
+      m.osd.videoSourceTag = ""
+    end if
     m.osd.itemData = videoContent[0].meta
   end if
 
@@ -1241,6 +1323,7 @@
   m.top.unobserveField("content")
   m.top.unobserveField("selectedSubtitle")
   m.top.unobserveField("audioIndex")
+  m.top.unobserveField("mediaSourceId")
   m.top.unobserveField("allowCaptions")
   m.top.unobserveField("subtitleTrack")
   m.top.unobserveField("globalCaptionMode")