chore(docs): update code docs

Author: jellyrock[bot]

docs/components_ItemGrid_LoadVideoContentTask.bs.html

@@ -338,12 +338,45 @@
   ' artifacts. If the user preference is set, and the only reason the server says we need to
   ' transcode is that the Encoding Level is not supported, then try to direct play but silently
   ' fall back to the transcode if that fails.
+  '
+  ' Resolution guard: Only attempt the level override when the source resolution is within the
+  ' codec's hardware ceiling. Many encoders tag 1080p content with inflated levels (e.g. 5.1)
+  ' even though the actual decode workload is within Roku's capability. But for resolutions
+  ' above the hardware limit (e.g. 4K h264), no level tolerance will help — skip the override.
+  ' Both height and width are checked to catch ultrawide or non-standard aspect ratios.
   if m.playbackInfo.MediaSources[0].MediaStreams.Count() > 0 and not isLive
     ' Find first video stream - MediaStreams[0] might be subtitle/audio
     videoStream = getFirstVideoStream(m.playbackInfo.MediaSources[0].MediaStreams)
     if isValid(videoStream) and isValid(videoStream.codec)
       tryDirectPlay = userSettings.playbackTryDirectH264ProfileLevel and videoStream.codec = "h264"
       tryDirectPlay = tryDirectPlay or (userSettings.playbackTryDirectHevcProfileLevel and videoStream.codec = "hevc")
+
+      ' Check source resolution against hardware ceiling before allowing override
+      if tryDirectPlay
+        sourceHeight = 0
+        sourceWidth = 0
+
+        if isValid(videoStream.Height)
+          sourceHeight = videoStream.Height
+          if type(sourceHeight) = "roString" or type(sourceHeight) = "String"
+            sourceHeight = sourceHeight.toInt()
+          end if
+        end if
+
+        if isValid(videoStream.Width)
+          sourceWidth = videoStream.Width
+          if type(sourceWidth) = "roString" or type(sourceWidth) = "String"
+            sourceWidth = sourceWidth.toInt()
+          end if
+        end if
+
+        ' h264: Roku hardware ceiling is 1080p — 4K h264 is physically impossible to decode
+        ' Check both dimensions to catch ultrawide or non-standard aspect ratios
+        if videoStream.codec = "h264" and (sourceHeight > 1080 or sourceWidth > 1920)
+          tryDirectPlay = false
+        end if
+        ' hevc: no additional guard needed — Roku supports up to 4K hevc natively
+      end if
     else
       tryDirectPlay = false
     end if

docs/data/search.json

@@ -146,8 +146,9 @@
           end for
 
           for each codecProfile in postData.DeviceProfile.CodecProfiles
-            if isValid(codecProfile.Codec) and LCase(codecProfile.Codec) = "h264"
-              applyResolutionCapToProfile(codecProfile, h264CapHeight, h264CapWidth)
+            ' Codec field is a comma-separated list of aliases (e.g. "h264,avc")
+            if isValid(codecProfile.Codec) and Instr(1, LCase(codecProfile.Codec), "h264") > 0
+              applyResolutionCapToProfile(codecProfile, h264CapHeight, h264CapWidth, true)
             end if
           end for
         end if

docs/module-deviceCapabilities.html

@@ -858,15 +858,16 @@
     ]
   }
 
-  ' check user setting before adding video level restrictions
-  if not globalUserSettings.playbackTryDirectH264ProfileLevel
-    h264ProfileArray.Conditions.push({
-      "Condition": "LessThanEqual",
-      "Property": "VideoLevel",
-      "Value": h264LevelString,
-      "IsRequired": false
-    })
-  end if
+  ' Always send VideoLevel so the server produces compatible transcodes.
+  ' The playbackTryDirectH264ProfileLevel setting is handled client-side in
+  ' LoadVideoContentTask — if the only transcode reason is VideoLevelNotSupported,
+  ' the client will attempt direct play with a transcode fallback.
+  h264ProfileArray.Conditions.push({
+    "Condition": "LessThanEqual",
+    "Property": "VideoLevel",
+    "Value": h264LevelString,
+    "IsRequired": false
+  })
 
   ' set max resolution
   h264ProfileArray.Conditions.Append(resolutionConditions)
