diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml
index 23ea9ad6..b3c0dbc5 100644
--- a/.github/workflows/release.yaml
+++ b/.github/workflows/release.yaml
@@ -4,6 +4,12 @@ on:
push:
branches: ['main']
tags: ['v*']
+ workflow_dispatch:
+ inputs:
+ tag:
+ description: 'Docker image tag (e.g. feature-vaapi)'
+ required: false
+ type: string
jobs:
build-and-push:
@@ -46,6 +52,7 @@ jobs:
tags: |
type=semver,pattern={{version}}
type=ref,event=branch
+ type=raw,value=${{ inputs.tag }},enable=${{ github.event_name == 'workflow_dispatch' && inputs.tag != '' }}
# Build and push Docker image
- name: Build and push Docker image
diff --git a/CHANGELOG.md b/CHANGELOG.md
index cfccf9bf..4513b88a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
### Added
+- **transcode**: Add VA-API hardware acceleration support for Linux hosts and Docker environments with Intel and AMD GPUs, featuring automatic DRI render node discovery, variable bitrate control, and structured transcoding observability logs
+- **docker**: Add modular hardware-accelerated transcoding presets matching Immich's compose configuration via `hwaccel.transcoding.yaml` with support for NVENC, QuickSync, RKMPP, and VA-API
+
### Fixed
### Changed
diff --git a/Dockerfile b/Dockerfile
index 384aa227..1db5b90d 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -30,11 +30,7 @@ RUN bun run scripts/extract-runtime-deps.ts
# Stage 2: Runner
FROM oven/bun:1.4.2 AS runner
-# Install ffmpeg/ffprobe
-COPY --from=mwader/static-ffmpeg:8.1 /ffmpeg /usr/local/bin/
-COPY --from=mwader/static-ffmpeg:8.1 /ffprobe /usr/local/bin/
-
-# Install system dependencies for sandbox runtime and agent
+# Install system dependencies and Jellyfin-FFmpeg (with VA-API support)
RUN apt-get update && apt-get install -y --no-install-recommends \
python3 \
make \
@@ -56,11 +52,24 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
poppler-utils \
imagemagick \
fonts-noto-cjk \
+ && . /etc/os-release \
+ && TARGETARCH=$(dpkg --print-architecture) \
+ && FFMPEG_VERSION="8.1.2-5" \
+ && curl -fsSL -o /tmp/jellyfin-ffmpeg.deb "https://github.com/jellyfin/jellyfin-ffmpeg/releases/download/v${FFMPEG_VERSION}/jellyfin-ffmpeg8_${FFMPEG_VERSION}-${VERSION_CODENAME}_${TARGETARCH}.deb" \
+ && apt-get install -y --no-install-recommends /tmp/jellyfin-ffmpeg.deb \
+ && rm -f /tmp/jellyfin-ffmpeg.deb \
+ && ldconfig /usr/lib/jellyfin-ffmpeg/lib \
+ && ln -sf /usr/lib/jellyfin-ffmpeg/ffmpeg /usr/local/bin/ffmpeg \
+ && ln -sf /usr/lib/jellyfin-ffmpeg/ffprobe /usr/local/bin/ffprobe \
+ && ln -sf /usr/lib/jellyfin-ffmpeg/ffmpeg /usr/bin/ffmpeg \
+ && ln -sf /usr/lib/jellyfin-ffmpeg/ffprobe /usr/bin/ffprobe \
&& apt-get clean \
&& rm -rf /var/lib/apt/lists/*
-# Set up working directory and make it owned by the bun user
-RUN mkdir -p /app/data && chown -R bun:bun /app
+# Set up working directory and make it owned by the bun user, ensure video/render group access
+RUN usermod -a -G video,render bun 2>/dev/null || true \
+ && mkdir -p /app/data \
+ && chown -R bun:bun /app
# Switch to the non-root bun user
USER bun
diff --git a/README.md b/README.md
index ac83ae99..fcbf6b7d 100644
--- a/README.md
+++ b/README.md
@@ -86,6 +86,9 @@ Docker Compose is the fastest way to get Shumai running. You do not need to clon
```bash
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose.yaml
```
+
+ > [!NOTE]
+ > By default, the standard `docker-compose.yaml` uses CPU software transcoding. If your server has a GPU (NVIDIA NVENC, Intel QuickSync, AMD/Intel VA-API, or Rockchip RKMPP) and you want to enable GPU hardware acceleration, check the [Hardware Transcoding Guide](https://docs.shumai.one/configuration/hardware-transcoding).
3. Configure environment variables (optional):
* `SHUMAI_SERVER_PORT` controls the port the Shumai server listens on. The default is `3000`.
diff --git a/README_CN.md b/README_CN.md
index baa70ee1..de0b966a 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -101,9 +101,11 @@ https://gh-proxy.com/https://raw.githubusercontent.com/shumaiOne/shumai/main/REA
2. 下载 `docker-compose.yaml` 配置文件:
```bash
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose-aliyun.yaml
-
```
+ > [!NOTE]
+ > 默认的 Docker Compose 配置使用基于 CPU 的软件转码。如果您的服务器配备了支持的显卡(NVIDIA NVENC、Intel QuickSync、AMD/Intel VA-API 或 Rockchip RKMPP)并需要开启 GPU 硬件加速转码,请参考 [硬件加速转码配置文档](https://docs.shumai.one/configuration/hardware-transcoding)。
+
3. 配置环境变量(可选):
* `SHUMAI_SERVER_PORT` 用于控制 Shumai 服务监听的端口,默认值为 `3000`。
diff --git a/docker-compose/local/docker-compose-aliyun.yaml b/docker-compose/local/docker-compose-aliyun.yaml
index 239a163b..c0c13a2b 100644
--- a/docker-compose/local/docker-compose-aliyun.yaml
+++ b/docker-compose/local/docker-compose-aliyun.yaml
@@ -26,6 +26,11 @@ services:
- '3000:3000'
volumes:
- ./data:/app/data
+ # Hardware Acceleration (NVENC / QuickSync / VA-API / RKMPP)
+ # Uncomment the extends section below for hardware acceleration:
+ # extends:
+ # file: hwaccel.transcoding.yaml
+ # service: cpu # set to one of [nvenc, quicksync, rkmpp, vaapi, vaapi-wsl] for accelerated transcoding
environment:
# Database Configuration
DATABASE_URL: postgres://shumai:shumai_password@shumai_postgres:5432/shumai_db?search_path=public&sslmode=disable
diff --git a/docker-compose/local/docker-compose.yaml b/docker-compose/local/docker-compose.yaml
index 42213fe5..141364d9 100644
--- a/docker-compose/local/docker-compose.yaml
+++ b/docker-compose/local/docker-compose.yaml
@@ -26,6 +26,11 @@ services:
- '3000:3000'
volumes:
- ./data:/app/data
+ # Hardware Acceleration (NVENC / QuickSync / VA-API / RKMPP)
+ # Uncomment the extends section below for hardware acceleration:
+ # extends:
+ # file: hwaccel.transcoding.yaml
+ # service: cpu # set to one of [nvenc, quicksync, rkmpp, vaapi, vaapi-wsl] for accelerated transcoding
environment:
# Database Configuration
DATABASE_URL: postgres://shumai:shumai_password@shumai_postgres:5432/shumai_db?search_path=public&sslmode=disable
diff --git a/docker-compose/local/hwaccel.transcoding.yaml b/docker-compose/local/hwaccel.transcoding.yaml
new file mode 100644
index 00000000..e73e8dfa
--- /dev/null
+++ b/docker-compose/local/hwaccel.transcoding.yaml
@@ -0,0 +1,44 @@
+# Configurations for hardware-accelerated transcoding
+services:
+ cpu: {}
+
+ nvenc:
+ deploy:
+ resources:
+ reservations:
+ devices:
+ - driver: nvidia
+ count: 1
+ capabilities:
+ - gpu
+ - compute
+ - video
+
+ quicksync:
+ devices:
+ - /dev/dri:/dev/dri
+
+ rkmpp:
+ security_opt: # enables full access to /sys and /proc, still far better than privileged: true
+ - systempaths=unconfined
+ - apparmor=unconfined
+ group_add:
+ - video
+ devices:
+ - /dev/rga:/dev/rga
+ - /dev/dri:/dev/dri
+ - /dev/dma_heap:/dev/dma_heap
+ - /dev/mpp_service:/dev/mpp_service
+
+ vaapi:
+ devices:
+ - /dev/dri:/dev/dri
+
+ vaapi-wsl: # use this for VAAPI if running in WSL2
+ devices:
+ - /dev/dri:/dev/dri
+ - /dev/dxg:/dev/dxg
+ volumes:
+ - /usr/lib/wsl:/usr/lib/wsl
+ environment:
+ - LIBVA_DRIVER_NAME=d3d12
diff --git a/docs/configuration/hardware-transcoding.mdx b/docs/configuration/hardware-transcoding.mdx
new file mode 100644
index 00000000..8d984e3f
--- /dev/null
+++ b/docs/configuration/hardware-transcoding.mdx
@@ -0,0 +1,219 @@
+---
+title: Hardware Transcoding
+description: Accelerate video transcoding and reduce CPU load with GPU hardware acceleration.
+---
+
+High-resolution camera recordings, phone videos, and animation media files require proxy transcoding to play smoothly in web browsers. Shumai transcodes these assets in the background, generating a universal `180p` proxy for instant scrubbing alongside full-resolution preview streams.
+
+Hardware-accelerated transcoding allows you to offload video encoding to a dedicated or integrated GPU, dramatically speeding up processing and freeing host CPU cores for other services.
+
+Shumai includes a built-in usability probe that tests hardware encoders at runtime. If GPU drivers or device nodes are unavailable, Shumai automatically falls back to software encoding without failing user tasks.
+
+---
+
+## Supported Backends
+
+| Backend | Hardware Platform | Container Driver / Devices |
+| :-------------- | :--------------------------------- | :----------------------------------------------- |
+| **`nvenc`** | NVIDIA GPUs | NVIDIA Container Toolkit (`gpu, compute, video`) |
+| **`quicksync`** | Intel Integrated & Arc GPUs | `/dev/dri` render nodes |
+| **`vaapi`** | AMD & Intel GPUs | `/dev/dri` render nodes |
+| **`rkmpp`** | Rockchip ARM SoCs (e.g. RK3588) | `/dev/rga`, `/dev/dri`, `/dev/mpp_service` |
+| **`vaapi-wsl`** | Windows Subsystem for Linux (WSL2) | `/dev/dri`, `/dev/dxg`, `/usr/lib/wsl` |
+
+---
+
+## Limitations
+
+- The instructions on this page focus on **Docker Compose**. Other container orchestrators (such as Kubernetes or Podman) require equivalent device passthrough configurations.
+- **Docker Desktop on macOS** runs inside a Linux virtual machine and does not support Apple Silicon VideoToolbox passthrough. (VideoToolbox hardware acceleration is supported when running Shumai natively via NPM or from source).
+- Hardware transcoding produces slightly different bitrate characteristics compared to software encoding. Shumai uses adaptive variable bitrate (VBR) rate control tailored to web streaming to maintain visual fidelity.
+
+---
+
+## Prerequisites
+
+### NVENC (NVIDIA)
+
+1. Ensure the official NVIDIA graphics driver is installed on the host:
+ ```bash
+ nvidia-smi
+ ```
+2. Install the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) on the host and restart Docker:
+ ```bash
+ sudo apt-get install -y nvidia-container-toolkit
+ sudo nvidia-ctk runtime configure --runtime=docker
+ sudo systemctl restart docker
+ ```
+
+### QuickSync & VA-API (Intel / AMD)
+
+1. Verify that the Linux kernel has initialized the Direct Rendering Infrastructure (DRI) render node:
+ ```bash
+ ls -la /dev/dri
+ ```
+ You should see `card0` and `renderD128` (or similar).
+2. Shumai's Docker image automatically adjusts group permissions on container startup so the non-root application user can access host `/dev/dri` devices without permission errors.
+
+### WSL2 (Windows)
+
+- Ensure you are running Windows 11 with WSL2 and have installed the appropriate GPU drivers on the Windows host.
+- Use the `vaapi-wsl` preset which maps `/dev/dxg` and `/usr/lib/wsl` into the container.
+
+---
+
+## Setup with Docker Compose
+
+Shumai uses a modular `hwaccel.transcoding.yaml` companion file to configure hardware devices.
+
+### Step 1: Download Configuration Files
+
+In your Shumai deployment directory, download the companion `hwaccel.transcoding.yaml` alongside `docker-compose.yaml`:
+
+```bash
+# Global / Official
+curl -o hwaccel.transcoding.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/hwaccel.transcoding.yaml
+
+# Accelerated Mirror (Mainland China)
+curl -o hwaccel.transcoding.yaml https://gh-proxy.com/https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/hwaccel.transcoding.yaml
+```
+
+### Step 2: Enable Hardware Acceleration in Docker Compose
+
+Open `docker-compose.yaml` (or `docker-compose-aliyun.yaml`), find the commented `extends` block under the `shumai` service, and uncomment it:
+
+```yaml
+services:
+ shumai:
+ # ...
+ # Hardware Acceleration (NVENC / QuickSync / VA-API / RKMPP)
+ extends:
+ file: hwaccel.transcoding.yaml
+ service: nvenc # set to one of [nvenc, quicksync, rkmpp, vaapi, vaapi-wsl]
+```
+
+Replace `nvenc` with your target backend:
+
+- `nvenc` for NVIDIA GPUs
+- `quicksync` for Intel Quick Sync
+- `vaapi` for AMD or Intel VA-API
+- `rkmpp` for Rockchip SoCs
+- `vaapi-wsl` for WSL2 on Windows
+
+### Step 3: Start the Stack
+
+Restart or recreate the Shumai container:
+
+```bash
+docker compose up -d
+```
+
+---
+
+## Single Compose File Setup (Unraid / Portainer)
+
+If your environment or container manager does not support multi-file `extends`, you can inline the hardware configuration directly into the `shumai` service in `docker-compose.yaml`:
+
+
+
+ ```yaml
+ services:
+ shumai:
+ # ...
+ deploy:
+ resources:
+ reservations:
+ devices:
+ - driver: nvidia
+ count: 1
+ capabilities:
+ - gpu
+ - compute
+ - video
+ ```
+
+
+
+ ```yaml services: shumai: # ... devices: - /dev/dri:/dev/dri ```
+
+
+
+ ```yaml services: shumai: # ... devices: - /dev/dri:/dev/dri - /dev/dxg:/dev/dxg volumes: -
+ /usr/lib/wsl:/usr/lib/wsl environment: - LIBVA_DRIVER_NAME=d3d12 ```
+
+
+
+ ```yaml
+ services:
+ shumai:
+ # ...
+ security_opt:
+ - systempaths=unconfined
+ - apparmor=unconfined
+ group_add:
+ - video
+ devices:
+ - /dev/rga:/dev/rga
+ - /dev/dri:/dev/dri
+ - /dev/dma_heap:/dev/dma_heap
+ - /dev/mpp_service:/dev/mpp_service
+ ```
+
+
+
+---
+
+## Web UI Settings
+
+In the Shumai Web UI, navigate to **Team Settings** > **Transcoding Settings**.
+
+- **Auto (Recommended)**: Shumai automatically probes candidate hardware encoders in optimal order (`h264_nvenc` → `h264_vaapi` → `h264_qsv` → `h264_amf` → `libx264`). If hardware acceleration is unavailable, it gracefully uses software encoding.
+- **Explicit Encoder**: You can pin the transcode pipeline to a specific encoder (e.g. `NVENC`, `Quick Sync`, `VA-API`).
+- **Off**: Forces CPU software encoding (`libx264`) for all video jobs.
+
+---
+
+## Verification & Monitoring
+
+### Check Transcode Logs
+
+When video transcoding begins on an uploaded asset, Shumai writes a structured log indicating the chosen encoder:
+
+```bash
+docker compose logs -f shumai
+```
+
+Look for the `Starting video transcoding` log entry:
+
+```json
+{
+ "level": 30,
+ "time": 1790414665096,
+ "encoder": "h264_nvenc",
+ "hardwareAcceleration": "auto",
+ "inputFile": "/tmp/transcode-.../video.mp4",
+ "outputFile": "/tmp/transcode-.../video-180p.mp4",
+ "msg": "Starting video transcoding"
+}
+```
+
+If hardware acceleration was successfully initialized, `encoder` will show `h264_nvenc`, `h264_vaapi`, or `h264_qsv`.
+
+### Monitor GPU Utilization
+
+While transcoding a video, you can observe hardware utilization on the host:
+
+- **NVIDIA**:
+ ```bash
+ nvidia-smi
+ # or
+ nvtop
+ ```
+- **Intel**:
+ ```bash
+ sudo intel_gpu_top
+ ```
+- **AMD**:
+ ```bash
+ sudo radeontop
+ ```
diff --git a/docs/docs.json b/docs/docs.json
index 927f275e..4cf129e9 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -70,7 +70,7 @@
},
{
"group": "Configuration",
- "pages": ["configuration/env-variables"]
+ "pages": ["configuration/env-variables", "configuration/hardware-transcoding"]
},
{
"group": "Temporal Deployment",
diff --git a/docs/getting-started/quickstart.mdx b/docs/getting-started/quickstart.mdx
index 986f7200..1cbad909 100644
--- a/docs/getting-started/quickstart.mdx
+++ b/docs/getting-started/quickstart.mdx
@@ -12,9 +12,14 @@ We support three installation options. For most administrators, **Docker Compose
Docker Compose automatically configures and spins up all required services (the web application, a database, and local storage).
1. **Download the Configuration**:
+
```bash
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose.yaml
```
+
+ > [!TIP]
+ > **Hardware Acceleration:** By default, the standard Compose stack uses CPU-based software transcoding. If your server has a dedicated or integrated GPU (NVIDIA, Intel, AMD, or Rockchip), see the [Hardware Transcoding Guide](/configuration/hardware-transcoding) to enable GPU acceleration via the companion `hwaccel.transcoding.yaml`.
+
2. **Start the Services**:
```bash
docker compose up -d
diff --git a/docs/using-shumai/transcode-settings.mdx b/docs/using-shumai/transcode-settings.mdx
index 711efb7e..b22a6c07 100644
--- a/docs/using-shumai/transcode-settings.mdx
+++ b/docs/using-shumai/transcode-settings.mdx
@@ -34,3 +34,9 @@ Team Owners can select how the transcoding engine handles uploaded files. Shumai
Transcoding is resource-intensive. Depending on your scaling needs, your administrator can run the transcode engine on the main server (Single-Server mode) or delegate tasks to specialized transcoding worker machines (Temporal Worker mode).
Note: In all modes, the processing machine must have the standard system media utilities (`ffmpeg` and `ffprobe`) installed.
+
+---
+
+## Hardware Acceleration
+
+To offload encoding workloads to GPUs (NVIDIA NVENC, Intel QuickSync, AMD/Intel VA-API, or Rockchip RKMPP), Shumai supports hardware-accelerated transcoding. See the [Hardware Transcoding Guide](/configuration/hardware-transcoding) for Docker Compose configuration, GPU passthrough, and driver prerequisites.
diff --git a/packages/core/src/transcode/transcode.test.ts b/packages/core/src/transcode/transcode.test.ts
index bd3ccf4f..befacf86 100644
--- a/packages/core/src/transcode/transcode.test.ts
+++ b/packages/core/src/transcode/transcode.test.ts
@@ -8,7 +8,10 @@ import {
calculateMaxBitrate,
H264_ENCODER_CONFIGS,
buildSdrToneMapFilterChain,
+ getVaapiDevice,
+ parseBitrateKbps,
} from './transcode'
+import { logger } from '@shumai/core/src/logger'
import { s3Service } from '@shumai/core/src/s3/s3'
import * as path from 'path'
import * as child_process from 'child_process'
@@ -1223,7 +1226,57 @@ describe('TranscodeService', () => {
'h264_amf',
])
expect(getPlatformEncoderCandidates('win32')).toEqual(['h264_nvenc', 'h264_qsv', 'h264_amf'])
- expect(getPlatformEncoderCandidates('linux')).toEqual(['h264_nvenc', 'h264_qsv', 'h264_amf'])
+ expect(getPlatformEncoderCandidates('linux')).toEqual([
+ 'h264_nvenc',
+ 'h264_vaapi',
+ 'h264_qsv',
+ 'h264_amf',
+ ])
+ })
+
+ it('getVaapiDevice should return device from SHUMAI_VAAPI_DEVICE or VAAPI_DEVICE env var', () => {
+ const origShumai = process.env.SHUMAI_VAAPI_DEVICE
+ const origVaapi = process.env.VAAPI_DEVICE
+ try {
+ process.env.SHUMAI_VAAPI_DEVICE = '/dev/dri/custom1'
+ expect(getVaapiDevice()).toBe('/dev/dri/custom1')
+ delete process.env.SHUMAI_VAAPI_DEVICE
+
+ process.env.VAAPI_DEVICE = '/dev/dri/custom2'
+ expect(getVaapiDevice()).toBe('/dev/dri/custom2')
+ } finally {
+ if (origShumai) process.env.SHUMAI_VAAPI_DEVICE = origShumai
+ else delete process.env.SHUMAI_VAAPI_DEVICE
+ if (origVaapi) process.env.VAAPI_DEVICE = origVaapi
+ else delete process.env.VAAPI_DEVICE
+ }
+ })
+
+ it('getVaapiDevice should pick highest index render node from driDir', () => {
+ const fakeDriDir = path.join(tempDir, 'fake-dri')
+ fs.mkdirSync(fakeDriDir, { recursive: true })
+ fs.writeFileSync(path.join(fakeDriDir, 'card0'), '')
+ fs.writeFileSync(path.join(fakeDriDir, 'renderD128'), '')
+ fs.writeFileSync(path.join(fakeDriDir, 'renderD129'), '')
+
+ expect(getVaapiDevice(fakeDriDir)).toBe(path.join(fakeDriDir, 'renderD129'))
+ })
+
+ it('getVaapiDevice should return null if driDir does not exist or has no render/card devices', () => {
+ expect(getVaapiDevice(path.join(tempDir, 'non-existent'))).toBeNull()
+
+ const emptyDir = path.join(tempDir, 'empty-dri')
+ fs.mkdirSync(emptyDir, { recursive: true })
+ expect(getVaapiDevice(emptyDir)).toBeNull()
+ })
+
+ it('parseBitrateKbps should parse number and various string bitrate units', () => {
+ expect(parseBitrateKbps(2_500_000)).toBe(2500)
+ expect(parseBitrateKbps('4500k')).toBe(4500)
+ expect(parseBitrateKbps('4500kbps')).toBe(4500)
+ expect(parseBitrateKbps('12M')).toBe(12000)
+ expect(parseBitrateKbps('1.5Mbps')).toBe(1500)
+ expect(parseBitrateKbps('invalid')).toBe(2500)
})
it('should calculate default bitrates by resolution height and width correctly', () => {
@@ -1385,6 +1438,38 @@ describe('TranscodeService', () => {
expect(encoder.presetArgs).toEqual(['-preset', 'fast', '-global_quality', '26'])
})
+ it('selectH264Encoder should select h264_vaapi before h264_qsv on linux when both are available', async () => {
+ const mockEncodersOutput = `
+ V....D libx264 libx264 H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10
+ V....D h264_qsv Intel Quick Sync Video H.264
+ V....D h264_vaapi H.264/AVC (VAAPI)
+ `
+ vi.spyOn(transcodeService, 'getVaapiDevice').mockReturnValue('/dev/dri/renderD128')
+ vi.mocked(execFile).mockImplementation(
+ (
+ _cmd: unknown,
+ args: unknown,
+ callback: unknown,
+ ): ReturnType => {
+ const cb = callback as (
+ err: Error | null,
+ result: { stdout: string; stderr: string },
+ ) => void
+ const argsArr = args as string[] | undefined
+ if (argsArr && argsArr[0] === '-encoders') {
+ cb(null, { stdout: mockEncodersOutput, stderr: '' })
+ } else if (typeof cb === 'function') {
+ cb(null, { stdout: '', stderr: '' })
+ }
+ return {} as ReturnType
+ },
+ )
+
+ const encoder = await transcodeService.selectH264Encoder('auto', 'linux')
+ expect(encoder.name).toBe('h264_vaapi')
+ expect(encoder.presetArgs).toEqual(['-compression_level', '4'])
+ })
+
it('selectH264Encoder should select h264_amf on win32 when available', async () => {
const mockEncodersOutput = `
V....D libx264 libx264 H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10
@@ -1451,6 +1536,197 @@ describe('TranscodeService', () => {
expect(encoder.presetArgs).toEqual(['-preset', 'fast', '-crf', '23', '-bf', '0'])
})
+ it('selectH264Encoder should select h264_vaapi on linux when available and dri device exists', async () => {
+ const mockEncodersOutput = `
+ V....D libx264 libx264 H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10
+ V....D h264_vaapi H.264/AVC (VAAPI)
+ V....D h264_amf AMD AMF H.264 Encoder
+ `
+ vi.mocked(execFile).mockImplementation(
+ (
+ _cmd: unknown,
+ args: unknown,
+ callback: unknown,
+ ): ReturnType => {
+ const cb = callback as (
+ err: Error | null,
+ result: { stdout: string; stderr: string },
+ ) => void
+ const argsArr = args as string[] | undefined
+ if (argsArr && argsArr[0] === '-encoders') {
+ cb(null, { stdout: mockEncodersOutput, stderr: '' })
+ } else if (typeof cb === 'function') {
+ cb(null, { stdout: '', stderr: '' })
+ }
+ return {} as ReturnType
+ },
+ )
+ vi.spyOn(transcodeService, 'getVaapiDevice').mockReturnValue('/dev/dri/renderD128')
+
+ const encoder = await transcodeService.selectH264Encoder('auto', 'linux')
+ expect(encoder.name).toBe('h264_vaapi')
+ expect(encoder.presetArgs).toEqual(['-compression_level', '4'])
+ })
+
+ it('selectH264Encoder should skip h264_vaapi on linux when vaapi device is not found', async () => {
+ const mockEncodersOutput = `
+ V....D libx264 libx264 H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10
+ V....D h264_vaapi H.264/AVC (VAAPI)
+ V....D h264_amf AMD AMF H.264 Encoder
+ `
+ vi.mocked(execFile).mockImplementation(
+ (
+ _cmd: unknown,
+ args: unknown,
+ callback: unknown,
+ ): ReturnType => {
+ const cb = callback as (
+ err: Error | null,
+ result: { stdout: string; stderr: string },
+ ) => void
+ const argsArr = args as string[] | undefined
+ if (argsArr && argsArr[0] === '-encoders') {
+ cb(null, { stdout: mockEncodersOutput, stderr: '' })
+ } else if (typeof cb === 'function') {
+ cb(null, { stdout: '', stderr: '' })
+ }
+ return {} as ReturnType
+ },
+ )
+ vi.spyOn(transcodeService, 'getVaapiDevice').mockReturnValue(null)
+
+ const encoder = await transcodeService.selectH264Encoder('auto', 'linux')
+ expect(encoder.name).toBe('h264_amf')
+ })
+
+ it('selectH264Encoder should skip h264_nvenc and fallback to libx264 when nvenc fails usability probe', async () => {
+ const mockEncodersOutput = `
+ V....D libx264 libx264 H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10
+ V....D h264_nvenc NVIDIA NVENC H.264 encoder
+ `
+ vi.mocked(execFile).mockImplementation(
+ (
+ _cmd: unknown,
+ args: unknown,
+ callback: unknown,
+ ): ReturnType => {
+ const cb = callback as (
+ err: Error | null,
+ result?: { stdout: string; stderr: string },
+ ) => void
+ const argsArr = args as string[] | undefined
+ if (argsArr && argsArr[0] === '-encoders') {
+ cb(null, { stdout: mockEncodersOutput, stderr: '' })
+ } else if (argsArr && argsArr.includes('h264_nvenc')) {
+ cb(new Error('Cannot load libcuda.so.1'))
+ } else if (typeof cb === 'function') {
+ cb(null, { stdout: '', stderr: '' })
+ }
+ return {} as ReturnType
+ },
+ )
+
+ const encoder = await transcodeService.selectH264Encoder('auto', 'linux')
+ expect(encoder.name).toBe('libx264')
+ })
+
+ it('isEncoderUsable should return true and cache result when probe succeeds', async () => {
+ const execFileMock = vi
+ .mocked(execFile)
+ .mockImplementation(
+ (
+ _cmd: unknown,
+ _args: unknown,
+ callback: unknown,
+ ): ReturnType => {
+ const cb = callback as (
+ err: Error | null,
+ result?: { stdout: string; stderr: string },
+ ) => void
+ if (typeof cb === 'function') {
+ cb(null, { stdout: '', stderr: '' })
+ }
+ return {} as ReturnType
+ },
+ )
+
+ const result1 = await transcodeService.isEncoderUsable('h264_nvenc')
+ expect(result1).toBe(true)
+ expect(execFileMock).toHaveBeenCalledTimes(1)
+
+ // Subsequent call should hit cache and not call execFile again
+ const result2 = await transcodeService.isEncoderUsable('h264_nvenc')
+ expect(result2).toBe(true)
+ expect(execFileMock).toHaveBeenCalledTimes(1)
+ })
+
+ it('isEncoderUsable should return false and cache result when probe fails', async () => {
+ const execFileMock = vi
+ .mocked(execFile)
+ .mockImplementation(
+ (
+ _cmd: unknown,
+ _args: unknown,
+ callback: unknown,
+ ): ReturnType => {
+ const cb = callback as (
+ err: Error | null,
+ result?: { stdout: string; stderr: string },
+ ) => void
+ if (typeof cb === 'function') {
+ cb(new Error('Driver init failed'))
+ }
+ return {} as ReturnType
+ },
+ )
+
+ const result1 = await transcodeService.isEncoderUsable('h264_qsv')
+ expect(result1).toBe(false)
+ expect(execFileMock).toHaveBeenCalledTimes(1)
+
+ // Cached call
+ const result2 = await transcodeService.isEncoderUsable('h264_qsv')
+ expect(result2).toBe(false)
+ expect(execFileMock).toHaveBeenCalledTimes(1)
+ })
+
+ it('isEncoderUsable should return false for h264_vaapi when getVaapiDevice returns null without running ffmpeg', async () => {
+ vi.spyOn(transcodeService, 'getVaapiDevice').mockReturnValue(null)
+ const execFileMock = vi.mocked(execFile)
+
+ const result = await transcodeService.isEncoderUsable('h264_vaapi')
+ expect(result).toBe(false)
+ expect(execFileMock).not.toHaveBeenCalled()
+ })
+
+ it('isEncoderUsable should probe vaapi with hw device options when vaapi device exists', async () => {
+ vi.spyOn(transcodeService, 'getVaapiDevice').mockReturnValue('/dev/dri/renderD128')
+ let probeArgs: string[] = []
+ vi.mocked(execFile).mockImplementation(
+ (
+ _cmd: unknown,
+ args: unknown,
+ callback: unknown,
+ ): ReturnType => {
+ probeArgs = (args as string[]) || []
+ const cb = callback as (
+ err: Error | null,
+ result?: { stdout: string; stderr: string },
+ ) => void
+ if (typeof cb === 'function') {
+ cb(null, { stdout: '', stderr: '' })
+ }
+ return {} as ReturnType
+ },
+ )
+
+ const result = await transcodeService.isEncoderUsable('h264_vaapi')
+ expect(result).toBe(true)
+ expect(probeArgs).toContain('-init_hw_device')
+ expect(probeArgs).toContain('vaapi=accel:/dev/dri/renderD128')
+ expect(probeArgs).toContain('h264_vaapi')
+ })
+
it('transcodeVideo with hardwareAcceleration off should use libx264, preset fast, crf 23, -bf 0, maxrate, and yuv420p', async () => {
vi.mocked(execFile).mockImplementation(
(
@@ -1713,6 +1989,163 @@ describe('TranscodeService', () => {
)
})
+ it('transcodeVideo with hardwareAcceleration auto and vaapi should use init_hw_device, hwupload, rc_mode 3, and omit pix_fmt yuv420p', async () => {
+ vi.spyOn(transcodeService, 'selectH264Encoder').mockResolvedValue(
+ H264_ENCODER_CONFIGS.h264_vaapi,
+ )
+ vi.spyOn(transcodeService, 'getVaapiDevice').mockReturnValue('/dev/dri/renderD128')
+ const loggerSpy = vi.spyOn(logger, 'info')
+
+ vi.mocked(execFile).mockImplementation(
+ (
+ _cmd: unknown,
+ _args: unknown,
+ callback: unknown,
+ ): ReturnType => {
+ const cb = callback as (
+ err: Error | null,
+ result: { stdout: string; stderr: string },
+ ) => void
+ if (typeof cb === 'function') {
+ cb(null, { stdout: '', stderr: '' })
+ }
+ return {} as ReturnType
+ },
+ )
+
+ const outputFile = path.join(tempDir, 'out_vaapi.mp4')
+ await transcodeService.transcodeVideo({
+ inputFile: 'input.mp4',
+ outputFile,
+ width: 1280,
+ height: 720,
+ hardwareAcceleration: 'auto',
+ sourceVideoBitrate: 600_000,
+ })
+
+ expect(child_process.execFile).toHaveBeenCalledWith(
+ 'ffmpeg',
+ expect.arrayContaining([
+ '-init_hw_device',
+ 'vaapi=accel:/dev/dri/renderD128',
+ '-filter_hw_device',
+ 'accel',
+ '-c:v',
+ 'h264_vaapi',
+ '-compression_level',
+ '4',
+ '-rc_mode',
+ '3',
+ '-b:v',
+ '497k',
+ '-maxrate',
+ '720k',
+ '-minrate',
+ '249k',
+ ]),
+ expect.any(Function),
+ )
+
+ const callArgs = vi.mocked(child_process.execFile).mock.calls[0][1] as string[]
+ expect(callArgs).not.toContain('-pix_fmt')
+ expect(callArgs).not.toContain('yuv420p')
+
+ const filterComplexIdx = callArgs.indexOf('-filter_complex')
+ expect(filterComplexIdx).toBeGreaterThan(-1)
+ expect(callArgs[filterComplexIdx + 1]).toContain('format=nv12,hwupload=extra_hw_frames=64')
+
+ expect(loggerSpy).toHaveBeenCalledWith(
+ expect.objectContaining({
+ encoder: 'h264_vaapi',
+ hardwareAcceleration: 'auto',
+ vaapiDevice: '/dev/dri/renderD128',
+ }),
+ 'Starting video transcoding',
+ )
+ })
+
+ it('transcodeVideo with explicit videoBitrate and vaapi calculates VBR distribution correctly', async () => {
+ vi.spyOn(transcodeService, 'selectH264Encoder').mockResolvedValue(
+ H264_ENCODER_CONFIGS.h264_vaapi,
+ )
+ vi.spyOn(transcodeService, 'getVaapiDevice').mockReturnValue('/dev/dri/renderD128')
+
+ vi.mocked(execFile).mockImplementation(
+ (
+ _cmd: unknown,
+ _args: unknown,
+ callback: unknown,
+ ): ReturnType => {
+ const cb = callback as (
+ err: Error | null,
+ result: { stdout: string; stderr: string },
+ ) => void
+ if (typeof cb === 'function') {
+ cb(null, { stdout: '', stderr: '' })
+ }
+ return {} as ReturnType
+ },
+ )
+
+ const outputFile = path.join(tempDir, 'out_vaapi_custom.mp4')
+ await transcodeService.transcodeVideo({
+ inputFile: 'input.mp4',
+ outputFile,
+ width: 1920,
+ height: 1080,
+ hardwareAcceleration: 'auto',
+ videoBitrate: '4500k',
+ })
+
+ const callArgs = vi.mocked(child_process.execFile).mock.calls[0][1] as string[]
+ expect(callArgs).toContain('-rc_mode')
+ expect(callArgs).toContain('3')
+ expect(callArgs).toContain('-b:v')
+ expect(callArgs).toContain('3104k')
+ expect(callArgs).toContain('-maxrate')
+ expect(callArgs).toContain('4500k')
+ expect(callArgs).toContain('-minrate')
+ expect(callArgs).toContain('1552k')
+ })
+
+ it('transcodeVideo should throw immediately when ffmpeg fails during hardware transcoding', async () => {
+ vi.spyOn(transcodeService, 'selectH264Encoder').mockResolvedValue(
+ H264_ENCODER_CONFIGS.h264_vaapi,
+ )
+ vi.spyOn(transcodeService, 'getVaapiDevice').mockReturnValue('/dev/dri/renderD128')
+
+ vi.mocked(execFile).mockImplementation(
+ (
+ _cmd: unknown,
+ _args: unknown,
+ callback: unknown,
+ ): ReturnType => {
+ const cb = callback as (
+ err: Error | null,
+ result: { stdout: string; stderr: string },
+ ) => void
+ if (typeof cb === 'function') {
+ cb(new Error('VAAPI driver error: failed to allocate surface'), {
+ stdout: '',
+ stderr: 'driver error',
+ })
+ }
+ return {} as ReturnType
+ },
+ )
+
+ const outputFile = path.join(tempDir, 'out_vaapi_fail.mp4')
+ await expect(
+ transcodeService.transcodeVideo({
+ inputFile: 'input.mp4',
+ outputFile,
+ width: 1280,
+ height: 720,
+ hardwareAcceleration: 'auto',
+ }),
+ ).rejects.toThrow('VAAPI driver error: failed to allocate surface')
+ })
+
it('transcodeVideo with threads > 0 should pass -threads to ffmpeg', async () => {
vi.mocked(execFile).mockImplementation(
(
diff --git a/packages/core/src/transcode/transcode.ts b/packages/core/src/transcode/transcode.ts
index cd243ae9..10d59156 100644
--- a/packages/core/src/transcode/transcode.ts
+++ b/packages/core/src/transcode/transcode.ts
@@ -13,6 +13,7 @@ import { ulid } from 'ulid'
import { promisify } from 'util'
import { mapConcurrent } from '../utils/async'
import { dataFormatNames } from './dataFormatNames'
+import { logger } from '@shumai/core/src/logger'
const execFileAsync = promisify(execFile)
@@ -157,6 +158,10 @@ export const H264_ENCODER_CONFIGS: Record = {
name: 'h264_qsv',
presetArgs: ['-preset', 'fast', '-global_quality', '26'],
},
+ h264_vaapi: {
+ name: 'h264_vaapi',
+ presetArgs: ['-compression_level', '4'],
+ },
h264_amf: {
name: 'h264_amf',
presetArgs: ['-quality', 'balanced', '-rc', 'qvbr', '-qvbr_quality_level', '26'],
@@ -181,10 +186,53 @@ export function getPlatformEncoderCandidates(
return ['h264_nvenc', 'h264_qsv', 'h264_amf']
case 'linux':
default:
- return ['h264_nvenc', 'h264_qsv', 'h264_amf']
+ return ['h264_nvenc', 'h264_vaapi', 'h264_qsv', 'h264_amf']
}
}
+export function getVaapiDevice(driDir = '/dev/dri'): string | null {
+ const envDevice = process.env.SHUMAI_VAAPI_DEVICE || process.env.VAAPI_DEVICE
+ if (envDevice) {
+ return envDevice
+ }
+
+ try {
+ if (!fs.existsSync(driDir)) {
+ return null
+ }
+ const entries = fs.readdirSync(driDir)
+ const renderNodes = entries
+ .filter((entry) => entry.startsWith('renderD') || entry.startsWith('card'))
+ .sort((a, b) => b.localeCompare(a, undefined, { numeric: true }))
+
+ if (renderNodes.length > 0) {
+ return path.join(driDir, renderNodes[0])
+ }
+ } catch {
+ return null
+ }
+
+ return null
+}
+
+export function parseBitrateKbps(bitrate: string | number): number {
+ if (typeof bitrate === 'number') {
+ return Math.round(bitrate / 1000)
+ }
+ const clean = bitrate.trim().toLowerCase()
+ if (clean.endsWith('m') || clean.endsWith('mbps')) {
+ return Math.round(parseFloat(clean) * 1000)
+ }
+ if (clean.endsWith('k') || clean.endsWith('kbps')) {
+ return Math.round(parseFloat(clean))
+ }
+ const num = parseFloat(clean)
+ if (Number.isFinite(num)) {
+ return num > 100_000 ? Math.round(num / 1000) : Math.round(num)
+ }
+ return 2500
+}
+
export function getDefaultBitrateBps(height: number, width?: number): number {
const longSide = Math.max(width || 0, height)
const shortSide = Math.min(width || height, height)
@@ -666,9 +714,11 @@ export class TranscodeService {
}
private availableEncodersCache: Set | null = null
+ private usableEncodersCache: Map = new Map()
clearEncodersCache(): void {
this.availableEncodersCache = null
+ this.usableEncodersCache.clear()
}
async getAvailableEncoders(): Promise> {
@@ -721,6 +771,78 @@ export class TranscodeService {
}
}
+ getVaapiDevice(driDir = '/dev/dri'): string | null {
+ return getVaapiDevice(driDir)
+ }
+
+ async isEncoderUsable(encoder: string): Promise {
+ const cached = this.usableEncodersCache.get(encoder)
+ if (cached !== undefined) {
+ return cached
+ }
+
+ if (encoder === 'h264_vaapi') {
+ const vaapiDevice = this.getVaapiDevice()
+ if (!vaapiDevice) {
+ this.usableEncodersCache.set(encoder, false)
+ return false
+ }
+ try {
+ await execFileAsync('ffmpeg', [
+ '-loglevel',
+ 'error',
+ '-init_hw_device',
+ `vaapi=accel:${vaapiDevice}`,
+ '-filter_hw_device',
+ 'accel',
+ '-f',
+ 'lavfi',
+ '-i',
+ 'color=c=black:s=256x256:d=0.04',
+ '-vf',
+ 'format=nv12,hwupload',
+ '-frames:v',
+ '1',
+ '-c:v',
+ 'h264_vaapi',
+ '-f',
+ 'null',
+ '-',
+ ])
+ this.usableEncodersCache.set(encoder, true)
+ return true
+ } catch (err) {
+ logger.debug({ encoder, err }, 'Encoder failed usability probe')
+ this.usableEncodersCache.set(encoder, false)
+ return false
+ }
+ }
+
+ try {
+ await execFileAsync('ffmpeg', [
+ '-loglevel',
+ 'error',
+ '-f',
+ 'lavfi',
+ '-i',
+ 'color=c=black:s=256x256:d=0.04',
+ '-frames:v',
+ '1',
+ '-c:v',
+ encoder,
+ '-f',
+ 'null',
+ '-',
+ ])
+ this.usableEncodersCache.set(encoder, true)
+ return true
+ } catch (err) {
+ logger.debug({ encoder, err }, 'Encoder failed usability probe')
+ this.usableEncodersCache.set(encoder, false)
+ return false
+ }
+ }
+
async selectH264Encoder(
hardwareAcceleration?: 'off' | 'auto',
platform: NodeJS.Platform = process.platform,
@@ -733,6 +855,10 @@ export class TranscodeService {
const candidates = getPlatformEncoderCandidates(platform)
for (const enc of candidates) {
if (available.has(enc) && H264_ENCODER_CONFIGS[enc]) {
+ const usable = await this.isEncoderUsable(enc)
+ if (!usable) {
+ continue
+ }
return H264_ENCODER_CONFIGS[enc]
}
}
@@ -748,8 +874,29 @@ export class TranscodeService {
params.sourceHdrType === 'dovi_p5'
const isHdrOutput = Boolean(params.hdr)
+ const encoder = await this.selectH264Encoder(params.hardwareAcceleration)
+ const isVaapi = encoder.name === 'h264_vaapi'
+ const vaapiDevice = isVaapi ? (this.getVaapiDevice() ?? '/dev/dri/renderD128') : undefined
+
+ logger.info(
+ {
+ encoder: encoder.name,
+ hardwareAcceleration: params.hardwareAcceleration ?? 'off',
+ inputFile: params.inputFile,
+ outputFile: params.outputFile,
+ vaapiDevice,
+ },
+ 'Starting video transcoding',
+ )
+
let filterComplex: string
- const args: string[] = ['-i', params.inputFile]
+ const args: string[] = []
+
+ if (isVaapi && vaapiDevice) {
+ args.push('-init_hw_device', `vaapi=accel:${vaapiDevice}`, '-filter_hw_device', 'accel')
+ }
+
+ args.push('-i', params.inputFile)
const baseScale = `scale=w=${params.width}:h=${params.height}:force_original_aspect_ratio=decrease,scale=w='trunc(iw/2)*2':h='trunc(ih/2)*2'`
if (params.overlayFile) {
@@ -762,6 +909,9 @@ export class TranscodeService {
if (params.frameRate) {
filterComplex += `,fps=${params.frameRate}`
}
+ if (isVaapi) {
+ filterComplex += ',format=nv12,hwupload=extra_hw_frames=64'
+ }
filterComplex += '[vout]'
args.push('-filter_complex', filterComplex, '-map', '[vout]')
@@ -795,7 +945,6 @@ export class TranscodeService {
args.push('-map', '0:a?')
}
- const encoder = await this.selectH264Encoder(params.hardwareAcceleration)
args.push('-c:v', encoder.name)
if (encoder.presetArgs.length > 0) {
args.push(...encoder.presetArgs)
@@ -814,6 +963,31 @@ export class TranscodeService {
const targetKbps = Math.max(50, Math.round(targetBps / 1000))
args.push('-b:v', `${targetKbps}k`)
}
+ } else if (isVaapi) {
+ let maxKbps: number
+ if (params.videoBitrate) {
+ maxKbps = parseBitrateKbps(params.videoBitrate)
+ } else {
+ const { maxrate } = calculateMaxBitrate(
+ params.height,
+ params.width,
+ params.sourceVideoBitrate,
+ params.frameRate,
+ )
+ maxKbps = parseInt(maxrate, 10)
+ }
+ const targetKbps = Math.max(25, Math.ceil(maxKbps / 1.45))
+ const minKbps = Math.max(10, Math.round(targetKbps / 2))
+ args.push(
+ '-rc_mode',
+ '3',
+ '-b:v',
+ `${targetKbps}k`,
+ '-maxrate',
+ `${maxKbps}k`,
+ '-minrate',
+ `${minKbps}k`,
+ )
} else {
if (params.videoBitrate) {
args.push('-b:v', params.videoBitrate)
@@ -828,7 +1002,9 @@ export class TranscodeService {
}
}
- args.push('-pix_fmt', 'yuv420p')
+ if (!isVaapi) {
+ args.push('-pix_fmt', 'yuv420p')
+ }
if (isSourceHdr && isHdrOutput) {
const isHlg = params.sourceHdrType === 'hlg' || params.sourceColorTransfer === 'arib-std-b67'
diff --git a/packages/webui/messages/en.json b/packages/webui/messages/en.json
index d5cf6dd9..2af25eb0 100644
--- a/packages/webui/messages/en.json
+++ b/packages/webui/messages/en.json
@@ -260,7 +260,7 @@
"hardware_acceleration_off": "Disabled (Software)",
"hardware_acceleration_off_description": "Uses software libx264 encoder with constant rate factor (CRF).",
"hardware_acceleration_auto": "Auto Detect",
- "hardware_acceleration_auto_description": "Automatically probes and uses GPU/Hardware acceleration (NVENC, QSV, AMF, VideoToolbox). If hardware acceleration is unsupported on the host, video transcoding may fail.",
+ "hardware_acceleration_auto_description": "Automatically probes and uses GPU/Hardware acceleration (NVENC, QSV, VA-API, AMF, VideoToolbox). If hardware acceleration is unsupported on the host, video transcoding may fail.",
"ffmpeg_threads": "FFmpeg Threads",
"ffmpeg_threads_description": "Maximum number of CPU threads used by FFmpeg during transcoding. Set to 0 for Auto.",
"threads_auto": "Auto",
diff --git a/packages/webui/messages/zh.json b/packages/webui/messages/zh.json
index 7dc1dd52..e588713e 100644
--- a/packages/webui/messages/zh.json
+++ b/packages/webui/messages/zh.json
@@ -260,7 +260,7 @@
"hardware_acceleration_off": "已禁用 (软件编码)",
"hardware_acceleration_off_description": "使用 CPU 的 libx264 软件编码器及 CRF 恒定画质模式。",
"hardware_acceleration_auto": "自动检测",
- "hardware_acceleration_auto_description": "自动检测并使用 GPU/硬件加速(NVENC、QSV、AMF、VideoToolbox)。若宿主硬件不支持加速,视频转码可能会失败。",
+ "hardware_acceleration_auto_description": "自动检测并使用 GPU/硬件加速(NVENC、QSV、VA-API、AMF、VideoToolbox)。若宿主硬件不支持加速,视频转码可能会失败。",
"ffmpeg_threads": "FFmpeg 线程数",
"ffmpeg_threads_description": "FFmpeg 转码时使用的最大 CPU 线程数。设置为 0 表示自动。",
"threads_auto": "自动",
diff --git a/scripts/docker-entrypoint.sh b/scripts/docker-entrypoint.sh
index 0d61b1b9..efe586ea 100644
--- a/scripts/docker-entrypoint.sh
+++ b/scripts/docker-entrypoint.sh
@@ -2,6 +2,20 @@
set -e
if [ "$(id -u)" = "0" ]; then
+ # Ensure the bun user has permissions to access mounted GPU and accelerator devices
+ # (/dev/dri/* for VA-API/QSV, /dev/rga, /dev/mpp_service, /dev/dma_heap/* for RKMPP, /dev/dxg for WSL2)
+ for dev in /dev/dri/* /dev/rga /dev/mpp_service /dev/dma_heap/* /dev/dxg; do
+ if [ -e "$dev" ]; then
+ gid=$(stat -c '%g' "$dev" 2>/dev/null || true)
+ if [ -n "$gid" ] && [ "$gid" != "0" ]; then
+ if ! getent group "$gid" >/dev/null 2>&1; then
+ groupadd -g "$gid" "hwaccel_group_$gid" 2>/dev/null || true
+ fi
+ usermod -a -G "$gid" bun 2>/dev/null || true
+ fi
+ fi
+ done
+
# Check if /app/data exists and is not owned by the bun user (UID 1000)
if [ -d "/app/data" ]; then
if [ "$(stat -c '%u' /app/data)" != "1000" ]; then