最近更新时间:2023.12.04 20:39:29
首次发布时间:2021.06.30 14:18:25
参数名 | 类型 | 描述 |
---|---|---|
ResponseMetadata | ResponseMetadata | |
Result | interface{} | 仅在请求成功时返回, 具体值参考每个 API 的说明。 |
参数名 | 类型 | 示例值 | 描述 |
---|---|---|---|
RequestId | String | Your_RequestId | 请求标识 |
Action | String | StartRecord | 接口名称 |
Version | String | 2021-04-22 | 接口版本 |
Service | String | rtc | 接口所属服务 |
Region | String | cn-north-1 | 地域参数:cn-north-1 (华北)ap-singapore-1 (新加坡)us-east-1 (美东) |
Error | ErrorInfo | 无 | 仅在请求失败时返回。 |
错误的结构定义。
参数名称 | 类型 | 描述 |
---|---|---|
CodeN | Uint32 | 网关的错误码 |
Code | String | API 的错误码,参看错误码。 |
Message | String | 具体的错误信息 |
BusinessId,TaskId,RoomId,UserId 等字段都遵循相同的命名规范:
长度不超过 128 个字节,字符集取值范围是:
A~Z
;a~z
;0~9
;@
.
_
-
。合流布局参数。
参数名称 | 类型 | 必填 | 示例值 | 描述 |
---|---|---|---|---|
LayoutMode | Uint32 | 否 | 0 | 布局模式。默认值为 0 ,值的范围为 {0, 1, 2, 3} 。0 为自适应布局模式。参看自适应布局。1 为垂直布局模式。参看垂直布局。2 为自定义布局模式。3 为并排布局模式。参看并排布局 |
MainVideoStream | Stream | 否 | 在垂直布局模式下生效,指定主画面流的属性。如果此参数为空,则主画面为随机的一路流。 | |
MainVideoStreamIndex | Uint32 | 否 | 在垂直布局模式下生效,指定主画面流的属性。如果此参数为空,则主画面为随机的一路流。该参数已废弃,具体参看注释1 | |
CustomLayout | CustomLayout | 否 | 使用自定义布局模式时,使用此参数进行具体设置。 |
注释1: 当前版本 MainVideoStreamIndex
依然可用,但我们强烈建议你使用 MainVideoStream
参数。如果你同时指定了 MainVideoStream
和 MainVideoStreamIndex
的值,此时只有 MainVideoStream
生效。
如果你选择使用自适应布局模式,合流时,不同的合流用户数量会适用不同的布局:
自适应布局会遵循以下规则:
如果你选择使用垂直布局模式,合流时,不同的合流用户数量会适用不同的布局:
垂直布局会遵循以下规则:
如果你选择使用并排布局模式,合流时,不同的合流用户数量会适用不同的布局:
自定义布局模式下,画面布局的具体设置。
参数名称 | 类型 | 必填 | 示例值 | 描述 |
---|---|---|---|---|
Canvas | Canvas | 否 | / | 整体屏幕(画布)的宽高以及背景色。 |
Regions | array of Region | 否 | / | 在自定义布局模式下,你可以使用 Regions 对每一路视频流进行画面布局设置。其中,每个 Region 对一路视频流进行画面布局设置。 |
自定义布局模式下,对于 StreamList
中的每个 Stream
,Regions
中都需要给出对应的布局信息,否则会返回请求不合法的错误。即 Regions.Region.StreamIndex
要与 TargetStreams.StreamList.Stream.Index
的值一一对应,否则自定义布局设置失败,返回 InvalidParameter
错误码。
整体屏幕(画布)的宽高以及背景色参数。
参数名称 | 类型 | 必填 | 示例值 | 描述 | 备注 |
---|---|---|---|---|---|
Width | Uint32 | 否 | 640 | 整体屏幕(画布)的宽度,单位为像素,范围为 [2, 1920] ,必须是偶数。默认值为 640 。值不合法时,自动调整为默认值。 | |
Height | Uint32 | 否 | 480 | 整体屏幕(画布)的高度,单位为像素,范围为 [2, 1920] ,必须是偶数。默认值为 480 。值不合法时,自动调整为默认值。 | |
Background | String | 否 | #000000 | 整体屏幕(画布)的背景色,用十六进制颜色码(HEX)表示。例如,#FFFFFF 表示纯白,#000000 表示纯黑。默认值为 #000000 。值不合法时,自动调整为默认值。 | 关于 Background 和 BackgroundImage 之间的关系,参看注释1。 |
BackgroundImage | String | 否 | 无 | 背景图片的 URL。长度最大为 1024 byte。可以传入的图片的格式包括:JPG, JPEG, PNG。如果背景图片的宽高和整体屏幕的宽高不一致,背景图片会缩放到铺满屏幕。 | 关于 Background 和 BackgroundImage 之间的关系,参看注释1。 |
视频流在整体画面中的布局参数。
- 当传入的必填参数值不合法时,返回错误码
InvalidParameter
。- 当传入的选填参数值不合法时,自动调整为默认值。
参数名称 | 类型 | 必填 | 示例值 | 描述 |
---|---|---|---|---|
StreamIndex | Uint32 | 是 | 0 | 流的标识。这个标志应和 TargetStreams.StreamList.Stream.Index 对应。 |
LocationX | Float32 | 否 | 0 | 视频流对应区域左上角的横坐标相对整体画面的比例,取值的范围为 [0.0, 1.0) 。默认值为 0 。若传入该参数,服务端会对该参数进行校验,若不合法会返回错误码 InvalidParameter 。参看关于 LocationX 的说明。 |
LocationY | Float32 | 否 | 0 | 视频流对应区域左上角的纵坐标相对整体画面的比例,取值的范围为 [0.0, 1.0) 。默认值为 0 。若传入该参数,服务端会对该参数进行校验,若不合法会返回错误码 InvalidParameter 。参看关于 LocationY 的说明。 |
WidthProportion | Float32 | 是 | 0.5 | 视频流对应区域宽度相对整体画面的比例,取值的范围为 (0.0, 1.0] 。 |
HeightProportion | Float32 | 是 | 0.5 | 视频流对应区域高度相对整体画面的比例,取值的范围为 (0.0, 1.0] 。 |
ZOrder | Uint32 | 否 | 0 | 当多个流的画面有重叠时,使用此参数设置指定画面的图层顺序。取值范围为 [0, 100] :0 表示该区域图像位于最下层,100 表示该区域图像位于最上层, 默认值为 0 。值不合法时,自动调整为默认值。 |
Alpha | Float32 | 否 | 1 | 画面的透明度,取值范围为 (0.0, 1.0] 。0.0 表示完全透明,1.0 表示完全不透明,默认值为 1.0 。值不合法时,自动调整为默认值。 |
RenderMode | Uint32 | 否 | 0 | 画面的渲染模式,值的范围为 {0, 1, 2,3} , 默认值为 0 :
目前 0 和 3 均为按照指定的宽高直接缩放,但我们推荐你使用 3 以便与客户端实现相同逻辑。不同渲染模式下,效果如下: ![]() |
SourceCrop | SourceCrop | 否 | / | 源流剪切功能,可以在源视频帧渲染之前进行裁剪,即预处理一次再渲染。转推直播和云端录制下, SourceCrop 对 AlternateImage 也生效。 |
AlternateImage | String | 否 | / | 占位图片的 url。长度不超过 1024 个字符串。参看关于 AlternateImage 的说明。 |
ApplySpatialAudio | Bool | 否 | / | 该路流对应的用户是否开启空间音频效果。
true |
SpatialPosition | Array of Int | 否 | [0,0,0] | 空间音频下,房间内指定用户所在位置的三维坐标,默认值为[0,0,0] 。数组长度为3 ,三个值依次对应X ,Y ,Z ,每个值的取值范围为[-100,100] 。 |
CornerRadius | Float | 否 | 0.1 | 转推直播下边框圆角半径与画布宽度的比例值,取值范围为 [0,1] ,默认值为 0 。圆角半径的像素位不能超过 Region 宽高最小值的一半,否则不会出现圆角效果。 |
MediaType | Uint32 | 否 | 0 | 该路流参与混流的媒体类型。
0 。值不合法时,自动调整为默认值。假如该路流为音视频流, MediaType 设为1 ,则只混入音频内容。 |
AlternateImageFillMode | Uint32 | 否 | 0 | 画面的渲染模式。
0 。值不合法时,自动调整为默认值。 |
备注:
LocationX
和 LocationY
的说明:Canvas.Width = 1920, Region.LocationX = 0.33
,那么该画布左上角的横坐标为 634
(1920*0.33=633.6,四舍五入取整)。WidthProportion
和 HeightProportion
的说明:Canvas.Width = 1920, Region.WidthProportion = 0.21
,那么该画布横向宽度为 404px
(1920*0.21=403.2,四舍五入取整后,再向上转换为偶数)。AlternateImage
的说明:
Region.StreamIndex
对应的视频流没有发布,或被暂停采集时,AlternateImage
对应的图片会填充 Region
对应的画布空间。当视频流被采集并发布时,AlternateImage
不造成任何影响。RenderMode
的设置,在画布中进行渲染。对原视频帧在渲染前进行裁剪。
参数名称 | 类型 | 必填 | 示例值 | 描述 |
---|---|---|---|---|
LocationX | Float32 | 否 | 0 | 裁剪后得到的视频帧左上角的横坐标相对裁剪前整体画面的比例,取值的范围为 [0.0, 1.0) 。默认值为 0.0 。值不合法时,自动调整为默认值。 |
LocationY | Float32 | 否 | 0 | 裁剪后得到的视频帧左上角的纵坐标相对裁剪前整体画面的比例,取值的范围为 [0.0, 1.0) 。默认值为 0.0 。值不合法时,自动调整为默认值。 |
WidthProportion | Float32 | 否 | 0.5 | 裁剪后得到的视频帧宽度相对裁剪前整体画面宽度的比例,取值范围为 (0.0, 1.0] 。默认值为 1.0 。值不合法时,自动调整为默认值。 |
HeightProportion | Float32 | 否 | 0.5 | 裁剪后得到的视频帧高度相对裁剪前整体画面宽度的比例,取值范围为 (0.0, 1.0] 。默认值为 1.0 。值不合法时,自动调整为默认值。 |
如果裁剪后计算得到的实际分辨率的宽或高不是偶数,会被自动调整为偶数。
音视频编码参数。
参数名称 | 类型 | 必填 | 示例值 | 描述 |
---|---|---|---|---|
VideoWidth | Uint32 | 否 | 640 | 输出画面的宽度。默认值为640 ,范围为 [2, 1920] ,必须是偶数。值不合法时,自动调整为默认值。自定义布局下此参数不生效,整体画面宽度以 canvas 中的 Width 为主。 |
VideoHeight | Uint32 | 否 | 480 | 输出画面的高度,范围为[2, 1920] ,必须是偶数,默认值为480 。值不合法时,自动调整为默认值。自定义布局下此参数不生效,整体画面高度以 canvas 中的 Height 为主。 |
VideoFps | Uint32 | 否 | 15 | 输出视频帧率。默认为 15 ,取值范围为 [1,60] 。值不合法时,自动调整为默认值。 |
VideoBitrate | Uint32 | 否 | / | 输出视频码率。取值范围 [0,10000] ,单位为 Kbps,默认值为 0 。为 0 时,表示自适应码率,会自动根据 VideoFps ,VideoWidth 以及 VideoHeight 计算出合理的码率。值不合法时,自动调整为默认值。 |
VideoCodec | Uint32 | 否 | 0 | 视频编码协议。默认值为 0 ,可以取 0 或 1 。取 0 时使用 H.264 ,取 1 时使用 ByteVC1 编码器。 |
VideoGop | Uint32 | 否 | 4 | 输出视频 GOP。默认为 4 ,取值范围为 [1,5] ,单位为秒。值不合法时,自动调整为默认值。 |
AudioCodec | Uint32 | 否 | 0 | 音频编码协议。默认值为 0 ,此时使用 aac 编码协议。目前只支持 aac。值不合法时,自动调整为默认值。 |
AudioProfile | Uint32 | 否 | 0 | 音频配置文件类型,在使用 aac 编码时生效。取值范围为 {0, 1, 2} 。0 :采用 LC 规格;1 : 采用 HE-AAC v1 规格;2 : 采用 HE-AAC v2 规格。取 2 时,只支持输出流音频声道数为双声道。0 。 |
AudioBitrate | Uint32 | 否 | / | 音频码率。取值范围为 [32,192] ,单位为 Kbps,默认值为 64 ,值不合法时,自动调整为默认值。当 AudioProfile =0 时:若输入参数取值范围为 [32,192] ,编码码率等于输入码率。当 AudioProfile =1 且 AudioChannels = 1 时:
AudioProfile =1 且 AudioChannels = 2 时:AudioProfile =2 时: |
AudioSampleRate | Uint32 | 否 | 48000 | 音频采样率。默认值 48000 ,枚举值为 {32000, 44100,48000} ,单位是 Hz。值不合法时,自动调整为默认值。 |
AudioChannels | Uint32 | 否 | 2 | 音频声道数。1 :单声道2 :双声道。2 。值不合法时,自动调整为默认值。 |
自适应码率模式下,RTC 默认不会设置超高码率。如果订阅屏幕流,建议自行设置高码率。不同场景下设置码率等视频发布参数,请参考设置视频发布参数。
录制与转推直播 control 字段
参数名称 | 类型 | 必填 | 示例值 | 描述 |
---|---|---|---|---|
MediaType | Uint32 | 否 | 0 | 流的类型,用于全局控制订阅的流的类型。默认值为0 ,可以取0 和1 。0 表示音视频,1 表示纯音频,暂不支持纯视频。值不合法时,自动调整为默认值。 |
FrameInterpolationMode | Uint32 | 否 | 0 | 选择补帧模式。默认值为0 ,可以取0 和1 。0 为补最后一帧,1 为补黑帧。值不合法时会自动调整为默认值。自动布局模式下,没有补帧的逻辑。 关于什么是补帧,参看补帧。关于补帧、占位图与上一帧的关系,参看注释1 |
MaxIdleTime | Uint32 | 否 | 180 | 任务的空闲超时时间,超过此时间后,任务自动终止。单位为秒。取值范围为 [10, 86400] , 默认值为 180 。 |
MaxRecordTime | Uint32 | 否 | 0 | (仅对录制有效)最大录制时长,单位为秒。默认值为 0 。0 表示不限制录制时长。 |
VolumeIndicationInterval | Float32 | 否 | 2 | (仅对转推直播有效)用户说话音量的回调间隔,单位为秒,取值范围为[0.3,∞] ,默认值为 2 。 |
VolumeIndicationMode | bool | 否 | false | (仅对转推直播有效)是否开启音量指示模式。
false 。
VolumeIndicationMode = true 的同时设置 MediaType = 1 ,该流推向 CDN 地址时,服务端会补黑帧。 关于音量指示模式的用法,参看[9999999#volume] |
TalkVolume | Uint32 | 否 | 30 | (仅对转推直播有效)有效说话音量大小。取值范围为[0,255] ,默认值为0 。 |
AddVolumeValue | Bool | 否 | false | SEI 中是否包含用户说话音量值。
false 。值不合法时自动调整为默认值。 |
SEIContentMode | Uint32 | 否 | 0 | 开启音量指示模式后,非关键帧携带 SEI 包含的信息类型。
|
SpatialConfig | Spatialconfig | 否 | / | 空间音频配置。若合流转推的音频参数设置为单声道,空间音频无效。 |
PushStreamMode | Uint32 | 否 | 0 | 转推直播推流模式,用于控制触发推流的时机。枚举值为{0,1} 。默认值为0 。0 :房间内有用户推 RTC 流时即触发 CDN 推流。1 :调用接口发起推流任务后,无论房间内是否有用户推 RTC 流,均可触发 CDN 推流。任务超时逻辑不变,依然是无用户推流即判定为超时。 |
补帧:在音视频录制或合流转推时,视频的帧率通常是固定的。但是,因为网络波动或其他原因,实际帧率可能无法达到预设的帧率。此时,需要补帧以保持视频流畅。补最后一帧意味着补充的视频帧和中断前的最后一帧相同,此时看到的画面可能会有短暂静止;补黑帧意味着补充的视频帧是全黑的。
使用占位图、补帧和上一帧的关系:
你可以在 Region
中传入 Alternateimage
字段设置占位图,在 Control
中传入FrameInterpolationMode
字段设置补帧模式,但占位图优先级高于补帧模式。
Region.StreamIndex
对应的视频流停止发布时, Region
对应的画布空间会根据设置填充占位图或补帧。但当视频流为屏幕流时,补帧模式不生效。Region.StreamIndex
对应的视频流发布后停止采集或推送时, Region
对应的画布空间会填充上一帧。Region.StreamIndex
对应的视频流发布时,设置的占位图或补顿模式不造成任何影响。参数名称 | 类型 | 必填 | 示例值 | 描述 |
---|---|---|---|---|
EnableSpatialRender | Bool | 否 | false | 是否开启空间音频处理功能。false :关闭。true :开启。false 。 |
AudienceSpatialPosition | Array of Int | 否 | [0,0,0] | 观众所在位置的三维坐标,默认值为[0,0,0] 。数组长度为3 ,三个值依次对应X ,Y ,Z ,每个值的取值范围为[-100,100] 。 |
AudienceSpatialOrientation | AudienceSpatialOrientation | 否 | / | 设置观众朝向。各个向量两两垂直,如果传入的值没有保证两两垂直,自动赋予默认值。默认值为:forward = [1, 0, 0] , right = [0, 1, 0] , up = [0, 0, 1] 。 |
AudienceSpatialOrientation
参数名称 | 类型 | 必填 | 示例值 | 描述 |
---|---|---|---|---|
Forward | Array of float | 否 | [1, 0, 0] | 前方朝向 |
Right | Array of float | 否 | [0, -1, 0] | 右边朝向 |
Up | Array of float | 否 | [0, 0, 1] | 头顶朝向 |
参数名称 | 类型 | 描述 |
---|---|---|
Vid | String | 文件在点播平台的唯一标识。你可以根据 vid 可以在点播平台上找到对应的文件。 |
Duration | Uint64 | 文件时长,单位为毫秒。 |
Size | Uint64 | 文件大小,单位为 byte。 |
StartTime | Uint64 | 文件开始录制的 UTC 时间,单位为毫秒。 |
StreamList | Array of Stream | 录制文件中包含流的列表。 |
VideoCodec | String | 视频录制编码协议。默认值为 0 ,可以取 0 或 1 。取 0 时使用 H.264 ,取 1 时使用 ByteVC1 编码器。 |
AudioCodec | String | 音频录制编码器 |
VideoWidth | Int | 录制视频宽度,单位为像素 |
VideoHeight | Int | 录制视频高度,单位为像素 |
火山引擎视频点播 VOD 服务的配置信息
参数名称 | 类型 | 描述 |
---|---|---|
AccountId | String | 火山引擎平台账号 ID,例如:200000000 。详细信息,请参看注释1。 |
Space | String | 用于存储录制结果的点播空间名。 |
注释1:
火山引擎平台账号 ID 查看路径:控制台->账号管理->账号信息
此账号 ID 为火山引擎主账号 ID。
若你调用 OpenAPI 鉴权过程中使用的 AK、SK 为子用户 AK、SK,账号 ID 也必须为火山引擎主账号 ID,不能使用子用户账号 ID。
订阅流的参数
参数名称 | 类型 | 必填 | 示例值 | 描述 |
---|---|---|---|---|
Index | Uint32 | 否 | 0 | 在自定义布局中,使用 Index 对流进行标志。后续在 Layout.regions.StreamIndex 中,你需要使用 Index 指定对应流的布局设置。 |
UserId | String | 是 | Your_UserId | 用户Id,表示这个流所属的用户。 |
StreamType | Uint32 | 否 | 0 | 流的类型,值可以取0 或1 ,默认值为0 。0 表示普通音视频流,1 表示屏幕流。 |
指定流的数量及属性参数。
参数名称 | 类型 | 必填 | 示例值 | 描述 |
---|---|---|---|---|
StreamList | array of Stream | 否 | 由Stream 组成的列表,可以为空。为空时,表示订阅房间内所有流。在一个 StreamList 中,Stream.Index 不能重复。 |
参数名 | 类型 | 描述 |
---|---|---|
RoomId | String | 房间 ID |
AppId | String | 应用 ID |
UserNum | Int | 仍在房间内的用户数 |
StreamNum | Int | 活跃流数 |
State | Int | 房间状态。0 表示不活跃,1 表示活跃。 |
CreatedAt | String | 房间创建时间 |
UpdatedAt | String | 房间解散时间 |
参数名 | 类型 | 示例值 | 描述 |
---|---|---|---|
CallId | String | Your_CallId | 通话 Id,是通话的唯一标识 |
RoomId | String | Your_RoomId | 返回房间 Id |
CreateTime | String | 2022-04-17T22:38:13+08:00 | 通话创建时间,格式为 RFC3339,单位秒 |
DestroyTime | String | 2022-04-17T22:38:13+08:00 | 通话结束时间,格式为 RFC3339,单位秒,若查询时还未结束,则返回空值。 |
ActiveUserNum | Int | 0 | 当前仍在房间用户数 |
IsFinished | bool | true | 通话是否结束 |
参数名 | 类型 | 描述 |
---|---|---|
AppId | String | 应用 ID |
Name | String | 用户名 |
Role | String | 用户角色 |
IP | String | 客户端 IP |
OS | String | 客户端操作系统 |
SDKVersion | String | 客户端 SDK 版本 |
PubStreamIds | Array of StreamId | 用户发布流 ID 列表 |
SubStreamIds | Array of StreamId | 用户订阅流 ID 列表 |
CreatedAt | String | 用户第一次进房时间 |
UpdatedAt | String | 用户最后一次退房时间 |
State | Int | 用户状态。0 表示不活跃,1 表示活跃。 |
参数名 | 类型 | 示例值 | 描述 |
---|---|---|---|
CallId | String | Your_CallId | 通话 Id,是通话的唯一标识。 |
RoomId | String | Your_RoomId | 查询房间 Id |
UserId | String | Your_UserId | 查询用户 Id |
CreatedAt | String | 2006-01-02T15:04:05+08:00 | CallId 下用户第一次进入通话时间,格式为 RFC3339,单位秒 |
LeaveAt | String | 2006-01-02T15:04:05+08:00 | CallId 下用户最后一次退出通话时间,格式为 RFC3339,单位秒。如果此时用户在线,返回为空。 |
Access | String | wifi | CallId 下用户最后一次进房对应的网络类型。枚举值:2g 、3g 、4g 、5g 、wifi 、unknown 。 |
OS | String | ios | CallId 下用户最后一次进房对应的设备平台。枚举值:android 、ios 、linux 、mac 、windows 、web 、unknown |
DeviceType | String | iPhone 11 | CallId 下用户最后一次进房对应的设备型号 |
SdkVersion | String | 3.30.101 | CallId 下用户最后一次进房使用 sdk 版本号 |
Pub | bool | true | CallId 下用户是否发布过流 |
Finished | bool | true | CallId 下用户是否离开房间 |
Duration | Int | 100 | CallId 下用户从第一次进房到最后一次离开房间的时间范围内真实在线时长(多次进出房时间间隔累加),单位为秒 |
Record | Array of record | / | CallId 下用户在通话内全部进退房记录 |
参数名 | 类型 | 示例值 | 描述 |
---|---|---|---|
Time | String | 2022-10-31T19:22:57+08:00 | 用户进房/退房时间,格式为 RFC3339,单位秒。 |
Type | String | join_room | 用户进房/退房类型,枚举值为 { join_room, leave_room} 。 |
截图产生的图片的相关配置。
参数名 | 类型 | 必填 | 示例值 | 描述 |
---|---|---|---|---|
Format | Uint32 | 否 | 0 | 图片的格式。值可取 0 或 1 ,默认为 0 。选择 0 时,图片格式为 JEPG ;选择 1 时,图片格式为 PNG 。默认值为 0 。值不合法时,自动调整为默认值。 |
Width | Uint32 | 否 | 0 | 实际使用视频帧的宽度,单位为像素,取值范围为 [0, 1920] 。默认值为 0 ,此时,和视频流的实际宽度相同。值不合法时,自动调整为默认值。 |
Height | Uint32 | 否 | 0 | 实际使用视频帧的高度,单位为像素,取值范围为 [0, 1080] ,默认值为 0 ,此时,和视频流的实际高度相同。值不合法时,自动调整为默认值。 |
Interval | Uint32 | 否 | 2 | 相邻截图之间的间隔时间,单位为秒,取值范围为 [1, 600] ,默认值为 2 。值不合法时,自动调整为默认值。 |
切片 control 字段
参数名称 | 类型 | 必选 | 示例值 | 描述 |
---|---|---|---|---|
Align | bool | 否 | false | 是否开启切片对齐功能。参看注释1。 |
Mixed | bool | 否 | false | 是否开启合流切片功能。参看注释2。 |
RedundantDuration | Uint32 | 否 | 2 | 冗余切片时长,单位为毫秒。关于冗余切片功能,参看注释3 |
IgnoreSilence | bool | 否 | false | 是否忽略静音切片。默认值为 false 。 |
Align
是音频切片对齐功能的开关,默认为 False
。你可以使用音频切片对齐功能,对齐各个用户音频切片的开始和结束时刻。
Align=False
时,关闭音频切片对齐。在某个切片周期中,如果用户有发送音频流的行为,即生成音频切片。如果用户在切片的周期中,有部分时间未发布音频,返回的音频切片时长会小于切片周期。各个用户音频切片开始时间不一定一致。Align=True
时,开启音频切片对齐。在某个切片周期中,如果用户有发送音频流的行为,即生成音频切片。切片长度和切片周期相等,且各个用户音频切片开始的时间一致。如果用户在切片的周期中,有部分时间未发布音频,切片长度不变,这段时间呈现静音帧。如果用户在某个切片周期中始终没有发布音频,则不生成音频切片。Mixed
是音频切片合流功能的开关。默认为 False
。
Mixed=False
时,只会对 TargetStreams
中指定的音频流分别切片。Mixed=True
时,除了会对 TargetStreams
中指定的音频流分别切片,还会对指定的音频流进行混音,生成合流切片,合流切片对应的用户名为 mixed
。此时,任务创建后,不管是否有人上麦,会持续回调混音切片。不同平台的回调参看:
操作 | Android API | iOS API | Windows API |
---|---|---|---|
本地麦克风录制和远端所有用户混音后的音频数据回调 | onMixedAudioFrame | onMixedAudioFrame: | onMixedAudioFrame |
Duration
值进行固定时长切片,可能存在敏感词被截断,未被识别的情况。此时你可以添加冗余切片,即上一段切片的末尾指定时长,来避免此情况,此时切片的时长变为RedundantDuration
+ Duration
。Duration
= 20
,redundantDuration
= 3
时,最终输出的前三个文件时长为:[0-20], [17-40], [37-60]。对象存储平台 TOS 的相关配置。
参数名 | 类型 | 必填 | 示例值 | 描述 |
---|---|---|---|---|
UserAccountId | String | 是 | Your_UserAccountId | 火山引擎平台账号 ID,例如:200000000 。详细信息,请参看注释1。 |
Region | String | 是 | Your_Region | Bucket 所在地域对应的 Region ID。参看 地域和访问域名。 |
EndPoint | String | 是 | Your_EndPoint | Bucket 对应的访问域名。参看 地域和访问域名。 该 API 下 EndPoint 只支持 S3 Endpoint 外网域名。 |
Bucket | String | 是 | Your_Bucket | 存储桶名称。 |
参数名 | 类型 | 必填 | 示例值 | 描述 |
---|---|---|---|---|
StreamUrl | String | 是 | rtmp://xxx | 在线流媒体地址。媒体格式应为:hls、rtmp、mp4、flv、dash、或 ts。如源流为海外,建议联系技术支持,以保障最佳体验。 |
MediaType | Int | 否 | 0 | 媒体类型。0 。 |
StreamMode | Int | 否 | 0 | 流处理模式。0 。 |
StartTimeStamp | Int | 否 | 0 | 任务起始时间戳,用于定时播放,Unix时间,单位为秒。默认为 0 ,表示立即启动。此参数仅对 StartRelayStream 接口生效。 |
Loop | bool | 否 | False | 是否循环播放,仅对源流为点播流时生效。 |
VideoWidth | Int | 否 | 640 | 视频宽度。转码时必填,单位为像素,范围为 [16, 1920],必须是偶数,值为奇数时自动调整为偶数。 |
VideoHeight | Int | 否 | 480 | 视频高度,转码时必填。单位为像素,范围为 [16, 1920],必须是偶数,值为奇数时自动调整为偶数。 |
FrameRate | Int | 否 | 15 | 发送帧率,值的范围为[1,30],默认值为15 ,转码时生效。 |
Bitrate | Int | 否 | 6000 | 最大发送码率,单位为 Kbps,不填则不限制,转码时生效。 |
公共流流的参数
参数名称 | 类型 | 必填 | 示例值 | 描述 |
---|---|---|---|---|
MediaType | Uint32 | 否 | 0 | 流的媒体类型。默认值为 0 。0 :音视频1 :纯音频2 :纯视频 |
StreamType | Int | 否 | 0 | 流类型。默认值为 0 。0 :媒体设备采集到的音视频1 :屏幕流 |
Index | Uint32 | 否 | 1 | 当选择自定义布局模式时,此字段必填。标记同一路公共流中不同的媒体流。 在同一个 TargetStreams 中,Stream.Index 是唯一的。 |
RoomId | String | 是 | Your_RoomId | 发布公共流的用户所在的房间 ID |
UserId | String | 否 | Your_UserId | 媒体流的发布方的用户 ID。UserId 为空时,表示订阅房间内所有流。 UserId 需全局唯一。不同房间内的 UserId 不能重复。 |
公共流布局参数
参数名称 | 类型 | 必填 | 示例值 | 描述 |
---|---|---|---|---|
LayoutMode | Int | 是 | 0 | 布局模式。默认值为 0 。0 为自适应布局模式。参看自适应布局。1 为垂直布局模式。参看垂直布局。2 为自定义布局模式。3 为并排布局模式。参看并排布局 |
VerticalLayout | VerticalLayout | 否 | 无 | 垂直布局参数 |
CustomLayout | CustomLayout | 否 | 无 | 自定义布局参数 |
公共流垂直布局参数
参数名 | 类型 | 必填 | 示例值 | 描述 |
---|---|---|---|---|
MainStream | stream | 否 | 无 | 指定在大窗口中显示的流及相关信息 1. 如果在 TargetStreams 中指定了某用户的音频和视频,但在MainStream 只指定该用户的音频,则公共流中只包含该用户的音频,大窗口的区域置空。 2. 如果在 TargetStreams 中指定了某用户的视频,但在MainStream只指定该用户的音频,则公共流中不包含该用户的音频和视频,大窗口的区域置空。 3. 如果 MainStream 中指定的用户不存在,大窗口的区域置空。 |
公共流自定义布局参数
参数名 | 类型 | 必填 | 示例值 | 描述 |
---|---|---|---|---|
Regions | CustomRegion[] | 是 | 无 | 自定义布局下,多路视频配置 |
FrameInterpolationMode | Int | 否 | 0 | 选择补帧模式。默认值为 0 。0 :补最后一帧1 :补黑帧。 |
BackgroundColor | String | 否 | #000000 | 背整体屏幕(画布)的背景色,格式为 #RGB(16进制),默认值为 #000000 (黑色), 范围为 #000000 ~ #ffffff (大小写均可)。值不合法时,自动调整为默认值。如果你设置了背景图片,背景图片会覆盖背景色。 |
BackgroundImage | String | 否 | http://xxxx.svg | 背景图片的 URL。长度最大为 1024 byte。可以传入的图片的格式包括:JPG , JPEG , PNG 。如果背景图片的宽高和整体屏幕的宽高不一致,背景图片会缩放到铺满屏幕。如果你设置了背景图片,背景图片会覆盖背景色。 |
公共流自定义布局下视频流布局参数
参数名 | 类型 | 必填 | 示例值 | 描述 |
---|---|---|---|---|
StreamIndex | Uint32 | 是 | 1 | 流标识。 StreamIndex 即 Stream.Index,用来指定布局设置将被应用到哪路流。 |
LocationX | float32 | 是 | 0 | 视频流对应区域左上角的横坐标相对整体画面的比例,取值的范围为 [0.0, 1.0)。 |
LocationY | float32 | 是 | 0 | 视频流对应区域左上角的纵坐标相对整体画面的比例,取值的范围为 [0.0, 1.0)。 |
WidthProportion | float32 | 是 | 0.5 | 视频流对应区域宽度相对整体画面的比例,取值的范围为 (0.0, 1.0]。 |
HeightProportion | float32 | 是 | 0.5 | 视频流对应区域高度相对整体画面的比例,取值的范围为 (0.0, 1.0]。 |
ZOrder | float32 | 否 | 0 | 当画面有重叠时,使用此参数设置指定画面的图层顺序,取值范围为 [0, 100]:0 表示该区域图像位于最下层,100 表示该区域图像位于最上层, 默认值为 0 。 |
Alpha | float32 | 否 | 1.0 | 画面的透明度,取值范围为 (0.0, 1.0]。0.0 表示完全透明,1.0 表示完全不透明,默认值为 1.0 。 |
RenderMode | Int | 否 | 0 | 画面的渲染模式,值的范围为 {0, 1, 2,3} , 默认值为 0 :0 表示按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同,就会导致画面变形1 表示按照显示区域的长宽比裁减视频,然后等比拉伸或缩小视频,占满显示区域。2 表示按照原始画面的宽高比缩放视频,在显示区域居中显示。如果原始画面宽高比与指定的宽高比不同,就会导致画面有空缺,空缺区域为填充的背景色值。值不合法时,自动调整为默认值。3 表示按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同,就会导致画面变形目前 0 和 3 均为按照指定的宽高直接缩放,但我们推荐你使用 3 以便与客户端实现相同逻辑。 |
AlternateImage | String | 否 | https://xx.com/img/1.png | 占位图片的 url |
SourceCrop | SourceCrop | 否 | 无 | 源流剪切功能。公共流功能下, SourceCrop 对 AlternateImage 不生效。 |
公共流音视频编码参数
参数名称 | 类型 | 必填 | 描述 |
---|---|---|---|
VideoConfig | VideoConfig | 否 | 视频编码配置 |
参数名称 | 类型 | 是否必填 | 示例值 | 描述 |
---|---|---|---|---|
Width | Uint32 | 否 | 640 | 输出画面的宽度。默认值为 640,范围为 [16, 1920],必须是偶数。 当公共流中只包含一路媒体流,并且 Layout.LayoutMode 不是 2 时,此项设置无效。公共流的宽高为该路视频宽高。 |
Height | Uint32 | 否 | 480 | 输出画面的高度,默认值为 480。范围为[16, 1920],必须是偶数。 当公共流中只包含一路媒体流,并且 Layout.LayoutMode 不是 2 时,此项设置无效。公共流的宽高为该路视频宽高。 |
FrameRate | Uint32 | 否 | 15 | 输出视频帧率。默认为 15,取值范围为 [1,60]。单位 fps |
Bitrate | Uint32 | 否 | 256 | 最高输出视频码率。取值范围 [0,10000],单位为 Kbps,默认值为 0 ,为 0 时表示自适应码率。 |
VideoCodec | Uint32 | 否 | 0 | 视频编码协议。枚举值为 {0, 5} ,默认值为 0 。 0 :H.264 。5 :VP8 。 如果选择 VP8 格式,请先联系火山技术支持配置。 |
公共流控制参数
参数名称 | 类型 | 必填 | 示例值 | 描述 |
---|---|---|---|---|
DataMsg | String | 否 | / | 插入公共流的自定义信息,可用于随流信息同步,长度不超过 4 kB。 数据会添加到当前视频帧开始的连续 30 个视频帧中。 只在调用 UpdatePublicStreamParam 时有效。 |
MaxIdleTime | Uint32 | 否 | 180 | 任务的空闲超时时间,超过此时间后,任务自动终止。单位为秒。取值范围为 [10, 86400],默认值为 180 。只在调用 StartPushPublicStream 时有效。 |
VolumeIndicationMode | Bool | 否 | / | 是否开启音量指示模式。true :开启音量提示。false :不开启音量提示。false 。 |
VolumeIndicationInterval | Uint32 | 否 | / | 音量指示的回调间隔。单位为毫秒,最小值为 100 ,默认值为 2000 。 值不合法时自动调整为默认值。VideoConfig.FrameRate 大于 10 fps 时,回调间隔才能达到 100ms。 |
UserCaptureStatsMode | Bool | 否 | / | 是否开启房间用户采集状态回调。开启后会通过 onPublicStreamDataMessageReceived 回调。true :开启房间用户采集状态回调。false :不开启房间用户采集状态回调。false 。 |
UserCaptureStatsInterval | Uint32 | 否 | / | 房间用户采集状态回调间隔,仅在纯音频时触发。单位为毫秒,默认值为 2000 ,取值范围为 [1000,2147483647] 。 值不合法时自动调整为默认值。 |
StreamPublishStatsMode | Bool | 否 | / | 是否开启房间用户发布状态回调,仅在纯音频时触发。开启后会通过 onPublicStreamDataMessageReceived 回调。true :开启房间用户发布状态回调。false :不开启房间用户发布状态回调。false 。 |
StreamPublishStatsInterval | Uint32 | 否 | / | 房间用户发布状态回调间隔,仅在纯音频时触发。单位为毫秒,默认值为 2000 ,取值范围为 [1000,2147483647] 。 值不合法时自动调整为默认值。 |
参数名 | 类型 | 必填 | 示例值 | 描述 |
---|---|---|---|---|
Width | Int | 否 | 1280 | 视频宽度,单位为像素,范围为 [50,1920] ,默认值为 1280 。必须是偶数,值为奇数时自动调整为偶数。 |
Height | Int | 否 | 720 | 视频高度,单位为像素,范围为 [50,1080] ,默认值为 720 。必须是偶数,值为奇数时自动调整为偶数。 |
FrameRate | Int | 否 | 15 | 发送帧率,单位为 帧/秒,范围为[1,60] ,默认值为 15 。帧率和码率设置建议参照视频发布参数对照表以获取最佳体验。 |
Bitrate | Int | 否 | 0 | 最大发送码率。取值范围为 [0,10000] ,单位为 Kbps,默认值 0 ,为 0 时表示自适应码率。 |
参数名 | 类型 | 必填 | 示例值 | 描述 |
---|---|---|---|---|
FreezeCheckInterval | Int | 否 | 5 | 对页面内容是否无变化的检测间隔。取值范围为[2,30] ,单位为秒。默认值为0 ,表示不启用。关于页面内容变化检测机制,请参看注释1。注意:页面无变化可能是您业务的正常场景,请谨慎评估页面实际内容情况后再开启此功能,以免任务提前退出。 |
BlankCheckInterval | Int | 否 | 5 | 对页面是否白屏的检测间隔。取值范围为[2,30] ,单位为秒。默认值为0 ,表示不启用。关于页面白屏检测机制,请参看注释2 注意:页面全白可能是您业务的正常场景,请谨慎评估页面实际内容情况后再开启此功能,以免任务提前退出。 |
CrashCheckInterval | Int | 否 | 5 | 对页面 JS 线程是否崩溃/卡死的检测间隔。 取值范围为[0,30] ,单位为秒。默认值为0 ,表示不启用。当出现检测命中时将进行任务重调度,并回调 Status=5,Reason="PageCrash" 。 |
注释1
Status=4,Reason="PageFreeze"
。Status=5,Reason="PageFreeze"
。注释2
Status=4,Reason="PageBlank"
。Status=5,Reason="PageBlank"
。参数名 | 类型 | 必填 | 示例值 | 描述 | 备注 |
---|---|---|---|---|---|
EnableEventNotify | Bool | 否 | true | 是否启用页面主动事件通知, 默认值为false 。false :页面在打开后就会开始采集,在收到 StopWebCast openAPI 请求后结束采集。true :在页面中注入两个 JS 函数:onWebcastStart() 和 onWebcastEnd() 。关于两个 JS 函数,参看注释3 | 开启页面主动事件通知后,通知采集开始构建,可参看注释4 |
StartTimeout | Int | 否 | 2 | 启用页面主动事件通知后,等待开始事件的超时时间。取值范围为[0,60] ,单位为秒。默认值为0 ,表示不启用。仅当 EnableEventNotify 为 true 时,此参数有效。Status=1 的回调。Status=4,Reason=" StartEventTimeout" 。重调度时将回调 Status=5,Reason="StartEventTimeout" 。 |
注释3:
当页面判断资源加载完成之后调用 onWebcastStart()
,控制程序才会开始进行页面内容的采集。当页面判断本次任务内容已完成时调用onWebcastEnd()
通知控制程序结束本次任务。StopWebCast
openAPI 效果不变,业务可提前结束任务。其他页面内容、JS 线程的检测(若启用),将在收到 onWebcastStart()
事件后才开始。
注释4:
当启用页面主动事件通知后,你可以参考以下示例代码来通知采集开始。
<script> if (ready() && typeof onWebcastStart === 'function') onWebcastStart(); </script>
参数名 | 返回值 | 描述 |
---|---|---|
join_room_success_rate | 此 AppId 在某一进房时间内的进房成功率(%)。 | 例如,5s_join_room_success_rate 表示进房时间在 5s 内的进房成功率。进房时间的默认值为 5s 。 |
stall_rate | 此 AppId 对应档位的卡顿率(%)。 | 例如,80ms_audio_stall_rate 表示通话过程中,音频卡顿在 80ms 以内的时间占比。若同时有音视频,则分别返回音频和视频的指标。 audio_stall_rate :音频卡顿率。卡顿时间的默认值为 80ms 。video_stall_rate :视频卡顿率。卡顿时间的默认值为 500ms 。 |
first_frame_send_success_rate | 此 AppId 的首帧发送成功率(%)。 | 若同时有音视频,则分别返回音频和视频的指标。audio_first_frame_send_success_rate :音频首帧发送成功率video_first_frame_send_success_rate :视频首帧发送成功率 |
first_frame_recv_success_rate | 此 AppId 的首帧解码成功率(%)。 | 若同时有音视频,则分别返回音频和视频的指标audio_first_frame_recv_success_rate :音频首帧解码成功率video_first_frame_recv_success_rate :视频首帧解码成功率 |
network_trans_delay | 此 AppId 对应档位的网络传输延时达标率(%)。 | 例如,400ms_network_trans_delay 表示通话过程中,两方的传输延时在 400ms 之内的时间占比。audio_network_trans_delay :音频网络传输时延达标率。传输延时的默认值为 400ms 。video_network_trans_delay :视频网络传输时延达标率。传输延时的默认值为 400ms 。 |
Indicator 值 | 返回值 | 备注 |
---|---|---|
user_count | 此 AppId 应用在所选日期通话总人数 | 通话人数按用户id去重。 例如:用户 A 在所选日期进入2个不同的房间,则通话人数计为1。 |
session_count | 此 AppId 应用在所选日期通话进出人次 | 用户每新进入房间一次,记一次进出 |
peak_concurrent_user | 此 AppId 应用在所选日期达到的最大同时在线人数 | 同时在线用户数的峰值,用户可在不同房间中 |
room_count | 此 AppId 应用在所选日期所创建的房间数 | 从有用户进入房间到所有用户退出,记为一个房间 |
high_concurrency_room | 此 AppId 应用在所选日期所有的高并发房间数 | 最高同时在线用户数大于等于100的房间数 |
peak_concurrent_room | 此 AppId 应用在所选日期最大同时在线房间数 | 同时进行中房间的峰值 |
avg_call_count | 此 AppId 应用在所选日期用户人均通话次数 | 人均通话次数=通话进出人次/通话人数 |
per_call_time | 该此 AppId 应用在所选日期用户人均单次通话时长 | 单次通话时长 = 通话总时长(一个用户进入多个房间会重复计算)/通话进出人次 例如: 用户 A 从10:00:00-10:10:00在房间1拉用户 B 的音视频流,同时从 10:00:00-10:05:00 在房间2拉用户 C 的音频流,则用户 A 的通话总时长为 (10+5) = 15 分钟。用户 A 的单次通话时长为 (15/2) = 7.5 分钟。 用户 D 从 10:00:00-10:09:00 在房间1拉用户 B 的视频流,则用户 D 的通话时长为 9 分钟。 则整体单次通话时长为 (15+9)/3 = 8 分钟 |
avg_call_time | 此 AppId 应用在所选日期用户人均通话时长 | 人均通话时长 = 通话时长(一个用户同时进入多个房间只计算一次)/通话人数 例如: 用户 A 从 10:00:00-10:10:00 在房间1拉用户 B 音视频流,同时从 10:00:00-10:05:00 在房间2拉用户 C 的音视频流,则用户 A 的通话时长是 10 分钟。 用户 D 从 10:00:00-10:08:00 在房间1拉用户 E 的视频流,同时从 10:00:00-10:08:00 在房间2拉用户 F 的视频流,则用户 D 的通话时长为 8 分钟。 人均通话时长为 9 分钟。 |
total_online_time | 此 AppId 应用在所选日期总房间在线时长 | 每个房间从第一个用户进入到最后一个用户退出的时间记为每个房间的在线时间,统计区间所有房间在线时长的总和记为总房间在线时长 |
avg_online_time | 此 AppId 应用在所选日期房间平均在线时长 | 总房间在线时长 / 总房间数 从有用户进入房间到所有用户退出,记为一个房间。 |
avg_user_count | 此 AppId 应用在所选日期房间平均在线人数 | 总通话人数按照用户id和房间id去重 / 总房间数 |
Indicator 值 | 解释 | 返回值 |
---|---|---|
online_user_count | 在线用户数 | 此 AppId 应用下在线用户数 |
online_room_count | 在线房间数 | 该此 AppId 应用下在线房间数 |
单流转推流的参数
参数名称 | 类型 | 必填 | 示例值 | 描述 |
---|---|---|---|---|
UserId | String | 是 | Your_UserId | 用户Id,表示这个流所属的用户。 |
StreamType | Uint32 | 否 | 0 | 流的类型,值可以取0 或1 ,默认值为0 。0 表示普通音视频流,1 表示屏幕流。 |
单流转推 control 参数
参数名 | 类型 | 必填 | 示例值 | 描述 |
---|---|---|---|---|
MediaType | Uint32 | 否 | 0 | 流的类型,用于全局控制订阅的流的类型。默认值为 0 ,可以取0 和1 。0 表示音视频,1 表示纯音频,暂不支持纯视频。值不合法时,自动调整为默认值。 |
MaxIdleTime | Uint32 | 否 | 180 | 任务的空闲超时时间,超过此时间后,任务自动终止。单位为秒。取值范围为 [10, 86400] , 默认值为 180 。 |
参数名 | 类型 | 示例值 | 描述 |
---|---|---|---|
SongId | String | Your_SongId | 歌曲 ID |
Songname | String | 告白气球 | 歌曲名称 |
Singer | String | 周杰伦 | 歌曲歌手名 |
VendorId | Int | 1 | 供应商 ID |
VendorName | String | Your_VendorName | 供应商名称 |
PosterUrl | String | http://www.com/xxx.jpg | 歌曲封面地址 |
LyricType | Array of Int | 0 | 歌词类型0 : krc 1 : lrc [0,1] : 两种歌词均有。 |
Duration | Int | 200 | 歌曲时长,单位为秒 |
BgmType | Int | 2 | 歌曲是否支持伴唱原唱切换。0 : 不支持。1 : 声道切换2 : 音轨切换 |
PitchType | Int | 1 | 歌曲是否支持打分。0 : 不支持1 : 支持 |
RecordType | Int | 1 | 歌曲是否支持录制。0 : 不支持1 : 支持 |
Segment | String | "[65.088, 87.168]" | 歌曲高潮部分 |
UpdateAt | Int | 1670518801 | 歌曲更新时间戳,unix 时间,单位为秒 |
LyricUrl | LyricUrl | 歌词文件地址。 建议优先使用 krc、不存在时下可选择 lrc |
参数名 | 类型 | 示例值 | 描述 |
---|---|---|---|
KrcUrl | String | http://www.xxx.krc | krc 歌词地址 |
LrcUrl | String | http://www.xxx.lrc | lrc 歌词地址 |
MidiUrl | String | http://www.xxx.mid | midi 文件地址 |