Add VAAPI hardware decode support

Author: tces1

README.md

@@ -39,6 +39,7 @@ Edit `docker/config/config.local.json` before starting:
 - set `upstream.url` to your Emby or Jellyfin server
 - set `server.public_url` if clients reach the proxy through another reverse proxy
 - leave `server.debug` as `false` for concise logs, or set it to `true` for detailed diagnostics
+- set `transcode.hardware_decode` to `vaapi` on Linux hosts with Intel or AMD `/dev/dri` hardware decode support
 
 Update `docker/docker-compose.yml` to mount the local config file if you use `config.local.json`:
 
@@ -86,6 +87,8 @@ Copy `config.example.json` and change the upstream URL:
     "enabled": true,
     "ffmpeg_path": "/usr/bin/ffmpeg",
     "temp_dir": "/var/lib/emby-transcoder/transcode",
+    "hardware_decode": "",
+    "hardware_device": "/dev/dri/renderD128",
     "max_sessions": 2,
     "buffer_pause_seconds": 300,
     "buffer_resume_seconds": 120,
@@ -96,6 +99,7 @@ Copy `config.example.json` and change the upstream URL:
 
 Leave `public_url` empty when clients connect directly to EmbyTranscoder. Set it when EmbyTranscoder sits behind another reverse proxy.
 Leave `debug` as `false` for concise action-level logs. Set it to `true` when you want detailed `TRACE_SWITCH` and request-level diagnostics.
+Set `hardware_decode` to `vaapi` to enable VAAPI hardware decode. The default `hardware_device` is `/dev/dri/renderD128`.
 
 ## Transcode Lifecycle
 

config.example.json

@@ -11,6 +11,8 @@
     "enabled": true,
     "ffmpeg_path": "/usr/bin/ffmpeg",
     "temp_dir": "/var/lib/emby-transcoder/transcode",
+    "hardware_decode": "",
+    "hardware_device": "/dev/dri/renderD128",
     "max_sessions": 2,
     "buffer_pause_seconds": 300,
     "buffer_resume_seconds": 120,

docker/README.md

