Skip to content

armgit / peach

Public Imported from GitHub
0

Peach: Local-first video metadata scraper and media manager.

feat(media): Linux 抽帧接入 VAAPI 硬件解码

longmeidaobfde1b84337d
diff --git a/docs/DOCKER.md b/docs/DOCKER.md
index 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.md
index 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.py
index 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 = 4
BACKENDS = ("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 acceleration
if 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, ...]:
pass
if 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.py
index 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):