本文为您介绍如何使用 Flutter 上传 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';

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

设置待上传文件 #

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

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

设置鉴权参数 #

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

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

设置空间 #

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

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

设置云端存储路径 #

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

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

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

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

参数说明如下表所示。

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

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

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

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

设置分类 #

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

VideoUploaderOptions options = VideoUploaderOptions(
   ...
   classificationId: "xxxxxxxxx",
}

上传控制 #

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

  VideoUploaderOptions options = VideoUploaderOptions(
     ...
  };
  BDVideoUploader uploader = await initVideoUploader(options);
  
  await uploader.start();
  

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

  await uploader.stop();
  

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

  await uploader.close();
  

设置回调 #

await uploader.setListener(
  VideoUploaderInfoCallback(
    // 视频上传成功后回调，需要在其中调用 close()方法以避免泄漏。uploadInfo为 BDVideoUploadInfo对象
    onUploadSuccess: (uploadInfo) async {
      print(
        '--- [VideoUploaderInfoCallback] onUploadSuccess: ${jsonEncode(uploadInfo)}',
      );
      await uploader.close();
    },
    // 视频上传失败回调，需要在其中调用 close() 方法以避免泄漏。
    onUploadFail: (errorCode, errorMsg, uploadInfo) {
      print(
        '--- [VideoUploaderInfoCallback] onUploadFail: $errorCode, $errorMsg, ${jsonEncode(uploadInfo)}',
      );
      await uploader.close();
    },
    // 视频上传进度回调:[0,100]
    onUpdateProgress: (progress) {
      print(
        '--- [VideoUploaderInfoCallback] onUpdateProgress: $progress',
      );
    },
  ),
);

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

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

进阶功能 #

设置封面图抽帧时间 #

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

// 单位为秒，默认值为 0
VideoUploaderOptions options = VideoUploaderOptions(
   ...
   poster: posterTime,
};

开启断点续传 #

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

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

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

设置全异步抽取 Meta #

如果您的业务场景无需实时抽取 Meta，则可以使用全异步抽取 Meta 的能力，提升上传速度。您需要调用 setEnableAsyncFetchMeta 。示例代码如下：

await uploader.setEnableAsyncFetchMeta(true);

自定义上传配置 #

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

VideoUploaderOptions options = VideoUploaderOptions(
   ...
   // 分片上传设置分片大小，单位为 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,
};

BDVideoUploader uploader = await initVideoUploader(options);

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

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

设置回调透传参数 #

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

// 需要携带的自定义参数，例如："appid=123&did=123456&uid=12345&Region=xxx&StoreRegion=xxx"
VideoUploaderOptions options = VideoUploaderOptions(
    ...
    serverParameter: "appid=123&did=123456&uid=12345&Region=xxx&StoreRegion=xxx",
);

设置工作流 ID #

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

// 设置工作流 ID
VideoUploaderOptions options = VideoUploaderOptions(
    ...
    templateId: templateId,
);