接口说明--视频点播-火山引擎

文档中心

立即注册

导航

接口说明

最近更新时间：2025.02.05 20:03:42首次发布时间：2021.02.23 10:42:41

Web 上传 SDK 支持上传视频、图片、普通文件。本文介绍 Web 上传 SDK 的相关参数、方法、生命周期和错误码等内容。

配置

initConfig

在初始化 TTUploader 实例时，您可以通过 initConfig 进行初始化配置。

const uploader = new TTUploader(initConfig);

initConfig 支持的参数如下表所示。

参数	类型	是否必传	默认值	说明
userId	String	是	null	用户 ID。用于进行单点追踪日志，定位某一个用户的日志，请设置一个唯一 ID。
appId	Number	是	null	应用 ID。用于定位某一条业务线的日志。
region	String	否	`cn-north-1`	上传地域。支持以下取值： `cn-north-1`：华北 `ap-southeast-1`：亚太东南（柔佛）注意亚太东南（柔佛）地域邀测中，仅针对企业用户开放。如有需求，请提交工单联系技术支持。
videoConfig	videoConfig	是	null	上传视频或普通文件使用到的配置。
useFileExtension	Boolean	否	`false`	是否带上文件扩展名。说明类型为 `Object` 时，上传设置有效。
useLocalStorage	Boolean	否	`true`	是否开启本地缓存写入上传信息。默认开启；关闭则断点续传失效。
useServerCurrentTime	Boolean	否	`false`	是否使用 `STSToken` 中的 `CurrentTime` 作为请求时间。该参数取值为 `true` 时，可以避免因为用户本地时间不准确导致的请求过期问题。说明 `CurrentTime` 需为能被 Date.parse() 正常解析的日期格式字符串，即 RFC2822 或 ISO 8601。
taskParallelLimit	Number	否	3	单个 Uploader 实例下，设置并行上传的文件数量。说明适用于多次调用 `addFile` 方法添加多个文件同时上传的场景。添加文件的数量大于该值时会串行排队执行上传。

videoConfig

videoConfig 为视频或普通文件上传专用配置，支持的参数如下表所示。

参数	类型	是否必传	默认值	说明
spaceName	String	是	null	空间名，在视频点播控制台中创建。

示例代码如下：

videoConfig: {
    spaceName: 'xxx', 
}

方法

本节为您介绍 Web 上传 SDK 提供的方法。

addFile(fileOption)

添加视频文件。调用该方法时，您需传入 fileOption。该方法返回当前文件的 key 值，在启动和取消文件上传时使用。示例代码如下：

const key = uploader.addFile({
    file: Blob, // 上传文件的 Blob 对象
    stsToken: {},
    type: 'video',
    processAction: [
        {
            Name: 'StartWorkflow',
            Input: {
                TemplateId: '25524a2dae4541db93b2e891d******' // 工作流 ID
            }
        },
        {
            Name: 'Snapshot',
            Input: {
                SnapshotTime: 2
            }
        }
    ]
});
console.log(key);  // 示例：file_1495442273603_999031

fileOption

fileOption 支持的参数如下表所示。

参数	类型	是否必传	默认值	说明
file	Blob	是	null	待上传文件。
stsToken	Object	是	null	临时上传 Token，需由应用服务端下发给客户端。详情请见客户端上传。
type	String	否	`video`	上传文件类型。取值如下： `video` `image` `object` `media`
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	JSON Array	否	null	媒资上传后的处理动作对象数组，可用于实现截图、设置媒资信息、触发工作流等功能。详见上传功能函数说明。

start(key)

启动上传任务。调用该方法时，您可传入文件的 key 值。如不传，则开始所有文件的上传。示例代码如下：

uploader.start();

removeFile(key)

移除某个待上传的文件。Key 值从 addFile 方法中返回。如果已调用 start 开始上传某文件，则必须使用 cancel 取消上传。示例代码如下：

uploader.removeFile('file_1495442273603_999031');

cancel(key)

取消某一文件的上传，同时删除暂存的上传信息。调用该方法时，您可传入文件的 key 值；如不传，则取消所有文件的上传。示例代码如下：

uploader.cancel();

pause(key)

暂停上传，将暂存当前文件的上传信息。调用该方法时，您可传入文件的 key 值；如不传，则暂停所有文件的上传。示例代码如下：

uploader.pause();

restart(key)

如果上传被暂停，调用此方法将从断点处恢复上传。调用该方法时，您可传入文件的 key 值；如不传，则恢复所有已暂停文件的上传。

