AVFoundation编程指南12-AVAssetExport
写在前面
喜欢AVFoundation资料的同学可以关注我的专题:《AVFoundation》专辑
也可以关注我的简书账号
正文
AVAssetExportSession可以以指定导出预设所描述的形式从现有AVAsset的内容创建新的定时媒体资源。
数据结构
AVAssetExportSession数据结构如下：
AVAssetExportSession数据结构
Export Preset Names
下面这些export选项可用于生成视频大小适合设备的视频文件。
export不会从较小的尺寸缩放较大尺寸的视频。视频将使用H.264压缩和音频将使用AAC进行压缩。
AVF_EXPORT NSString *const AVAssetExportPresetLowQuality NS_AVAILABLE(10_11, 4_0);
AVF_EXPORT NSString *const AVAssetExportPresetMediumQuality NS_AVAILABLE(10_11, 4_0);
AVF_EXPORT NSString *const AVAssetExportPresetHighestQuality NS_AVAILABLE(10_11, 4_0);
下面这个export(导出)方式视频方面使用HEVC压缩和音频方面将使用AAC进行压缩。有些设备可能无法支持某些尺寸。
AVF_EXPORT NSString *const AVAssetExportPresetHEVCHighestQuality NS_AVAILABLE(10_13, 11_0);
下面的导出方式视频采用HEVC压缩，音频采用AAC压缩。有些设备可能无法支持某些尺寸。
AVF_EXPORT NSString *const AVAssetExportPreset640x480 NS_AVAILABLE(10_7, 4_0);
AVF_EXPORT NSString *const AVAssetExportPreset960x540 NS_AVAILABLE(10_7, 4_0);
AVF_EXPORT NSString *const AVAssetExportPreset1280x720 NS_AVAILABLE(10_7, 4_0);
AVF_EXPORT NSString *const AVAssetExportPreset1920x1080 NS_AVAILABLE(10_7, 5_0);
AVF_EXPORT NSString *const AVAssetExportPreset3840x2160 NS_AVAILABLE(10_10, 9_0);
下面的导出方式视频采用HEVC压缩，音频采用AAC压缩。有些设备可能无法支持某些尺寸。
AVF_EXPORT NSString *const AVAssetExportPresetHEVC1920x1080 NS_AVAILABLE(10_13, 11_0);
AVF_EXPORT NSString *const AVAssetExportPresetHEVC3840x2160 NS_AVAILABLE(10_13, 11_0);
下面的导出选项将生成仅具有音频的.m4a文件，其中包含适当的iTunes无间隙播放数据
AVF_EXPORT NSString *const AVAssetExportPresetAppleM4A NS_AVAILABLE(10_7, 4_0);
下面的导出选项将使所有轨道的媒体完全按照存储在源资源中的方式传递到output，除了通道无法通过的轨道，通常是由于指定的outputFileType指示的容器格式的约束。
此选项不包含在-allExportPresets和-exportPresetsCompatibleWithAsset返回的数组中。
AVF_EXPORT NSString *const AVAssetExportPresetPassthrough NS_AVAILABLE(10_7, 4_0);
如果当前的操作系统是MAC OS操作系统并且不是嵌入式操作系统也不是iOS操作系统的话，下面的导出方式也可以使用
下面这些导出选项用于生成可在指定Apple设备上播放的文件。
这些预设仅适用于桌面导出。
这些文件应具有.m4v扩展名（或m4a用于仅包含音频源的导出）。
AVF_EXPORT NSString *const AVAssetExportPresetAppleM4VCellular NS_AVAILABLE(10_7, NA);
AVF_EXPORT NSString *const AVAssetExportPresetAppleM4ViPod NS_AVAILABLE(10_7, NA);
AVF_EXPORT NSString *const AVAssetExportPresetAppleM4V480pSD NS_AVAILABLE(10_7, NA);
AVF_EXPORT NSString *const AVAssetExportPresetAppleM4VAppleTV NS_AVAILABLE(10_7, NA);
AVF_EXPORT NSString *const AVAssetExportPresetAppleM4VWiFi NS_AVAILABLE(10_7, NA);
AVF_EXPORT NSString *const AVAssetExportPresetAppleM4V720pHD NS_AVAILABLE(10_7, NA);
AVF_EXPORT NSString *const AVAssetExportPresetAppleM4V1080pHD NS_AVAILABLE(10_8, NA);
下面这个导出选项将生成带有Apple ProRes 422视频和LPCM音频的QuickTime视频。
AVF_EXPORT NSString *const AVAssetExportPresetAppleProRes422LPCM NS_AVAILABLE(10_7, NA);
AVAssetExportSessionStatus
AVAssetExportSessionStatusUnknown,
AVAssetExportSessionStatusWaiting,
AVAssetExportSessionStatusExporting,
AVAssetExportSessionStatusCompleted,
AVAssetExportSessionStatusFailed,
AVAssetExportSessionStatusCancelled
AVAssetExportSession
+ (nullable instancetype)exportSessionWithAsset:(AVAsset *)asset presetName:(NSString *)presetName NS_AVAILABLE(10_7, 4_1);
| 函数名 | exportSessionWithAsset:presetName: |
|---|---|
| 解释 | 返回指定源资源和预设的AVAssetExportSession实例。 |
| 参数 |
asset:用于导出的 AVAsset对象。presetName:NSString，指定导出的预设模板的名称。 |
| 返回值 |
AVAssetExportSession的一个实例。 |
| 备注 | 如果指定的asset属于AVAsset，AVMutableComposition或AVMutableMovie的可变子类，则如果在操作开始后改变asset，则任何与导出相关的操作的结果都是未定义的。这些操作包括但不限于：1）测试导出预设与asset的兼容性，2）计算输出文件的最大持续时间或估计长度，以及3）导出操作本身。 |
- (nullable instancetype)initWithAsset:(AVAsset *)asset presetName:(NSString *)presetName NS_DESIGNATED_INITIALIZER;
| 函数名 | initWithAsset:presetName: |
|---|---|
| 解释 | 使用指定的预设初始化AVAssetExportSession，并将源设置为asset的内容。 |
| 参数 |
asset:用于导出的 AVAsset对象。presetName:NSString，指定导出的预设模板的名称。 |
| 返回值 | 返回初始化的AVAssetExportSession。 |
| 备注 | 如果指定的asset属于AVAsset，AVMutableComposition或AVMutableMovie的可变子类，则如果在操作开始后改变asset，则任何与导出相关的操作的结果都是未定义的。这些操作包括但不限于：1）测试导出预设与asset的兼容性，2）计算输出文件的最大持续时间或估计长度，以及3）导出操作本身。 |
@property (nonatomic, readonly) NSString *presetName;
除非另有说明，否则AVAssetExortSession属性是可以进行键值观察的。
指示初始化AVExportSession的预设名称。
@property (nonatomic, retain, readonly) AVAsset *asset NS_AVAILABLE(10_8, 5_0);
指示初始化AVExportSession的AVAsset实例。
@property (nonatomic, copy, nullable) AVFileType outputFileType;
指示会话要写入的文件类型。
在调用-exportAsynchronouslyWithCompletionHandler：;之前，必须设置此属性的值。否则-exportAsynchronouslyWithCompletionHandler：将引发NSInternalInconsistencyException。
将此属性的值设置为不在会话支持的文件类型中的文件类型将导致NSInvalidArgumentException。详情请参阅supportedFileTypes。
@property (nonatomic, copy, nullable) NSURL *outputURL;
指示导出会话输出的URL。你可以使用UTTypeCopyPreferredTagWithClass（outputFileType，kUTTagClassFilenameExtension）为你指定的outputFileType获取适当的路径扩展。有关UTTypeCopyPreferredTagWithClass和kUTTagClassFilenameExtension的更多信息，请参阅<MobileCoreServices / UTType.h>，在Mac OS X上可以查看<LaunchServices / UTType.h>。
@property (nonatomic) BOOL shouldOptimizeForNetworkUse;
表示应该优化输出文件以供网络使用，例如一个QuickTime电影文件应该支持"fast start"。
@property (nonatomic, readonly) AVAssetExportSessionStatus status;
表示导出会话的状态。
@property (nonatomic, readonly, nullable) NSError *error;
描述导出状态为AVAssetExportSession状态失败时发生的错误。
- (void)exportAsynchronouslyWithCompletionHandler:(void (^)(void))handler;
| 函数名 | exportAsynchronouslyWithCompletionHandler: |
|---|---|
| 解释 | 启动导出会话的异步执行。 |
| 参数 |
handler:如果导出的内部准备失败，则将同步调用该处理程序。在 -exportAsynchronouslyWithCompletionHandler：return之后，也可以异步调用处理程序，在以下情况中： 1）如果在导出过程中发生故障，包括加载，重新编码或将媒体数据写入输出失败。 2）如果调用 -cancelExport。3）如果导出会话成功，则将其输出完全写入 outputURL。在每种情况下， AVAssetExportSession.status都将发出asset读取器的终端状态信号，如果发生故障，则表示NSError描述失败可以从 error属性中获取。 |
| 备注 | 启动异步导出操作并立即返回。 |
@property (nonatomic, readonly) float progress;
以0到1.0的比例指定导出的进度。值为0表示导出尚未开始，值为1.0表示导出已完成。此属性不是可以进行键值观察的。
- (void)cancelExport;
| 函数名 | cancelExport |
|---|---|
| 解释 | 取消导出会话的执行。 |
| 备注 | 取消可以在导出运行时被调用。 |
AVAssetExportSessionPresets
+ (NSArray<NSString *> *)allExportPresets;
| 函数名 | allExportPresets |
|---|---|
| 解释 | 返回所有可用的导出预设名称。 |
| 返回值 |
NSArray，包含每个可用预设名称的NSString。 |
| 备注 | 返回NSStrings数组，其中包含所有可用预设的名称。请注意，并非所有预设都是兼容所有AVAssets。 |
+ (NSArray<NSString *> *)exportPresetsCompatibleWithAsset:(AVAsset *)asset;
| 函数名 | exportPresetsCompatibleWithAsset: |
|---|---|
| 解释 | 仅返回与给定AVAsset对象兼容的标识符。 |
| 参数 |
asset:用于导出的 AVAsset对象。 |
| 返回值 | 包含NSString值的NSArray，用于兼容导出类型的标识符。该数组是可用作参数的有效标识符的完整列表initWithAsset：presetName：具有指定的asset。 |
| 备注 | 并非所有导出预设都与所有AVAsset兼容。例如，仅视频asset与仅音频预设不兼容。此方法仅返回与给定asset兼容的预设的标识符。客户端应传入准备导出的AVAsset。为了确保使用给定预设的导出操作的设置和运行成功，没有重大变化（例如添加或删除track）应在检索兼容标识符和执行导出操作之间对asset进行操作。此方法将访问AVAsset的tracks属性以构建返回的NSArray。为了避免阻塞调用线程，应使用AVAsynchro加载tracks属性 |
+ (void)determineCompatibilityOfExportPreset:(NSString *)presetName withAsset:(AVAsset *)asset outputFileType:(nullable AVFileType)outputFileType completionHandler:(void (^)(BOOL compatible))handler NS_AVAILABLE(10_9, 6_0);
| 函数名 | determineCompatibilityOfExportPreset:withAsset:outputFileType:completionHandler: |
|---|---|
| 解释 | 对导出预设，AVAsset和输出文件类型的兼容性执行检查。如果是兼容的，则使用YES调用完成处理程序参数兼容;否则就是NO。 |
| 参数 |
presetName:NSString，指定导出的预设模板的名称。asset:用于导出的 AVAsset对象。outputFileType:指示要检查的文件类型的AVFileType;或者nil，查询是否存在任何兼容类型。 completionHandler:使用兼容性结果调用的 block。 |
AVAssetExportSessionFileTypes
@property (nonatomic, readonly) NSArray<AVFileType> *supportedFileTypes;
根据初始化目标的预设，指示目标可以写入的文件类型。
不执行AVAsset检查以确定其内容是否与支持的文件类型兼容。如果你需要在启动导出之前做出该决定，请使用- （void）determineCompatibleFileTypesWithCompletionHandler：（void（^）（NSArray * compatibleFileTypes））handler :.
- (void)determineCompatibleFileTypesWithCompletionHandler:(void (^)(NSArray<AVFileType> *compatibleFileTypes))handler NS_AVAILABLE(10_9, 6_0);
| 函数名 | determineCompatibleFileTypesWithCompletionHandler: |
|---|---|
| 解释 | 对初始化对象的AVAsset和Preset执行检查，以确定ExportSession可以写入的文件类型列表。 |
| 参数 |
handler:当检查完成时，使用一组文件类型调用 ExportSession可以写入。请注意，这可能计为零。 |
| 备注 | 此方法与supportedFileTypes属性的不同之处在于，它执行AVAsset的检查，以确定其与每个会话支持的文件类型的兼容性。 |
AVAssetExportSessionDurationAndLength
@property (nonatomic) CMTimeRange timeRange;
指定要从源导出的时间范围。导出会话的默认timeRange为kCMTimeZero..kCMTimePositiveInfinity，表示将导出asset的完整持续时间。
@property (nonatomic, readonly) CMTime maxDuration API_AVAILABLE(macos(10.14), ios(4.0), tvos(9.0)) __WATCHOS_PROHIBITED;
根据源asset，导出预设和fileLengthLimit的当前值，提供对可能导出的介质的最大持续时间的估计。当export达到最大持续时间时，export不会停止;将timeRange属性设置为仅导出特定时间范围。
@property (nonatomic) long long fileLengthLimit API_AVAILABLE(macos(10.14), ios(4.0), tvos(9.0)) __WATCHOS_PROHIBITED;
表示导出文件的估计字节大小。导出预设为AVAssetExportPresetPassthrough或AVAssetExportPresetAppleProRes422LPCM时返回零。如果尚未设置timeRange属性的数值（即，not invalid，indefinite或infinite），则此属性也将返回零。
指示会话输出不应超过的文件长度。根据源asset的内容，输出可能略微超过文件长度限制。如果在使用输出之前需要遵守严格的限制，则应测试输出文件的长度。另请参见maxDuration和timeRange。
AVAssetExportSessionMetadata
@property (nonatomic, copy, nullable) NSArray<AVMetadataItem *> *metadata;
指定要由导出会话写入输出文件的AVMetadataItems的NSArray。如果此键的值为nil，则导出asset中的任何现有元数据将尽可能准确地转换为输出文件的相应元数据键空间并写入输出。
@property (nonatomic, retain, nullable) AVMetadataItemFilter *metadataItemFilter NS_AVAILABLE(10_9, 7_0);
指定在导出期间使用的过滤器对象，以确定应从源asset传输哪些元数据项。如果此键的值为nil，则不应用过滤器。这是默认值。过滤器不会应用于通过元数据属性设置的元数据。要在元数据属性上设置元数据之前将过滤器应用于元数据，详情请参阅AVMetadataItem的AVMetadataItemArrayFiltering类别中的方法。
AVAssetExportSessionMediaProcessing
@property (nonatomic, copy) AVAudioTimePitchAlgorithm audioTimePitchAlgorithm NS_AVAILABLE(10_9, 7_0);
指示用于管理缩放音频编辑的音频音调的处理算法。各种时间间距算法的常数，例如， AVAudioTimePitchAlgorithmSpectral，在AVAudioProcessingSettings.h中定义。如果将此属性设置为该文件中定义的常量以外的值，则将引发NSInvalidArgumentException。默认值为AVAudioTimePitchAlgorithmSpectral。
@property (nonatomic, copy, nullable) AVAudioMix *audioMix;
指示是否启用非默认音频混合以进行导出，并提供音频混合的参数。导出预设为AVAssetExportPresetPassthrough时忽略。
@property (nonatomic, copy, nullable) AVVideoComposition *videoComposition;
指示是否启用视频合成以进行导出，并提供视频合成的说明。导出预设为AVAssetExportPresetPassthrough时忽略。
@property (nonatomic, readonly, nullable) id <AVVideoCompositing> customVideoCompositor NS_AVAILABLE(10_9, 7_0);
表示使用的自定义视频合成器实例（如果有的话）。
AVAssetExportSessionMultipass
@property (nonatomic) BOOL canPerformMultiplePassesOverSourceMediaData NS_AVAILABLE(10_10, 8_0);
| 函数名 | canPerformMultiplePassesOverSourceMediaData |
|---|---|
| 解释 | 确定导出会话是否可以对源媒体执行多次传递以获得更好的结果。 |
| 备注 | 当此属性的值为YES时，导出会话可以以更长的导出时间为代价生成更高质量的结果。将此属性设置为YES还可能需要导出会话在导出期间将临时数据写入磁盘。要控制临时数据的位置，请使用属性directoryForTemporaryFiles。默认值为 NO。并非所有导出会话配置都可以通过源媒体执行多次传递而受益。在这些情况下，将此属性设置为YES无效。导出开始后无法设置此属性。 |
@property (nonatomic, copy, nullable) NSURL *directoryForTemporaryFiles NS_AVAILABLE(10_10, 8_0);
| 函数名 | directoryForTemporaryFiles |
|---|---|
| 解释 | 指定适合包含导出过程中生成的临时文件的目录 |
| 备注 | 当以某种方式配置时，AVAssetExportSession可能需要编写临时文件，例如当canPerformMultiplePassesOverSourceMediaData设置为YES时。此属性可用于控制文件系统中创建临时文件的位置。导出完成，取消或失败时，将删除所有临时文件。当此属性的值为 nil时，导出会话将在编写临时文件时选择合适的位置。默认值为nil。导出开始后无法设置此属性。如果 URL指向的位置不是目录，不存在，不在本地文件系统上，或者无法在此目录中创建文件（例如，由于权限不足或沙盒限制），导出将失败）。 |
| 上一章 | 目录 | 下一章 |
|---|
