You need to enable JavaScript to run this app.
导航
视频点播
  • 文档首页
    • /视频点播/上传 SDK/小程序上传 SDK/集成小程序上传 SDK
集成小程序上传 SDK
最近更新时间：2025.03.04 14:00:34首次发布时间：2023.08.09 10:55:03
我的收藏
有用
有用
无用
无用

本文为您介绍如何集成小程序上传 SDK，支持微信小程序、抖音小程序。

适用版本

本文档适用于小程序上传 SDK 2.0.0 及以上版本。其他版本请参考历史版本小程序上传 SDK。

准备工作

获取临时上传 Token

上传前需要从服务端获取上传临时安全凭证 UploadAuthToken。为方便您的使用，视频点播服务端 SDK 对 UploadAuthToken 的签发进行了封装，详见以下文档：

注意

由于签名计算放在前端会暴露 AccessKey 和 SecretKey，我们把签名计算过程放在后端实现。实现的方式如下：

  • 利用签名 SDK 可以生成一对临时的 AK、SK。
  • 前端向业务服务端获取签名结果。
  • 正式部署时请在后端加一层自己网站本身的权限检验。

添加域名白名单

将网关地址和上传地址添加到小程序的访问白名单中。

  • request 合法域名：

    https://vod.volcengineapi.com
https://mcs.zijieapi.com
https://tob-upload-x.volcvod.com
https://tob-upload-y.volcvod.com
https://tob-upload-x-d.volcvod.com
https://tob-upload-y-d.volcvod.com
https://tob-upload-sinfonline.volcvod.com
https://tob-upload-sinfonlinea.volcvod.com
https://tob-upload-sinfonlinec.volcvod.com
https://tob-upload-sinfonline-d.volcvod.com
https://tob-upload-sinfonlinea-d.volcvod.com
https://tob-upload-sinfonlinec-d.volcvod.com
https://tob-upload-sinfonline-fallback.volcvod.com
https://tob-upload-sinfonlinec-fallback.volcvod.com
https://tob-upload-sinfonlinea-fallback.volcvod.com

    如下图所示：
    Image

  • uploadFile 合法域名：

    https://tob-upload-x.volcvod.com
https://tob-upload-y.volcvod.com
https://tob-upload-x-d.volcvod.com
https://tob-upload-y-d.volcvod.com
https://tob-upload-sinfonline.volcvod.com
https://tob-upload-sinfonlinea.volcvod.com
https://tob-upload-sinfonlinec.volcvod.com
https://tob-upload-sinfonline-d.volcvod.com
https://tob-upload-sinfonlinea-d.volcvod.com
https://tob-upload-sinfonlinec-d.volcvod.com
https://tob-upload-sinfonline-fallback.volcvod.com
https://tob-upload-sinfonlinec-fallback.volcvod.com
https://tob-upload-sinfonlinea-fallback.volcvod.com

    如下图所示：
    Image

快速开始

引入 npm 包

npm install tt-uploader-miniprogram

实现上传逻辑

import TTUploader from 'tt-uploader-miniprogram';

// 1. 初始化 uploader
const uploader = new TTUploader({
  userId: 'volcengine-user1',  // 建议设置能识别用户的唯一标识 ID，用于上传出错时排查问题，不要传入非 ASCII 编码。
  appId: 8888,                 // 在视频点播控制台应用管理中创建的 AppID，视频点播的质量监控等都是以这个参数来区分业务方的，务必正确填写。
  videoConfig: {
    spaceName: 'your spaceName' // 在视频点播中创建的点播空间名。
  }
});

// 2. 设置监听事件
uploader.on('error', (info) => {
    console.log('上传失败', info)
})
uploader.on('progress', (infor) => {
    console.log('上传进度：', infor.percent)
});
uploader.on('complete', (info) => {
    console.log('上传成功', info)
})

// 3. 添加上传文件
const key = uploader.addFile({
   path: '',      // 文件临时路径，从 chooseMedia 回调中获取。
   size: 1234,    // 文件大小，从 chooseMedia 回调中获取。
   // 从服务端获取到的签名 token，见上方【获取上传签名说明】说明
   stsToken: {
       "CurrentTime":"2023-03-31T07:47:14.866Z",
       "ExpiredTime":"2023-05-30T07:47:14.866Z",
       "SessionToken":"STS2eyJU******MTlmZWEzNzBlNWQ4ZmU3NjAwMTljIn0=",
       "AccessKeyId":"AKTPZDM1ODg3MG******zODEyYmZiNTU5ODg",
       "SecretAccessKey":"aNXEA8uvCBF7tqtoolAxJ******l7KTZcaxyOWQbuPqg=="
   }, 
   type : 'media',       // 上传文件类型，三个可选值：（默认值）media(视频或者音频)，image(图片)，object（普通文件）
});

// 4. 开始上传
uploader.start(key)

初始化配置说明

初始化 uploader 实例时，可配置的属性如下，示例如下：

