5 分钟上手 SwiftVideoGenerator：单张图片加音频生成视频的保姆级教程

【免费下载链接】swift-video-generator项目地址: https://gitcode.com/gh_mirrors/sw/swift-video-generator

想用一张静态图片配上一段背景音乐，快速生成一条竖屏短视频？SwiftVideoGenerator就是这样一个轻量级的 iOS 开源库，它提供了一种极其简单的方式，把图片和音频组合成视频，甚至还能合并、分割、倒放视频。本教程将带你从零开始，用 5 分钟完成单张图片加音频生成视频的全流程，全程保姆级讲解，无需深入 AVFoundation 底层，适合新手开发者。

SwiftVideoGenerator 是什么？它能做什么？

SwiftVideoGenerator 是一个基于 Swift 编写的 iOS 视频生成框架，核心思路是"喂给它图片和音频，它还你一条视频"。它支持以下几种生成模式：

• single：单张图片 + 单个音频 → 生成一条视频（本教程重点）
• multiple：多张图片 + 多个音频，按顺序拼接成一条视频
• singleAudioMultipleImage：一段音频 + 多张图片，图片按时间轴轮播
• 额外能力：合并多段视频、视频倒放、按时间段裁剪、视频替换音频

它的实现基于 AVFoundation，但把所有复杂的编码、合成逻辑都封装在了 VideoGenerator.swift 中，你只需要调用一个方法即可完成图片转视频。

环境要求与安装方式

支持的环境条件

• iOS 12.0 及以上
• Xcode 10 及以上
• Swift 4 及以上

三种安装方法任选其一

方法一：CocoaPods 安装（推荐）

在 Podfile 中加入一行：

platform :ios, '12.0' use_frameworks! target '你的项目名' do pod 'SwiftVideoGenerator' end

然后执行pod install，之后通过import SwiftVideoGenerator引入即可。

方法二：Swift Package Manager 安装

在 Xcode 中选择 File → Swift Packages → Add Package Dependency，将仓库地址https://gitcode.com/gh_mirrors/sw/swift-video-generator填入即可，库的配置见 Package.swift。

方法三：手动集成

直接从 Sources/SwiftVideoGenerator/Classes 目录下载VideoGenerator.swift、Error和Extensions文件夹中的文件，拖入 Xcode 工程即可，手动集成方式可参考 SwiftVideoGenerator.podspec 中的文件清单。

核心代码：单张图片加音频生成视频

第一步：准备素材

在工程中准备一张图片和一段音频（示例工程的素材放在 Example/SwiftVideoGenerator/Images.xcassets 和 Example/SwiftVideoGenerator/Resources 目录中，包括 scene1～scene4 四张场景图和 audio1～audio4 四段音频）。

第二步：一行代码触发视频生成

核心调用只需几行代码，完整写法参考示例工程 ViewController.swift：

import SwiftVideoGenerator if let audioURL = Bundle.main.url(forResource: "audio1", withExtension: "mp3") { VideoGenerator.fileName = "myFirstVideo" VideoGenerator.shouldOptimiseImageForVideo = true VideoGenerator.current.generate( withImages: [UIImage(named: "scene1")!], andAudios: [audioURL], andType: .single, { progress in print("生成进度：\(progress.fractionCompleted)") }, outcome: { result in switch result { case .success(let url): print("视频生成成功：\(url)") case .failure(let error): print("生成失败：\(error.localizedDescription)") } } ) }

是不是很简单？generate方法会在后台队列异步处理，通过progress回调实时反馈进度，生成完成后通过outcome回调返回视频文件地址（默认保存在 Documents 目录，格式为 m4v）。

第三步：理解常用配置项

为了让视频更贴合需求，VideoGenerator 提供了几个常用静态属性：

其中shouldOptimiseImageForVideo会自动调用 ImageExtension.swift 中的resizeImageToVideoSize()，把图片统一缩放到适合视频播放的尺寸（宽 800～1400、高不超过 1200 的 16 倍数），避免大图造成的内存压力。

进阶玩法：不限于单图单音频

熟悉了基础用法后，你还可以轻松扩展：

• 多图多音频拼接：把andType改为.multiple，传入等长的图片数组和音频数组，视频会按顺序轮播拼接，适合做幻灯片式短视频。
• 单音频多图轮播：使用.singleAudioMultipleImage，多张图片会在一段音频的时间轴内均匀分布，非常适合制作相册回忆视频。
• 视频合并：调用VideoGenerator.mergeMovies(videoURLs:)，可以把多段 mov/mp4 视频合并为一条。
• 视频倒放与裁剪：reverseVideo(fromVideo:)支持倒放，splitVideo(withURL:atStartTime:andEndTime:)支持按时间段裁剪。

这些功能全部封装在 VideoGenerator.swift 中，调用方式与上面保持一致，只是参数不同。

常见问题与避坑指南

Q1：生成失败，提示 "AVAssetWriter failed to start writing"？通常是图片数组为空或音频文件无法访问。请确认资源已加入工程 Target，并用Bundle.main.url(forResource:withExtension:)能正确取到文件。

Q2：生成的视频画面模糊或比例不对？建议保持shouldOptimiseImageForVideo = true，让库自动优化图片尺寸；也可以手动设置scaleWidth（如 800 或 1200）来控制输出宽度。

Q3：视频时长不受控制？带音频时视频时长等于音频总时长；若不想让音频决定时长，可设置maxVideoLengthInSeconds；不带音频时用videoDurationInSeconds指定时长。

Q4：音频与图片数量不匹配？.multiple模式下，多出的音频或图片会被自动忽略，只取两者中数量较少的一方。

Q5：错误信息如何排查？所有错误类型集中在 VideoGeneratorError.swift 中，通过error.localizedDescription即可拿到可读的错误说明。

总结

SwiftVideoGenerator 把复杂的 AVFoundation 视频合成逻辑简化成了一个方法调用，单张图片加音频生成视频只需要三步：准备素材、调用generate方法、在回调里接收结果。无论是做内容创作工具、相册视频 App，还是快速验证视频想法，它都是一个性价比极高的选择。赶快动手试试，5 分钟后你也能拥有自己的视频生成能力！

【免费下载链接】swift-video-generator项目地址: https://gitcode.com/gh_mirrors/sw/swift-video-generator