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

前提条件

已完成集成 SDK。

基础功能

初始化 SDK

// 引入头文件
import { TTUploaderUtil} from '@bytedance/bduploader';

// 初始化 SDK，App 生命周期内只需初始化一次
if (this.mSDKInit == 0) {
  // 开启日志调试
  TTUploaderUtil.setEnableNativeLog(1); // 0: disable native log, 1: enable native log
  TTUploaderUtil.init(getContext(this).getApplicationContext());
  this.mSDKInit = 1;
}

创建实例

// 引入头文件
import {
  TTVideoUploader,
  UploadType,
  BDVideoInfo,
  LogInfo,
  VideoInfoListener,
  TTVideoUploadNotifier,
} from '@bytedance/bduploader';

// 创建 videoUploader 示例
this.videoUploader = new TTVideoUploader();

设置待上传文件

// 设置待上传文件的路径
this.videoUploader.setPathName(this.filePath); 

设置鉴权

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

this.videoUploader.setTopAccessKey(this.accessKey); // 设置 AK
this.videoUploader.setTopSecretKey(this.secretKey); // 设置 SK
this.videoUploader.setTopSessionToken(this.sts2Token) // 设置 STSToken

设置上传域名和地域

// 如无特殊情况，请传入如下默认值
this.videoUploader.setUploadDomain("vod.volcengineapi.com"); // 设置上传域名
this.videoUploader.setRegionName("cn-north-1"); // 设置上传地域

设置空间

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

this.videoUploader.setSpaceName(this.spaceName); // 设置空间名称

设置云端存储路径

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

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

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

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

参数说明如下表所示。

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

// 设置完整的 fileName
if (this.fileName.length > 0) {
  this.videoUploader.setFileName(this.fileName);
}

// 设置前缀 
if (this.filePrefix.length > 0) {
  this.videoUploader.setFilePrefix(this.filePrefix);
}

// 设置后缀
if (this.fileExtension.length > 0) {
  this.videoUploader.setFileExtension(this.fileExtension);
}

设置分类

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

if (this.classificationId > 0) {
  this.videoUploader.setClassificationId(this.classificationId);
}

上传控制

// 开始或恢复上传
private async startVideoUploader(): Promise<void> {
  await this.videoUploader?.start();
}

// 暂停上传
private async stopVideoUploader(): Promise<void> {
  await this.videoUploader?.stop();
}

// 终止上传
public async closeVideoUploader(): Promise<void> {
  await this.videoUploader?.close();
  this.videoUploader = undefined;
}

设置回调

详情请见回调说明。

// 设置回调
let listener = new UploaderVideoListener(this.videoUploader, this);
this.videoUploader.setVideoInfoListener(listener);

// 监听回调
export class UploaderVideoListener implements VideoInfoListener {
  private videoUploader?: TTVideoUploader;

  constructor(videoUploader: TTVideoUploader, uploaderPage: UploaderPage) {
    this.videoUploader = videoUploader;
  }

  // 上传进度和上传状态回调。详见 [onNotify 说明](https://www.volcengine.com/docs/4/147563#%E8%AE%BE%E7%BD%AE%E5%9B%9E%E8%B0%83)
  async onNotify(what: number, info: BDVideoInfo): Promise<void> {
    hilog.info(0x0000, 'UploaderVideoListener', 'onNotify:%{public}d', what);
    if (what == TTVideoUploadNotifier.MsgIsComplete) {
      await this.uploaderPage.closeVideoUploader();
    } else if (what == TTVideoUploadNotifier.MsgIsFail) {
      await this.uploaderPage.closeVideoUploader();
    } else if (what == TTVideoUploadNotifier.MsgIsUpdateProgress) {
    } else if (what == TTVideoUploadNotifier.MsgIsFlushComplete) {
    } else if (what == TTVideoUploadNotifier.MessageIsDiskResumeInfoError) {
    } 
  }

  // 关键日志回调，您可将回调信息上传到您的服务器，可通过日志排查线上问题。
  // 不使用空实现即可。
  onLog(what: number, info: LogInfo): void {
    hilog.info(0x0000, 'UploaderVideoListener', 'onLog:%{public}s', info);
  }
}

进阶功能

设置封面图抽帧时间

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

this.videoUploader.setPoster(this.posterTime); // 单位为秒，默认值为 0

设置回调透传参数

该参数值会通过 FileUploadComplete 回调中的 CallbackArgs 参数返回给您的服务端。示例代码如下：

this.videoUploader.setServerParameter(this.serverParam); // 设置回调参数

设置工作流 ID

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

this.videoUploader.setTemplateId(this.templateId);

设置全异步抽取 Meta

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

this.videoUploader.setGetMetaMode(this.getMetaMode); // 1 = async, 0 = sync

自定义上传配置

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

// 是否开启 HTTPS
this.videoUploader.setEnableHttps(this.enableHttps); 

// 设置分片上传的分片大小，单位为 byte，默认值为 512 * 1024
if (this.sliceSize > 0) {
  this.videoUploader.setSliceSize(this.sliceSize);
}

// 开启并行上传的线程数，默认值为 1
if (this.socketNum > 0) {
  this.videoUploader.setSocketNum(this.socketNum);
}

// 设置 SDK 总建连超时时间，单位为秒，默认值为 300
if (this.timeoutSec > 0) {
    this.videoUploader.setSDKMaxRetryTimeout(this.timeoutSec);
}