飞牛 NAS 视频自动转码工具

[](https://github.com/yang1245789/fpk-converter#%E9%A3%9E%E7%89%9B-nas-%E8%A7%86%E9%A2%91%E8%87%AA%E5%8A%A8%E8%BD%AC%E7%A0%81%E5%B7%A5%E5%85%B7)

面向飞牛 fnOS 的本地自用视频转码应用。它会定时扫描授权目录，把符合条件的视频串行转码为 H.264/H.265，并支持 Intel Quick Sync Video（QSV）硬件编码。

当前可用版本：v1.0.51。该版本已在实际环境中稳定运行：成功调用 GPU/QSV 转码、启动前功能自检通过、源片色彩参数自动保留、队列按入队时间共用 300 秒稳定等待、应用升级后旧版残留进程会被自动清理。

下载与安装

[](https://github.com/yang1245789/fpk-converter#%E4%B8%8B%E8%BD%BD%E4%B8%8E%E5%AE%89%E8%A3%85)

从 Releases 下载最新版 fpkconverter.fpk，在飞牛 NAS 应用中心手动安装。

安装后请进入：

应用 → 视频转码 → 应用设置 → 授权目录

给需要监控的视频目录授予读写权限，例如：

/vol3/1000/**

本应用使用飞牛官方手册中的 Root 权限模式运行，目的是让 ffmpeg 能访问 /dev/dri/renderD* GPU 设备。请只在信任安装包来源、明确需要本地硬件转码时使用。

GPU 转码说明

[](https://github.com/yang1245789/fpk-converter#gpu-%E8%BD%AC%E7%A0%81%E8%AF%B4%E6%98%8E)

勾选 GPU 加速后，应用会强制使用 Intel QSV：

• H.264 目标编码使用 h264_qsv
• H.265 目标编码使用 hevc_qsv
• QSV 失败时停止当前文件，不自动降级 CPU
• 启动前会用极短测试视频先验证 QSV 是否可用

应用会优先复用飞牛 mediasrv 的运行环境：

ffmpeg=/usr/trim/lib/mediasrv/ffmpeg
LIBVA_DRIVER_NAME=iHD
LIBVA_DRIVERS_PATH=/usr/trim/lib/mediasrv/dri
qsv_device=/dev/dri/renderD*

如果系统存在多个 renderD* 设备，应用会按顺序尝试。

CPU 参与是正常的

[](https://github.com/yang1245789/fpk-converter#cpu-%E5%8F%82%E4%B8%8E%E6%98%AF%E6%AD%A3%E5%B8%B8%E7%9A%84)

即使 GPU 转码已经正常工作，CPU 仍会参与一部分流程，这不是异常：

• 读取源文件和磁盘 IO
• 解复用容器，例如 MP4/MKV
• 音频流 copy 或封装
• 把视频帧送入 QSV 编码器
• MP4 faststart 处理
• 进度解析、日志、数据库记录和 Web UI 状态更新

启动前自检

[](https://github.com/yang1245789/fpk-converter#%E5%90%AF%E5%8A%A8%E5%89%8D%E8%87%AA%E6%A3%80)

点击启动后，应用不会立刻扫描目录，而是先检查：

• 监控目录是否可读
• 临时目录是否可写
• ffmpeg 是否可运行
• ffprobe 是否可运行
• 勾选 GPU 时，QSV 是否能完成 1 秒测试编码

只有自检通过，才会进入正式扫描和转码流程。

源片色彩参数保留

[](https://github.com/yang1245789/fpk-converter#%E6%BA%90%E7%89%87%E8%89%B2%E5%BD%A9%E5%8F%82%E6%95%B0%E4%BF%9D%E7%95%99)

v1.0.48 起，转码命令会先用 ffprobe 读取源文件的色彩元数据，并在 ffmpeg 输出端原样附带：

• -color_primaries（色域，如 BT.709 / BT.2020）
• -color_trc（传输特性，如 SMPTE2084 / ARIB-STD-B67）
• -colorspace（色彩矩阵）
• -color_range（tv / pc 范围）
• -pix_fmt（如 yuv420p / p010le）

源片有什么色彩参数就写什么，不会臆造缺失值。SDR 源在播放器上不再出现"发灰"现象。

队列与进程治理

[](https://github.com/yang1245789/fpk-converter#%E9%98%9F%E5%88%97%E4%B8%8E%E8%BF%9B%E7%A8%8B%E6%B2%BB%E7%90%86)

v1.0.49：队列引入了"等待中 / 处理中"的活动集合，同一文件在 300 秒稳定等待期内不会被重复入队，避免日志里反复刷新等待时间。

v1.0.50：每次点击启动时，应用会先扫描并终止上一版本残留的 start_converter.py 进程，再启动当前版本，避免新旧版本混跑导致疑似 bug 的现象。同时启动日志会打印当前转码核心版本号，便于现场判断装的是不是最新版。

v1.0.51：修复串行队列等待语义。300 秒稳定等待从文件入队时间开始计算，而不是从 worker 取出文件时重新计算。多个文件同时入队时，后续文件如果已经在队列中等满 300 秒，轮到它时会直接开始转码。

功能特性

[](https://github.com/yang1245789/fpk-converter#%E5%8A%9F%E8%83%BD%E7%89%B9%E6%80%A7)

• 定时扫描授权目录，不使用 inotify
• 串行转码，一次只处理一个文件
• 文件加入队列后按入队时间等待 300 秒，避免文件尚未写完就开始转码
• 队列活动集合去重，等待期内不重复入队
• 当前文件进度条
• 失败文件受控重试，避免坏文件无限循环
• converter.log 自动轮转，旧日志压缩
• ffmpeg_*.log / ffprobe_*.log 自动清理
• SQLite 记录已处理文件，避免重复转码
• 转码后更小时才替换原文件
• 同路径替换前先备份，失败时保留原文件
• 启动时清理旧版本遗留进程
• 启动日志打印当前转码核心版本

配置说明

[](https://github.com/yang1245789/fpk-converter#%E9%85%8D%E7%BD%AE%E8%AF%B4%E6%98%8E)

优点

[](https://github.com/yang1245789/fpk-converter#%E4%BC%98%E7%82%B9)

• 专为飞牛 fnOS 适配：直接复用 mediasrv 的 ffmpeg、VAAPI 驱动和 QSV 环境，不需要用户自己装驱动或编译 ffmpeg。
• GPU/QSV 真的能用：经过 v46 → v50 的迭代，已在装有 Intel 核显的飞牛设备上稳定调用 hevc_qsv / h264_qsv。
• 启动即可知道行不行：启动前自检会先跑 1 秒 QSV 测试编码，环境有问题立刻报错，而不是悄悄退回 CPU 或卡住。
• 色彩参数不丢失：SDR 源转码后不"发灰"，色域和传输特性原样保留。
• 日志和文件治理完整：日志自动轮转，临时 ffmpeg 日志自动清理，转码后只在更小才替换原文件，并先备份。
• 升级无残留：启动时会清理旧版本遗留的转码进程，装新版后看到的就是新版的行为。
• 完全本地、自用、可审计：纯 Python + Flask，源码在 GitHub 上，不依赖任何外部服务，不上传任何数据。

缺点

[](https://github.com/yang1245789/fpk-converter#%E7%BC%BA%E7%82%B9)

• 必须以 Root 模式运行：为了访问 /dev/dri/renderD*，包内 run-as 设置为 root。安全性收益的代价是权限边界变宽，不适合发布到第三方应用中心审核。
• GPU 模式下 UI 上的 preset 和 crf 行为与 CPU 模式不一致：QSV 不支持 slow/medium/fast 这一组 x264/x265 预设，应用内固定为 -preset medium；UI 上的 CRF 在 GPU 模式下被映射为 -global_quality，画质曲线与 CPU x265 的 CRF 并不完全等价。
• HDR 10bit 源不能保证完整保留：当前色彩参数会原样写出，但 hevc_qsv 在不同硬件上对 BT.2020/SMPTE2084/p010le 的支持不一致，HDR → HDR 转码并未做端到端验证，建议 HDR 源暂时跳过本工具或单独处理。
• 不支持 inotify 实时触发：依赖周期扫描，新文件最长要等一个扫描周期 + 300 秒稳定等待才会进入处理。
• 串行处理，不并发：一次只转一个文件，处理大量短视频时整体吞吐受限。
• 替换原文件存在风险：虽然有"更小才替换 + 先备份"保护，但仍是写入用户原始目录，唯一重要的母带请勿放在监控目录里。
• 诊断仍偏日志驱动：环境异常主要靠读 converter.log 排查，没有图形化的诊断面板。

改进方向

[](https://github.com/yang1245789/fpk-converter#%E6%94%B9%E8%BF%9B%E6%96%B9%E5%90%91)

• 更细的 GPU 编码参数控制：暴露 look_ahead、b_strategy、-qmax/-qmin、global_quality 滑杆，让用户在画质和码率之间精细调节。
• HDR / 10bit 完整链路：识别 BT.2020 / SMPTE2084 源时自动启用 -pix_fmt p010le 并做 tonemap 选项，提供"保持 HDR"或"安全转 SDR BT.709"两种模式。
• AV1 / VP9 编码器支持：在带 Arc 或 12 代以上 Xeon/Core 核显的飞牛设备上启用 av1_qsv。
• 可选并发：在配置里允许 1-N 并发，让多核多盘的设备能跑满 GPU。
• inotify 触发 + 周期扫描双轨：新文件落盘即排队，不再等扫描周期。
• Web UI 诊断页：把 ffmpeg -hwaccels、vainfo、renderD* 权限、QSV 探测结果直接渲染到一个诊断页，告别翻日志。
• 可选不替换原文件模式：将转码结果输出到独立目录，源文件只读不动，适合不信任替换流程的用户。
• 更友好的失败处理：失败重试次数、失败黑名单、失败原因分类（编码失败 / 文件损坏 / 空间不足）在 UI 上区分展示。
• 多用户 / 非 Root 路线：调研飞牛官方有没有"应用用户加入 video/render 组"的标准做法，争取去掉 root 依赖。

不足

[](https://github.com/yang1245789/fpk-converter#%E4%B8%8D%E8%B6%B3)

• 当前 GPU 模式下，UI 上的 编码预设 选项实际不生效，应用内硬编码为 -preset medium，未在界面上明确禁用或灰显。
• CRF 在 CPU 与 GPU 两种模式下走两条不同参数路径（-crf vs -global_quality），用户教育成本偏高。
• HDR 源未做端到端测试，目前以"原样透传色彩参数"为主，遇到部分 HDR 源仍可能出现颜色异常，需要用户自行甄别。
• 没有 ffprobe 失败时的回退策略——如果 ffprobe 读不到色彩元数据，会按"什么都不写"处理，部分播放器可能仍会因元数据空缺而判错色域。
• 错误信息直接展示 ffmpeg 原始 stderr，对非技术用户不够友好。
• 缺少自动化的 GPU/CPU 占用统计，"GPU 真的在干活吗"目前仍要靠 intel_gpu_top 这种外部工具确认。
• 没有英文 README，国际化暂不在视野内。

运行日志

[](https://github.com/yang1245789/fpk-converter#%E8%BF%90%E8%A1%8C%E6%97%A5%E5%BF%97)

页面会显示最近转码输出。正常 GPU 启动时应能看到类似日志：

视频转码核心版本: 1.0.51
已清理遗留旧转码进程: [12345, 12346]
=== 启动前功能自检 ===
ffmpeg 自检通过
ffprobe 自检通过
GPU/QSV 自检通过: /dev/dri/renderD128
启动前功能自检通过，进入正式扫描流程
QSV 尝试 1/1: 使用设备 /dev/dri/renderD128
保留源片色彩参数: {'color_primaries': 'bt709', 'color_trc': 'bt709', 'colorspace': 'bt709', 'color_range': 'tv', 'pix_fmt': 'yuv420p'}
转码进度: 42.5% | 当前文件: ...

如果出现 No VA display found、Failed to create a VAAPI device 或 无权读写 /dev/dri/renderD128，请确认安装的是 v1.0.46 或更新版本，并重新启动应用。

自行打包

[](https://github.com/yang1245789/fpk-converter#%E8%87%AA%E8%A1%8C%E6%89%93%E5%8C%85)

git clone https://github.com/yang1245789/fpk-converter.git
cd fpk-converter
FN_PACK=/path/to/fnpack bash scripts/build_fpk.sh

构建产物：

fpkconverter.fpk

版本历史

[](https://github.com/yang1245789/fpk-converter#%E7%89%88%E6%9C%AC%E5%8E%86%E5%8F%B2)

注意事项

[](https://github.com/yang1245789/fpk-converter#%E6%B3%A8%E6%84%8F%E4%BA%8B%E9%A1%B9)

1. 首次使用必须在 fnOS 应用设置中授权监控目录。
2. GPU 模式仍会看到 CPU 参与，这是正常现象。
3. 应用会替换原文件，请先确认目录内没有唯一重要数据。
4. Root 硬件转码版适合手动安装自用，不适合发布到第三方应用中心审核场景。
5. HDR 10bit 源在当前版本下不保证颜色完全一致，建议先在小样本上验证。
6. 如需停止转码，请使用页面上的"停止"按钮。

开源协议

[](https://github.com/yang1245789/fpk-converter#%E5%BC%80%E6%BA%90%E5%8D%8F%E8%AE%AE)

MIT License 附件：fpkconverter (1).zip