const uploader = new TTUploader({
    userId: 'xxx',
    appId: 8888,
    
    //视频/普通文件上传必传字段
    videoConfig: {
        spaceName: 'your space name'
    },
    useFileExtension: true,
    uploadTimeout: 1000 * 60 * 30,
    gatewayTimeout: 1000 * 60 * 5
});

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

参数

类型

是否必传

默认值

描述

userId

String

是

null

用户 ID。用于进行单点追踪日志，定位某一个用户的日志，请设置一个唯一 ID。

appId

Number

是

null

应用 ID。用于定位某一条业务线的日志。

videoConfig

Object

是

null

点播上传（视频/文件）专用配置。具体请参见下方videoConfig 详细参数说明。

useFileExtension

Boolean

否

false

是否使用文件扩展名作为存储 URI 的后缀。

说明

小程序上传 SDK 根据文件路径自动截取文件后缀。

uploadTimeout

Number

否

30min

上传文件请求的超时时间，单位为 ms。示例为 1000 * 60 * 30。

gatewayTimeout

Number

否

5min

网关请求的超时时间，单位为 ms。示例为 1000 * 60 * 5。

videoConfig 详细参数说明如下表所示：

参数

类型

是否必传

默认值

描述

spaceName

String

是

null

空间名，在视频点播控制台中创建。

API 说明

addFile(fileOption)

添加视频文件，传入的 fileOption 配置如下表所示。

参数

类型

是否必传

默认值

描述

path

String

是

null

待上传文件的临时路径。

size

Number

是

null

上传文件的大小。

stsToken

Object

是

null

临时上传 Token，需由应用服务端下发给客户端。详情请见客户端上传。

type

String

否

media

上传文件类型。可选值如下：

  • media
  • image
  • object

callbackArgs

String

否

null

自定义信息。该参数值会通过 FileUploadComplete 回调中的 CallbackArgs 参数透传给您的服务端。

fileName

String

否

null

文件路径。文件在视频点播存储中的存储位置，等同于传统对象存储的对象键（ObjectKey）概念。最大不超过 1024 个字符。您可根据业务需求自定义文件路径。

说明

  • 视频点播的文件路径必须携带文件后缀，例如 ".mp4"。不强制要求携带文件前缀。
  • 具体的字符规则，请见文件命名通用字符规则。
  • 设置 FileName 后， 当 FileName 相同时，有文件覆盖的风险。您需确保不同文件的 FileName 不同。
  • 传入 FileName 后，不需要再传入 FileExtension 参数。

fileExtension

String

否

null

文件后缀。视频点播存储中文件的类型。

说明

  • 当您传入 fileExtension 时，不需要重复传入 fileName 参数，视频点播将生成 32 位随机字符串，和您传入的 fileExtension 共同拼接成文件路径。
  • 以 . 开头，不超过 8 位。

storageClass

Number

否

1

存储类型。取值如下：

  • 1：标准存储。
  • 2：归档存储。

processAction

Array of processAction

否

null

媒资上传后的处理动作对象数组，可用于实现截图、设置媒资信息、触发工作流等功能。详见上传功能函数说明。

该方法返回当前文件的 key 值时，在上传和取消上使用，代码示例如下所示：

const key = uploader.addFile({
    file: file, // 上传的文件对象
    stsToken: {},
    type: 'media',
    processAction: [
        {
            Name: 'Snapshot',
            Input: {
                SnapshotTime: 2
            }
        }
    ]
});
console.log(key);  // file_1495442273603_999031 （类似格式）

start(key)

启动上传任务。如果该上传任务被暂停，则再次调用此方法时将恢复上传。传入文件的 key 值，如果不传参数，则所有已添加的文件将开始上传。

uploader.start();

pause(key)

暂停上传，将暂存当前文件的上传信息。传入文件的 key 值，如果不传参数，则将暂停所有文件的上传。

uploader.pause('file_1495442273603_999031');

restart(key)

恢复上传，将恢复当前被暂停的上传任务。传入文件的 key 值，如果不传参数，则将恢复所有文件的上传。

uploader.restart();

cancel(key)

取消某一文件的上传，同时删除暂存的上传信息。传入文件的 key 值，如果不传参数，则将取消所有文件的上传。

uploader.cancel();

回调事件说明

在文件上传的过程中，小程序上传 SDK 会依次抛出各类事件以通知外部，您可根据业务需要监听这些事件，事件名称和事件描述如下表所示：

事件名称

事件描述

progress

文件上传过程中会多次触发，可用于标识文件上传进度。详见 progress 事件。

complete

文件上传成功时触发，标识一个上传任务结束。详见 complete 事件。

error

上传失败、发生错误时触发。详见 error 事件。

// 监听事件
uploader.on('progress', function(info) {
    console.log('上传进度:', info.percent);
});
uploader.on('complete', function(info) {
    console.log('上传成功:', info);
});
uploader.on('error', function(info) {
    console.error('上传失败:', info);
});

