本文为您介绍如何使用 iOS 上传 SDK 以简单便捷的方式将视频上传至视频点播服务。

适用版本

此文档适用于上传 SDK 1.32.2 及以上版本，其他版本请参考 iOS 视频上传 SDK（历史版本）。

前提条件

• 已集成 SDK。
• 在视频点播控制台创建空间。
• 在视频点播控制台创建应用并获取 App ID。详情请见应用管理。

基础功能

初始化 SDK

参考以下示例代码初始化上传 SDK：

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // 初始化 TTSDK
    [self initTTSDK];
    
    return YES;
}
 
- (void)initTTSDK {
    // 开启上传模块调试日志，建议 Debug 阶段保持开启，便于排查问题。
#if DEBUG
    [[BDUploadUtilTool sharedInstance] enableNativeLogFunc:YES];
#endif

    // 请在视频点播控制台应用管理页面获取 AppID
    // NSString *appId = @"you app id";
    // 注意，如果需要集成 TTSDK 其他模块，请设置 licenseName。
    // 如果没有，则 licenseName 参数可以移除。
    TTSDKConfiguration *configuration = [TTSDKConfiguration defaultConfigurationWithAppID:<#appid#> licenseName:licenseName];
    [TTSDKManager startWithConfiguration:configuration];
}

初始化视频上传实例

#import <TTSDK/BDFileUploaderHeader.h>

- (void)initVideoUploader {
    // 1. 初始化视频上传对象，需要传入视频文件路径
    // NSString *filePath = @"path/to/upload/file";
    BDVideoUploaderClient *videoUploadClient = [[BDVideoUploaderClient alloc] initWithFilePath:<#filepath#>];
  
    // 2. 设置鉴权参数。您需要在应用服务端通过视频点播服务端 SDK 签发临时上传 Token，下发给客户端，再设置给 SDK。鉴权参数说明详见[客户端上传](https://www.volcengine.com/docs/4/3151)
    //NSDictionary *authParameter = @{
    //    BDFileUploadAccessKey: accessKeyId,
    //    BDFileUploadSecretKey: secretKeyId,
    //    BDFileUploadSessionToken: sessionToken,
    //    空间相关说明请参考[空间管理](https://www.volcengine.com/docs/4/65669)
    //    BDFileUploadSpace: uploadSpace,
    //};
    [videoUploadClient setAuthorizationParameter:<#authparameter#>];
    
    // 3. 按照接入方需要，配置需要自定义设置的参数
    // 此方法可以在上传开始之前调用多次，
    // SDK 将根据传入的 dictonary 对上传实例进行增量或覆盖
    [videoUploadClient setUploadConfig:@{
        // 指定文件分片大小
        BDFileUploadSliceSize:@(512 * 1024),
    }];
    
    // 4. 设置上传实例的 delegate
    //  @see {BDVideoUploadClientDelegate.h}
    videoUploadClient.delegate = self;
    
    // 5. 全局持有上传对象
    self.videoUploadClient = videoUploadClient;
}

设置云端存储路径

文件上传完成后的云端存储路径形式如下：

StoreUri = {{BucketName}}/{{FilePrefix}}{{FileTitle}}{{FileExtension}}

以下为一个完整的云端存储路径示例。

ASmapleBucketName/path/to/foo/bar/test.mp4

参数说明如下表所示。

您可参考以下示例代码设置云端存储路径。

// FileName = FilePrefix + FileTitle + FileExtension
[self.videoUploadClient setFileName:<#filename#>];

// 设置前缀, 以 / 结尾
[self.videoUploadClient setFilePrefix:<#fileprefix#>];
// 设置后缀，需要以点开头，例：.mp4，.flv，.mp3
[self.videoUploadClient setFileExtension:<#fileextension#>];

设置分类

调用 setClassificationId 方法传入分类 ID，从而对视频进行分类。您可在视频点播控制台指定空间内的分类管理页面创建分类并获取分类 ID，具体请见分类管理。示例代码如下：

- (void)setClassificationId:(NSInteger)classificationId;

上传控制

上传控制支持的操作有开始上传、暂停上传和终止上传。

[self.videoUploadClient start];

[self.videoUploadClient stop];

[self.videoUploadClient close];

设置回调

您可以设置回调获取视频上传结果和上传进度。代码示例如下所示。

#pragma mark - BDVideoUploadClientDelegate

/// 视频上传完成回调
/// @param uploadClient 视频上传实例
/// @param videoInfo 视频上传完成后回调的信息
/// @param error 如果上传失败，则会返回 error
- (void)videoUpload:(nonnull BDVideoUploaderClient*)uploadClient didFinish:(nullable BDVideoUploadInfo *)videoInfo error:(nullable NSError *)error {
    if (!error) {
       // 视频上传成功
    } else {
       // 视频上传失败 
       // 可以根据 BDVideoUploadInfo 的详细信息，判断上传错误的具体原因。详见 [BDVideoUploadInfo](https://www.volcengine.com/docs/4/147579#bdvideouploadinfo)
       NSLog  
    }
    // 释放上传对象
    [uploadClient close];
}
 
/// 视频上传进度回调
/// @param uploadClient 视频上传对象
/// @param progress 视频上传的进度
- (void)videoUpload:(nonnull BDVideoUploaderClient*)uploadClient progressDidUpdate:(NSInteger)progress {
    // NSLog(@"progress update:%ld", progress);
}

如果上传失败，则会返回 error。SDK 错误码和网关错误码在 NSError 中存储的位置不同。具体位置如下所示。

- (void)videoUpload:(nonnull BDVideoUploaderClient*)uploadClient didFinish:(nullable BDVideoUploadInfo *)videoInfo error:(nullable NSError *)error {
    if (!error) {
        // 上传成功
    } else {
        // 上传失败
        // 获取 SDK 错误码
        NSLog(@"SDK error code is: %ld", error.code);
        // 如果存在网关错误码，网关错误码会包含在 NSError.userInfo 中，可以根据需要进行解析
        if ([error.userInfo isKindOfClass:NSDictionary.class]) {
            NSLog(@"error message is: %@", error.userInfo[@"message"]);
        }
    }
    // 释放上传对象
    [uploadClient close];
}

具体错误码含义和建议处理方式请见上传 SDK 错误码。

进阶功能

设置封面图抽帧时间

调用 setSnapshot 设置视频自动抽帧时间点，单位为秒。设置成功后，上传 SDK 将根据您设置的固定时间点截取视频帧，作为视频的封面图。示例代码如下：

[self.videoUploadClient setSnapshot:<#CGFloat#>];

开启断点续传

如想开启断点续传功能，您需在每次初始化上传对象后、开始上传之前，调用 setUploadConfig 并设置 BDFileUploadDiskResumeOption。开启断点续传后，用户在您的应用中上传文件时，如果发生强制退出应用等情况导致上传中断，下次上传同一个文件时，上传 SDK 会自动获取断点，并从断点处继续上传，从而节省上传时间。
示例代码如下：

- (void)initVideoUploader {
    ......
 
    [videoUploadClient setUploadConfig:@{
       // 开启断点续传功能： 
        // 1：开启。任务中断后，从断点处续传。
        // 0：关闭。任务中断后，重新开始上传。
        BDFileUploadDiskResumeOption: @(1),
    }];
    
    ......
}

设置全异步抽取 Meta

如果您的业务场景无需实时抽取 Meta，则可以使用全异步抽取 Meta 的能力，提升上传速度。您需要调用 setGetMetaMode 并将 mode 设为 BDVideoUploadGetMetaModeAsync。示例代码如下：

- (void)setGetMetaMode:(BDVideoUploadGetMetaMode)mode;

自定义上传配置

上传 SDK 支持自定义上传配置。您可在开始上传前调用 setUploadConfig 方法进行配置。setUploadConfig 方法的原型如下：

- (void)setUploadConfig:(NSDictionary*)config;

其中 config dictionary 可选字段和取值类型说明如下表所示。

以 BDFileUploadSliceSize 为例，设置上传文件分片大小的示例代码如下：

[self.videoUploadClient setUploadConfig:@{
    // 设置文件分片大小为 512 KB
    BDFileUploadSliceSize:@(512 * 1024),
}];

设置回调透传参数

调用 setRequestParameter 设置回调透传参数。该参数值会通过 FileUploadComplete 回调中的 CallbackArgs 参数返回给您的服务端。示例代码如下：

[self.uploader setRequestParameter:@[BDFileUploadCustomedParameter: ""]]

设置工作流 ID

调用 setTemplateId 方法传入工作流 ID，从而触发媒体处理任务。您可在视频点播控制台指定空间内的工作流页面获取工作流 ID，具体详见工作流。

- (void)setTemplateId:(NSString *)templateId;

日志回调

如果您具备日志回溯的能力，想要获取线上日志并分析问题，SDK 提供以下接口将 SDK 日志回调给接入方。

[[BDUploadUtilTool sharedInstance] setLogCallback:^(NSString *info, int level) {
    NSLog(@"custom_log:%@", info);
}];

参考信息

BDVideoUploadInfo

{"Bitrate":463419,"Duration":39.726999999999997,"FileType":"video","Format":"MP4","Height":360,"Md5":"53f62abe3c29d0654b3405af7***7060","Size":2301285,"StoreUri":"tos-vod-cn-v-309be6ba73***b04/cd404e7bef654554b638422***7c0c40","Width":640}