You need to enable JavaScript to run this app.
导航
上传素材
最近更新时间:2024.08.23 21:05:34首次发布时间:2022.10.19 11:39:13

本文为您介绍如何使用 iOS 上传 SDK 以简单便捷的方式将素材上传至视频点播服务。上传 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 和 Category 取值说明

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,组成方式为 FileName = FilePrefix + FileTitle + FileExtension

注意

设置 FileName 时,必须带有文件后缀,如 .mp4、.mp3 等。

[self.materialUploadClient setFileName:<#filename#>];
// [self.materialUploadClient setFileName: @"path/to/foo/bar/test.mp4"];

上传控制

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

SDK 内部在执行此函数的时候,会新建线程,不会阻塞。实现开始上传的代码示例如下所示。
[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 错误码

BDVideoUploadInfo

参数

说明

vid

视频 Vid

oid

TOS 存储 key

md5

视频文件的 MD5

videoMetaInfo

媒资信息,例如:码率、格式、长度、宽高等, 代码示例如下所示。

{"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}

说明

媒资信息的详情请参见确认上传

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),
}];