转码设置

遇到浏览器播不了的视频编码或封装时，可以通过转码设置让服务端用 FFmpeg 把本地视频实时转成 HLS 流再播；生成的分片文件会写入 workspace/transcoded。

何时开启

在线播放默认优先走浏览器直连。如果遇到格式或编码不被当前浏览器支持——比如点开报错、一直黑屏转圈，或者只有声音没有画面，可以去通用设置的「转码设置」里打开「自动转码播放」，以后播不动时就会自动切过去。

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

同一份媒体搭配相同的转码参数时，会共用正在跑的转码任务并复用已生成的 HLS 文件；要是中途中断或出错了，下次播放时会重新生成。

基础设置

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

转码质量分为三档：

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

硬件加速

如果纯靠软件编码太慢，点开视频可能要等很久才能起播，甚至看一会儿就卡顿缓冲。这时可以看看 workspace/transcoded 下对应媒体的目录：如果 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 报错时，可以先切回「无（软件编码）」确认基础转码是否正常，再附上设备型号、部署方式和相关日志向项目反馈。