# livephoto-demo **Repository Path**: wu1g119/livephoto-demo ## Basic Information - **Project Name**: livephoto-demo - **Description**: LivePhoto 合成服务 一个基于 Spring Boot 的 LivePhoto/动态照片合成服务，支持将视频和图片合成为多平台兼容的动态照片格式。 功能特性 多平台支持：同时生成 iOS LivePhoto、Android Motion Photo、华为动态照片格式 自动裁剪：支持视频自动裁剪，可选择从开头/结尾/中间截取指定时长 FFmpeg 自动安装：首次运行自动检测并下载对应操作系 - **Primary Language**: Java - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-02-02 - **Last Updated**: 2026-02-02 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # LivePhoto 合成服务 一个基于 Spring Boot 的 LivePhoto/动态照片合成服务，支持将视频和图片合成为多平台兼容的动态照片格式。 ## 功能特性 - **多平台支持**：同时生成 iOS LivePhoto、Android Motion Photo、华为动态照片格式 - **自动裁剪**：支持视频自动裁剪，可选择从开头/结尾/中间截取指定时长 - **FFmpeg 自动安装**：首次运行自动检测并下载对应操作系统的 FFmpeg - **Web 界面**：提供友好的 Web 上传界面，支持拖拽上传 - **RESTful API**：提供完整的 API 接口，支持异步任务处理 ## 技术栈 ``` | 技术 | 版本 | 说明 | |------|------|------|/ | Java | 21 | LTS 版本 | | Spring Boot | 3.4.2 | Web 框架 | | FFmpeg | 自动下载 | 视频处理 | | TwelveMonkeys | 3.10.1 | 图片处理 | | mp4parser | 1.9.56 | HEIF 容器封装 | | metadata-extractor | 2.19.0 | 图片元数据处理 | ``` ## 项目架构 ``` src/main/java/com/livephoto/ ├── LivePhotoDemoApplication.java # 启动类 ├── config/ │ ├── FFmpegConfig.java # FFmpeg 配置 │ ├── FFmpegInitializer.java # FFmpeg 自动初始化 │ └── WebConfig.java # Web 配置 ├── controller/ │ ├── LivePhotoController.java # LivePhoto API 控制器 │ └── FileController.java # 文件下载控制器 ├── service/ │ ├── LivePhotoService.java # 服务接口 │ ├── impl/ │ │ └── LivePhotoServiceImpl.java # 服务实现 │ ├── processor/ │ │ ├── VideoProcessor.java # 视频处理器 │ │ ├── MetadataProcessor.java # 元数据处理器 │ │ └── LivePhotoGenerator.java # LivePhoto 生成器 │ └── storage/ │ └── FileStorageService.java # 文件存储服务 ├── dto/ │ ├── LivePhotoRequest.java # 请求 DTO │ ├── LivePhotoResponse.java # 响应 DTO │ └── ProgressResponse.java # 进度响应 DTO ├── entity/ │ └── TaskInfo.java # 任务信息实体 ├── util/ │ ├── FFmpegUtil.java # FFmpeg 工具类 │ ├── FFmpegDownloader.java # FFmpeg 下载器 │ ├── HeifGenerator.java # HEIF 格式生成器 │ ├── ImageUtil.java # 图片工具类 │ ├── PlatformDetector.java # 平台检测工具 │ └── ZipUtil.java # ZIP 压缩工具 └── exception/ ├── BusinessException.java # 业务异常 └── GlobalExceptionHandler.java # 全局异常处理 ``` ## 业务流程 ``` ┌─────────────────────────────────────────────────────────────────┐ │ 用户上传视频/图片 │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ VideoProcessor: 视频裁剪、格式转换 │ │ - 根据用户设置裁剪视频 (开头/结尾/中间) │ │ - 转换为 MP4 格式 │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ ImageProcessor: 图片处理 │ │ - 如无图片则从视频提取封面帧 │ │ - 调整图片格式和质量 │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ LivePhotoGenerator: 生成多平台格式 │ │ ├── iOS: JPEG + MOV (Content Identifier 配对) │ │ ├── Android: MVIMG.jpg (视频嵌入 JPEG + XMP 元数据) │ │ └── 华为: HEIF 单文件 + 配对文件 (IMG_xxx.jpg + IMG_xxx.mp4) │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 打包为 ZIP 文件供用户下载 │ └─────────────────────────────────────────────────────────────────┘ ``` ## 输出格式兼容性 | 平台 | 格式 | 文件 | 兼容设备 | |------|------|------|----------| | iOS | LivePhoto | IMG.JPG + MOV.MOV | iPhone, iPad | | Android | Motion Photo | MVIMG.jpg | Google Pixel, 小米, OPPO, vivo, 三星 | | 华为 | HEIF/配对文件 | LIVP.heif 或 IMG_xxx.jpg + IMG_xxx.mp4 | 华为/荣耀 (HarmonyOS) | ### XMP 元数据兼容性 生成的 Motion Photo 包含多厂商兼容的 XMP 元数据： ```xml GCamera:MotionPhoto="1" GCamera:MicroVideo="1" GCamera:MicroVideoOffset="xxx" HWMP:MotionPhoto="1" SGCAM:MotionPhoto="1" Container:Directory ``` ## 快速开始 ### 环境要求 - JDK 21+ - Maven 3.6+ - FFmpeg (首次运行自动下载) ### 运行项目 ```bash # 克隆项目 git clone cd livephoto2 # 编译运行 mvn spring-boot:run # 或打包后运行 mvn clean package java -jar target/livephoto-demo-1.0.0-SNAPSHOT.jar ``` 访问 http://localhost:18091 打开 Web 界面。 ### 配置文件 `application.yml`: ```yaml livephoto: ffmpeg: auto-download: true # 自动下载 FFmpeg use-system-path: true # 优先使用系统 PATH 中的 FFmpeg local-path: ./ffmpeg-bin # 本地 FFmpeg 存放路径 max-video-duration: 30 # 最大视频时长(秒) video-codec: libx264 # 视频编码器 video-crf: 23 # 视频质量 (0-51, 越小质量越高) timeout: 300 # 处理超时时间(秒) ``` ## API 接口 ### 创建合成任务 ```http POST /api/livephoto/create Content-Type: multipart/form-data video: 视频文件 (必需) image: 图片文件 (可选) platform: ios | android | both | all | huawei trimEnabled: true | false (是否裁剪,默认true) trimDuration: 3.0 (裁剪后时长,秒,默认3) trimPosition: start | end | middle (裁剪位置,默认start) ``` **响应**: ```json { "taskId": "abc123", "status": "pending", "progress": 0, "message": "任务已提交" } ``` ### 查询任务进度 ```http GET /api/livephoto/progress/{taskId} ``` **响应**: ```json { "taskId": "abc123", "status": "completed", "progress": 100, "message": "处理完成", "zipDownloadUrl": "/download/abc123" } ``` ### 下载结果 ```http GET /download/{taskId} ``` ### FFmpeg 状态检查 ```http GET /api/livephoto/ffmpeg/status ``` ## 使用说明 ### iOS 设备 1. 解压 ZIP 文件，进入 `ios` 目录 2. 将 `xxx_IMG.JPG` 和 `xxx_MOV.MOV` 通过 AirDrop 或 iTunes 导入相册 3. iOS 会自动识别并配对为 LivePhoto ### Android 设备 (小米/OPPO/vivo/三星) 1. 解压 ZIP 文件，进入 `android` 目录 2. 将 `xxx_MVIMG.jpg` 复制到手机 `DCIM/Camera` 目录 3. 打开相册即可看到动态照片 ### 华为设备 1. 解压 ZIP 文件，进入 `huawei` 目录 2. 方案A：将 `.heif` 文件复制到手机相册 3. 方案B：将同名的 `IMG_xxx.jpg` 和 `IMG_xxx.mp4` 同时复制到 `DCIM/Camera` 4. 华为相册会自动识别为动态照片 ## 目录结构 ``` livephoto2/ ├── src/ │ ├── main/ │ │ ├── java/com/livephoto/ # Java 源码 │ │ └── resources/ │ │ ├── application.yml # 配置文件 │ │ ├── static/ │ │ │ └── index.html # Web 界面 │ │ └── templates/ │ │ └── download.html # 下载页面 │ └── test/ # 测试代码 ├── docker/ │ └── Dockerfile # Docker 构建文件 ├── pom.xml # Maven 配置 └── README.md ``` ## Docker 部署 ```bash # 构建镜像 docker build -t livephoto-service -f docker/Dockerfile . # 运行容器 docker run -d -p 18091:18091 --name livephoto livephoto-service ``` ## 注意事项 1. **视频时长**：LivePhoto 建议 3 秒以内，默认自动裁剪 2. **文件大小**：上传文件大小受 `spring.servlet.multipart.max-file-size` 限制 3. **华为兼容性**：HarmonyOS 3+ 兼容性更好 4. **微信朋友圈**：当前测试小米澎湃3系统中完美,其它Android Motion Photo 在微信中支持未测,iOS可用 ## License MIT License ### demo调试页面 ![img_1.png](doc/img_1.png) ![img_2.png](doc/img_2.png) ![img_3.png](doc/img_3.png)