progress 事件

progress事件回调的参数如下所示：

属性

类型

描述

percent

Number

整体上传进度。单位为百分比。取值范围为 [0, 99]，为整数。

说明

当complete事件，触发后才认为进度为 100。

totalSize

Number

上传文件的总体大小，单位为 byte。

sentSize

Number

此时已发送的字节数，单位为 byte。

key

String

标识本次上传任务的字符串，由 addFile() 方法返回。

oid

String

文件存储的 URI（统一资源标识符）。

sliceIndex

Number

可选，在分片上传的场景下，标识此索引的分片上传完成。

uploadId

String

可选，在分片上传的场景下，标识此次上传的唯一 ID。

complete 事件

complete事件回调的参数如下所示：

属性

类型

描述

filePath

String

文件在本地的临时路径。

fileSize

Number

文件大小，单位为 byte。

startTime

Number

文件开始上传的时间戳。

totalDuration

Number

上传总体耗时，单位为 ms。

key

String

当前上传任务的 key。

说明

addFile 时，是自动生成的。

oid

String

文件存储的 URI。

percent

Number

当前上传总体进度百分比。

speed

Number

文件上传的平均速度，单位为 kb/s。

status

Number

文件上传运行状态。取值如下：

  • 1：正在运行
  • 2：取消运行
  • 3：暂停运行
  • 4：上传成功
  • 5：上传失败

type

'success'

'error'

  • success：成功
  • error：失败

uploadId

String

可选，本次上传所使用的uploadId

extra

Object

当前状态的描述（随着生命周期不断变化）

extra.message

String

描述性信息。

uploadResult

Object

上传成功之后返回的音视频 Meta 信息，封面信息等。详见 uploadResult。

uploadResult

视频上传

对于视频上传的返回结果，默认情况下只会返回 Vid，如果想获取详细的视频元信息、封面图，请在上传时添加配置。

属性

类型

描述

Vid

String

视频 ID，vid 是视频在视频架构中的唯一 ID。

PosterUri

String

封面图 uri，当添加有截取封面信息的配置时返回。

SourceInfo

Object

视频源信息。

SourceInfo.Bitrate

Number

视频码率，单位：Kbps。

SourceInfo.Duration

Number

视频时长，单位：秒。

SourceInfo.FileType

String

文件类型。取值如下：

  • video：视频。
  • audio：音频。

SourceInfo.Format

String

文件格式。

SourceInfo.Fps

Number

帧率。

SourceInfo.Height

Number

视频高度，单位为 px。

SourceInfo.Width

Number

视频宽度，单位为 px。

SourceInfo.Size

Number

视频文件大小，单位为 byte。

SourceInfo.StoreUri

String

视频源文件在 TOS 存储桶中的 URI。

注意

获取视频播放地址请不要使用这种方式访问。

SourceInfo.Md5

String

视频文件 md5 值。

SourceInfo.TosStorageClass

String

文件在对象存储中的存储类型。

SourceInfo.VideoStreamMeta

Object

视频流 meta 信息，当添加有获取 meta 信息的配置时返回。

VideoStreamMeta.Duration

Number

视频时长，单位：秒。

VideoStreamMeta.Width

Number

视频宽度，单位为 px。

VideoStreamMeta.Height

Number

视频高度，单位为 px。

VideoStreamMeta.Codec

String

视频编码格式。

VideoStreamMeta.Bitrate

Number

视频流码率，单位：kbps

VideoStreamMeta.Definition

String

视频清晰度。

VideoStreamMeta.Fps

Number

视频流帧率。

AudioStreamMeta

Object

音频流 meta 信息

AudioStreamMeta.Code

String

音频编码格式。

AudioStreamMeta.Duration

Number

音频时长，单位：秒。

AudioStreamMeta.SampleRate

Number

音频采样率。

AudioStreamMeta.Bitrate

Number

音频码率，单位：Kbps

AudioStreamMeta.Quality

String

音频质量。

普通文件上传

属性

类型

描述

Uri

String

源文件在 TOS 存储桶中的 URI，格式为 bucket/oid。

ObjectMeta

Object

文件 meta 信息，当添加有获取 meta 信息的配置时返回。

ObjectMeta.Md5

String

文件 md5 值。

ObjectMeta.Uri

String

与上层中的 Uri 一致。

error 事件

error 事件回调的参数如下所示：

属性

类型

描述

key

String

标识本次上传任务的字符串，由 addFile 方法返回

code

Number

错误码，包含小程序原生的错误码

error

String

具体错误，包含小程序原生的错误信息

message

String

错误描述信息

type

String

事件类型，固定为 error。

stage

Number

上传任务发生错误的阶段

statusCode

Number

可选，网络请求的状态码

oid

String

可选，文件的 URI。

uploadId

String

可选，唯一的上传 ID。

错误码

详见上传 SDK 错误码。