Probe VAAPI support on startup

Author: tces1

README.md

@@ -40,6 +40,7 @@ Edit `docker/config/config.local.json` before starting:
 - 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
+- startup will probe VAAPI availability and fall back to software decode if the device or ffmpeg support is missing
 
 Update `docker/docker-compose.yml` to mount the local config file if you use `config.local.json`:
 
@@ -100,6 +101,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`.
+If the device or ffmpeg probe fails, startup falls back to software decode and logs the reason.
 
 ## Transcode Lifecycle
 

docker/README.md

@@ -24,6 +24,7 @@ Edit `config/config.json` before startup, or copy it to `config/config.local.jso
 - 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`
+- startup probes VAAPI support and falls back to software decode when the device is unavailable or ffmpeg lacks VAAPI
 
 For GitHub Actions publishing to Docker Hub, set `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN` in the repository secrets.
 

internal/transcode/ffmpeg_args_test.go

@@ -1,6 +1,7 @@
 package transcode
 
 import (
+	"errors"
 	"path/filepath"
 	"slices"
 	"testing"
@@ -101,3 +102,54 @@ func TestBuildFFmpegArgsAppliesVAAPIHardwareDecodeBeforeInput(t *testing.T) {
 		t.Fatalf("hardware decode args should be input options before -i: %v", args)
 	}
 }
+
+func TestResolveHardwareDecodeKeepsVAAPIWhenProbePasses(t *testing.T) {
+	options := resolveHardwareDecodeOptions("/usr/bin/ffmpeg", FFmpegOptions{
+		HardwareDecode: "vaapi",
+		HardwareDevice: "/dev/dri/renderD128",
+	}, func(path string, options FFmpegOptions) error {
+		if path != "/usr/bin/ffmpeg" {
+			t.Fatalf("ffmpeg path = %q", path)
+		}
+		if options.HardwareDecode != "vaapi" {
+			t.Fatalf("hardware decode = %q", options.HardwareDecode)
+		}
+		return nil
+	})
+
+	if options.HardwareDecode != "vaapi" || options.HardwareDevice != "/dev/dri/renderD128" {
+		t.Fatalf("options = %+v", options)
+	}
+}
+
+func TestResolveHardwareDecodeFallsBackToSoftwareWhenProbeFails(t *testing.T) {
+	options := resolveHardwareDecodeOptions("/usr/bin/ffmpeg", FFmpegOptions{
+		HardwareDecode: "vaapi",
+		HardwareDevice: "/dev/dri/renderD128",
+	}, func(string, FFmpegOptions) error {
+		return errors.New("device not accessible")
+	})
+
+	if options.HardwareDecode != "" || options.HardwareDevice != "" {
+		t.Fatalf("expected software fallback, options = %+v", options)
+	}
+}
+
+func TestNewManagerFallsBackToSoftwareDecodeWhenHardwareProbeFails(t *testing.T) {
+	manager := NewManager(Options{
+		FFmpegPath:     "/usr/bin/ffmpeg",
+		HardwareDecode: "vaapi",
+		HardwareDevice: "/dev/dri/renderD128",
+		HardwareProbe: func(string, FFmpegOptions) error {
+			return errors.New("device not accessible")
+		},
+	})
+
+	runner, ok := manager.options.Runner.(FFmpegRunner)
+	if !ok {
+		t.Fatalf("runner = %T", manager.options.Runner)
+	}
+	if runner.Options.HardwareDecode != "" || runner.Options.HardwareDevice != "" {
+		t.Fatalf("expected runner to use software decode, options = %+v", runner.Options)
+	}
+}

internal/transcode/manager.go

@@ -37,6 +37,7 @@ type Options struct {
 	ReapInterval          time.Duration
 	RestartGraceTimeout   time.Duration
 	Runner                Runner
+	HardwareProbe         HardwareProbe
 }
 
 type Request struct {
@@ -128,12 +129,13 @@ func NewManager(options Options) *Manager {
 	options.HardwareDecode = strings.ToLower(strings.TrimSpace(options.HardwareDecode))
 	options.HardwareDevice = strings.TrimSpace(options.HardwareDevice)
 	if options.Runner == nil && options.FFmpegPath != "" {
+		ffmpegOptions := resolveHardwareDecodeOptions(options.FFmpegPath, FFmpegOptions{
+			HardwareDecode: options.HardwareDecode,
+			HardwareDevice: options.HardwareDevice,
+		}, options.HardwareProbe)
 		options.Runner = FFmpegRunner{
-			Path: options.FFmpegPath,
-			Options: FFmpegOptions{
-				HardwareDecode: options.HardwareDecode,
-				HardwareDevice: options.HardwareDevice,
-			},
+			Path:    options.FFmpegPath,
+			Options: ffmpegOptions,
 		}
 	}
 	return &Manager{options: options, sessions: map[string]*Session{}, media: map[string]MediaInfo{}}
@@ -681,6 +683,79 @@ type FFmpegOptions struct {
 	HardwareDevice string
 }
 
+type HardwareProbe func(ffmpegPath string, options FFmpegOptions) error
+
+func resolveHardwareDecodeOptions(ffmpegPath string, options FFmpegOptions, probe HardwareProbe) FFmpegOptions {
+	options.HardwareDecode = strings.ToLower(strings.TrimSpace(options.HardwareDecode))
+	options.HardwareDevice = strings.TrimSpace(options.HardwareDevice)
+	switch options.HardwareDecode {
+	case "", "none", "off", "false":
+		return FFmpegOptions{}
+	case "vaapi":
+		if options.HardwareDevice == "" {
+			options.HardwareDevice = "/dev/dri/renderD128"
+		}
+	default:
+		logging.Infof("hardware decode unavailable mode=%s reason=unsupported fallback=software", options.HardwareDecode)
+		return FFmpegOptions{}
+	}
+
+	if probe == nil {
+		probe = defaultHardwareProbe
+	}
+	if err := probe(ffmpegPath, options); err != nil {
+		logging.Infof("hardware decode unavailable mode=%s device=%s reason=%v fallback=software", options.HardwareDecode, options.HardwareDevice, err)
+		return FFmpegOptions{}
+	}
+	logging.Infof("hardware decode enabled mode=%s device=%s", options.HardwareDecode, options.HardwareDevice)
+	return options
+}
+
+func defaultHardwareProbe(ffmpegPath string, options FFmpegOptions) error {
+	if strings.TrimSpace(ffmpegPath) == "" {
+		return errors.New("ffmpeg path is required")
+	}
+	switch options.HardwareDecode {
+	case "vaapi":
+		if err := probeFFmpegHWAccel(ffmpegPath, "vaapi"); err != nil {
+			return err
+		}
+		return probeDevice(options.HardwareDevice)
+	default:
+		return fmt.Errorf("unsupported hardware decode mode %q", options.HardwareDecode)
+	}
+}
+
+func probeFFmpegHWAccel(ffmpegPath, name string) error {
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+
+	output, err := exec.CommandContext(ctx, ffmpegPath, "-hide_banner", "-hwaccels").CombinedOutput()
+	if ctx.Err() != nil {
+		return fmt.Errorf("ffmpeg hwaccel probe timed out")
+	}
+	if err != nil {
+		return fmt.Errorf("ffmpeg hwaccel probe failed: %w", err)
+	}
+	for _, line := range strings.Split(string(output), "\n") {
+		if strings.EqualFold(strings.TrimSpace(line), name) {
+			return nil
+		}
+	}
+	return fmt.Errorf("ffmpeg does not list %s hwaccel", name)
+}
+
+func probeDevice(device string) error {
+	if strings.TrimSpace(device) == "" {
+		return errors.New("hardware device is required")
+	}
+	file, err := os.OpenFile(device, os.O_RDWR, 0)
+	if err != nil {
+		return fmt.Errorf("open hardware device: %w", err)
+	}
+	return file.Close()
+}
+
 func (r FFmpegRunner) Start(ctx context.Context, session *Session, request Request) (Process, error) {
 	if r.Path == "" {
 		return nil, errors.New("ffmpeg path is required")