@@ -1026,15 +1027,16 @@
       ]
     }
 
-    ' check user setting before adding VideoLevel restrictions
-    if not globalUserSettings.playbackTryDirectHevcProfileLevel
-      hevcProfileArray.Conditions.push({
-        "Condition": "LessThanEqual",
-        "Property": "VideoLevel",
-        "Value": hevcLevelString,
-        "IsRequired": false
-      })
-    end if
+    ' Always send VideoLevel so the server produces compatible transcodes.
+    ' The playbackTryDirectHevcProfileLevel setting is handled client-side in
+    ' LoadVideoContentTask — if the only transcode reason is VideoLevelNotSupported,
+    ' the client will attempt direct play with a transcode fallback.
+    hevcProfileArray.Conditions.push({
+      "Condition": "LessThanEqual",
+      "Property": "VideoLevel",
+      "Value": hevcLevelString,
+      "IsRequired": false
+    })
 
     ' set max resolution
     hevcProfileArray.Conditions.Append(resolutionConditions)
@@ -1288,33 +1290,64 @@
 
 ' Apply a paired Height + Width resolution cap to a codec profile's Conditions.
 ' No-ops if a Height condition at or below maxHeight already exists.
+' When the existing cap is wider than maxHeight, replaces it (avoids duplicate conditions
+' that can confuse the server's condition evaluation order).
 ' @param codecProfile {object} - The codec profile AA containing a Conditions array
 ' @param maxHeight {integer} - The max height to cap at (e.g. 1080)
 ' @param maxWidth {integer} - The max width to cap at (e.g. 1920)
 ' @param isRequired {boolean} - Whether the condition is required for direct play
 sub applyResolutionCapToProfile(codecProfile as object, maxHeight as integer, maxWidth as integer, isRequired = false as boolean)
   if not isValid(codecProfile) or not isValid(codecProfile.Conditions) then return
 
-  for each condition in codecProfile.Conditions
-    if isValid(condition.Property) and condition.Property = "Height"
-      if condition.Value.toInt() <= maxHeight
-        return ' Resolution cap already present
+  ' Scan for existing Height/Width conditions and track their indices
+  heightIndex = -1
+  widthIndex = -1
+  for i = 0 to codecProfile.Conditions.count() - 1
+    condition = codecProfile.Conditions[i]
+    if isValid(condition.Property)
+      if condition.Property = "Height"
+        if condition.Value.toInt() <= maxHeight
+          return ' Existing cap is already at or below the target — nothing to do
+        end if
+        heightIndex = i
+      else if condition.Property = "Width"
+        widthIndex = i
       end if
     end if
   end for
 
-  codecProfile.Conditions.push({
-    "Condition": "LessThanEqual",
-    "Property": "Height",
-    "Value": maxHeight.toStr(),
-    "IsRequired": isRequired
-  })
-  codecProfile.Conditions.push({
-    "Condition": "LessThanEqual",
-    "Property": "Width",
-    "Value": maxWidth.toStr(),
-    "IsRequired": isRequired
-  })
+  ' Replace existing conditions in-place to avoid duplicates
+  if heightIndex >= 0
+    codecProfile.Conditions[heightIndex] = {
+      "Condition": "LessThanEqual",
+      "Property": "Height",
+      "Value": maxHeight.toStr(),
+      "IsRequired": isRequired
+    }
+  else
+    codecProfile.Conditions.push({
+      "Condition": "LessThanEqual",
+      "Property": "Height",
+      "Value": maxHeight.toStr(),
+      "IsRequired": isRequired
+    })
+  end if
+
+  if widthIndex >= 0
+    codecProfile.Conditions[widthIndex] = {
+      "Condition": "LessThanEqual",
+      "Property": "Width",
+      "Value": maxWidth.toStr(),
+      "IsRequired": isRequired
+    }
+  else
+    codecProfile.Conditions.push({
+      "Condition": "LessThanEqual",
+      "Property": "Width",
+      "Value": maxWidth.toStr(),
+      "IsRequired": isRequired
+    })
+  end if
 end sub
 
 ' Receives and returns an assArray of supported profiles and levels for each video codec