chore(docs): update code docs

Author: jellyrock[bot]

docs/components_ItemGrid_LoadVideoContentTask.bs.html

@@ -358,7 +358,7 @@
     return
   end if
 
-  addAudioStreamsToVideo(video)
+  addAudioStreamsToVideo(video, meta, mediaSourceId)
 
   audioIndexList = []
   for each audioTrackEntry in video.fullAudioData
@@ -540,18 +540,48 @@
   end if
 end sub
 
-' addAudioStreamsToVideo: Add audio stream data to video
+' addAudioStreamsToVideo: Populate video.fullAudioData with the item's audio tracks.
 '
-' @param {dynamic} video component to add fullAudioData to
-sub addAudioStreamsToVideo(video)
-  audioStreams = []
-  mediaStreams = m.playbackInfo.MediaSources[0].MediaStreams
-
-  for i = 0 to mediaStreams.Count() - 1
-    if LCase(mediaStreams[i].Type) = "audio"
-      audioStreams.push(mediaStreams[i])
+' Sources from the original item metadata (meta.mediaSourcesData) — NOT from the
+' PlaybackInfo response. The /PlaybackInfo response can return a transcode-shaped
+' MediaSource carrying only the chosen audio stream, which would shrink the OSD picker
+' to a single entry (issue #500). The OSD picker must always list every original track
+' so the user can switch.
+'
+' @param {object} video - video AA receiving the fullAudioData field
+' @param {dynamic} meta - item metadata (from ItemMetaData) holding mediaSourcesData
+' @param {dynamic} mediaSourceId - chosen MediaSource ID (matches one entry under meta.mediaSourcesData.mediaSources)
+sub addAudioStreamsToVideo(video as object, meta as dynamic, mediaSourceId as dynamic)
+  mediaStreams = invalid
+
+  if isValid(meta) and isValid(meta.mediaSourcesData) and isValid(meta.mediaSourcesData.mediaSources)
+    sources = meta.mediaSourcesData.mediaSources
+    if isValidAndNotEmpty(mediaSourceId)
+      for each source in sources
+        if isValid(source) and source.Id = mediaSourceId and isValid(source.MediaStreams)
+          mediaStreams = source.MediaStreams
+          exit for
+        end if
+      end for
     end if
-  end for
+    if not isValid(mediaStreams) and isValid(sources[0]) and isValid(sources[0].MediaStreams)
+      mediaStreams = sources[0].MediaStreams
+    end if
+  end if
+
+  ' Defensive fallback if metadata is unavailable (shouldn't happen — ItemMetaData ran above)
+  if not isValid(mediaStreams) and isValid(m.playbackInfo) and isValid(m.playbackInfo.MediaSources) and isValid(m.playbackInfo.MediaSources[0])
+    mediaStreams = m.playbackInfo.MediaSources[0].MediaStreams
+  end if
+
+  audioStreams = []
+  if isValid(mediaStreams)
+    for i = 0 to mediaStreams.Count() - 1
+      if LCase(mediaStreams[i].Type) = "audio"
+        audioStreams.push(mediaStreams[i])
+      end if
+    end for
+  end if
 
   video.fullAudioData = audioStreams
 end sub

docs/components_video_VideoPlayerView.bs.html

@@ -607,20 +607,25 @@
 ' Event handler for when audioIndex changes.
 ' For direct play: switches audio track directly using Roku's availableAudioTracks
 ' (no stop/reload needed since all tracks are in the container).
-' For transcoded: must reload since the server needs to re-encode with the selected track.
+' For transcoded — or when the newly-selected stream exceeds the device's audio
+' capability (e.g. switching from stereo back to an 8ch track on a stereo Roku) —
+' must reload so the server transcodes the new selection.
 sub onAudioIndexChange()
   m.log.info("Audio index changed by user", "newIndex", m.top.audioIndex, "isTranscoded", m.top.isTranscoded, "position", m.top.position, "currentAudioTrack", m.top.audioTrack)
 
-  ' Direct play: all audio tracks are in the container — just switch the Roku track
-  if not m.top.isTranscoded and isValid(m.top.availableAudioTracks)
+  ' Direct play: all audio tracks are in the container — just switch the Roku track,
+  ' but only if the newly-selected stream is actually decodable by the device.
+  ' Roku's native audioTrack switch can't make an undecodable track playable, so
+  ' picking e.g. an 8ch track on a stereo device must go through the reload path.
+  if not m.top.isTranscoded and isValid(m.top.availableAudioTracks) and isSelectedAudioStreamDirectPlayable(m.top.audioIndex, m.top.fullAudioData)
     newTrack = getRokuAudioTrackPosition(m.top.audioIndex, m.top.fullAudioData, m.top.availableAudioTracks)
     m.log.info("Direct play audio switch", "jellyfinIndex", m.top.audioIndex, "rokuTrack", newTrack)
     m.top.audioTrack = newTrack
     reportPlayback()
     return
   end if
 
-  ' Transcoded or availableAudioTracks not available: must reload
+  ' Transcoded, availableAudioTracks not available, or stream not direct-playable: must reload
   m.log.info("Audio change requires reload", "isTranscoded", m.top.isTranscoded)
 
   ' Save the current video position

docs/data/search.json

@@ -799,16 +799,18 @@
 ' and also counts all track types, so Roku Track = Jellyfin Index + 1.
 '
 ' When availableAudioTracks is provided (populated by Roku during active playback),
