You need to enable JavaScript to run this app.
导航
上传视频
最近更新时间:2024.11.05 11:38:04首次发布时间:2022.10.17 21:06:08

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

适用版本

此文档适用于上传 SDK 1.32.2 及以上的版本,其他版本请参考 Android 视频上传 SDK(历史版本)

前提条件

已完成上传 SDK 的集成准备

基础功能

日志调试

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

说明

Release 线上版本一定要关闭,目的是减少性能开销。

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());

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

参数

类型

说明

AppId

String

必填,App ID,从控制台应用管理获取。详情请参见管理应用

AppName

String

必填, App 英文名,从控制台应用管理获取。

AppVersion

String

必填,App 版本号,可使用 BuildConfig.VERSION_NAME。合法版本号应包含大于、等于 2 个分隔符,如 "1.3.2"。

AppChannel

String

必填,渠道号。您可自定义,如小米应用商店 (xiaomi)、华为应用市场 (huawei) 等。

创建实例

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

BDVideoUploader mUploader = new BDVideoUploader();

设置上传的文件

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

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

设置鉴权

您需要在应用服务端通过视频点播服务端 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

参数说明如下表所示。

参数

是否必选

说明

BucketName

N/A

存储桶名称,您无需设置。

FilePrefix

文件前缀,路径字符串,支持多级路径,如 path/to/foo/bar/。文件前缀必须以 / 结尾,否则会上传失败。

FileTitle

文件名称。如您没有设置,SDK 会自动生成 32 位字符串作为文件名称。

FileExtension

文件后缀。最终完整路径中必须包含 FileExtension,否则会上传失败。文件后缀需以 . 开头,如 .mp4.mp3

注意

具体的字符规则,请见文件命名通用字符规则

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

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

设置分类

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

public void setClassificationId(long classificationId)

注意

素材不支持分类。

上传控制

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

SDK 内部在执行此函数的时候,会新建线程,不会阻塞。实现开始上传的代码示例如下所示。
mUploader.start();

注意

上传完成后,请调用 close() ,否则会内存泄漏。

设置回调

回调的线程:在 A 线程创建 Uploader 实例,如果 A 线程存在 Looper,则在 A 线程回调;否则在主线程回调。

public void setListener(BDVideoUploaderListener listener)

public interface BDVideoUploaderListener {
    // 上传进度和上传状态的回调,详见下表 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 回调说明如下表所示。

消息类型

返回的 what 值

说明

对应 parameter 含义

对应 info 含义

MsgIsComplete

0

视频上传完成通知。调用 close() 来释放上传对象。

0,无意义

详见 BDVideoInfo

MsgIsFlushComplete

50

视频秒传完成通知。调用 close() 来释放上传对象。

0,无意义

详见 BDVideoInfo

MsgIsFail

2

视频上传失败通知。如果需重试,请调用 start() 重新上传;否则调用 close()来释放上传对象。

详见上传 SDK 错误码

详见 BDVideoInfo

MsgIsUpdateProgress

1

视频上传进度更新。

上传进度。取值范围为[0,100]

无需关注

MessageIsDiskResumeInfoError

120

sdk 发现无法走断点续传时回调,同时 fallback 到普通上传;接入方最终会得到上传成功或失败的回调。

-1,无意义

无需关注

进阶功能

设置封面图抽帧时间

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

// 单位为秒,默认值为 0
public void setPoster(float posterTime)

开启断点续传

如想开启断点续传功能,您需要调用 setSDKConfigDirsetDiskResumeOption。开启断点续传后,用户在您的应用中上传文件时,如果发生强制退出应用等情况导致上传中断,下次上传同一个文件时,上传 SDK 会自动获取断点,并从断点处继续上传,从而节省上传时间。
示例代码如下:

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

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

说明

通过 Reader 设置的上传文件不支持断点续传。

设置全异步抽取 Meta

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

mUploader.setGetMetaMode(GET_META_ASYNC); 

自定义上传配置

上传 SDK 还支持分片上传等功能,您可以设置分片大小、开启并行上传的线程数等能力。实现的代码示例如下所示。

// 分片上传设置分片大小,单位为 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)

// 开启 HTTPS,设置 1 为全开启
public void setEnableHttps(int isEnableHttps)

设置回调透传参数

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

// 需要携带的自定义参数,例如:"appid=123&did=123456&uid=12345&Region=xxx&StoreRegion=xxx"
public void setServerParameter(String value)

设置工作流 ID

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

// 设置工作流 ID
mUploader.setTemplateId(templateId);

日志回调

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

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

/**
 * 开启日志回调,传参
 * LOG_PRINT_NONE  本地不打印日志、也不回调日志
 * LOG_PRINT_LOCAL 仅本地打印日志
 * LOG_PRINT_CALL_BACK 仅回调日志
 * LOG_PRINT_BOTH 本地打印日志,并且回调日志
 */
BDUploadLog.setLogPrintType(LOG_PRINT_BOTH);

/**
 * 日志信息会通过此接口回调
 * @param level 日志级别
 * @param tag 日志 tag
 * @param msg 日志内容
 */
BDUploadLog.setALogCallback((level, tag, msg) -> {
    // 调用接入方日志回溯接口
});

参考信息

BDVideoInfo

参数

说明

mVideoId

视频 ID,即视频点播服务为音视频类型资源生成的 Vid。

mMid

素材 ID,即视频点播服务为素材类型资源生成的 Mid。

mCoverUri

封面 URI。

mTosKey

TOS 存储 key。

mErrorCode

错误码。详见上传 SDK 错误码

mErrorMsg

错误信息。

mVideoMediaInfo

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

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

说明

媒资信息详情请参见确认上传中的 SourceInfo 参数。

mCallbackArgs

透传服务端回调信息。

mLog

为空,目前不使用。

mProgress

上传进度。取值范围为 [0,100]。

mEncryptionMeta

为空,目前不使用。