feat(transcode): add VA-API hardware acceleration support (#430)

* feat(transcode): add VA-API hardware acceleration support

* fix(docker): switch to jellyfin-ffmpeg 8.1.2-5 for VA-API support

* fix(transcode): probe hardware encoder usability to skip uninitialized drivers

* ci(release): add workflow_dispatch trigger with custom tag input

* fix(transcode): use 256x256 frame dimension for encoder usability probe

* feat(docker): add hwaccel transcoding compose presets matching immich

* docs: add hardware transcoding documentation and quickstart references

* feat(transcode): prioritize h264_vaapi before h264_qsv on Linux

* fix(docker): extend device permission loop to rkmpp and wsl accelerator nodes
This commit is contained in:
Yiling-J
2026-09-26 20:55:57 +08:00
committed by GitHub
parent 941bf0fd1b
commit 94ea4c917a
17 changed files with 947 additions and 16 deletions
+7
View File
@@ -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
+3
View File
@@ -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
+16 -7
View File
@@ -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
+3
View File
@@ -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`.
+3 -1
View File
@@ -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`。
@@ -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
+5
View File
@@ -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
@@ -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
+219
View File
@@ -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`:
<AccordionGroup>
<Accordion title="NVIDIA NVENC">
```yaml
services:
shumai:
# ...
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities:
- gpu
- compute
- video
```
</Accordion>
<Accordion title="Intel QuickSync / AMD VA-API">
```yaml services: shumai: # ... devices: - /dev/dri:/dev/dri ```
</Accordion>
<Accordion title="WSL2 (Windows)">
```yaml services: shumai: # ... devices: - /dev/dri:/dev/dri - /dev/dxg:/dev/dxg volumes: -
/usr/lib/wsl:/usr/lib/wsl environment: - LIBVA_DRIVER_NAME=d3d12 ```
</Accordion>
<Accordion title="Rockchip RKMPP">
```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
```
</Accordion>
</AccordionGroup>
---
## 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` &rarr; `h264_vaapi` &rarr; `h264_qsv` &rarr; `h264_amf` &rarr; `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
```
+1 -1
View File
@@ -70,7 +70,7 @@
},
{
"group": "Configuration",
"pages": ["configuration/env-variables"]
"pages": ["configuration/env-variables", "configuration/hardware-transcoding"]
},
{
"group": "Temporal Deployment",
+5
View File
@@ -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
+6
View File
@@ -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.
+434 -1
View File
@@ -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<typeof child_process.execFile> => {
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<typeof child_process.execFile>
},
)
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<typeof child_process.execFile> => {
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<typeof child_process.execFile>
},
)
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<typeof child_process.execFile> => {
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<typeof child_process.execFile>
},
)
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<typeof child_process.execFile> => {
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<typeof child_process.execFile>
},
)
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<typeof child_process.execFile> => {
const cb = callback as (
err: Error | null,
result?: { stdout: string; stderr: string },
) => void
if (typeof cb === 'function') {
cb(null, { stdout: '', stderr: '' })
}
return {} as ReturnType<typeof child_process.execFile>
},
)
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<typeof child_process.execFile> => {
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<typeof child_process.execFile>
},
)
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<typeof child_process.execFile> => {
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<typeof child_process.execFile>
},
)
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<typeof child_process.execFile> => {
const cb = callback as (
err: Error | null,
result: { stdout: string; stderr: string },
) => void
if (typeof cb === 'function') {
cb(null, { stdout: '', stderr: '' })
}
return {} as ReturnType<typeof child_process.execFile>
},
)
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<typeof child_process.execFile> => {
const cb = callback as (
err: Error | null,
result: { stdout: string; stderr: string },
) => void
if (typeof cb === 'function') {
cb(null, { stdout: '', stderr: '' })
}
return {} as ReturnType<typeof child_process.execFile>
},
)
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<typeof child_process.execFile> => {
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<typeof child_process.execFile>
},
)
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(
(
+180 -4
View File
@@ -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<string, EncoderConfig> = {
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<string> | null = null
private usableEncodersCache: Map<string, boolean> = new Map()
clearEncodersCache(): void {
this.availableEncodersCache = null
this.usableEncodersCache.clear()
}
async getAvailableEncoders(): Promise<Set<string>> {
@@ -721,6 +771,78 @@ export class TranscodeService {
}
}
getVaapiDevice(driDir = '/dev/dri'): string | null {
return getVaapiDevice(driDir)
}
async isEncoderUsable(encoder: string): Promise<boolean> {
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'
+1 -1
View File
@@ -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",
+1 -1
View File
@@ -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": "自动",
+14
View File
@@ -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