Peach: Local-first video metadata scraper and media manager.
feat(media): Linux 抽帧接入 VAAPI 硬件解码
longmeidaobfde1b84337d
diff --git a/docs/DOCKER.md b/docs/DOCKER.mdindex 7e0d75c0b..a757a7d0d 100644--- a/docs/DOCKER.md+++ b/docs/DOCKER.md@@ -101,6 +101,8 @@ local = '/media'Linux 首次重编码时会探测实际可用的硬件编码器,整片 MP4 与 HLS 分片共享探测结果。AMD / Intel 使用 VAAPI;存在 NVIDIA 设备时探测 NVENC。探测失败的后端在当前服务进程内不再尝试,重启服务后重新探测。封装复制不需要硬件探测。+封面、九宫格与时间轴抽帧也使用同一渲染节点做 VAAPI 解码,范围限 H.264、HEVC、VP9、AV1;节点建不出 VAAPI 设备、编码不在范围内或本帧解码失败时改用软件解码。「抽帧解码方式」选软件时不探测。+镜像自带 OpenCV(`vision` 依赖组)和头像取景与比对用的人脸模型(YuNet 为 MIT,SFace 为 Apache-2.0,许可证在同一目录),位于 `/app/tools/face-models`,由 `PEACH_FACE_MODELS` 指向,容器不联网也能用。构建镜像时按固定地址下载并校验 SHA-256。镜像包含 Debian FFmpeg、Mesa VAAPI 驱动与 `vainfo`。AMD 宿主机需加载 `amdgpu` 和对应固件,并提供 `/dev/dri/renderD*`。Intel 需在自定义镜像内安装适配设备的 VAAPI 驱动;Mesa 驱动不代表已覆盖全部 Intel GPU。将下面的条目合入 Compose 的 `services.peach`,设备路径按宿主机调整:diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.mdindex e79dcc77b..46e26d618 100644--- a/docs/OPERATIONS.md+++ b/docs/OPERATIONS.md@@ -523,7 +523,7 @@ untrunc 按相同顺序查找,对应目录为 `tools/untrunc`。独立程序- 同时最多进行 2 个转码或探测,单次最长 1 小时,关掉播放页会取消对应的任务。- 115 和 PikPak 的视频通过媒体库配置中声明的挂载目录播放。能不能播,以在 Peach 里实际打开一个已知视频为准。-Peach 配置「媒体库与入库 → 视频预览」中的「抽帧解码方式」与「应用与维护 → 视频播放」中的「转码方式」分别保存为运行 Peach 那台电脑的偏好,两者互不影响,均可选择「自动(硬件优先)」或软件。抽帧设置控制封面、九宫格与时间轴;扫描、读 NFO 和时长探测不依赖 GPU。播放设置只控制 Peach 服务端的整片与 HLS 转码,浏览器直接播放时自行选择解码方式。保存无需重启,对新任务生效;已生成的有效缓存继续使用,运行中的 FFmpeg 不被强行中断。macOS 抽帧在同一超时预算内尝试 VideoToolbox,Windows 抽帧对 H.264、HEVC、VP9、AV1 尝试 D3D11VA,失败后都回退软件;视频编码格式探测按文件大小和修改时间缓存。Windows 播放的自动档依次探测 NVENC、AMF、QSV 编码,三者都不可用时用 D3D11VA 解码再交给 libx264;AMF 只接受 AMD 显卡上的 D3D11 设备,Peach 按显卡序号逐个探测。偏好通过 `/api/media-processing` 的 GET/POST 读写,`preview_acceleration` 和 `playback_acceleration` 分别接受 `auto/software`;省略的字段保持现值。这个接口与时间轴缩略图的 `/api/thumbnail-jobs` 和 `/api/configuration/*` 一样只接受运行 Peach 的电脑发来的请求,其他设备即使已登录或处于开放访问也返回 403。`PEACH_TRANSCODE_BACKEND` 可用于管理员诊断,支持 `auto/software/nvenc/amf/qsv/vaapi/videotoolbox`,显式 `software` 会保持禁用硬件。+Peach 配置「媒体库与入库 → 视频预览」中的「抽帧解码方式」与「应用与维护 → 视频播放」中的「转码方式」分别保存为运行 Peach 那台电脑的偏好,两者互不影响,均可选择「自动(硬件优先)」或软件。抽帧设置控制封面、九宫格与时间轴;扫描、读 NFO 和时长探测不依赖 GPU。播放设置只控制 Peach 服务端的整片与 HLS 转码,浏览器直接播放时自行选择解码方式。保存无需重启,对新任务生效;已生成的有效缓存继续使用,运行中的 FFmpeg 不被强行中断。macOS 抽帧在同一超时预算内尝试 VideoToolbox,Windows 抽帧对 H.264、HEVC、VP9、AV1 尝试 D3D11VA,Linux 对同一范围尝试第一个可用 VAAPI 渲染节点,失败后都回退软件;视频编码格式探测按文件大小和修改时间缓存。Windows 播放的自动档依次探测 NVENC、AMF、QSV 编码,三者都不可用时用 D3D11VA 解码再交给 libx264;AMF 只接受 AMD 显卡上的 D3D11 设备,Peach 按显卡序号逐个探测。偏好通过 `/api/media-processing` 的 GET/POST 读写,`preview_acceleration` 和 `playback_acceleration` 分别接受 `auto/software`;省略的字段保持现值。这个接口与时间轴缩略图的 `/api/thumbnail-jobs` 和 `/api/configuration/*` 一样只接受运行 Peach 的电脑发来的请求,其他设备即使已登录或处于开放访问也返回 403。`PEACH_TRANSCODE_BACKEND` 可用于管理员诊断,支持 `auto/software/nvenc/amf/qsv/vaapi/videotoolbox`,显式 `software` 会保持禁用硬件。卡片悬停预览请求的 `/stream` 不带流会话,取消不了,也看不到浏览器断开。片源需要整片转码且没有现成缓存时,这条请求直接回 415,不启动 FFmpeg;详情与沉浸模式带会话播放,关闭时按会话结束转码。diff --git a/src/peach/hardware_transcode.py b/src/peach/hardware_transcode.pyindex 706f228c8..4f5d50c03 100644--- a/src/peach/hardware_transcode.py+++ b/src/peach/hardware_transcode.py@@ -15,6 +15,8 @@ CUDA_DECODE_CODECS = frozenset({"h264", "hevc", "vp9", "av1"})VIDEOTOOLBOX_DECODE_CODECS = frozenset({"h264", "hevc", "av1", "prores"})#: D3D11VA 与 CUDA 同一份名单:名单外的编码(如 vc1)硬解出错时 FFmpeg 不报错,绿帧直接进缓存。D3D11_DECODE_CODECS = CUDA_DECODE_CODECS+#: Linux 抽帧的 VAAPI 解码沿用同一份名单,理由同上。+VAAPI_DECODE_CODECS = CUDA_DECODE_CODECS#: AMF 只认 AMD 显卡上的 D3D11 设备,混合显卡机器上默认序号常是别家,按序号逐个试。D3D11_ADAPTER_PROBES = 4BACKENDS = ("auto", "software", "nvenc", "amf", "qsv", "vaapi", "videotoolbox")@@ -39,6 +41,18 @@ def d3d11va_decode_options(codec: str, device: str = "") -> tuple[str, ...]:return ("-hwaccel", "d3d11va", *(("-hwaccel_device", device) if device else ()))+def vaapi_devices(configured: str = "") -> list[str]:+ """`PEACH_VAAPI_DEVICE` 指定了就只用它,否则按序号列出本机的 DRM 渲染节点。"""+ return [configured] if configured else sorted(p.as_posix() for p in Path("/dev/dri").glob("renderD*"))+++def vaapi_decode_options(codec: str, device: str) -> tuple[str, ...]:+ """Linux 显卡解码。同 D3D11VA,不指定输出格式,解出的帧回到内存交给缩放与 JPEG 编码。"""+ if codec not in VAAPI_DECODE_CODECS:+ return ()+ return ("-hwaccel", "vaapi", "-hwaccel_device", device)++def _run_probe(ffmpeg: Path, label: str, arguments: tuple[str, ...]) -> bool:"""跑一条只吃合成画面、输出丢弃的探测命令;失败记一条警告。"""command = (str(ffmpeg), "-hide_banner", "-loglevel", "error", "-nostdin", *arguments,@@ -64,6 +78,15 @@ def _d3d11va_ready(ffmpeg: str) -> bool:return _run_probe(Path(ffmpeg), "d3d11va", ("-init_hw_device", "d3d11va", *_SYNTHETIC_FRAME))+@lru_cache(maxsize=8)+def _vaapi_device(ffmpeg: str, configured: str) -> str:+ """第一个这份 FFmpeg 建得出 VAAPI 设备的渲染节点;容器没映射 `/dev/dri` 时为空。"""+ for device in vaapi_devices(configured):+ if _run_probe(Path(ffmpeg), f"vaapi {device}", ("-init_hw_device", f"vaapi=va:{device}", *_SYNTHETIC_FRAME)):+ return device+ return ""++@lru_cache(maxsize=128)def _frame_codec(ffprobe: str, source: str, size: int, modified: int) -> str:from .media_probe import probe_file@@ -76,15 +99,19 @@ def _frame_codec(ffprobe: str, source: str, size: int, modified: int) -> str:def frame_decode_options(ffmpeg: str, source: str) -> tuple[str, ...]:"""本机抽帧按文件世代复用编码探测,解码初始化失败由调用方回退。- Windows 只给名单内的编码开 D3D11VA,编码探测不到就软件解码。+ Windows 与 Linux 只给名单内的编码开 D3D11VA/VAAPI,编码探测不到就软件解码。"""- if sys.platform not in ("darwin", "win32") or not Path(ffmpeg).is_file():+ linux = sys.platform.startswith("linux")+ if not (linux or sys.platform in ("darwin", "win32")) or not Path(ffmpeg).is_file():return ()from .media_processing_policy import accelerationif acceleration(purpose="preview") == "software" or os.environ.get("PEACH_TRANSCODE_BACKEND") == "software":return ()if sys.platform == "win32" and not _d3d11va_ready(ffmpeg):return ()+ device = _vaapi_device(ffmpeg, os.environ.get("PEACH_VAAPI_DEVICE", "").strip()) if linux else ""+ if linux and not device:+ return ()codec = ""ffprobe = Path(ffmpeg).with_name("ffprobe" + Path(ffmpeg).suffix)try:@@ -96,6 +123,8 @@ def frame_decode_options(ffmpeg: str, source: str) -> tuple[str, ...]:passif sys.platform == "win32":return d3d11va_decode_options(codec)+ if linux:+ return vaapi_decode_options(codec, device)return videotoolbox_decode_options(codec)@@ -187,8 +216,7 @@ class HardwareTranscoder:if windows:candidates.append(HardwareEncoder("d3d11va"))if self.backend == "vaapi" or (self.backend == "auto" and sys.platform.startswith("linux")):- devices = [self.device] if self.device else sorted(p.as_posix() for p in Path("/dev/dri").glob("renderD*"))- candidates.extend(HardwareEncoder("vaapi", device) for device in devices)+ candidates.extend(HardwareEncoder("vaapi", device) for device in vaapi_devices(self.device))return tuple(candidates)def active(self) -> bool:diff --git a/tests/test_hardware_transcode.py b/tests/test_hardware_transcode.pyindex 82c1d492e..3513d7137 100644--- a/tests/test_hardware_transcode.py+++ b/tests/test_hardware_transcode.py@@ -116,6 +116,43 @@ class HardwareDetectionTests(unittest.TestCase):self.assertTrue(hardware.encoders(Path("ffmpeg")))self.assertEqual(run.call_count, 1)+ def test_linux_frame_capture_uses_the_first_vaapi_node_that_initializes(self):+ from peach import hardware_transcode+ probes = []++ def probe(_ffmpeg, _label, arguments):+ probes.append(arguments)+ return arguments[1] == "vaapi=va:/dev/dri/renderD129"++ hardware_transcode._vaapi_device.cache_clear()+ self.addCleanup(hardware_transcode._vaapi_device.cache_clear)+ with tempfile.TemporaryDirectory() as directory:+ ffmpeg = Path(directory) / "ffmpeg"+ ffmpeg.write_bytes(b"")+ ffmpeg.with_name("ffprobe").write_bytes(b"")+ source = Path(directory) / "clip.mkv"+ source.write_bytes(b"fixture")+ with patch("peach.hardware_transcode.sys.platform", "linux"), patch.object(Path, "glob", return_value=[Path("/dev/dri/renderD128"), Path("/dev/dri/renderD129")]), patch.object(hardware_transcode, "_run_probe", side_effect=probe), patch("peach.media_processing_policy.acceleration", return_value="auto"):+ for codec, expected in (("hevc", ("-hwaccel", "vaapi", "-hwaccel_device", "/dev/dri/renderD129")),+ ("vc1", ())):+ with self.subTest(codec=codec), patch.object(hardware_transcode, "_frame_codec", return_value=codec):+ self.assertEqual(hardware_transcode.frame_decode_options(str(ffmpeg), str(source)), expected)+ self.assertEqual([arguments[:2] for arguments in probes],+ [("-init_hw_device", "vaapi=va:/dev/dri/renderD128"), ("-init_hw_device", "vaapi=va:/dev/dri/renderD129")],+ "渲染节点探测按 FFmpeg 缓存,第二部片不再探测")+ self.assertNotIn("-hwaccel_output_format", expected)++ def test_linux_frame_capture_without_render_nodes_stays_software_without_probing(self):+ from peach import hardware_transcode+ hardware_transcode._vaapi_device.cache_clear()+ self.addCleanup(hardware_transcode._vaapi_device.cache_clear)+ with tempfile.TemporaryDirectory() as directory:+ ffmpeg = Path(directory) / "ffmpeg"+ ffmpeg.write_bytes(b"")+ with patch("peach.hardware_transcode.sys.platform", "linux"), patch.object(Path, "glob", return_value=[]), patch.object(hardware_transcode, "_run_probe") as probe, patch("peach.media_processing_policy.acceleration", return_value="auto"):+ self.assertEqual(hardware_transcode.frame_decode_options(str(ffmpeg), str(ffmpeg)), ())+ probe.assert_not_called()+class WindowsBackendTests(unittest.TestCase):def setUp(self):