@@ -23,6 +23,7 @@ Edit `config/config.json` before startup, or copy it to `config/config.local.jso
 - set `upstream.url` to your Emby or Jellyfin server
 - set `server.public_url` if clients reach the proxy through another reverse proxy
 - set `server.debug` to `true` when you need detailed diagnostics
+- set `transcode.hardware_decode` to `vaapi` to use Intel or AMD VAAPI hardware decode through `/dev/dri`
 
 For GitHub Actions publishing to Docker Hub, set `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN` in the repository secrets.
 

docker/config/config.json

@@ -11,6 +11,8 @@
     "enabled": true,
     "ffmpeg_path": "/usr/bin/ffmpeg",
     "temp_dir": "/var/lib/emby-transcoder/transcode",
+    "hardware_decode": "",
+    "hardware_device": "/dev/dri/renderD128",
     "max_sessions": 2,
     "buffer_pause_seconds": 300,
     "buffer_resume_seconds": 120,

docker/docker-compose.yml

@@ -5,6 +5,8 @@ services:
     restart: unless-stopped
     ports:
       - "8097:8097"
+    devices:
+      - /dev/dri:/dev/dri
     volumes:
       - ./config/config.json:/app/config/config.json:ro
       - ./data/transcode:/var/lib/emby-transcoder/transcode

internal/config/config.go

@@ -29,6 +29,8 @@ type Transcode struct {
 	Enabled             bool          `json:"enabled"`
 	FFmpegPath          string        `json:"ffmpeg_path"`
 	TempDir             string        `json:"temp_dir"`
+	HardwareDecode      string        `json:"hardware_decode"`
+	HardwareDevice      string        `json:"hardware_device"`
 	MaxSessions         int           `json:"max_sessions"`
 	BufferPauseSeconds  int           `json:"buffer_pause_seconds"`
 	BufferResumeSeconds int           `json:"buffer_resume_seconds"`
@@ -103,6 +105,11 @@ func normalize(cfg *Config) {
 	if cfg.Transcode.TempDir == "" {
 		cfg.Transcode.TempDir = "/var/lib/emby-transcoder/transcode"
 	}
+	cfg.Transcode.HardwareDecode = strings.ToLower(strings.TrimSpace(cfg.Transcode.HardwareDecode))
+	cfg.Transcode.HardwareDevice = strings.TrimSpace(cfg.Transcode.HardwareDevice)
+	if cfg.Transcode.HardwareDecode == "vaapi" && cfg.Transcode.HardwareDevice == "" {
+		cfg.Transcode.HardwareDevice = "/dev/dri/renderD128"
+	}
 	if cfg.Transcode.MaxSessions <= 0 {
 		cfg.Transcode.MaxSessions = 2
 	}

internal/config/config_test.go

@@ -76,3 +76,26 @@ func TestLoadMergesJSONOverDefaults(t *testing.T) {
 		t.Fatalf("clients = %+v", cfg.Clients)
 	}
 }
+
+func TestLoadSupportsVAAPIHardwareDecode(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "config.json")
+	err := os.WriteFile(path, []byte(`{
+		"upstream": {"url": "http://emby.local:8096"},
+		"transcode": {"hardware_decode": "vaapi"}
+	}`), 0o600)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	cfg, err := config.Load(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if cfg.Transcode.HardwareDecode != "vaapi" {
+		t.Fatalf("hardware decode = %q", cfg.Transcode.HardwareDecode)
+	}
+	if cfg.Transcode.HardwareDevice != "/dev/dri/renderD128" {
+		t.Fatalf("hardware device = %q", cfg.Transcode.HardwareDevice)
+	}
+}

internal/proxy/server.go

@@ -47,6 +47,8 @@ func NewWithTransport(cfg config.Config, transport http.RoundTripper) (*Server,
 		MaxSessions:           cfg.Transcode.MaxSessions,
 		TempDir:               cfg.Transcode.TempDir,
 		FFmpegPath:            cfg.Transcode.FFmpegPath,
+		HardwareDecode:        cfg.Transcode.HardwareDecode,
+		HardwareDevice:        cfg.Transcode.HardwareDevice,
 		BufferPauseThreshold:  cfg.Transcode.BufferPause,
 		BufferResumeThreshold: cfg.Transcode.BufferResume,
 		IdleTimeout:           cfg.Transcode.IdleTimeout,

internal/transcode/ffmpeg_args_test.go

@@ -72,3 +72,32 @@ func TestBuildFFmpegArgsDoesNotThrottleInputWithRealtimeFlag(t *testing.T) {
 		t.Fatalf("ffmpeg args should not include realtime throttling: %v", args)
 	}
 }
+
+func TestBuildFFmpegArgsAppliesVAAPIHardwareDecodeBeforeInput(t *testing.T) {
+	session := &Session{
+		ID:  "item123",
+		Dir: t.TempDir(),
+	}
+	request := Request{InputURL: "http://upstream/stream"}
+
+	args := buildFFmpegArgs(session, request, FFmpegOptions{
+		HardwareDecode: "vaapi",
+		HardwareDevice: "/dev/dri/renderD128",
+	})
+
+	hwaccelIndex := slices.Index(args, "-hwaccel")
+	if hwaccelIndex < 0 || args[hwaccelIndex+1] != "vaapi" {
+		t.Fatalf("missing VAAPI hwaccel args: %v", args)
+	}
+	deviceIndex := slices.Index(args, "-hwaccel_device")
+	if deviceIndex < 0 || args[deviceIndex+1] != "/dev/dri/renderD128" {
+		t.Fatalf("missing VAAPI device args: %v", args)
+	}
+	inputIndex := slices.Index(args, "-i")
+	if inputIndex < 0 {
+		t.Fatalf("missing -i in args: %v", args)
+	}
+	if hwaccelIndex > inputIndex || deviceIndex > inputIndex {
+		t.Fatalf("hardware decode args should be input options before -i: %v", args)
+	}
+}

internal/transcode/manager.go

@@ -28,6 +28,8 @@ type Options struct {
 	MaxSessions           int
 	TempDir               string
 	FFmpegPath            string
+	HardwareDecode        string
+	HardwareDevice        string
 	BufferPauseThreshold  time.Duration
 	BufferResumeThreshold time.Duration
 	BufferCheckInterval   time.Duration
@@ -123,8 +125,16 @@ func NewManager(options Options) *Manager {
 	if options.RestartGraceTimeout <= 0 {
 		options.RestartGraceTimeout = defaultRestartGraceTimeout
 	}
+	options.HardwareDecode = strings.ToLower(strings.TrimSpace(options.HardwareDecode))
+	options.HardwareDevice = strings.TrimSpace(options.HardwareDevice)
 	if options.Runner == nil && options.FFmpegPath != "" {
-		options.Runner = FFmpegRunner{Path: options.FFmpegPath}
+		options.Runner = FFmpegRunner{
+			Path: options.FFmpegPath,
+			Options: FFmpegOptions{
+				HardwareDecode: options.HardwareDecode,
+				HardwareDevice: options.HardwareDevice,
+			},
+		}
 	}
 	return &Manager{options: options, sessions: map[string]*Session{}, media: map[string]MediaInfo{}}
 }
@@ -662,15 +672,21 @@ func durationToTicks(d time.Duration) int64 {
 }
 
 type FFmpegRunner struct {
-	Path string
+	Path    string
+	Options FFmpegOptions
+}
+
+type FFmpegOptions struct {
+	HardwareDecode string
+	HardwareDevice string
 }
 
 func (r FFmpegRunner) Start(ctx context.Context, session *Session, request Request) (Process, error) {
 	if r.Path == "" {
 		return nil, errors.New("ffmpeg path is required")
 	}
 
-	args := buildFFmpegArgs(session, request)
+	args := buildFFmpegArgs(session, request, r.Options)
 	playlist := filepath.Join(session.Dir, "master.m3u8")
 	logPath := filepath.Join(session.Dir, "ffmpeg.log")
 	logging.Infof("transcode start id=%s segment=%d", session.ID, session.SegmentStartIndex)
@@ -708,16 +724,21 @@ func (r FFmpegRunner) Start(ctx context.Context, session *Session, request Reque
 	return process, nil
 }
 
-func buildFFmpegArgs(session *Session, request Request) []string {
+func buildFFmpegArgs(session *Session, request Request, options ...FFmpegOptions) []string {
 	playlist := filepath.Join(session.Dir, "master.m3u8")
 	segmentPattern := filepath.Join(session.Dir, "segment_%05d.ts")
+	ffmpegOptions := FFmpegOptions{}
+	if len(options) > 0 {
+		ffmpegOptions = options[0]
+	}
 	args := []string{
 		"-hide_banner",
 		"-loglevel", "info",
 	}
 	if headerText := ffmpegHeaders(request.Headers); headerText != "" {
 		args = append(args, "-headers", headerText)
 	}
+	args = appendHardwareDecodeArgs(args, ffmpegOptions)
 	if session.StartTimeTicks > 0 {
 		args = append(args, "-ss", ticksSeconds(session.StartTimeTicks))
 	}
@@ -751,6 +772,21 @@ func buildFFmpegArgs(session *Session, request Request) []string {
 	return args
 }
 
+func appendHardwareDecodeArgs(args []string, options FFmpegOptions) []string {
+	switch strings.ToLower(strings.TrimSpace(options.HardwareDecode)) {
+	case "", "none", "off", "false":
+		return args
+	case "vaapi":
+		args = append(args, "-hwaccel", "vaapi")
+		if device := strings.TrimSpace(options.HardwareDevice); device != "" {
+			args = append(args, "-hwaccel_device", device)
+		}
+		return args
+	default:
+		return args
+	}
+}
+
 func ticksSeconds(ticks int64) string {
 	return strconv.FormatFloat(float64(ticks)/10_000_000, 'f', 6, 64)
 }