chore(docs): update code docs

Author: jellyrock[bot]

docs/data/search.json

@@ -204,26 +204,26 @@
           end for
         end if
 
-        ' Remove AAC from codec list in two scenarios:
-        ' 1. ANY multichannel source (>2ch) when user has passthrough support - prevents transcoding to AAC which would downmix to stereo
-        ' 2. Unsupported AAC profiles (Main, HE-AAC) - TODO: Remove after server supports transcoding between AAC profiles
-        shouldRemoveAac = false
+        ' Tailor the device profile's transcoding AudioCodec list to the source in two scenarios:
+        ' 1. Multichannel source (>2ch) with passthrough support - drops stereo-output codecs so
+        '    the server only offers surround variants (eac3/ac3/dts) in the HLS master playlist.
+        '    Without this, Roku's HLS player has been observed to pick the stereo variant.
+        ' 2. AAC source with unsupported profile (Main, HE-AAC) - drops AAC so transcoding
+        '    falls through to MP3.  TODO: remove once server transcodes between AAC profiles.
+        shouldOptimize = false
 
-        ' Scenario 1: ANY multichannel source with passthrough support
-        ' Removes AAC to force server to use surround passthrough codecs (eac3, ac3, dts) instead of transcoding to stereo AAC
         if channelCount > 2 and hasPassthruSupport
-          shouldRemoveAac = true
+          shouldOptimize = true
         end if
 
-        ' Scenario 2: AAC with unsupported profile
         if isValid(selectedAudioStream.Codec) and LCase(selectedAudioStream.Codec) = "aac"
           if isValid(selectedAudioStream.Profile) and (LCase(selectedAudioStream.Profile) = "main" or LCase(selectedAudioStream.Profile) = "he-aac")
-            shouldRemoveAac = true
+            shouldOptimize = true
           end if
         end if
 
-        if shouldRemoveAac
-          removeUnsupportedAacFromProfile(postData.DeviceProfile, channelCount)
+        if shouldOptimize
+          optimizeAudioCodecListForSource(postData.DeviceProfile, channelCount)
         end if
       end if
     end if
@@ -516,37 +516,47 @@
   end if
 end sub
 