-' matches by language for robustness against non-standard MKV track numbering.
-' Falls back to Index + 1 mapping when availableAudioTracks is not available
-' (e.g., before playback starts or for non-MKV containers).
+' matches by language with ordinal disambiguation: among same-language Jellyfin streams
+' (in original order), find the position N of the chosen index, then return the Nth
+' same-language Roku track. This avoids returning the wrong track when multiple streams
+' share a language (e.g. main + commentary, both English — issue #500).
+' Falls back to Index + 1 mapping when availableAudioTracks is not available or no
+' ordinal match can be found (e.g., before playback starts or for non-MKV containers).
 '
 ' @param {integer} jellyfinAudioIndex - The Jellyfin audio stream index
 ' @param {dynamic} audioStreamsArray - Jellyfin fullAudioData array (must have .index and .language fields)
 ' @param {dynamic} [availableAudioTracks=invalid] - Roku's availableAudioTracks array (has .track and .language)
 ' @returns {string} - Roku track identifier string for audioTrack field
 function getRokuAudioTrackPosition(jellyfinAudioIndex as integer, audioStreamsArray as dynamic, availableAudioTracks = invalid as dynamic) as string
-  ' When Roku's availableAudioTracks is populated, match by language for accuracy
   if isValid(availableAudioTracks) and isValid(audioStreamsArray)
     ' Find the language of the selected Jellyfin stream
     selectedLanguage = ""
@@ -822,13 +824,29 @@
     end for
 
     if selectedLanguage <> ""
-      for each rokuTrack in availableAudioTracks
-        if isValid(rokuTrack.track) and isValid(rokuTrack.language)
-          if LCase(rokuTrack.language) = selectedLanguage
-            return rokuTrack.track
+      ' Position of the chosen stream among same-language Jellyfin streams
+      jfPosition = -1
+      jfSeen = 0
+      for each stream in audioStreamsArray
+        if isValid(stream.language) and LCase(stream.language) = selectedLanguage
+          if isValid(stream.index) and stream.index = jellyfinAudioIndex
+            jfPosition = jfSeen
+            exit for
           end if
+          jfSeen += 1
         end if
       end for
+
+      ' Take the Nth same-language Roku track
+      if jfPosition >= 0
+        rokuSeen = 0
+        for each rokuTrack in availableAudioTracks
+          if isValid(rokuTrack.track) and isValid(rokuTrack.language) and LCase(rokuTrack.language) = selectedLanguage
+            if rokuSeen = jfPosition then return rokuTrack.track
+            rokuSeen += 1
+          end if
+        end for
+      end if
     end if
   end if
 

docs/module-LoadVideoContentTask.html

@@ -185,6 +185,43 @@
   return ""
 end function
 
+' isSelectedAudioStreamDirectPlayable: Whether the audio stream at jellyfinAudioIndex
+' inside audioStreams is decodable by the current device.
+'
+' Used by mid-playback audio switching to decide whether Roku's native track-switch is
+' viable, or whether a server reload is required (e.g. switching back to an 8ch track
+' on a stereo device — Roku can't decode it natively, so a transcode reload is needed).
+'
+' @param {integer} jellyfinAudioIndex - Jellyfin index of the chosen audio stream
+' @param {dynamic} audioStreams - Array of audio MediaStream objects (e.g. fullAudioData)
+' @returns {boolean} - true if the chosen stream can be direct-played on this device
+function isSelectedAudioStreamDirectPlayable(jellyfinAudioIndex as integer, audioStreams as dynamic) as boolean
+  if not isValid(audioStreams) then return false
+  selected = invalid
+  for each stream in audioStreams
+    if isValid(stream.index) and stream.index = jellyfinAudioIndex
+      selected = stream
+      exit for
+    end if
+  end for
+  if not isValid(selected) then return false
+  return isStreamDirectPlayable(selected, getDeviceAudioCapabilities())
+end function
+
+' isCommentaryAudioStream: Determine whether a stream is a commentary/secondary track.
+'
+' Detection: case-insensitive substring match for "commentary" in the stream Title.
+' Used by findBestAudioStreamIndex() to deprioritize commentary tracks during auto-selection
+' so a director's-commentary stereo track doesn't outrank the main multichannel track on a
+' stereo device (issue #500).
+'
+' @param {object} stream - MediaStream object from Jellyfin metadata
+' @returns {boolean} - true if the stream looks like a commentary track
+function isCommentaryAudioStream(stream as object) as boolean
+  if not isValid(stream) or not isValid(stream.Title) then return false
+  return inStr(1, LCase(stream.Title), "commentary") > 0
+end function
+
 ' findBestAudioStreamIndex: Primary function for selecting the best audio stream
 '
 ' Selection priority when playDefault = true (Jellyfin: "Play default audio track regardless of language"):
@@ -250,6 +287,23 @@
     return 0
   end if
 
+  ' Deprioritize commentary tracks (issue #500): when at least one non-commentary track
+  ' exists, hide commentary entries from all subsequent selection logic so a stereo
+  ' commentary track can't outrank the multichannel main track on a stereo device.
+  ' Files with only commentary tracks fall through with the original list.
+  mainStreams = []
+  for i = 0 to audioStreams.Count() - 1
+    if not isCommentaryAudioStream(audioStreams[i])
+      mainStreams.push(audioStreams[i])
+    end if
+  end for
+  if mainStreams.Count() > 0
+    audioStreams = mainStreams
+    if audioStreams.Count() = 1 and isValid(audioStreams[0].index)
+      return audioStreams[0].index
+    end if
+  end if
+
   ' Multiple audio tracks - apply selection logic
 
   ' BRANCH 1: "Play default track" setting is enabled