From e0d3b37dd7bae25dc00b8b2bd6340b35656d4613 Mon Sep 17 00:00:00 2001
From: Alexandre <44178713+alexbelgium@users.noreply.github.com>
Date: Mon, 17 Nov 2025 18:55:29 +0100
Subject: [PATCH] Clarify i915 enable_guc host requirements

---
 jellyfin/CHANGELOG.md                         |  3 ++
 jellyfin/README.md                            |  3 ++
 jellyfin/config.yaml                          |  4 ++-
 .../etc/cont-init.d/25-i915-enable-guc.sh     | 36 +++++++++++++++++++
 4 files changed, 45 insertions(+), 1 deletion(-)
 create mode 100755 jellyfin/rootfs/etc/cont-init.d/25-i915-enable-guc.sh

diff --git a/jellyfin/CHANGELOG.md b/jellyfin/CHANGELOG.md
index 926a8986c..a0b9452d2 100644
--- a/jellyfin/CHANGELOG.md
+++ b/jellyfin/CHANGELOG.md
@@ -1,4 +1,7 @@
 
+## 10.11.3 (17-11-2025)
+- Add optional `i915_enable_guc` setting to apply Intel GuC mode at startup for improved hardware encoding stability, with runtime-only changes that rely on the host exposing `/sys/module/i915/parameters/enable_guc`.
+
 ## 10.11.2 (08-11-2025)
 - Update to latest version from linuxserver/docker-jellyfin (changelog : https://github.com/linuxserver/docker-jellyfin/releases)
 - Added support for configuring extra environment variables via the `env_vars` add-on option alongside config.yaml. See https://github.com/alexbelgium/hassio-addons/wiki/Add-Environment-variables-to-your-Addon-2 for details.
diff --git a/jellyfin/README.md b/jellyfin/README.md
index 14a17ba82..72d4d4479 100644
--- a/jellyfin/README.md
+++ b/jellyfin/README.md
@@ -43,6 +43,7 @@ Webui can be found at `<your-ip>:8096` or through the sidebar using Ingress.
 | `cifsusername` | str | | SMB username for network shares |
 | `cifspassword` | str | | SMB password for network shares |
 | `cifsdomain` | str | | SMB domain for network shares |
+| `i915_enable_guc` | int | | Optional Intel iGPU `enable_guc` parameter (0-3) applied at startup for improved hardware encoding compatibility. Does not reconfigure the kernel; the host must already expose `/sys/module/i915/parameters/enable_guc`. |
 | `DOCKER_MODS` | list | | Additional Docker mods for hardware acceleration |
 
 ### Example Configuration
@@ -69,6 +70,8 @@ Available Docker mods for hardware acceleration:
 - `linuxserver/mods:jellyfin-amd` - AMD hardware acceleration
 - `linuxserver/mods:jellyfin-rffmpeg` - Custom FFmpeg build
 
+For Intel systems that require GuC submission for stable hardware encoding (e.g., N6005), set `i915_enable_guc` to `2` to apply the kernel parameter at container startup. The add-on only writes to the existing runtime module parameter; no kernel rebuild or boot parameter change is attempted. If the path `/sys/module/i915/parameters/enable_guc` is missing or read-only on the host kernel, the add-on logs a warning and continues without modification.
+
 ### Mounting Drives
 
 This addon supports mounting both local drives and remote SMB shares:
diff --git a/jellyfin/config.yaml b/jellyfin/config.yaml
index 8bd543a2d..368b616d0 100644
--- a/jellyfin/config.yaml
+++ b/jellyfin/config.yaml
@@ -92,6 +92,7 @@ options:
   PGID: 0
   PUID: 0
   data_location: /share/jellyfin
+  i915_enable_guc: null
 panel_admin: false
 panel_icon: mdi:billiards-rack
 ports:
@@ -120,10 +121,11 @@ schema:
   cifspassword: str?
   cifsusername: str?
   data_location: str
+  i915_enable_guc: int?
   localdisks: str?
   networkdisks: str?
 slug: jellyfin
 udev: true
 url: https://github.com/alexbelgium/hassio-addons
-version: "10.11.2"
+version: "10.11.3"
 video: true
diff --git a/jellyfin/rootfs/etc/cont-init.d/25-i915-enable-guc.sh b/jellyfin/rootfs/etc/cont-init.d/25-i915-enable-guc.sh
new file mode 100755
index 000000000..c659a8031
--- /dev/null
+++ b/jellyfin/rootfs/etc/cont-init.d/25-i915-enable-guc.sh
@@ -0,0 +1,36 @@
+#!/usr/bin/with-contenv bashio
+# shellcheck shell=bash
+set -e
+
+if ! bashio::config.has_value 'i915_enable_guc'; then
+    exit 0
+fi
+
+GUC_VALUE=$(bashio::config 'i915_enable_guc')
+
+if [[ "${GUC_VALUE}" = "null" ]]; then
+    exit 0
+fi
+
+if [[ ${GUC_VALUE} -lt 0 || ${GUC_VALUE} -gt 3 ]]; then
+    bashio::log.warning "Invalid i915_enable_guc value '${GUC_VALUE}'. Expected a value between 0 and 3. Skipping configuration."
+    exit 0
+fi
+
+PARAM_PATH="/sys/module/i915/parameters/enable_guc"
+
+if [ ! -e "${PARAM_PATH}" ]; then
+    bashio::log.warning "i915 module parameter not found at ${PARAM_PATH}. The add-on cannot enable GuC unless the host kernel exposes this path."
+    exit 0
+fi
+
+if [ ! -w "${PARAM_PATH}" ]; then
+    bashio::log.warning "Missing permission to change ${PARAM_PATH}. Try enabling privileged mode or ensure the host allows changing the parameter."
+    exit 0
+fi
+
+if echo "${GUC_VALUE}" > "${PARAM_PATH}"; then
+    bashio::log.info "Set i915 enable_guc to ${GUC_VALUE}."
+else
+    bashio::log.warning "Failed to set i915 enable_guc to ${GUC_VALUE}."
+fi