本文为您介绍如何使用 Android 上传 SDK 以简单便捷的方式将素材上传至视频点播服务。上传 SDK 支持上传字幕、封面图、预告片、音频等素材。

适用版本

此文档适用于上传 SDK 1.32.2 及以上的版本，其他版本请参考Android 素材上传 SDK（历史版本）。

前提条件

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

基础功能

日志调试

开发的过程中，建议打开 logcat 日志，便于调试，排查问题。

BDUploadLog.turnOn(LOG_DEBUG, 1);
BDUploadUtil.setEnableNativeLog(true);

初始化 SDK

初始化操作是轻量的，建议放到 Application#onCreate 中执行，保障初始化顺序。

Env.init(new Config.Builder()
        .setApplicationContext(context)
        .setAppID("your app id")
        .setAppName("your app English name")
        // 合法版本号应大于、等于 3 位，如："1.3.2"
        .setAppVersion(BuildConfig.VERSION_NAME)
        .setAppChannel("channel name")
        .build());

详细的参数说明如下表所示。

创建实例

实现创建实例的代码示例如下所示。

BDMaterialUploader mUploader = new BDMaterialUploader();

设置上传的文件

设置上传的文件，支持 2 种方式，任选其一。

mUploader.setPathName("/data/user/0/xxx/files/test.mp4"); 

mUploader.setMediaDataReader(reader) 

设置鉴权参数

您需要在应用服务端通过视频点播服务端 SDK 签发临时上传 Token，下发给客户端，再设置给 SDK。鉴权参数说明详见客户端上传。实现的代码示例如下所示。

mUploader.setTopAccessKey("xxx");
mUploader.setTopSecretKey("xxx");
mUploader.setTopSessionToken("xxx");

设置空间

实现设置空间的代码示例如下所示。空间相关说明请参考空间管理。

mUploader.setSpaceName("xxx");

设置云端存储路径

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

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

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

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

参数说明如下表所示。

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

// FileName = FilePrefix + FileTitle + FileExtension
// 例 1，云端的存储路径：tos-pathxxx/volc/test.mp4
mUploader.setFileName("volc/test.mp4"); 
// 例 2，云端的存储路径：tos-pathxxx/test.mp4
mUploader.setFileName("test.mp4");

// 设置后缀，必须设置，需要以 . 开头，如 .mp4、.mp3 等。
mUploader.setFileExtension(".mp4"); 
// 设置前缀，可选设置，需要以 / 结尾
mUploader.setFilePrefix("volc/"); 

// 例 1，云端的存储路径: tos-pathxxx/volc/b8bb180086f945709dfda76bc9c6133d.mp4
mUploader.setFileExtension(".mp4"); 
mUploader.setFilePrefix("volc/"); 

// 例 2，云端的存储路径: tos-pathxxx/b8bb180086f945709dfda76bc9c6133d.mp4
mUploader.setFileExtension(".mp4");

设置素材信息

设置素材信息接口的代码示例如下所示。

public void setFileType(String fileType)
public void setTitle(String title)
public void setTags(String tags)
public void setDescription(String description)
public void setCategory(String category)
public void setFormat(String format) 

详细的参数说明如下表所示。

FileType 取值和 Category 对应关系如下表所示。

上传控制

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

mUploader.start();

mUploader.stop();

mUploader.close()

设置回调

回调的线程：在 A 线程创建 Uploader 实例，如果 A 线程存在 Looper，则在 A 线程回调；否则在主线程回调。

public void setListener(BDMaterialUploaderListener listener)

public interface BDMaterialUploaderListener {
    // 上传进度和上传状态的回调，详见下表 onNotify 回调说明
    void onNotify(int what, long parameter, BDVideoInfo info);
    
    // 关键日志回调，接入方可将回调信息上传到自己的服务器，可通过日志排查线上问题。
    // 需要通过 mUploader.setEnableLogCallBack(true) 开启才能生效。
    // 不使用空实现即可。
    void onLog(int what, int code, String info);
    
    // 上传出错重试时回调；由接入方检查网络状态，
    // 返回 1 sdk 认为有网，进行重试；
    // 返回 0 sdk 认为无网，不再进行重试
    // 如接入方不想检查网络状态，返回 1 即可，SDK 会在重试次数、超时时间内重试。
    int videoUploadCheckNetState(int errorCode, int tryCount);

    // 暂未使用
    String getStringFromExtern(int key);
}

onNotify 回调说明如下表所示。

进阶功能

断点续传

实现的代码示例如下所示。

// 指定断点续传配置文件存放目录，上传 sdk 需要有读写权限，初始化后全局设置 1 次即可。
BDUploadUtil.setSDKConfigDir(dir)

// 打开断点续传，每个 Uploader 实例都需设置
mUploader.setDiskResumeOption(1);

其他配置

实现的代码示例如下所示。

// 分片上传设置分片大小，单位 byte，默认值 512 * 1024；
public void setSliceSize(int size)

// 开启并行上传的线程数，默认值 1
public void setSocketNum(int num)  

// 单次tcp 建连超时，单位 ms， 默认值 5000
public void setTcpOpenTimeOutMilliSec(int openTimeOutMilliSec) 

// 单个分片传输超时，单位 s，默认 40
public void setRWTimeout(int timeOut) 

// 总的建联超时，单位 s，默认 70
public void setMaxFailTime(int maxTime)

// 系统 socket 单次读写超时，单位 s，默认 10
public void setTranTimeOutUnit(int tranTimeOutUnit)

// 复用连接的超时时间，防止老连接质量变差，导致的上传速度变慢，单位 s，默认 6
public void setAliveMaxFailTime(int maxFailTime)

// 分片重试次数，默认值 2
public void setSliceReTryCount(int retryCount) 

// 文件级别的重试次数，默认值 3
public void setFileRetryCount(int retryCount)

// 接入方自定义参数，如"testkey=testValue" 
public void setServerParameter(String value)

// 开启 https，设置 1 为全开启
public void setEnableHttps(int isEnableHttps)