From a6f0fd75ff9d548e0893e767bcb1ca975beb4e60 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Sun, 19 Jul 2026 13:08:23 +0000
Subject: [PATCH] docs: opt-in Intel /dev/dri passthrough for Quick Sync hosts

Document commented devices/group_add on the client compose example and
README host setup. Clarify that static FFmpeg still cannot use QSV until
the optional image work in #611. Fixes #610.

Co-authored-by: Josh J <josh@joshjacobs.net>
---
 .env.example               |  4 ++++
 README.md                  | 33 +++++++++++++++++++++++++++++++++
 docker-compose.yml.example | 10 ++++++++++
 3 files changed, 47 insertions(+)

diff --git a/.env.example b/.env.example
index d764788..a9b2f17 100644
--- a/.env.example
+++ b/.env.example
@@ -6,3 +6,7 @@ LOG_LEVEL=INFO
 LOG_DEST=file
 # Optional override; default is /app/data/streamdl.log when LOG_DEST is file/both
 # LOG_FILE=/app/data/streamdl.log
+
+# Intel /dev/dri passthrough is configured in docker-compose (devices/group_add),
+# not via env. See README "Intel Quick Sync / /dev/dri passthrough".
+# Default client FFmpeg is static and has no QSV yet (#611).
diff --git a/README.md b/README.md
index d2944b2..c91393f 100644
--- a/README.md
+++ b/README.md
@@ -73,6 +73,39 @@ Example directory setup before launching:
 mkdir -p downloads/{,in}complete config data
 ```
 
+### Intel Quick Sync / `/dev/dri` passthrough
+
+StreamDL can optionally receive the host Intel graphics device so hardware encode/decode is possible **when FFmpeg supports it**.
+
+**Important limitations today**
+
+- The default client image uses `mwader/static-ffmpeg`, which does **not** include Quick Sync (QSV) or VAAPI. Passing `/dev/dri` into that image alone will not accelerate encodes.
+- Most StreamDL downloads remux with stream copy (`-c copy` for VODs; optional via `FFMPEG_STREAM_COPY` for live). Remuxing does not use the GPU. Quick Sync only helps when something **re-encodes** (in-process via `FFMPEG_EXTRA_*`, or a `post_script` transcoder).
+- A QSV/VAAPI-capable client image is tracked in #611; first-class hwaccel presets in #612.
+
+**Enable device access (opt-in)**
+
+1. Confirm the host has a render node, e.g. `ls -l /dev/dri`.
+2. Note the `video` / `render` group IDs (they vary by distro):
+   ```shell
+   getent group video render
+   stat -c '%g' /dev/dri/renderD128
+   ```
+3. In `docker-compose.yml`, uncomment the client `devices:` / `group_add:` block from `docker-compose.yml.example` and replace the example GIDs with yours.
+4. Keep `PUID`/`PGID` as usual for download file ownership; `group_add` is separate and only grants DRM device access.
+
+Example (GIDs illustrative only):
+
+```yaml
+devices:
+  - /dev/dri:/dev/dri
+group_add:
+  - "44"   # video
+  - "992"  # render
+```
+
+On TrueNAS / Kubernetes-style apps, map the same device and supplemental groups through the UI or runtime equivalent of Docker `devices` + `group_add`.
+
 ### Logging
 
 StreamDL can send full application logs to a file, container stdout, or both:
diff --git a/docker-compose.yml.example b/docker-compose.yml.example
index 116532e..32470f6 100644
--- a/docker-compose.yml.example
+++ b/docker-compose.yml.example
@@ -18,5 +18,15 @@ services:
       - ./downloads/complete:/app/out # completed downloads location
       - ./config:/app/config # config folder - using a folder allows host updates without cycling the container
       - ./data:/app/data # VOD DB + default streamdl.log when LOG_DEST=file/both
+    # Optional: Intel Quick Sync / VAAPI device passthrough (see README).
+    # Uncomment only on hosts with /dev/dri. GIDs are host-specific — run
+    # `stat -c '%g' /dev/dri/renderD128` and `getent group video render`.
+    # NOTE: The default client image ships static FFmpeg without QSV/VAAPI.
+    # Device access alone is not enough until a QSV-capable image is available (#611).
+    # devices:
+    #   - /dev/dri:/dev/dri
+    # group_add:
+    #   - "44"    # video  — replace with your host video GID
+    #   - "992"   # render — replace with your host render GID
     depends_on:
       - server