uploader.restart();

生命周期

此处的生命周期是指上传某一个文件时候的生命周期，即一个视频上传产品线上的各个任务。
捕获某个生命周期的示例代码如下所示。

uploader.on('xxx', function(data) {
    console.log('xxx', data);
});

生命周期各阶段如下表所示。

阶段名称	描述
crc32	文件分片并获取 crc32。完成后得到 crc32Array（crc32 信息数组）和 sliceLength（每个分片的长度）。
preUpload	获取视频上传信息。完成后得到 signature（上传签名）、token（complete 时依赖 token）、oid 和 vid
initUploadID	初始化分片上传。完成后得到上传所需的 uploadID。
progress	视频并行分片上传进行中。实时更新 percent（总体进度）。
fileMerge	分片上传成功，合并文件
complete	视频上传并获取封面完成。部分已开获取分片权限的用户，上传完成后可得到 video、poster 和 speed（上传速度）。

Returned Value

在捕获每一个生命周期时都可获得描述当前状态的 data 信息，该信息在整个周期中不断完善，最终得到的 data 信息如下表所示：

参数	描述
uploadResult	上传完成后的各种信息，包括 vid，uri 等（complete 获取）。详见 uploadResult
startTime	文件开始上传的时间戳
endTime	文件完成上传的时间戳
stageStartTime	各阶段开始时间戳
stageEndTime	各阶段完成时间戳
duration	各阶段持续时间，计算公式：stageEndTime - stageStartTime
extra	当前状态的描述（随着生命周期不断变化）
fileSize	当前视频文件大小（crc32 获取）
key	当前视频文件的 key（addFile 时自动生成）
oid	存放的文件 ID （preUpload 获取）
percent	当前上传总体进度百分比（％）
speed	当前上传速度，单位为 kb/s
signature	上传所需的签名信息（preUpload 获取）
sliceLength	每一个分片的 size（crc32 获取）
stage	当前所处生命周期，如果是不支持的浏览器，则该值为 'browserError'
status	文件上传运行状态。取值如下： `1`：正在运行。 `2`：代表取消运行。 `3`：暂停运行。
task	队列实例
type	当前任务状态，成功／失败
uploadID	上传所需的 uploadID（ initUploadID 获取）

uploadResult

视频上传

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

参数	类型	描述
Vid	String	视频 id，vid 是视频在视频架构中的唯一 id
PosterUri	String	封面图 uri，当添加有截取封面信息的配置时返回
VideoMeta	Object	视频meta信息，当添加有获取 meta 信息的配置时返回
VideoMeta.Duration	Number	视频时长，单位：秒
VideoMeta.Width	Number	视频宽度
VideoMeta.Height	Number	视频高度
VideoMeta.Format	String	视频格式
VideoMeta.Bitrate	Number	视频码率，单位：bps
VideoMeta.FileType	String	文件类型
VideoMeta.Size	Number	视频文件大小
VideoMeta.Md5	String	视频文件 md5 值
VideoMeta.Uri	String	视频源文件在 tos 中的 uri，获取视频播放地址请不要使用这种方式访问
SourceInfo.VodVideoStreamMeta	Object	视频流 meta 信息，当添加有获取 meta 信息的配置时返回
VideoStreamMeta.Duration	Number	视频时长，单位：秒
VideoStreamMeta.Width	Number	视频宽度
VideoStreamMeta.Height	Number	视频高度
VideoStreamMeta.Codec	String	视频编码格式
VideoStreamMeta.Bitrate	Number	视频流码率，单位：bps
VideoStreamMeta.Definition	String	视频清晰度
VideoStreamMeta.Fps	Number	视频流帧率
AudioStreamMeta	Object	音频流 meta 信息
AudioStreamMeta.Code	String	音频编码格式
AudioStreamMeta.Duration	Number	音频时长
AudioStreamMeta.SampleRate	Number	音频采样率
AudioStreamMeta.Bitrate	Number	音频码率，单位：bps
AudioStreamMeta.Quality	String	音频质量

普通文件上传

参数	类型	描述
Uri	String	源文件在 tos 中的 uri，格式为 bucket/oid
ObjectMeta	Object	文件 meta 信息，当添加有获取meta信息的配置时返回
ObjectMeta.Md5	String	文件 md5 值
ObjectMeta.Uri	String	与上层中的 Uri 一致

错误码

详见上传 SDK 错误码。