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

前提条件 #

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

基础功能 #

初始化 SDK #

参考以下代码初始化 SDK。您可根据实际情况自主选择是否接入 SDK 的日志上报功能。强烈建议您启用该功能模块，若您无需使用日志上报或不希望隐私数据被采集，请在初始化前时将 openAppLog 指定为 false。

EnvOptions options = EnvOptions(
  appID: '123456',
  appChannel: 'appChannel',
  appVersion: '1.0.0',
  appName: "FlutterUploadDemo",
  openAppLog: true,
  autoStartAppLog: true,
  debugLogLevel: true,
  enableLocalLogPrint: true,
  enableLogCallback: true,
);

await initEnv(options);

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

日志回调 #

当 enableLogCallback 处于启用状态时，可调用 setLogCallback 实现日志回调。

import 'package:volc_bd_file_upload/core/upload.dart';

// msg: 日志内容。 level: 0 - 6 ，值越大日志级别越高
await setLogCallback((msg, level) {
  print('log callback------------>: $msg, $level');
});

创建实例 #

实现创建实例的示例代码如下：

import 'package:volc_bd_file_upload/bd_file_upload.dart';

MaterialUploaderOptions options = MaterialUploaderOptions(
  accessKey: "your accessKey",
  secretKey: "your secretKey",
  sessionToken: "your sessionToken",
  serviceID: "your serviceID",
  filePaths: filePath,// 只支持单个文件，因此List长度必须为1。
  };
  
BDMaterialUploader uploader = await initMaterialUploader(options);

设置待上传文件 #

仅支持上传单个文件，因此列表长度必须为 1。

MaterialUploaderOptions options = MaterialUploaderOptions(
...
filePaths: ["filePath1"],
}

设置鉴权参数 #

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

MaterialUploaderOptions options = MaterialUploaderOptions(
  accessKey: "your accessKey",
  secretKey: "your secretKey",
  sessionToken: "your token",
  ...
}

设置空间 #

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

MaterialUploaderOptions options = MaterialUploaderOptions(
   ...
   serviceID: "your service ID",
}

设置云端存储路径 #

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

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

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

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

参数说明如下表所示。

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

MaterialUploaderOptions options = MaterialUploaderOptions(
    ...
    // 例 1，云端的存储路径：tos-pathxxx/volc/test.mp4
    fileName: "volc/test.mp4",
    //  例 2，云端的存储路径：tos-pathxxx/test.mp4
    // fileName: "test.mp4",
);

// 例 云端的存储路径: tos-pathxxx/volc/b8bb180086f945709dfda76bc9c6133d.mp4
MaterialUploaderOptions options = MaterialUploaderOptions(
    // 设置后缀，必须设置，需要以 . 开头，如 .mp4、.mp3 等。
    fileExtension: ".mp4",
    // 设置前缀，可选设置，需要以 / 结尾
    filePrefix: "volc/",
    ...
);

设置素材信息 #

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

MaterialUploaderOptions options = MaterialUploaderOptions(
    ...
    title: "title",
    tags: "tags",
    description: "description",
    format: formatStr,
);

BDMaterialUploader uploader = await initMaterialUploader(options);

await uploader.setFileType(fileType);

await uploader.setCategory(category);

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

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

上传控制 #

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

• 开始上传：SDK 内部在执行此函数的时候，会新建线程，不会阻塞。实现开始上传的代码示例如下所示。

  await uploader.start();
  

• 暂停上传：实现暂停上传的代码示例如下所示。

  await uploader.stop();
  

• 终止上传：终止上传，并释放底层上传对象，释放后不能够继续进行上传。实现终止上传的代码示例如下所示。

  await uploader.close()
  

设置回调 #

await uploader.setListener(
  MaterialUploaderInfoCallback(
    // 素材上传成功回调，需要调用close() 方法以避免内存泄漏
    onUploadSuccess: (uploadInfo) async {
      print(
        '--- [MaterialUploaderInfoCallback] onUploadSuccess: ${jsonEncode(uploadInfo)}',
      );
      await uploader.close();
    },
    // 素材上传失败回调，调用 close() 方法以避免内存泄漏
    onUploadFail: (errorCode, errorMsg, uploadInfo) {
      print(
        '--- [MaterialUploaderInfoCallback] onUploadFail: $errorCode, $errorMsg, ${jsonEncode(uploadInfo)}',
      );
      await uploader.close();
    },
    // 素材上传进度回调:[0,100]
    onUpdateProgress: (progress) {
      print(
        '--- [MaterialUploaderInfoCallback] onUpdateProgress: $progress',
      );
    },
  ),
);

回调中 errorCode 为错误码，errorMsg 为错误日志，详情请见上传 SDK 错误码。
回调中 uploadInfo 类型为 BDMaterialUploadInfo，具体说明如下表所示：

{"Bitrate":463419,"Duration":39.726999999999997,"FileType":"video","Format":"MP4","Height":360,"Md5":"53f62abe3c29d0654b3405af77060","Size":2301285,"StoreUri":"tos-vod-cn-v-309be6ba73b04/cd404e7bef654554b638422***7c0c40","Width":640}

进阶功能 #

断点续传 #

调用 setDiskResumeOption 开启断点续传功能。开启断点续传后，用户在您的应用中上传文件时，如果发生强制退出应用等情况导致上传中断，下次上传同一个文件时，上传 SDK 会自动获取断点，并从断点处继续上传，从而节省上传时间。若为 Android 端，您还需额外设置断点续传文件的存放目录（有两种设置存放目录的方式，二选一即可）。示例代码如下：

// Android 端需要额外设置resumeConfigDir的值传入断点续传文件存放目录，注意不能以 "/" 结尾
MaterialUploaderOptions options = MaterialUploaderOptions(
   ...
   resumeConfigDir: diskResumeFilePath,
};
// 除了上述方式设置断点续传文件存放目录，你还可以使用下面这行代码进行设置（2选1即可）
await uploader.setSDKConfigDirForAndroid(diskResumeFilePath);


// 开启断点续传，1 开启，0关闭，默认关闭
await uploader.setDiskResumeOption(1);

自定义上传配置 #

MaterialUploaderOptions options = MaterialUploaderOptions(
   ...
   // 接入方自定义参数，如 "testkey=testValue" 
   serverParameter: "testkey=testValue"，
   // 分片上传设置分片大小，单位为 byte，默认值为 512 * 1024
   sliceSize: 512 * 512,
   // 开启并行上传的线程数，默认值为 1
   socketNum: 1,
   // 单个分片传输超时，单位为 s，默认值为 40
   rwTimeout: 40,
   // 总建连超时，单位为 s，默认值为 70
   maxFailTime: 70,
   //  系统 socket 单次读写超时，单位为 s，默认值为 10
   tranTimeout: 10,
   // 分片重试次数，默认值为 2
   sliceRetryCount: 2,
   // 文件级别的重试次数，默认值为 3
   fileRetryCount:3,
};

BDMaterialUploader uploader = await initMaterialUploader(options);

// 单次 TCP 建连超时，单位为 ms，默认值为 5000
await uploader.setTcpOpenTimeOutMs(5000);

// 复用连接的超时时间，防止老连接质量变差，导致的上传速度变慢，单位为 s，默认值为 6
await uploader.setAliveMaxFailTime(6);