本文为您介绍如何使用 Android 上传 SDK 以简单便捷的方式将视频上传至视频点播服务。
此文档适用于上传 SDK 1.32.2 及以上的版本,其他版本请参考 Android 视频上传 SDK(历史版本)。
已完成上传 SDK 的集成准备。
开发的过程中,建议打开 logcat 日志,便于调试,排查问题。
说明
Release 线上版本一定要关闭,目的是减少性能开销。
BDUploadLog.turnOn(LOG_DEBUG, 1); BDUploadUtil.setEnableNativeLog(true);
初始化操作是轻量的,建议放到 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 | |
AppName | String | 必填, App 英文名,从控制台应用管理获取。 |
AppVersion | String | 必填,App 版本号,可使用 |
AppChannel | String | 必填,渠道号。您可自定义,如小米应用商店 ( |
实现创建实例的代码示例如下所示。
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 | 否 | 文件前缀,路径字符串,支持多级路径,如 |
FileTitle | 否 | 文件名称。如您没有设置,SDK 会自动生成 32 位字符串作为文件名称。 |
FileExtension | 是 | 文件后缀。最终完整路径中必须包含 |
注意
具体的字符规则,请见文件命名通用字符规则。
您可参考以下示例代码设置云端存储路径。
// 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)
注意
素材不支持分类。
上传控制支持的操作开始上传、暂停上传和终止上传。
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 | 视频上传完成通知。调用 | 0,无意义 | 详见 BDVideoInfo |
MsgIsFlushComplete | 50 | 视频秒传完成通知。调用 | 0,无意义 | 详见 BDVideoInfo |
MsgIsFail | 2 | 视频上传失败通知。如果需重试,请调用 | 详见 BDVideoInfo | |
MsgIsUpdateProgress | 1 | 视频上传进度更新。 | 上传进度。取值范围为[0,100] | 无需关注 |
MessageIsDiskResumeInfoError | 120 | sdk 发现无法走断点续传时回调,同时 fallback 到普通上传;接入方最终会得到上传成功或失败的回调。 | -1,无意义 | 无需关注 |
调用 setPoster
设置视频自动抽帧时间点,单位为秒。设置成功后,上传 SDK 将根据您设置的固定时间点截取视频帧,作为视频的封面图。示例代码如下:
// 单位为秒,默认值为 0 public void setPoster(float posterTime)
如想开启断点续传功能,您需要调用 setSDKConfigDir
和 setDiskResumeOption
。开启断点续传后,用户在您的应用中上传文件时,如果发生强制退出应用等情况导致上传中断,下次上传同一个文件时,上传 SDK 会自动获取断点,并从断点处继续上传,从而节省上传时间。
示例代码如下:
// 指定断点续传配置文件存放目录,上传 SDK 需要有读写权限,初始化后全局设置 1 次即可。 BDUploadUtil.setSDKConfigDir(dir) // 开启断点续传,每个 Uploader 实例都需设置。 mUploader.setDiskResumeOption(1);
说明
通过 Reader
设置的上传文件不支持断点续传。
如果您的业务场景无需实时抽取 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)
调用 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) -> { // 调用接入方日志回溯接口 });
参数 | 说明 |
---|---|
mVideoId | 视频 ID,即视频点播服务为音视频类型资源生成的 Vid。 |
mMid | 素材 ID,即视频点播服务为素材类型资源生成的 Mid。 |
mCoverUri | 封面 URI。 |
mTosKey | TOS 存储 key。 |
mErrorCode | 错误码。详见上传 SDK 错误码。 |
mErrorMsg | 错误信息。 |
mVideoMediaInfo | 媒资信息,包含码率、格式、长度、宽高等。示例如下:
说明 媒资信息详情请参见确认上传中的 |
mCallbackArgs | 透传服务端回调信息。 |
mLog | 为空,目前不使用。 |
mProgress | 上传进度。取值范围为 [0,100]。 |
mEncryptionMeta | 为空,目前不使用。 |