# 视频壁纸 — 需求契约

> 创建时间：2026-05-28
> 状态：需求已确认

## 目标

支持将视频文件（mp4/WebM/GIF）设为桌面壁纸，WebView2 `<video>` 标签播放。

## 用户场景

1. 用户在设置页选择"视频壁纸"，弹出文件选择对话框（过滤 mp4/WebM/GIF）
2. 选中视频后，桌面壁纸立即切换为视频循环播放
3. 视频静音播放，不干扰用户工作
4. 全屏应用（游戏/视频播放器）时自动暂停，退出全屏后恢复

## 验收标准

- [ ] 支持 mp4、WebM、GIF 格式
- [ ] 视频循环播放，无黑帧闪烁
- [ ] 默认静音，设置页可选开启声音
- [ ] 全屏应用时暂停视频，退出恢复
- [ ] 视频文件路径持久化，重启后恢复
- [ ] 视频填充方式：cover（默认），不拉伸变形
- [ ] 设置页可预览当前视频壁纸

## 本次范围

- 本地视频文件作为壁纸
- 视频播放控制（静音/循环/暂停恢复）

## 非目标

- 在线视频 URL 播放（属于"网页壁纸"方向）
- 视频编辑/裁剪
- 多显示器不同视频

## 约束

- WebView2 `<video>` 原生能力，不引入额外播放器库
- 视频文件不嵌入 exe，用户自行管理文件路径
- 大视频文件（>500MB）需考虑内存占用，不做完整 dataURI 转换，用文件 URL
- 复用现有壁纸类型切换架构（`saveWallpaperType`）

## 风险

| 风险 | 缓解 |
|------|------|
| 大视频内存占用 | 不转 dataURI，用 `file:///` 协议加载 |
| WebView2 视频解码兼容性 | 测试 H.264/VP9 编码，不支持的格式提示用户 |
| 视频切换时闪烁 | 预加载下一帧，CSS transition 淡入 |

## 技术方案

- `wallpaper.go` 新增壁纸类型 `video`
- 视频 HTML 模板：全屏 `<video>` 标签，autoplay/loop/muted/cover
- `config.go` 新增 `VideoPath string` 字段
- `settings.go` 新增 `pickVideoFile` 函数（复用文件对话框，过滤视频格式）
- 前端设置页 WallpaperSection 新增"视频壁纸"选项