-' Removes AAC from the device profile codec list to prevent stereo downmix of multichannel audio.
-' Also handles unsupported AAC profiles (Main, HE-AAC).
-' For stereo sources (≤2ch), also removes surround passthrough codecs (eac3, ac3, dts)
-' so transcoding falls through to MP3 (better compatibility + smaller files).
-sub removeUnsupportedAacFromProfile(deviceProfile as object, channelCount as integer)
+' Tailors a video transcoding profile's AudioCodec list to the current source's channel count
+' so the server (and downstream HLS variant selection) can't fall back to a less-desirable codec.
+'
+' Multichannel source (>2ch):
+'   Strips ALL stereo-output codecs (aac, mp3, flac, alac, pcm, lpcm, wav, vorbis). Without this,
+'   Jellyfin's HLS muxer offers BOTH the surround codec AND a stereo fallback as separate variants
+'   in the master playlist, and Roku's HLS player has been observed (via in-house testing on
+'   physical hardware; no upstream tracking issue at time of writing) to pick the stereo variant —
+'   defeating the entire point of having surround passthrough hardware. Caller must already have
+'   verified the device has surround passthrough before invoking with channelCount > 2.
+'
+' Stereo source (≤2ch):
+'   Strips surround passthrough codecs (eac3, ac3, dts) plus aac so transcoding falls through to
+'   mp3. Avoids handing the server a surround target codec for content that's only 2ch anyway.
+sub optimizeAudioCodecListForSource(deviceProfile as object, channelCount as integer)
   ' Validate inputs
   if not isValid(deviceProfile) then return
   if not isValid(deviceProfile.TranscodingProfiles) then return
 
-  ' Surround passthrough codecs that should be removed for stereo sources
+  ' Codecs that, as a server transcode target, can't carry surround channels — strip these for
+  ' multichannel sources so the server is forced to pick a surround codec from the remaining list.
+  ' Note: this list is intentionally distinct from `stereoOutputCodecs` in deviceCapabilities.bs;
+  ' that list represents Roku decode-path behavior (different concept), so the contents differ.
+  stereoOnlyCodecs = ["aac", "mp3", "flac", "alac", "pcm", "lpcm", "wav", "vorbis"]
+  ' Surround passthrough codecs — pointless for stereo sources, strip them.
   surroundCodecs = ["eac3", "ac3", "dts"]
 
   for each rule in deviceProfile.TranscodingProfiles
     if isValid(rule.Type) and rule.Type = "Video"
       if isValid(rule.AudioCodec)
-        ' Split codec list into array
         codecList = rule.AudioCodec.split(",")
         newCodecList = []
 
-        ' Remove AAC always, and surround codecs for stereo sources
         for each codec in codecList
           skipCodec = false
 
-          ' Always skip AAC to prevent downmix
-          if codec = "aac"
+          if channelCount > 2 and arrayHasValue(stereoOnlyCodecs, codec)
             skipCodec = true
           end if
 
-          ' For stereo sources (≤2ch), also skip surround codecs
-          ' This ensures transcoding goes to MP3 instead of trying AC3/EAC3
-          if channelCount <= 2 and arrayHasValue(surroundCodecs, codec)
+          if channelCount <= 2 and (codec = "aac" or arrayHasValue(surroundCodecs, codec))
             skipCodec = true
           end if
 
@@ -555,7 +565,10 @@
           end if
         end for
 
-        ' Rebuild codec string
+        if newCodecList.count() = 0 and codecList.count() > 0
+          print "[optimizeAudioCodecListForSource] WARN: AudioCodec list for container '" + rule.Container + "' became empty after optimization (source ch=" + channelCount.toStr() + ", original=" + rule.AudioCodec + "); server may reject the transcoding rule"
+        end if
+
         rule.AudioCodec = newCodecList.join(",")
       end if
     end if

docs/module-items.html

@@ -502,7 +502,9 @@
   for each container in transcodingContainers
     audioCodecList = []
 
-    ' 1. AAC always first (efficient for stereo, removed at playback time for multichannel sources with passthrough)
+    ' 1. AAC always first (efficient for stereo). On multichannel + passthru playback, all
+    '    stereo-output codecs (including AAC) are stripped at playback time by
+    '    optimizeAudioCodecListForSource (see items.bs).
     audioCodecList.push("aac")
 
     ' 2. Add surround passthrough codecs if supported (in preference order)
@@ -591,24 +593,30 @@
   resolutionConditions = getResolutionConditions()
 
   ' ========================================
-  ' DETECT SURROUND PASSTHROUGH SUPPORT
+  ' USER SETTING — FORCE SERVER-SIDE MULTICHANNEL HANDLING
   ' ========================================
-
-  sixChannelPassthruCodecs = getSupportedPassthruCodecs(di, 6)
-  eightChannelPassthruCodecs = getSupportedPassthruCodecs(di, 8)
-  hasSurroundPassthru = sixChannelPassthruCodecs.count() > 0 or eightChannelPassthruCodecs.count() > 0
-
-  ' Check user setting for multichannel decode preference
-  ' When disabled, force stereo-output codecs to 2ch max (same as passthrough behavior)
+  '
+  ' playbackDecodeMultichannelAudio = false means the user has explicitly asked us to keep
+  ' multichannel sources off the Roku's decoder — usually because Roku's downmix sounded worse
+  ' than the server's on their system, or because they want bitstream surround output preserved
+  ' via server transcoding instead of relying on Roku PCM output.
+  '
+  ' Effect: cap stereo-output codecs at 2ch in the codec profile so the server is forced to
+  ' transcode multichannel sources rather than offering them for direct play.
   userWantsDecodeLimit = not globalUserSettings.playbackDecodeMultichannelAudio
 
   ' ========================================
   ' CODEC CATEGORIES
   ' ========================================
 
-  ' Codecs that Roku decodes multichannel but only OUTPUTS as stereo PCM
-  ' When user has a receiver, we force these to 2ch max to trigger transcoding
-  ' to surround output codecs (eac3/ac3/dts) instead of direct playing and downmixing
+  ' Codecs whose decode-then-output path on Roku does not always pass through multichannel —
+  ' depending on the user's Audio Output Mode and HDMI/eARC sink, these may downmix to 2ch PCM.
+  ' We do NOT cap these at 2ch by default: most modern HDMI sinks accept multichannel PCM and
+  ' the official Roku decode behavior produces correct multichannel output for capable users.
+  ' The cap is applied only when userWantsDecodeLimit is true (see setting above).
+  '
+  ' Note: this list is intentionally distinct from `stereoOnlyCodecs` in items.bs; that list
+  ' represents server transcode-target capability (different concept), so the contents differ.
   stereoOutputCodecs = ["aac", "flac", "alac", "pcm", "lpcm", "wav", "opus", "vorbis"]
 
   ' ========================================
@@ -619,11 +627,12 @@
   audioChannels = [8, 6, 2] ' highest first
 
   for each audioCodec in audioCodecs
-    ' Special handling for stereo-output codecs when user has surround passthrough OR user disabled multichannel decode
-    ' These codecs decode multichannel but Roku only outputs as stereo PCM
-    if arrayHasValue(stereoOutputCodecs, audioCodec) and (hasSurroundPassthru or userWantsDecodeLimit)
-      ' Force to 2 channels maximum to prevent Roku from downmixing multichannel to stereo
-      ' This triggers server to transcode to surroundOutputCodecs (eac3/ac3/dts) or stereo instead
+    ' When the user has explicitly disabled on-device multichannel decoding, cap stereo-output
+    ' codecs at 2ch to force server-side transcoding for multichannel sources.
+    if arrayHasValue(stereoOutputCodecs, audioCodec) and userWantsDecodeLimit
+      ' Force to 2 channels maximum to prevent Roku from decoding the multichannel source.
+      ' Server transcodes to a surround codec (eac3/ac3/dts) if surround passthrough is
+      ' available, otherwise transcodes to stereo.
       for each codecType in ["VideoAudio", "Audio"]
         ' Special AAC profile restrictions (Main and HE-AAC not supported)
         if audioCodec = "aac"