转码设置

转码设置用于在浏览器无法直接播放本地视频时，由服务端通过 FFmpeg 将视频实时转为 HLS 流。

• 支持在播放器播放失败时自动切换为服务端转码
• 支持按低、中、高三档设置转码质量
• 支持选择硬件加速方式，降低实时转码时的 CPU 压力
• 支持查看、停止和删除转码任务
• 转码后的 HLS 文件会写入workspace/transcoded

何时开启

在线播放会优先使用浏览器直连播放。若遇到视频格式、编码或封装不被当前浏览器支持，表现为无法开始播放、播放报错或只有声音没有画面，可以尝试在通用设置的「转码设置」中开启自动转码播放。

播放器也可以在右上角设置中手动切换为「服务端转码」。切换后，Kaloscope 会启动 FFmpeg，把当前视频实时转为 M3U8 播放列表和 TS 分段，浏览器再通过 HLS 播放这些分段。

相同媒体和转码设置会共用正在运行的任务，并复用已完成的 HLS 文件；中断或异常的转码会在下次播放时重新生成。

基础设置

设置	说明
自动转码播放	浏览器播放失败时，自动从直连播放切换为服务端转码，避免手动重试
转码质量	控制实时转码的画质和资源消耗，质量越高画面越好，但 CPU/GPU 压力越大
硬件加速	选择 FFmpeg 使用的硬件编码方式，默认「无（软件编码）」
VAAPI 设备	VAAPI 和 Linux QSV 使用的渲染设备，留空时默认尝试使用/dev/dri/renderD128

转码质量包含以下档位：

档位	适用场景
低（快速）	优先降低转码压力，适合设备性能有限或临时播放
中（均衡）	默认推荐，兼顾画质和资源消耗
高（最佳）	优先画质，适合性能充足的设备

硬件加速

如果软件编码速度较慢，播放可能需要等待较长时间才能开始，也可能在播放过程中缓冲。此时可以观察workspace/transcoded目录下对应媒体的 HLS 分段生成速度：如果segment_*.ts文件生成明显慢于播放进度，可以尝试开启硬件加速。

Kaloscope 支持选择以下几种硬件加速方式：

类型	常见设备或平台
Intel QSV	Linux 上的 Intel 核显
VAAPI	Linux VAAPI 设备，常见于 Intel / AMD 核显
Nvidia NVENC	Nvidia 显卡
VideoToolBox	macOS 设备

启动硬件转码前，Kaloscope 会检查 FFmpeg、编码器和设备是否可用，并针对当前视频探测硬件解码和滤镜支持。硬件解码或滤镜不兼容时，会在保留硬件编码的同时回退到 CPU 处理；硬件编码器或设备不可用时，任务会直接报错，不会自动改用软件编码。

转码任务

管理员可以在系统监控 → 转码任务查看媒体名称、状态、转码设置、进度、分段数和缓存大小。运行中的任务可以停止，已停止、已完成或异常任务可以删除；删除任务只会移除对应的 HLS 缓存，不会删除原始媒体文件。

VAAPI 示例

以 Docker Compose 部署并使用 VAAPI 为例，首先需要把宿主机的/dev/dri映射到 Kaloscope 容器中：

services:
  kaloscope:
    image: kaloscope/kaloscope:latest
    container_name: kaloscope
    devices:
      - /dev/dri:/dev/dri

然后进入通用设置的「转码设置」：

1. 将「硬件加速」选择为「Video Acceleration API (VAAPI)」
2. 如果设备路径不是默认值，在「VAAPI 设备」中填写实际路径，例如/dev/dri/renderD128
3. 保存后重新尝试播放需要转码的视频

如果不确定容器内的设备路径，可以进入容器检查/dev/dri下的文件。常见路径为/dev/dri/renderD128，也可能因设备和系统环境不同而变化。

兼容性提示

由于开发者测试设备有限，无法保证所有设备类型和驱动组合都能成功启用硬件加速。如果遇到转码失败、播放异常或 FFmpeg 报错，可以先切回「无（软件编码）」确认基础转码是否正常，并将设备型号、部署方式和相关日志反馈给项目。