let5see/to-live-photo
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

feat: M2-M4 完成，添加 AI 增强、设计系统、App Store 准备

Browse Source 
新增功能：
- AI 超分辨率模块 (Real-ESRGAN Core ML)
- Soft UI 设计系统 (DesignSystem.swift)
- 设置页、隐私政策页、引导页
- 最近作品管理器

App Store 准备：
- 完善截图 (iPhone 6.7"/6.5", iPad 12.9")
- App Store 元数据文档
- 修复应用图标 alpha 通道
- 更新显示名称为 Live Photo Studio

工程配置：
- 配置 Git LFS 跟踪 mlmodel 文件
- 添加 Claude skill 开发指南
- 更新 .gitignore 规则

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
empty
2025-12-16 10:24:31 +08:00
parent 64cdb82459
commit 5aba93e967
46 changed files with 5279 additions and 421 deletions
Download Patch File Download Diff File Expand all files Collapse all files

238
docs/APP_STORE_METADATA.md Normal file
View File

@@ -0,0 +1,238 @@
# App Store 上架元数据
> 准备上传到 App Store Connect 的所有文案和信息
---
## 基本信息
| 项目 | 内容 |
|------|------|
| **应用名称** | Live Photo Maker |
| **副标题** | 视频一键转动态壁纸 |
| **Bundle ID** | xyz.let5see.livephotomaker |
| **版本号** | 1.0 |
| **Build 号** | 1 |
| **分类** | 主类别: Photo & Video / 次类别: Utilities |
| **年龄分级** | 4+ |
| **价格** | 免费 |
---
## 应用描述
### 简短描述（Promotional Text，170字符以内）
```
将任意视频转换为 Live Photo，设置为动态锁屏壁纸。AI 超分辨率增强，让壁纸更清晰。
```
### 完整描述
```
Live Photo Maker 是一款简单易用的动态壁纸制作工具，让你的锁屏动起来！
主要功能：
【一键转换】
• 从相册选择视频，一键转换为 Live Photo
• 智能时长裁剪，自动适配系统要求
• 支持各种视频格式：MP4、MOV、H.264、HEVC
【精准编辑】
• 多种比例模板：iPhone 锁屏、全面屏、4:3 等
• 双指缩放和拖拽，精准裁剪画面
• 滑块选择封面帧，预览实时更新
【AI 超分辨率】
• 使用 AI 技术提升封面画质
• 让你的壁纸更加清晰细腻
• 离线处理，无需网络
【兼容模式】
• 智能诊断视频参数
• 自动转换为最兼容格式
• 支持 4K、HDR、HEVC 等高规格视频
【设置引导】
• 详细的壁纸设置教程
• 常见问题解答
• 分步骤图文指引
使用提示：
• 需要 iOS/iPadOS 17 或更高版本以获得完整的动态壁纸体验
• iOS 16 用户可以创建 Live Photo，但锁屏不支持动态效果
• 所有处理均在本地完成，不上传任何内容到服务器
让每次拿起手机都有惊喜，现在就开始制作你的专属动态壁纸吧！
```
---
## 关键词（100字符以内）
```
Live Photo,动态壁纸,锁屏壁纸,视频转换,AI增强,照片,壁纸,动图,实况照片,超分辨率
```
---
## 新功能（版本说明）
### 1.0 版本
```
Live Photo Maker 正式发布！
• 视频一键转换为 Live Photo
• 多种比例模板，适配各种设备
• 双指缩放裁剪，精准控制画面
• AI 超分辨率增强封面画质
• 兼容模式支持各种视频格式
• 详细的壁纸设置引导
```
---
## 隐私政策 URL
```
https://let5sne.github.io/xyz.let5see.livephotomaker/privacy.html
```
✅ 已托管到 GitHub Pages，内容包含：
- 本地处理模式（免费）说明
- 云端增强模式（Pro）说明（为未来功能预留）
- 权限说明、数据收集、数据存储
- 第三方服务、用户权利
---
## 支持 URL
```
https://let5sne.github.io/xyz.let5see.livephotomaker/support.html
```
✅ 已托管到 GitHub Pages，内容包含：
- 常见问题 FAQ（动态效果、生成失败、LIVE 标识等）
- 壁纸设置步骤引导
- 联系邮箱：support@let5see.xyz
---
## 使用条款 URL
```
https://let5sne.github.io/xyz.let5see.livephotomaker/terms.html
```
✅ 已托管到 GitHub Pages，内容包含：
- 服务说明
- 订阅与内购条款（Apple IAP）
- 使用限制、云端服务条款
- 免责声明、知识产权
---
## 截图要求
### iPhone 截图（必需）
| 尺寸 | 设备 | 数量 |
|------|------|------|
| 6.7" | iPhone 15 Pro Max / 14 Pro Max | 3-10 张 |
| 6.5" | iPhone 14 Plus / 11 Pro Max | 3-10 张 |
| 5.5" | iPhone 8 Plus / 7 Plus | 3-10 张（可选） |
### iPad 截图（如支持 iPad）
| 尺寸 | 设备 | 数量 |
|------|------|------|
| 12.9" (6代) | iPad Pro 12.9" | 3-10 张 |
| 12.9" (2代) | iPad Pro 12.9" (旧款) | 3-10 张（可选） |
### 建议截图内容
1. **首页** - 展示导入入口和整体设计
2. **编辑页** - 展示比例模板和裁剪功能
3. **AI 增强开关** - 展示 AI 超分辨率功能
4. **处理进度** - 展示生成过程
5. **成功结果页** - 展示完成状态
6. **壁纸引导页** - 展示设置教程
---
## App Preview 视频（可选）
| 尺寸 | 要求 |
|------|------|
| 时长 | 15-30 秒 |
| 格式 | H.264, 30fps |
| 分辨率 | 与截图相同 |
建议内容：展示完整的「选择视频 → 编辑 → 生成 → 设置壁纸」流程
---
## 审核备注
```
测试说明：
1. 从相册选择任意视频
2. 调整比例和时长参数
3. 点击生成按钮等待处理完成
4. Live Photo 会自动保存到相册
5. 按照引导设置为锁屏壁纸
注意：
• 需要授权相册访问权限
• 动态壁纸功能需要 iOS 17+
• 所有处理在本地完成，无需网络
```
---
## 版权信息
```
© 2025 let5see.xyz. All rights reserved.
```
---
## 上架检查清单
### 开发者账号
- [ ] Apple Developer Program 已加入（$99/年）
- [ ] App Store Connect 账号已创建
### 应用配置
- [x] Bundle ID: xyz.let5see.livephotomaker
- [x] 版本号: 1.0
- [x] 应用图标: 1024x1024
- [x] 权限说明文案
- [x] 隐私政策（应用内）
- [x] 使用条款（应用内）
### 在线页面
- [x] 隐私政策 URL（GitHub Pages）
- [x] 支持 URL（GitHub Pages）
- [x] 使用条款 URL（GitHub Pages）
- [x] 联系邮箱: support@let5see.xyz
### 需要准备
- [ ] iPhone 截图（至少 6.7" 和 6.5"）
- [ ] iPad 截图（如果支持 iPad）
### 构建上传
- [ ] Xcode Archive 构建
- [ ] 上传到 App Store Connect
- [ ] TestFlight 内部测试
- [ ] 提交审核
---
## 本地化（可选，后续版本）
目前应用界面为简体中文，后续可考虑添加：
- 英文 (English)
- 繁体中文 (Traditional Chinese)
- 日文 (Japanese)

296
docs/TEST_MATRIX.md Normal file
View File

@@ -0,0 +1,296 @@
# Live Photo Maker 测试文档
## 测试矩阵
### 设备覆盖
| 设备类型 | 系统版本 | 测试优先级 |
|---------|---------|-----------|
| iPhone (任意机型) | iOS 18+ | P0 |
| iPhone (任意机型) | iOS 17.x | P0 |
| iPhone (任意机型) | iOS 16.x | P1 |
| iPad (任意机型) | iPadOS 18+ | P1 |
| iPad (任意机型) | iPadOS 17.x | P1 |
### 素材覆盖
| 素材类型 | 编码 | 帧率 | 方向 | HDR | 测试优先级 |
|---------|------|------|------|-----|-----------|
| 标准视频 | H.264 | 30fps | 竖屏 | SDR | P0 |
| 标准视频 | H.264 | 60fps | 竖屏 | SDR | P0 |
| HEVC 视频 | HEVC | 30fps | 竖屏 | SDR | P0 |
| HEVC 视频 | HEVC | 60fps | 竖屏 | SDR | P1 |
| 横屏视频 | H.264 | 30fps | 横屏 | SDR | P1 |
| HDR 视频 | HEVC | 30fps | 竖屏 | HDR | P1 |
| 4K 视频 | H.264/HEVC | 30fps | 竖屏 | SDR | P2 |
---
## 测试用例
### TC001: 基础导入流程
**前置条件**: 相册中有可用视频
**步骤**:
1. 打开 App，进入首页
2. 点击「选择视频」按钮
3. 从相册选择一个 2-5 秒的视频
4. 等待视频加载完成
**预期结果**:
- 视频加载成功，跳转到编辑页
- 编辑页显示视频预览
- 时长滑块显示正确的时间范围
**优先级**: P0
---
### TC002: 编辑页参数调整
**前置条件**: 已导入视频，处于编辑页
**步骤**:
1. 调整时长滑块，选择 1-1.5 秒区间
2. 切换不同的比例模板（锁屏/全屏/4:3）
3. 使用双指手势缩放和拖动预览区域
4. 开启/关闭兼容模式
**预期结果**:
- 时长滑块可正常拖动，显示选中时长
- 切换比例后预览区域实时更新
- 手势操作流畅，裁剪区域可调整
- 兼容模式开关状态正确显示
**优先级**: P0
---
### TC003: 生成 Live Photo
**前置条件**: 已完成编辑参数设置
**步骤**:
1. 点击「生成 Live Photo」按钮
2. 观察进度页面的阶段变化
3. 等待生成完成
**预期结果**:
- 显示进度条和阶段文案
- 阶段依次为：normalize → extractKeyFrame → writePhotoMetadata → writeVideoMetadata → saveToAlbum → validate
- 生成成功后跳转到结果页
- 结果页显示「Live Photo 已保存」
**优先级**: P0
---
### TC004: 相册验证
**前置条件**: Live Photo 已生成并保存
**步骤**:
1. 打开系统「照片」App
2. 找到刚保存的照片
3. 查看照片详情，确认有 LIVE 标识
4. 长按照片，触发动画播放
**预期结果**:
- 照片左上角显示「LIVE」标识
- 长按可播放动画效果
- 动画时长约 0.9 秒
**优先级**: P0
---
### TC005: 设置为壁纸（iOS 17+）
**前置条件**: Live Photo 已保存，设备为 iOS 17+
**步骤**:
1. 在结果页点击「查看壁纸设置指南」
2. 按引导打开照片 App
3. 选择 Live Photo → 分享 → 用作壁纸
4. 确认 Live Photo 图标已开启（高亮）
5. 完成设置，锁屏长按测试
**预期结果**:
- 引导页正确显示 iOS 17+ 的步骤
- 壁纸设置成功
- 锁屏长按可触发动画
**优先级**: P0
---
### TC006: 兼容模式测试
**前置条件**: 有 4K/HDR/HEVC 视频素材
**步骤**:
1. 导入高规格视频
2. 查看自动诊断建议
3. 开启兼容模式
4. 生成 Live Photo
**预期结果**:
- 显示「建议开启兼容模式」提示
- 兼容模式下参数自动调整为 720p/30fps/H.264/SDR
- 生成成功，文件体积较小
**优先级**: P1
---
### TC007: 取消生成
**前置条件**: 正在生成 Live Photo
**步骤**:
1. 在进度页点击「取消」按钮
2. 确认取消操作
**预期结果**:
- 生成任务立即停止
- 返回编辑页或首页
- 缓存目录中的临时文件已清理
**优先级**: P1
---
### TC008: 最近作品
**前置条件**: 已成功生成至少一个 Live Photo
**步骤**:
1. 返回首页
2. 查看「最近作品」区域
3. 点击最近作品卡片
**预期结果**:
- 显示最近生成的作品缩略图
- 显示比例和时间信息
- 点击可进入壁纸引导页
**优先级**: P1
---
### TC009: 设置页功能
**前置条件**: 无
**步骤**:
1. 点击首页右上角设置图标
2. 查看权限状态
3. 点击「清理缓存」
4. 点击「导出诊断报告」
**预期结果**:
- 权限状态正确显示（已授权/未授权）
- 缓存清理后显示「0 KB」
- 诊断报告生成并弹出分享面板
**优先级**: P2
---
### TC010: iOS 16 系统限制提示
**前置条件**: 设备为 iOS 16
**步骤**:
1. 完成 Live Photo 生成
2. 进入壁纸引导页
**预期结果**:
- 显示「iOS 17+ 才支持锁屏动态效果」警告
- 引导步骤说明 iOS 16 的限制
- FAQ 包含相关问题解答
**优先级**: P1
---
### TC011: AI 超分辨率增强
**前置条件**: 设备支持 AI 增强（iOS 17+，≥4GB RAM）
**步骤**:
1. 导入视频，进入编辑页
2. 开启「AI 超分辨率」开关
3. 确认显示「分辨率提升约 2 倍」等信息
4. 点击生成 Live Photo
5. 观察进度页显示「AI 增强封面」阶段
**预期结果**:
- AI 增强阶段耗时约 2-3 秒
- 生成成功，封面图分辨率提升
- 无崩溃或异常
**优先级**: P1
---
### TC012: AI 增强不可用设备
**前置条件**: 设备不支持 AI 增强（iOS 16 或 <4GB RAM）
**步骤**:
1. 进入编辑页
2. 查看 AI 超分辨率区域
**预期结果**:
- 开关置灰不可点击
- 显示「当前设备不支持 AI 增强」提示
**优先级**: P2
---
## 异常场景
### TC013: 权限被拒绝
**步骤**: 在系统设置中拒绝相册权限后尝试保存
**预期结果**: 显示错误提示，引导用户前往设置授权
---
### TC014: 视频时长不足
**步骤**: 导入时长小于 0.5 秒的视频
**预期结果**: 显示「视频时长不足」错误提示
---
### TC015: 磁盘空间不足
**步骤**: 在磁盘空间极低时尝试生成
**预期结果**: 显示存储空间不足错误，建议清理缓存
---
## 验收标准
- [ ] P0 用例全部通过（TC001-TC005）
- [ ] P1 用例通过率 ≥ 90%（TC006-TC011）
- [ ] 无崩溃
- [ ] 生成成功率 ≥ 95%（标准素材）
- [ ] 相册识别率 100%
- [ ] AI 增强成功率 ≥ 90%（支持设备）
## 测试用例统计
| 优先级 | 用例数 | 说明 |
|--------|--------|------|
| P0 | 5 | TC001-TC005，核心流程 |
| P1 | 6 | TC006-TC011，进阶功能 |
| P2 | 4 | TC012, TC013-TC015，边界场景 |
| **总计** | **15** | |

252
docs/USER_GUIDE.md Normal file
View File

@@ -0,0 +1,252 @@
# Live Photo Maker 用户手册
## 快速开始
### 第一步：导入视频
1. 打开 App，在首页点击「选择视频」按钮
2. 从相册中选择一段视频（建议 2-5 秒）
3. 等待视频加载完成，自动跳转到编辑页
> 💡 **提示**：首次使用需要授权相册访问权限
---
### 第二步：编辑参数
#### 比例模板
- **iPhone 锁屏**：9:19.5，适合设置为锁屏壁纸
- **全面屏**：9:16，适合全面屏手机
- **4:3**：经典比例
#### 时长调整
- 使用滑块选择视频片段（1-1.5 秒）
- Live Photo 标准时长约 0.9 秒
#### 画面裁剪
- **双指缩放**：调整画面大小
- **拖拽移动**：调整画面位置
#### 封面帧选择
- 滑动选择器选择静态封面帧
- 预览区域实时显示效果
#### 兼容模式（推荐开启）
- 自动将视频转换为最兼容的格式
- 参数：720p / 30fps / H.264 / SDR
- 适用于：4K 视频、HDR 视频、HEVC 编码视频
---
### 第三步：生成 Live Photo
1. 点击「生成 Live Photo」按钮
2. 等待处理完成（通常 10-30 秒）
3. 生成成功后自动保存到相册
#### 处理阶段说明
| 阶段 | 说明 |
|------|------|
| normalize | 视频格式标准化 |
| extractKeyFrame | 提取封面帧 |
| writePhotoMetadata | 写入照片元数据 |
| writeVideoMetadata | 写入视频元数据 |
| saveToAlbum | 保存到相册 |
| validate | 校验 Live Photo |
---
### 第四步：设置为壁纸
#### iOS/iPadOS 17+ 设置方法
1. 打开系统「照片」App
2. 找到刚保存的 Live Photo（左上角有 LIVE 标识）
3. 点击左下角「分享」按钮
4. 选择「用作壁纸」
5. **重要**：确保 Live Photo 图标已开启（高亮状态）
6. 点击「添加」完成设置
7. 锁屏后长按屏幕测试动态效果
#### iOS/iPadOS 16 限制
⚠️ iOS/iPadOS 16 系统不支持将 Live Photo 设置为带动态效果的锁屏壁纸。
- 可以设置为普通静态壁纸
- 升级到 iOS/iPadOS 17+ 可获得完整体验
---
## 设置页功能
### 权限状态
- 显示当前相册权限状态
- 如未授权，可点击「前往设置授权」
### 清理缓存
- 显示当前缓存大小
- 清理缓存不会影响已保存的 Live Photo
### 清空最近作品记录
- 仅清除 App 内的作品记录
- 不会删除相册中的 Live Photo
### 导出诊断报告
- 用于反馈问题时附带
- 仅包含日志和参数，不含媒体内容
---
## 常见问题 FAQ
### Q1: 为什么长按壁纸没有动画效果？
**可能原因及解决方案**：
1. **低电量模式已开启**
- 前往「设置 → 电池」关闭低电量模式
2. **Live Photo 效果未开启**
- 设置壁纸时，确保 Live Photo 图标为高亮状态
3. **系统版本不支持**
- iOS/iPadOS 16 不支持锁屏动态效果
- 升级到 iOS/iPadOS 17+ 可解决
4. **照片不是 Live Photo**
- 在相册中确认照片左上角有「LIVE」标识
---
### Q2: 生成失败怎么办？
**尝试以下步骤**：
1. **开启兼容模式**
- 适用于高分辨率、HDR、特殊编码的视频
2. **缩短选择时长**
- 选择 1 秒左右的片段
3. **更换视频素材**
- 尝试使用 iPhone 原生拍摄的视频
4. **清理缓存后重试**
- 前往「设置 → 清理缓存」
5. **重启 App**
- 完全退出后重新打开
---
### Q3: 相册里找不到 LIVE 标识？
**可能原因**：
1. **照片未正确保存**
- 检查保存时是否提示成功
2. **查看方式不对**
- 在「照片」App 中查看，不是「文件」App
3. **滤镜显示**
- 在「照片」App 中，点击「相簿 → 媒体类型 → Live Photo」查看
---
### Q4: 为什么建议开启兼容模式？
某些视频格式可能不被系统完全支持为 Live Photo 的配对视频：
| 素材类型 | 建议 |
|---------|------|
| 4K 视频 | 开启兼容模式 |
| HDR 视频 | 开启兼容模式 |
| HEVC (H.265) | 开启兼容模式 |
| H.264 1080p | 可不开启 |
兼容模式会将视频转换为：
- 分辨率：720p
- 帧率：30fps
- 编码：H.264
- 色彩：SDR
---
### Q5: 支持哪些视频格式？
**支持的格式**：
- MP4 / MOV / M4V
- H.264 / HEVC (H.265) 编码
- SDR / HDR 色彩空间
- 任意分辨率（会自动缩放）
- 任意帧率（会自动调整）
**不支持**：
- 网络视频链接
- 非视频文件
---
### Q6: Live Photo 占用多少存储空间？
单个 Live Photo 通常占用 **2-5 MB**：
- 静态照片：约 1-2 MB
- 配对视频：约 1-3 MB
开启兼容模式后，文件体积会更小。
---
## 错误代码说明
| 错误代码 | 含义 | 建议操作 |
|---------|------|---------|
| LPB-001 | 导入失败 | 检查视频格式，换一个视频重试 |
| LPB-101 | 标准化失败 | 开启兼容模式重试 |
| LPB-201 | 提取帧失败 | 缩短视频时长，开启兼容模式 |
| LPB-301 | 元数据写入失败 | 清理缓存后重试 |
| LPB-401 | 保存失败 | 检查相册权限，检查存储空间 |
| LPB-901 | 未知错误 | 导出诊断报告并反馈 |
---
## 技术规格
### 输出参数
| 参数 | 标准模式 | 兼容模式 |
|------|---------|---------|
| 照片分辨率 | 最高 1080p | 720p |
| 视频分辨率 | 最高 1080p | 720p |
| 视频帧率 | 60fps | 30fps |
| 视频编码 | 保持原编码 | H.264 |
| 色彩空间 | 保持原色彩 | SDR |
| 时长 | ~0.9 秒 | ~0.9 秒 |
### 系统要求
- **最低支持**：iOS/iPadOS 16.0
- **完整体验**：iOS/iPadOS 17.0+
- **存储空间**：建议剩余 100 MB 以上
---
## 隐私说明
- 所有处理均在本地完成
- 不上传任何媒体内容到服务器
- 仅在用户明确操作时访问相册
- 诊断报告不包含媒体内容
---
## 反馈与支持
如遇到问题，请通过以下方式反馈：
1. 在 App 内「设置 → 导出诊断报告」
2. 将诊断报告通过邮件发送给我们
3. 描述问题发生的步骤和现象
我们会尽快处理您的反馈！