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