本文为您介绍如何使用 iOS 上传 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. 设置鉴权参数。您需要在应用服务端通过视频点播服务端 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,
// BDFileUploadServiceID: serviceId
//};
[materialUploadClient setAuthorizationParameter:<#authparameter#>];
// 3. 按照接入方需要,配置需要自定义设置的参数。
[materialUploadClient setUploadConfig:@{
// 指定文件分片大小
BDFileUploadSliceSize:@(512 * 1024),
}];
// 4. 素材上传必需的参数
// 素材上传时服务端会对 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 和 Category 取值说明
FileType(String) | Category(String) | 说明 |
---|---|---|
media | video | 视频文件 |
audio | 音频文件 | |
image | image | 静态图片 |
dynamic_img | 动态图片 | |
object | subtitle | 字幕 |
font | 字体文件 |
文件上传完成后的云端存储路径形式如下:
StoreUri = {{BucketName}}/{{FilePrefix}}{{FileTitle}}{{FileExtension}}
以下为一个完整的云端存储路径示例。
ASmapleBucketName/path/to/foo/bar/test.mp4
参数说明如下表所示。
参数 | 是否必选 | 说明 |
---|---|---|
BucketName | N/A | 存储桶名称,您无需设置。 |
FilePrefix | 否 | 文件前缀,路径字符串,支持多级路径,如 |
FileTitle | 否 | 文件名称。如您没有设置,SDK 会自动生成 32 位字符串作为文件名称。 |
FileExtension | 是 | 文件后缀。最终完整路径中必须包含 |
注意
具体的字符规则,请见文件命名通用字符规则。
您可参考以下示例代码设置云端存储路径。
// FileName = FilePrefix + FileTitle + FileExtension
[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 的详细信息,判断上传错误的具体原因。详见 [BDVideoUploadInfo](https://www.volcengine.com/docs/4/147579#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 错误码。
上传 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),
}];