Merge pull request 'Feat/jellyfin hw transcoding' (#3) from feat/jellyfin-hw-transcoding into main

Reviewed-on: #3

docs/superpowers/specs/2026-07-26-jellyfin-hw-transcoding.md

@@ -106,3 +106,40 @@ show up as low CPU, some GPU (`intel_gpu_top`) activity instead.
 - Exact supported codec list depends on the iGPU generation (device ID
   `9a49`) — confirm via `vainfo` output once run, and enable only the
   hardware decode paths it actually reports.
+
+## Post-deploy fix: two additional runtime packages required
+
+After the initial deploy (Task 1's `SupplementaryGroups` grant) and
+enabling QSV in the dashboard, HEVC HDR playback hung indefinitely
+(Direct Play worked for some titles; titles that needed a real
+transcode+tonemap never produced output). Root-caused via
+`journalctl -u jellyfin` and the per-session ffmpeg transcode log
+(`find / -xdev -iname '*ffmpeg-transcode*'`) — two separate runtimes
+were missing beyond `intel-media-driver` (which only provides VAAPI):
+
+1. **QSV session creation failed:** `Error creating a MFX session: -9`
+   / `Error initializing an MFX session: -3` on
+   `-init_hw_device qsv=qs@va`. VAAPI and QSV are separate runtimes on
+   Linux — QSV needs the oneVPL/MFX GPU implementation. Fix: added
+   `pkgs.vpl-gpu-rt` ("oneAPI Video Processing Library Intel GPU
+   implementation"; note `onevpl-intel-gpu` is the old, renamed
+   attribute) to `hardware.graphics.extraPackages` in
+   `machines/jupiter/hardware-configuration.nix`.
+
+2. **OpenCL device creation failed:** `Failed to get number of OpenCL
+   platforms: -1001` (`CL_PLATFORM_NOT_FOUND_KHR`) on
+   `-init_hw_device opencl=ocl@va`. The `tonemap_opencl` filter jellyfin
+   uses for HDR→SDR tone-mapping needs a working OpenCL ICD, which
+   nothing installed so far provides. Fix: added
+   `pkgs.intel-compute-runtime` ("Intel Graphics Compute Runtime oneAPI
+   Level Zero and OpenCL, supporting 12th Gen and newer" — matches
+   jupiter's Tiger Lake/Xe iGPU) to the same `extraPackages` list.
+
+Confirmed working end-to-end: HEVC HDR transcode with QSV encode +
+OpenCL tone-map runs at `speed=2.68x` realtime on jupiter's iGPU, and
+plays smoothly on Apple TV (JellyTV app).
+
+Both packages live in `machines/jupiter/hardware-configuration.nix`
+(`hardware.graphics.extraPackages`), alongside `intel-media-driver`,
+rather than in the jellyfin module itself — they're iGPU runtime
+capabilities, not something specific to the jellyfin service.

docs/superpowers/specs/2026-07-27-mibook-boot-desktop-choice-design.md

@@ -0,0 +1,61 @@
+# mibook: choose terminal-only vs desktop at boot
+
+## Goal
+
+Let mibook boot to a text console by default, with KDE fully installed and
+launchable on demand. The user decides after boot whether they need the
+graphical desktop, without rebuilding the system.
+
+## Behavior
+
+- mibook boots to a text console (`multi-user.target`). SDDM and Plasma do
+  **not** start automatically.
+- KDE (SDDM + Plasma 6) remains fully installed.
+- Running `desktop` in the terminal starts the SDDM display manager, which
+  presents the graphical login screen; logging in there enters a Plasma 6
+  session.
+- No reverse command. To return to a text console, stop the display manager
+  (`sudo systemctl stop display-manager`) or reboot.
+- Other machines that enable the `kde-desktop` profile are unaffected; their
+  desktop still starts on boot.
+
+## Implementation
+
+### `modules/environments/kde-desktop/default.nix`
+
+Add an opt-out option to the existing profile:
+
+- New option `my.profiles.kde-desktop.startOnBoot`, a boolean defaulting to
+  `true`. The default preserves the current behavior for every consumer.
+- The existing `config` block (SDDM, Plasma 6, user packages) stays enabled
+  whenever the profile is enabled, regardless of `startOnBoot`.
+- When `startOnBoot = false`, additionally apply:
+  - `systemd.services.display-manager.wantedBy = lib.mkForce [ ];` so SDDM is
+    defined but not pulled in by any boot target.
+  - `systemd.defaultUnit = "multi-user.target";` so the boot target is the
+    text console.
+  - A `desktop` command provided via
+    `pkgs.writeShellScriptBin "desktop" "exec sudo systemctl start display-manager.service"`,
+    added to `environment.systemPackages`.
+
+### `machines/mibook/environments.nix`
+
+Set `kde-desktop.startOnBoot = false;` alongside the existing
+`kde-desktop.enable = true;`.
+
+## Testing / verification
+
+- `nix build '.#nixosConfigurations.mibook.config.system.build.toplevel'`
+  builds without error.
+- After `nixos-rebuild switch` on mibook: system boots to a TTY, no SDDM;
+  running `desktop` brings up the SDDM login and a working Plasma session.
+- Confirm jupiter (or any non-mibook consumer) is unchanged: its evaluated
+  `systemd.defaultUnit` / display-manager wantedBy are not altered.
+
+## Trade-offs
+
+- `desktop` relies on `sudo`; the user has sudo access, so no extra
+  configuration is required.
+- Chose "boot to terminal, launch on demand" over a GRUB boot-menu entry
+  because it is more robust across NixOS generations and needs no fragile
+  static kernel entries.

flake.lock

@@ -89,11 +89,11 @@
         "nixpkgs-regression": "nixpkgs-regression"
       },
       "locked": {
-        "lastModified": 1784375420,
-        "narHash": "sha256-dt1zVj4MRpmffhsgQk+3tx1m/pFTXbtVWrn5KZ1y+8Q=",
+        "lastModified": 1784762557,
+        "narHash": "sha256-R/r6jRnANV50c8F5Fz5+1Q1moab0IGWRk+cg5ME2nMY=",
         "owner": "NixOS",
         "repo": "nix",
-        "rev": "bebd2f851a304e9fb2e143ce0cbeff577c6a37ac",
+        "rev": "d10c84cd0cc0efdcb29cf2611caf5fbcd10fa071",
         "type": "github"
       },
       "original": {
@@ -143,11 +143,11 @@
         "nixpkgs": "nixpkgs_2"
       },
       "locked": {
-        "lastModified": 1784310968,
-        "narHash": "sha256-rkSPTePrKqs4dg+i7ZFCq93+HrClac6oSwXX927SVjA=",
+        "lastModified": 1784723954,
+        "narHash": "sha256-1CfD8ZUjCkTgjsneLZ/lxCHhgDfqxxE7/GX0MmsgiqA=",
         "owner": "NixOS",
         "repo": "nixos-hardware",
-        "rev": "779c32a00155994c86cde8213a8dd4df139d4355",
+        "rev": "a017f5b72210026af5b3ac5949f08d94380a6fbd",
         "type": "github"
       },
       "original": {
@@ -218,11 +218,11 @@
     },
     "nixpkgs-unstable": {
       "locked": {
-        "lastModified": 1784497964,
-        "narHash": "sha256-WhdsTtaih3DgTPP/PX023b36UNQyMzEoi6GkPyGx0y4=",
-        "rev": "241313f4e8e508cb9b13278c2b0fa25b9ca27163",
+        "lastModified": 1784796856,
+        "narHash": "sha256-vwxWgF+Gj276WznzGb1LxGsK/39HaQwgQXiU3EkC844=",
+        "rev": "e2587caef70cea85dd97d7daab492899902dbf5d",
         "type": "tarball",
-        "url": "https://releases.nixos.org/nixos/unstable/nixos-26.11pre1037713.241313f4e8e5/nixexprs.tar.xz"
+        "url": "https://releases.nixos.org/nixos/unstable/nixos-26.11pre1040357.e2587caef70c/nixexprs.tar.xz"
       },
       "original": {
         "id": "nixpkgs",
@@ -245,11 +245,11 @@
     },
     "nixpkgs_3": {
       "locked": {
-        "lastModified": 1784432872,
-        "narHash": "sha256-IX7j5TvSD7hYC9NZ8mgmq7pZ97mYyl24Qs4Tz4uyvO4=",
-        "rev": "fd1462031fdee08f65fd0b4c6b64e22239a77870",
+        "lastModified": 1784707089,
+        "narHash": "sha256-DUedXhD2Rg8q4Xyd07Sb90eZGy4gg6W+Vl/WbLNwAZo=",
+        "rev": "b3fe9581c9061c749abef42b6d4ee7b7c05c33fa",
         "type": "tarball",
-        "url": "https://releases.nixos.org/nixos/26.05/nixos-26.05.5591.fd1462031fde/nixexprs.tar.xz"
+        "url": "https://releases.nixos.org/nixos/26.05/nixos-26.05.5845.b3fe9581c906/nixexprs.tar.xz"
       },
       "original": {
         "id": "nixpkgs",

machines/mibook/configuration.nix

@@ -44,6 +44,14 @@
 
   services.openssh.enable = true;
 
+  # KDE (PowerDevil) power settings: do nothing on lid close while on AC power.
+  # Shipped as a system-wide default; KConfig cascades so a user's own
+  # ~/.config/powerdevilrc will override this if present.
+  environment.etc."xdg/powerdevilrc".text = ''
+    [AC][SuspendAndShutdown]
+    LidAction=0
+  '';
+
   system = {
     stateVersion = "23.05";
     autoUpgrade.enable = true;

machines/mibook/environments.nix

@@ -6,6 +6,7 @@ in
 {
   my.profiles = {
     kde-desktop.enable = true;
+    kde-desktop.startOnBoot = false;
     zsh.enable = true;
     apps = {
       desktop_apps = true;

modules/environments/kde-desktop/default.nix

@@ -11,17 +11,37 @@ in
 {
   options.my.profiles.kde-desktop = with lib; {
     enable = mkEnableOption "KDE Desktop Environment";
+    startOnBoot = mkOption {
+      type = types.bool;
+      default = true;
+      description = ''
+        Whether the display manager (SDDM) starts automatically at boot.
+        When false, the system boots to a text console and KDE can be
+        launched on demand with the `desktop` command.
+      '';
+    };
   };
 
-  config = lib.mkIf cfg.enable {
-    services = {
-      displayManager.sddm.enable = true;
-      displayManager.sddm.wayland.enable = true;
-      desktopManager.plasma6.enable = true;
-    };
-    users.users.finn.packages = with pkgs; [
-      # Programms can be added here...
-      numix-icon-theme
-    ];
-  };
+  config = lib.mkIf cfg.enable (lib.mkMerge [
+    {
+      services = {
+        displayManager.sddm.enable = true;
+        displayManager.sddm.wayland.enable = true;
+        desktopManager.plasma6.enable = true;
+      };
+      users.users.finn.packages = with pkgs; [
+        # Programms can be added here...
+        numix-icon-theme
+      ];
+    }
+    (lib.mkIf (!cfg.startOnBoot) {
+      # Boot to a text console; SDDM stays installed but is not pulled in
+      # by any boot target. Launch KDE on demand with `desktop`.
+      systemd.services.display-manager.wantedBy = lib.mkForce [ ];
+      systemd.defaultUnit = lib.mkForce "multi-user.target";
+      environment.systemPackages = [
+        (pkgs.writeShellScriptBin "desktop" "exec sudo systemctl start display-manager.service")
+      ];
+    })
+  ]);
 }