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

文档中心

立即注册

导航

接口说明

最近更新时间：2024.11.14 14:37:10首次发布时间：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: 'GetMeta'
        },
        {
            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	回调时回传给用户，用于客户端上传时，您希望透传客户端的一些信息。
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	视频/文件上传后的处理 Action 对象数组。有多个处理请求时可以配置多个动作对象。对象中的 input 会被透传到对应的处理服务中。

start(key)

启动上传任务。如果上传被暂停，则再次调用此方法时将从断点处开始上传。调用该方法时，您需传入文件的 key 值；如不传，则开始所有文件的上传。示例代码如下：

uploader.start();

removeFile(key)

移除某个待上传的文件或者取消该文件的上传。其中，key 值从 addFile 方法中返回。示例代码如下：

uploader.removeFile('file_1495442273603_999031');

cancel(key)

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

uploader.cancel();

pause(key)

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

uploader.pause();

生命周期

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

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 错误码。

参考信息

processAction

processAction 对象的结构如下表所示。

参数	类型	是否必传	默认值	说明
Name	String	是	无	Action 名称
Input	Object	否	无	Action 输入

processAction 对象目前支持的 Action 如下表所示。

Action 名称	Action 输入	说明	返回上传结果
GetMeta	void	抽取视频元信息。若不传，上传成功与否不依赖抽取元信息，可能取到元信息也可能没有。若传，则抽取元信息与上传成功强绑定。抽取元信息失败时，上传失败。	VideoMeta/ObjectMeta
StartWorkflow	StartWorkflowInput	触发工作流配置。注意上传和触发工作流为异步过程，工作流触发失败不影响上传任务提交成功，使用此方法请注意关注工作流执行情况。	void
Snapshot	SnapshotInput	截图配置。默认抽第一帧，可以指定视频时间点抽帧做封面图。	PosterUri
AddOptionInfo	AddOptionInfoInput	添加媒资信息配置。	void

StartWorkflowInput

触发工作流配置。

参数	类型	是否必传	默认值	说明
TemplateId	String	是	无	工作流 ID。上传完成后如果希望自动触发媒体处理工作流，可传入此参数。可在视频点播控制台媒体处理 > 工作流页面获取工作流 ID。

SnapshotInput

截图配置。

参数	类型	是否必传	默认值	说明
SnapshotTime	Float	是	无	截图时间。视频点播服务端会截取该时间的视频帧作为视频封面。单位为秒，默认值为 0。

AddOptionInfoInput

媒资信息配置。

参数	类型	是否必传	默认值	说明
Title	String	否	无	媒资标题。大小不超过 512 个字符。
Tags	String	否	无	媒资标签。多个标签可用逗号隔开。
Description	String	否	无	媒资描述。
RecordType	Int	否	1	媒资类型。取值如下： `1`：音视频。 `2`：素材。说明音视频和素材的定义详见媒资上传概述。
Category	String	否	无	素材类型。当 `RecordType` 参数取值为 `2` （素材）时，您必须传入 `Category` 参数指定素材类型。取值如下： `video`：视频 `audio`：音频 `image`：图片 `dynamic_img`：动图 `subtitle`：字幕 `font`：字体
Format	String	否	无	媒资格式。若传入 `Format` ，以您传入参数为准，否则以系统识别出的 `Format` 为准。若遇到特殊文件无法识别，`Format` 可能为空。
ClassificationId	int64	否	无	音视频的分类 ID。音视频的分类是由您自行创建并管理的，方式如下：在视频点播控制台系统设置 > 分类管理页面创建。通过 CreateVideoClassification 接口创建。

FileType 和 Category 的对应关系

fileOption.type 和 AddOptionInfoInput.Category 参数取值的对应关系如下表所示。

type 取值	对应 Category 取值
media	`video`：视频。 `audio`：音频。
image	`image`：图片。 `dynamic_img`：动图。
object	`subtitle`：字幕。 `font`：字体。