本文为您介绍如何使用 iOS 上传 SDK 以简单便捷的方式将素材上传至视频点播服务。上传 SDK 支持上传字幕、封面图、预告片、音频等素材。
已完成上传 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]; }
注意
需要注意 BDMaterialUploaderClient
实例的生命周期,不能设置为局部变量。如果设置为局部变量,当变量离开作用域后,实例会被销毁从而导致上传失败。
- (void)initMaterialUploader { // 1. 初始化素材上传对象,需要传入素材文件路径 // NSString *filePath = @"path/to/upload/file"; BDMaterialUploaderClient *materialUploadClient = [[BDMaterialUploaderClient alloc] initWithFilePath:<#filepath#>]; // 2. 设置鉴权。鉴权参数需要接入方向自己的 Server 端获取 //NSDictionary *authParameter = @{ // BDFileUploadAccessKey: accessKeyId, // BDFileUploadSecretKey: secretKeyId, // BDFileUploadSessionToken: sessionToken, // 空间相关说明请参考空间管理: // BDFileUploadSpace: uploadSpace, // BDFileUploadServiceID: serviceId //}; [materialUploadClient setAuthorizationParameter:<#authparameter#>]; // 3. 按照接入方需要,配置需要自定义设置的参数。 [materialUploadClient setUploadConfig:@{ // 指定文件分片大小 BDFileUploadSliceSize:@(512 * 1024), }]; // 4. 素材上传必需的参数 // @note: 素材上传时服务端会对 filetype 和 category 进行校验,需要注意映射关系,见下方。 [materialUploadClient setRequestParameter:@{ BDFileUploadFileTypeStr: <#filetype#>, }]; [materialUploadClient setCategory:<#category#>]; // 5. 素材上传独有的参数 [materialUploadClient setTitle:<#title#>]; [materialUploadClient setTags:<#tags#>]; // e.g. @"testMateTag,testMateTagOne" [materialUploadClient setDescription:<#description#>]; [materialUploadClient setFormat:<#format#>]; // e.g. @"mp4" // 6. 设置上传实例的 delegate // @see {BDVideoUploadClientDelegate.h} materialUploadClient.delegate = self; // 7. 全局持有上传对象 self.materialUploadClient = materialUploadClient; }
详细的素材参数说明如下表所示。
参数 | 类型 | 描述 |
---|---|---|
Title | String | 标题 |
Tags | String | 多个标签可用逗号隔开 |
Description | String | 描述信息 |
Format | String | 格式。若传入 Format 的话,以您传入参数为准,否则以系统识别出的 Format 为准。若遇到特殊文件无法识别,Format 可能为空。 |
FileType(String) | Category(String) | 说明 |
---|---|---|
media | video | 视频文件 |
audio | 音频文件 | |
image | image | 静态图片 |
dynamic_img | 动态图片 | |
object | subtitle | 字幕 |
font | 字体文件 |
上传完成后,文件在云端的存储路径形式如下所示。StoreUri = {{BucketName}}/{{FilePrefix}}{{FileTitle}}{{FileExtension}}
其中BucketName
不需要接入方设置,其他几个参数说明如下表示。
参数 | 含义 | 是否必选 | 描述 |
---|---|---|---|
FilePrefix | 文件前缀 | 否 | 路径字符串,支持多级路径(如 path/to/foo/bar/) |
FileTitle | 文件标题 | 否 | 如果不手动设置,SDK 会自动生成 32 位字符串作为文件标题 |
FileExtension | 文件后缀 | 是 | 最终完整路径中必须包含 FileExtension,否则会上传失败。 |
例如:ASmapleBucketName/path/to/foo/bar/test.mp4
,则对应关系如下所示。
参数(示例) | 含义 | 描述 |
---|---|---|
ASmapleBucketName/ | 存储桶名称 | 接入方不用设置。 |
path/to/foo/bar/ | 文件前缀 | 可选。 |
test | 文件标题 | 可选;如果不设置,SDK 会自动生成一个 32 位字符串作为文件名。 |
.mp4 | 文件后缀 | 必传;不传报错。 |
设置云端存储路径,支持 2 种方式。您可根据自身需求,任选其一。
注意
设置 FileName 时,必须带有文件后缀,如 .mp4、.mp3 等。
[self.materialUploadClient setFileName:<#filename#>]; // [self.materialUploadClient setFileName: @"path/to/foo/bar/test.mp4"];
上传控制支持的操作有开始上传、暂停上传和终止上传。
[self.materialUploadClient start];
注意
上传完成后,请调用 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) { // 素材上传成功 // 可以根据 BDVideoUploadInfo 的详细信息,判断上传错误的具体原因。详见下文说明 } else { // 素材上传失败 } // 释放上传对象 [uploadClient close]; } /// 素材上传进度回调 /// @param uploadClient 素材上传对象 /// @param progress 素材上传的进度 - (void)videoUpload:(nonnull BDVideoUploaderClient*)uploadClient progressDidUpdate:(NSInteger)progress { // NSLog(@"progress update:%ld", progress); }
如果上传失败,SDK 会返回 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 错误码。
参数 | 说明 |
---|---|
vid | 视频 Vid |
oid | TOS 存储 key |
md5 | 视频文件的 MD5 |
videoMetaInfo | 媒资信息,例如:码率、格式、长度、宽高等, 代码示例如下所示。
说明 媒资信息的详情请参见确认上传。 |
encryptionInfo | 为空,目前不使用。 |
coverURI | 封面 Uri |
callbackArgs | 透传服务端回调信息 |
上传 SDK 还支持一些自定义配置,您可以根据需要,在开始上传前,调用 setUploadConfig
方法进行配置。
- (void)setUploadConfig:(NSDictionary*)config;
其中 config dictionary 可选字段和取值类型说明如下表所示。
字段名 | 类型 | 说明 |
---|---|---|
BDFileUploadSliceSize | NSNumber(NSInteger) | 设置分片大小,单位:byte,默认 512KB |
BDFileUploadSocketNum | NSNumber(NSInteger) | 分片上传时的并发连接数 |
BDFileUploadTcpOpenTimeOutMilliSec | NSNumber(NSInteger) | 单次tcp 建连超时,单位: ms, 默认值 5000 |
BDFileUploadMaxFailTimes | NSNumber(NSInteger) | 建立连接超时,单位:s |
BDFileUploadRWTimeout | NSNumber(NSInteger) | 单个分片传输超时时间,单位: s,默认值 40 |
BDFileUploadSliceRetryCount | NSNumber(NSInteger) | 单分片上传可以重试的次数 |
BDFileUploadFileRetryCount | NSNumber(NSInteger) | 文件级别的上传重试次数 |
BDFileUploadTranTimeOutUnit | NSNumber(NSInteger) | 系统 socket 单次读写超时,单位:s,默认 70 |
BDFileUploadAliveMaxFailTime | NSNumber(NSInteger) | 复用连接的超时时间 |
BDFileUploadHttpsEnable | NSNumber(BDUploadHttpsOpen) | 开启https,可以根据上传阶段分步开 |
如下为实现的示例代码。
[self.materialUploadClient setUploadConfig:@{ // 指定文件分片大小, 512KB BDFileUploadSliceSize:@(512 * 1024), }];