Video previews in Image History stop working after ffmpeg 9.0 upgrade (-vsync removed)

快速结论：该报错发生在 SwarmUI 将 ffmpeg 升级到 9.0 之后，视频缩略图无法生成 WebP 动图预览，且 Image History 面板会渲染出空白/损坏图片。优先排查 SwarmUI 的 ffmpeg 预览命令中是否仍在使用已被 9.0 移除的 -vsync 0 参数，以及缓存中是否残留了错误类型的预览数据。

适用环境：SwarmUI，系统升级到 ffmpeg 9.0+（如 Arch Linux 从 8.1.2 升级到 9.0-5）。未在 Issue 中确认操作系统、Python、CUDA、显卡等其他环境信息。

最快修复方案：暂无确认的一步修复方案。社区维护者已提交补丁修复，但该 Issue 中没有提供已经过官方验证的、可直接用命令行一键完成修复的方法。你可以等待 SwarmUI 上游版本更新，或手动应用 Issue 中附带的补丁文件。

注意事项：即使修复了 ffmpeg 参数问题，已损坏的预览缓存不会自动恢复，还需要在 Utilities 选项卡中执行 Reset All Metadata，或等待 24 小时预览缓存过期。修复补丁为社区贡献，尚未经官方长期验证，在执行前请先备份数据或代码。

问题场景

在 SwarmUI 中通过任意 text2video 模型（例如 minimax-h3 后端）生成 .mp4 视频后，Image History 面板中的视频缩略图显示为空白或损坏图片。在桌面端和移动端都会出现，而静态图片缩略图不受影响。触发条件为系统完成 ffmpeg 9.0 升级，SwarmUI 版本未改动。

报错原文

Video previews in Image History stop working after ffmpeg 9.0 upgrade (-vsync removed)

The browser receives a response with Content-Type: image/jpg whose body is actually the raw video bytes (an MP4 container), which an <img> cannot render.

原因分析

根本原因是 ffmpeg 在 5.1 版本弃用了 -vsync 参数，并在 9.0 版本中彻底移除。SwarmUI 的 DoFfmpegPreviewGeneration 方法（位于 src/Accounts/UserImageHistoryHelper.cs）仍在生成 WebP 动图预览时传递 -vsync 0，导致命令以非零状态退出，无法创建 .swarmpreview.webp 文件。而生成静态 JPG 预览的命令不使用 -vsync，因此仍然成功。

第二个问题是缓存回退机制存在缺陷：当视频只有 JPG 预览而没有 WebP 时，GetOrCreatePreviewFor 方法（位于 src/Utils/OutputMetadataTracker.cs）会用视频的扩展名（mp4）去调用 ToMetadataJpg()，但该方法对视频媒体类型返回 null，导致缓存条目存储了 null 数据，最终 ViewOutput 将原始 MP4 字节以 image/jpg 形式返回给前端，浏览器无法渲染。

环境排查

确认 ffmpeg 版本是否为 9.0 或更高（例如 Arch Linux 通过 pacman 升级到 2:9.0-5）。
在 SwarmUI 中确认 Server → UI → Allow Animated Previews 是否已启用。
检查视频生成目录下是否只有 .swarmpreview.jpg 而没有 .swarmpreview.webp 文件。
确认系统上的 ffmpeg 8.1.2 升级前的行为是否正常，以排除其他系统级变更影响。

解决步骤

升级 SwarmUI 至包含 Issue 中补丁修复的版本，或手动应用社区提供的补丁文件：fix_ffmpeg_vsync.patch 和 fix_preview_fallback.patch。
补丁 1 将 -vsync 0 替换为 -fps_mode passthrough，并使用版本探测或参数回退策略保证兼容 ffmpeg 5.1 之前的旧版本和 9.0 之后的新版本。
补丁 2 修复缓存回退逻辑，使仅有 JPG 预览的视频直接返回该 JPG 文件，而非错误地将其当作视频媒体类型处理。
若已有损坏的缓存条目，在 SwarmUI 的 Utilities 选项卡中执行 Reset All Metadata，或者等待 24 小时预览缓存自动过期后重新生成。
在无法立即应用补丁的情况下，可优先尝试将系统 ffmpeg 降级到 8.1.2 或更低版本（作为临时规避手段）。

验证方法

修复后在 Image History 面板中重新打开先前损坏的视频记录，确认缩略图能正常显示为动画 WebP 或静态 JPG 帧。手动再次生成一个新视频，确认其缩略图在生成后立即正常出现。检查视频数据目录下是否生成了 .swarmpreview.webp 文件，或在只有 JPG 预览时确认没有错误地返回 MP4 文件内容。