You need to enable JavaScript to run this app.
导航
实时音视频
  • 文档首页
    • /
  • 实时音视频

2020-12-01

最近更新时间：2023.12.04 20:39:29

首次发布时间：2021.06.30 14:18:25

我的收藏

返回参数

BaseResponse

参数名类型描述
ResponseMetadataResponseMetadata
Resultinterface{}仅在请求成功时返回, 具体值参考每个 API 的说明。

ResponseMetadata

参数名类型示例值描述
RequestIdStringYour_RequestId请求标识
ActionStringStartRecord接口名称
VersionString2021-04-22接口版本
ServiceStringrtc接口所属服务
RegionStringcn-north-1地域参数：
  • cn-north-1 (华北)
  • ap-singapore-1 (新加坡)
  • us-east-1 (美东)
    • ErrorErrorInfo无仅在请求失败时返回。

    ErrorInfo

    错误的结构定义。

    参数名称类型描述
    CodeNUint32网关的错误码
    CodeStringAPI 的错误码，参看错误码。
    MessageString具体的错误信息

    ID

    BusinessId，TaskId，RoomId，UserId 等字段都遵循相同的命名规范：

    长度不超过 128 个字节，字符集取值范围是：

    • 英文大写字母：A~Z；
    • 英文小写字母：a~z；
    • 数字：0~9；
    • @ . _ -。

    视频布局相关参数

    Layout

    合流布局参数。

    参数名称类型必填示例值描述
    LayoutModeUint32否0布局模式。默认值为 0，值的范围为 {0, 1, 2, 3}。
  • 0 为自适应布局模式。参看自适应布局。
  • 1 为垂直布局模式。参看垂直布局。
  • 2 为自定义布局模式。
  • 3 为并排布局模式。参看并排布局
    • MainVideoStreamStream否在垂直布局模式下生效，指定主画面流的属性。如果此参数为空，则主画面为随机的一路流。
    MainVideoStreamIndexUint32否在垂直布局模式下生效，指定主画面流的属性。如果此参数为空，则主画面为随机的一路流。该参数已废弃，具体参看注释1
    CustomLayoutCustomLayout否使用自定义布局模式时，使用此参数进行具体设置。

    注释1: 当前版本 MainVideoStreamIndex 依然可用，但我们强烈建议你使用 MainVideoStream 参数。如果你同时指定了 MainVideoStream 和 MainVideoStreamIndex 的值，此时只有 MainVideoStream 生效。

    布局说明

    如果你选择使用自适应布局模式，合流时，不同的合流用户数量会适用不同的布局：

    • 2人：
      image
    • 4人：
      image
    • 5~9 10~16人：
      image
    • 17人：
      alt

    自适应布局会遵循以下规则：

    • 具体布局会根据人数进行选择，遵循以上示意图。人数未达到布局适用的最多人数时，空缺窗口会显示背景色。
    • 只发送音频的用户仍然会在整体布局上占据窗口，窗口会显示背景色。
    • 如果实际视频流的宽高比与视窗的宽高比不一致，会自动对视频进行裁剪以适配窗口的大小。

    如果你选择使用垂直布局模式，合流时，不同的合流用户数量会适用不同的布局：

    image

    image

    垂直布局会遵循以下规则：

    • 对于大窗口：
      • 如果未指定用户，大窗口会随机显示一个用户；如果指定用户未进入频道或进入频道未发布流，大窗口会显示背景色。
      • 如果实际视频流的宽高比与窗口的宽高比不一致，窗口会按照显示区域的长宽比裁减视频，并等比拉伸或缩小视频，以占满显示区域。
    • 对于小窗口：
      • 小视窗根据加入的顺序进行排列。如果某个用户退出频道，紧跟的后序用户会占据前序用户的窗口，并依次替补。
      • 如果实际视频流的宽高比与视窗的宽高比不一致，视频会裁剪以适配视窗的大小。
      • 人数未达到布局适用的最多人数时，空缺窗口会显示背景色。
      • 只发送音频的用户仍然会在整体布局上占据窗口，窗口会显示背景色。

    如果你选择使用并排布局模式，合流时，不同的合流用户数量会适用不同的布局：

    image

    CustomLayout

    自定义布局模式下，画面布局的具体设置。

    参数名称类型必填示例值描述
    CanvasCanvas否/整体屏幕（画布）的宽高以及背景色。
    Regionsarray of Region否/在自定义布局模式下，你可以使用 Regions 对每一路视频流进行画面布局设置。其中，每个 Region 对一路视频流进行画面布局设置。

    自定义布局模式下，对于 StreamList 中的每个 Stream，Regions 中都需要给出对应的布局信息，否则会返回请求不合法的错误。即 Regions.Region.StreamIndex 要与 TargetStreams.StreamList.Stream.Index 的值一一对应，否则自定义布局设置失败，返回 InvalidParameter 错误码。

    Canvas

    整体屏幕（画布）的宽高以及背景色参数。

    参数名称类型必填示例值描述备注
    WidthUint32否640整体屏幕（画布）的宽度，单位为像素，范围为 [2, 1920]，必须是偶数。默认值为 640。值不合法时，自动调整为默认值。
    HeightUint32否480整体屏幕（画布）的高度，单位为像素，范围为 [2, 1920]，必须是偶数。默认值为 480。值不合法时，自动调整为默认值。
    BackgroundString否#000000整体屏幕（画布）的背景色，用十六进制颜色码（HEX）表示。例如，#FFFFFF 表示纯白，#000000 表示纯黑。默认值为 #000000。值不合法时，自动调整为默认值。关于 Background 和 BackgroundImage 之间的关系，参看注释1。
    BackgroundImageString否无背景图片的 URL。长度最大为 1024 byte。可以传入的图片的格式包括：JPG, JPEG, PNG。如果背景图片的宽高和整体屏幕的宽高不一致，背景图片会缩放到铺满屏幕。关于 Background 和 BackgroundImage 之间的关系，参看注释1。
    1. 如果你设置了背景图片，背景图片会覆盖背景色。

    Region

    视频流在整体画面中的布局参数。

    • 当传入的必填参数值不合法时，返回错误码 InvalidParameter 。
    • 当传入的选填参数值不合法时，自动调整为默认值。
    参数名称类型必填示例值描述
    StreamIndexUint32是0流的标识。这个标志应和 TargetStreams.StreamList.Stream.Index 对应。
    LocationXFloat32否0视频流对应区域左上角的横坐标相对整体画面的比例，取值的范围为 [0.0, 1.0)。默认值为 0。若传入该参数，服务端会对该参数进行校验，若不合法会返回错误码 InvalidParameter。参看关于 LocationX 的说明。
    LocationYFloat32否0视频流对应区域左上角的纵坐标相对整体画面的比例，取值的范围为 [0.0, 1.0)。默认值为 0。若传入该参数，服务端会对该参数进行校验，若不合法会返回错误码 InvalidParameter。参看关于 LocationY 的说明。
    WidthProportionFloat32是0.5视频流对应区域宽度相对整体画面的比例，取值的范围为 (0.0, 1.0]。
    HeightProportionFloat32是0.5视频流对应区域高度相对整体画面的比例，取值的范围为 (0.0, 1.0]。
    ZOrderUint32否0当多个流的画面有重叠时，使用此参数设置指定画面的图层顺序。取值范围为 [0, 100]：0 表示该区域图像位于最下层，100 表示该区域图像位于最上层, 默认值为 0。值不合法时，自动调整为默认值。
    AlphaFloat32否1画面的透明度，取值范围为 (0.0, 1.0]。0.0 表示完全透明，1.0 表示完全不透明，默认值为 1.0。值不合法时，自动调整为默认值。
    RenderModeUint32否0画面的渲染模式，值的范围为 {0, 1, 2，3}, 默认值为 0：
    • 0 表示按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同，就会导致画面变形
    • 1 表示按照显示区域的长宽比裁减视频，然后等比拉伸或缩小视频，占满显示区域。
    • 2 表示按照原始画面的宽高比缩放视频，在显示区域居中显示。如果原始画面宽高比与指定的宽高比不同，就会导致画面有空缺，空缺区域为填充的背景色值。
    • 3 表示按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同，就会导致画面变形
    值不合法时，自动调整为默认值。
    目前 0 和 3 均为按照指定的宽高直接缩放，但我们推荐你使用 3 以便与客户端实现相同逻辑。
    不同渲染模式下，效果如下：alt
    SourceCropSourceCrop否/源流剪切功能，可以在源视频帧渲染之前进行裁剪，即预处理一次再渲染。转推直播和云端录制下， SourceCrop 对 AlternateImage 也生效。
    AlternateImageString否/占位图片的 url。长度不超过 1024 个字符串。参看关于 AlternateImage 的说明。
    ApplySpatialAudioBool否/该路流对应的用户是否开启空间音频效果。
    • true：开启空间音频效果。
    • false：关闭空间音频效果。
    默认值为 true
    SpatialPositionArray of Int否[0,0,0]空间音频下，房间内指定用户所在位置的三维坐标，默认值为[0,0,0]。数组长度为3，三个值依次对应X,Y,Z，每个值的取值范围为[-100,100]。
    CornerRadiusFloat否0.1转推直播下边框圆角半径与画布宽度的比例值，取值范围为 [0,1]，默认值为 0。圆角半径的像素位不能超过 Region 宽高最小值的一半，否则不会出现圆角效果。
    MediaTypeUint32否0该路流参与混流的媒体类型。
    • 0：音视频
    • 1：纯音频
    • 2：纯视频
    默认值为 0。值不合法时，自动调整为默认值。
    假如该路流为音视频流，MediaType设为1，则只混入音频内容。
    AlternateImageFillModeUint32否0画面的渲染模式。
    • 0：按照用户原始视频帧比例进行缩放
    • 1：保持图片原有比例
    默认值为 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 的说明：
      1. 在 Region.StreamIndex 对应的视频流没有发布，或被暂停采集时，AlternateImage 对应的图片会填充 Region 对应的画布空间。当视频流被采集并发布时，AlternateImage 不造成任何影响。
      2. 可以传入的图片的格式包括：JPG, JPEG, PNG。
      3. 当图片和画布尺寸不一致时，图片根据 RenderMode 的设置，在画布中进行渲染。

    SourceCrop

    对原视频帧在渲染前进行裁剪。

    参数名称类型必填示例值描述
    LocationXFloat32否0裁剪后得到的视频帧左上角的横坐标相对裁剪前整体画面的比例，取值的范围为 [0.0, 1.0)。默认值为 0.0。值不合法时，自动调整为默认值。
    LocationYFloat32否0裁剪后得到的视频帧左上角的纵坐标相对裁剪前整体画面的比例，取值的范围为 [0.0, 1.0)。默认值为 0.0。值不合法时，自动调整为默认值。
    WidthProportionFloat32否0.5裁剪后得到的视频帧宽度相对裁剪前整体画面宽度的比例，取值范围为 (0.0, 1.0]。默认值为 1.0。值不合法时，自动调整为默认值。
    HeightProportionFloat32否0.5裁剪后得到的视频帧高度相对裁剪前整体画面宽度的比例，取值范围为 (0.0, 1.0]。默认值为 1.0。值不合法时，自动调整为默认值。

    如果裁剪后计算得到的实际分辨率的宽或高不是偶数，会被自动调整为偶数。

    视频编码相关

    Encode

    音视频编码参数。

    参数名称类型必填示例值描述
    VideoWidthUint32否640输出画面的宽度。默认值为640，范围为 [2, 1920]，必须是偶数。值不合法时，自动调整为默认值。自定义布局下此参数不生效，整体画面宽度以 canvas 中的 Width 为主。
    VideoHeightUint32否480输出画面的高度，范围为[2, 1920]，必须是偶数，默认值为480。值不合法时，自动调整为默认值。自定义布局下此参数不生效，整体画面高度以 canvas 中的 Height 为主。
    VideoFpsUint32否15输出视频帧率。默认为 15，取值范围为 [1,60]。值不合法时，自动调整为默认值。
    VideoBitrateUint32否/输出视频码率。取值范围 [0,10000]，单位为 Kbps，默认值为 0。为 0时，表示自适应码率，会自动根据 VideoFps,VideoWidth以及 VideoHeight 计算出合理的码率。值不合法时，自动调整为默认值。
    VideoCodecUint32否0视频编码协议。默认值为 0，可以取 0 或 1。取 0 时使用 H.264,取 1 时使用 ByteVC1 编码器。
    VideoGopUint32否4输出视频 GOP。默认为 4，取值范围为 [1,5]，单位为秒。值不合法时，自动调整为默认值。
    AudioCodecUint32否0音频编码协议。默认值为 0，此时使用 aac 编码协议。目前只支持 aac。值不合法时，自动调整为默认值。
    AudioProfileUint32否0音频配置文件类型，在使用 aac 编码时生效。取值范围为 {0, 1, 2}。
  • 0 :采用 LC 规格；
  • 1: 采用 HE-AAC v1 规格；
  • 2: 采用 HE-AAC v2 规格。取 2 时，只支持输出流音频声道数为双声道。
    • 默认值为 0。
    AudioBitrateUint32否/音频码率。取值范围为 [32,192],单位为 Kbps，默认值为 64，值不合法时，自动调整为默认值。
    当AudioProfile=0时：
    若输入参数取值范围为 [32,192]，编码码率等于输入码率。
    当AudioProfile=1且 AudioChannels = 1 时：
    • 若输入参数取值范围为 [32,64]，编码码率等于输入码率。
    • 若输入参数取值范围为 [64,192]，编码码率固定为64。
      • 当AudioProfile=1且 AudioChannels = 2 时：
    • 若输入参数取值范围为 [32,128]，编码码率等于输入码率。
    • 若输入参数取值范围为 [128,192]，编码码率固定为128。
      • 当AudioProfile=2时：
    • 若输入参数取值范围为 [32,64]，编码码率等于输入码率。
    • 若输入参数取值范围为 [64,192]，编码码率固定为64。
    AudioSampleRateUint32否48000音频采样率。默认值 48000，枚举值为 {32000, 44100,48000}，单位是 Hz。值不合法时，自动调整为默认值。
    AudioChannelsUint32否2音频声道数。
  • 1：单声道
  • 2：双声道。
    • 默认值为 2。值不合法时，自动调整为默认值。

    自适应码率模式下，RTC 默认不会设置超高码率。如果订阅屏幕流，建议自行设置高码率。不同场景下设置码率等视频发布参数,请参考设置视频发布参数。

    Control

    录制与转推直播 control 字段

    参数名称类型必填示例值描述
    MediaTypeUint32否0流的类型，用于全局控制订阅的流的类型。默认值为0，可以取0和1。0表示音视频，1表示纯音频，暂不支持纯视频。值不合法时，自动调整为默认值。
    FrameInterpolationModeUint32否0选择补帧模式。默认值为0，可以取0和1。0为补最后一帧，1为补黑帧。值不合法时会自动调整为默认值。
    自动布局模式下，没有补帧的逻辑。
    关于什么是补帧，参看补帧。关于补帧、占位图与上一帧的关系，参看注释1
    MaxIdleTimeUint32否180任务的空闲超时时间，超过此时间后，任务自动终止。单位为秒。取值范围为 [10, 86400], 默认值为 180。
    MaxRecordTimeUint32否0（仅对录制有效）最大录制时长，单位为秒。默认值为 0。0 表示不限制录制时长。
    VolumeIndicationIntervalFloat32否2(仅对转推直播有效）用户说话音量的回调间隔，单位为秒，取值范围为[0.3,∞]，默认值为 2。
    VolumeIndicationModebool否false(仅对转推直播有效）是否开启音量指示模式。
    • true：是。此时非关键帧中也可能携带 SEI 信息。
    • false：否。此时只会在关键帧中携带 SEI 信息。
    默认值为 false。
      若 VolumeIndicationMode = true 的同时设置 MediaType = 1，该流推向 CDN 地址时，服务端会补黑帧。 关于音量指示模式的用法，参看[9999999#volume]
    TalkVolumeUint32否30(仅对转推直播有效）有效说话音量大小。取值范围为[0,255]，默认值为0。
    AddVolumeValueBool否falseSEI 中是否包含用户说话音量值。
    • false：否。
    • true：包含。
    默认值为 false。值不合法时自动调整为默认值。
    SEIContentModeUint32否0开启音量指示模式后，非关键帧携带 SEI 包含的信息类型。
    • 0：全量信息。
    • 1：只有音量信息和时间戳。
    关于 SEI 结构，参看服务端合流转推 SEI 结构
    SpatialConfigSpatialconfig否/空间音频配置。若合流转推的音频参数设置为单声道，空间音频无效。
    PushStreamModeUint32否0转推直播推流模式，用于控制触发推流的时机。枚举值为{0，1}。默认值为0。
  • 0：房间内有用户推 RTC 流时即触发 CDN 推流。
  • 1：调用接口发起推流任务后，无论房间内是否有用户推 RTC 流,均可触发 CDN 推流。
    • 值不合法时，自动调整为默认值。
    任务超时逻辑不变，依然是无用户推流即判定为超时。

    补帧：在音视频录制或合流转推时，视频的帧率通常是固定的。但是，因为网络波动或其他原因，实际帧率可能无法达到预设的帧率。此时，需要补帧以保持视频流畅。补最后一帧意味着补充的视频帧和中断前的最后一帧相同，此时看到的画面可能会有短暂静止；补黑帧意味着补充的视频帧是全黑的。

    使用占位图、补帧和上一帧的关系:

    你可以在 Region 中传入 Alternateimage 字段设置占位图,在 Control 中传入FrameInterpolationMode 字段设置补帧模式,但占位图优先级高于补帧模式。

    • 在 Region.StreamIndex 对应的视频流停止发布时, Region 对应的画布空间会根据设置填充占位图或补帧。但当视频流为屏幕流时，补帧模式不生效。
    • 当 Region.StreamIndex 对应的视频流发布后停止采集或推送时, Region 对应的画布空间会填充上一帧。
    • 当 Region.StreamIndex 对应的视频流发布时,设置的占位图或补顿模式不造成任何影响。

    SpatialConfig

    参数名称类型必填示例值描述
    EnableSpatialRenderBool否false是否开启空间音频处理功能。
  • false：关闭。
  • true：开启。
    • 默认值为 false。
    AudienceSpatialPositionArray of Int否[0,0,0]观众所在位置的三维坐标，默认值为[0,0,0]。数组长度为3，三个值依次对应X,Y,Z，每个值的取值范围为[-100,100]。
    AudienceSpatialOrientationAudienceSpatialOrientation否/设置观众朝向。各个向量两两垂直，如果传入的值没有保证两两垂直，自动赋予默认值。默认值为：forward = [1, 0, 0], right = [0, 1, 0], up = [0, 0, 1]。

    AudienceSpatialOrientation

    参数名称类型必填示例值描述
    ForwardArray of float否[1, 0, 0]前方朝向
    RightArray of float否[0, -1, 0]右边朝向
    UpArray of float否[0, 0, 1]头顶朝向

    录制相关

    RecordFile

    参数名称类型描述
    VidString文件在点播平台的唯一标识。你可以根据 vid 可以在点播平台上找到对应的文件。
    DurationUint64文件时长，单位为毫秒。
    SizeUint64文件大小，单位为 byte。
    StartTimeUint64文件开始录制的 UTC 时间，单位为毫秒。
    StreamListArray of Stream录制文件中包含流的列表。
    VideoCodecString视频录制编码协议。默认值为 0，可以取 0 或 1。取 0 时使用 H.264,取 1 时使用 ByteVC1 编码器。
    AudioCodecString音频录制编码器
    VideoWidthInt录制视频宽度，单位为像素
    VideoHeightInt录制视频高度，单位为像素

    Vod

    火山引擎视频点播 VOD 服务的配置信息

    参数名称类型描述
    AccountIdString火山引擎平台账号 ID，例如：200000000。详细信息，请参看注释1。
    SpaceString用于存储录制结果的点播空间名。

    注释1:

    • 火山引擎平台账号 ID 查看路径：控制台->账号管理->账号信息
      alt

    • 此账号 ID 为火山引擎主账号 ID。

    • 若你调用 OpenAPI 鉴权过程中使用的 AK、SK 为子用户 AK、SK，账号 ID 也必须为火山引擎主账号 ID，不能使用子用户账号 ID。

    音视频流相关

    Stream

    订阅流的参数

    参数名称类型必填示例值描述
    IndexUint32否0在自定义布局中，使用 Index 对流进行标志。后续在 Layout.regions.StreamIndex 中，你需要使用 Index 指定对应流的布局设置。
    UserIdString是Your_UserId用户Id，表示这个流所属的用户。
    StreamTypeUint32否0流的类型，值可以取0或1，默认值为0。0表示普通音视频流，1表示屏幕流。

    Streams

    指定流的数量及属性参数。

    参数名称类型必填示例值描述
    StreamListarray of Stream否由Stream组成的列表，可以为空。为空时，表示订阅房间内所有流。在一个 StreamList 中，Stream.Index 不能重复。

    房间管理相关

    Room

    参数名类型描述
    RoomIdString房间 ID
    AppIdString应用 ID
    UserNumInt仍在房间内的用户数
    StreamNumInt活跃流数
    StateInt房间状态。0 表示不活跃，1 表示活跃。
    CreatedAtString房间创建时间
    UpdatedAtString房间解散时间

    RoomListItem

    参数名类型示例值描述
    CallIdStringYour_CallId通话 Id，是通话的唯一标识
    RoomIdStringYour_RoomId返回房间 Id
    CreateTimeString2022-04-17T22:38:13+08:00通话创建时间，格式为 RFC3339，单位秒
    DestroyTimeString2022-04-17T22:38:13+08:00通话结束时间，格式为 RFC3339，单位秒，若查询时还未结束，则返回空值。
    ActiveUserNumInt0当前仍在房间用户数
    IsFinishedbooltrue通话是否结束

    User

    参数名类型描述
    AppIdString应用 ID
    NameString用户名
    RoleString用户角色
    IPString客户端 IP
    OSString客户端操作系统
    SDKVersionString客户端 SDK 版本
    PubStreamIdsArray of StreamId用户发布流 ID 列表
    SubStreamIdsArray of StreamId用户订阅流 ID 列表
    CreatedAtString用户第一次进房时间
    UpdatedAtString用户最后一次退房时间
    StateInt用户状态。0 表示不活跃，1 表示活跃。

    UserListItem

    参数名类型示例值描述
    CallIdStringYour_CallId通话 Id，是通话的唯一标识。
    RoomIdStringYour_RoomId查询房间 Id
    UserIdStringYour_UserId查询用户 Id
    CreatedAtString2006-01-02T15:04:05+08:00CallId下用户第一次进入通话时间,格式为 RFC3339，单位秒
    LeaveAtString2006-01-02T15:04:05+08:00CallId下用户最后一次退出通话时间，格式为 RFC3339，单位秒。如果此时用户在线，返回为空。
    AccessStringwifiCallId下用户最后一次进房对应的网络类型。枚举值：2g、3g、4g、5g、wifi、unknown。
    OSStringiosCallId下用户最后一次进房对应的设备平台。枚举值：android、ios、linux、mac、windows、web、unknown
    DeviceTypeStringiPhone 11CallId下用户最后一次进房对应的设备型号
    SdkVersionString3.30.101CallId下用户最后一次进房使用 sdk 版本号
    PubbooltrueCallId下用户是否发布过流
    FinishedbooltrueCallId下用户是否离开房间
    DurationInt100CallId下用户从第一次进房到最后一次离开房间的时间范围内真实在线时长（多次进出房时间间隔累加），单位为秒
    RecordArray of record/CallId下用户在通话内全部进退房记录

    Record

    参数名类型示例值描述
    TimeString2022-10-31T19:22:57+08:00用户进房/退房时间，格式为 RFC3339，单位秒。
    TypeStringjoin_room用户进房/退房类型，枚举值为 { join_room, leave_room}。

    抽帧截图相关

    ImageConfig

    截图产生的图片的相关配置。

    参数名类型必填示例值描述
    FormatUint32否0图片的格式。值可取 0 或 1，默认为 0。选择 0 时，图片格式为 JEPG；选择 1 时，图片格式为 PNG。默认值为 0。值不合法时，自动调整为默认值。
    WidthUint32否0实际使用视频帧的宽度，单位为像素，取值范围为 [0, 1920]。默认值为 0，此时，和视频流的实际宽度相同。值不合法时，自动调整为默认值。
    HeightUint32否0实际使用视频帧的高度，单位为像素，取值范围为 [0, 1080]，默认值为 0，此时，和视频流的实际高度相同。值不合法时，自动调整为默认值。
    IntervalUint32否2相邻截图之间的间隔时间，单位为秒，取值范围为 [1, 600]，默认值为 2。值不合法时，自动调整为默认值。

    切片相关

    Control(for segment)

    切片 control 字段

    参数名称类型必选示例值描述
    Alignbool否false是否开启切片对齐功能。参看注释1。
    Mixedbool否false是否开启合流切片功能。参看注释2。
    RedundantDurationUint32否2冗余切片时长，单位为毫秒。关于冗余切片功能，参看注释3
    IgnoreSilencebool否false是否忽略静音切片。默认值为 false 。

    1. Align 是音频切片对齐功能的开关，默认为 False。你可以使用音频切片对齐功能，对齐各个用户音频切片的开始和结束时刻。

      • 当 Align=False 时，关闭音频切片对齐。在某个切片周期中，如果用户有发送音频流的行为，即生成音频切片。如果用户在切片的周期中，有部分时间未发布音频，返回的音频切片时长会小于切片周期。各个用户音频切片开始时间不一定一致。
      • 当 Align=True 时，开启音频切片对齐。在某个切片周期中，如果用户有发送音频流的行为，即生成音频切片。切片长度和切片周期相等，且各个用户音频切片开始的时间一致。如果用户在切片的周期中，有部分时间未发布音频，切片长度不变，这段时间呈现静音帧。如果用户在某个切片周期中始终没有发布音频，则不生成音频切片。

    2. Mixed 是音频切片合流功能的开关。默认为 False。

      • 当 Mixed=False 时，只会对 TargetStreams 中指定的音频流分别切片。
      • 当 Mixed=True 时，除了会对 TargetStreams 中指定的音频流分别切片，还会对指定的音频流进行混音，生成合流切片，合流切片对应的用户名为 mixed。此时，任务创建后，不管是否有人上麦，会持续回调混音切片。

      不同平台的回调参看：

    操作Android APIiOS APIWindows API
    本地麦克风录制和远端所有用户混音后的音频数据回调onMixedAudioFrameonMixedAudioFrame:onMixedAudioFrame
    1. 当前服务端按照传入的Duration值进行固定时长切片,可能存在敏感词被截断，未被识别的情况。此时你可以添加冗余切片，即上一段切片的末尾指定时长，来避免此情况，此时切片的时长变为RedundantDuration + Duration。
      例如：当 Duration = 20，redundantDuration = 3 时，最终输出的前三个文件时长为：[0-20], [17-40], [37-60]。

    对象存储和消息队列相关

    TosConfig

    对象存储平台 TOS 的相关配置。

    参数名类型必填示例值描述
    UserAccountIdString是Your_UserAccountId火山引擎平台账号 ID，例如：200000000。详细信息，请参看注释1。
    RegionString是Your_RegionBucket 所在地域对应的 Region ID。参看 地域和访问域名。
    EndPointString是Your_EndPointBucket 对应的访问域名。参看 地域和访问域名。
    该 API 下 EndPoint 只支持 S3 Endpoint 外网域名。
    BucketString是Your_Bucket存储桶名称。

    在线媒体流相关

    StreamControl

    参数名类型必填示例值描述
    StreamUrlString是rtmp://xxx在线流媒体地址。媒体格式应为：hls、rtmp、mp4、flv、dash、或 ts。如源流为海外，建议联系技术支持，以保障最佳体验。
    MediaTypeInt否0媒体类型。
  • 0：音视频
  • 1：音频。采用此选项时，必须是 AAC 或 Opus 编码。
  • 2：视频
    • 默认值为0。
    StreamModeInt否0流处理模式。
  • 0：转码。采用此选项时，原视频编码方式必须是 H.264 或 ByteVC1。
  • 1：转封装。采用此选项时，原视频编码方式必须是 H.264 或 ByteVC1。
    • 默认值为0。
    StartTimeStampInt否0任务起始时间戳，用于定时播放，Unix时间，单位为秒。默认为 0，表示立即启动。此参数仅对 StartRelayStream接口生效。
    Loopbool否False是否循环播放，仅对源流为点播流时生效。
    VideoWidthInt否640视频宽度。转码时必填，单位为像素，范围为 [16, 1920]，必须是偶数，值为奇数时自动调整为偶数。
    VideoHeightInt否480视频高度，转码时必填。单位为像素，范围为 [16, 1920]，必须是偶数，值为奇数时自动调整为偶数。
    FrameRateInt否15发送帧率，值的范围为[1，30]，默认值为15，转码时生效。
    BitrateInt否6000最大发送码率，单位为 Kbps,不填则不限制，转码时生效。

    公共流相关

    Stream

    公共流流的参数

    参数名称类型必填示例值描述
    MediaTypeUint32否0流的媒体类型。默认值为 0 。
    0：音视频
    1：纯音频
    2：纯视频
    StreamTypeInt否0流类型。默认值为 0。
    0：媒体设备采集到的音视频
    1：屏幕流
    IndexUint32否1当选择自定义布局模式时，此字段必填。标记同一路公共流中不同的媒体流。
    在同一个 TargetStreams 中，Stream.Index 是唯一的。
    RoomIdString是Your_RoomId发布公共流的用户所在的房间 ID
    UserIdString否Your_UserId媒体流的发布方的用户 ID。UserId 为空时，表示订阅房间内所有流。
    UserId 需全局唯一。不同房间内的 UserId 不能重复。

    Layout

    公共流布局参数

    参数名称类型必填示例值描述
    LayoutModeInt是0布局模式。默认值为 0。
  • 0 为自适应布局模式。参看自适应布局。
  • 1 为垂直布局模式。参看垂直布局。
  • 2 为自定义布局模式。
  • 3 为并排布局模式。参看并排布局
    • VerticalLayoutVerticalLayout否无垂直布局参数
    CustomLayoutCustomLayout否无自定义布局参数

    VerticalLayout

    公共流垂直布局参数

    参数名类型必填示例值描述
    MainStreamstream否无指定在大窗口中显示的流及相关信息
    1. 如果在 TargetStreams 中指定了某用户的音频和视频，但在MainStream 只指定该用户的音频，则公共流中只包含该用户的音频，大窗口的区域置空。
    2. 如果在 TargetStreams 中指定了某用户的视频，但在MainStream只指定该用户的音频，则公共流中不包含该用户的音频和视频，大窗口的区域置空。
    3. 如果 MainStream 中指定的用户不存在，大窗口的区域置空。

    CustomLayout

    公共流自定义布局参数

    参数名类型必填示例值描述
    RegionsCustomRegion[]是无自定义布局下，多路视频配置
    FrameInterpolationModeInt否0选择补帧模式。默认值为 0。
  • 0 ：补最后一帧
  • 1 ：补黑帧。
    • 自动布局模式下，没有补帧的逻辑。关于补帧，参看补帧。
    BackgroundColorString否#000000背整体屏幕（画布）的背景色，格式为 #RGB(16进制)，默认值为 #000000（黑色）, 范围为 #000000 ~ #ffffff (大小写均可)。值不合法时，自动调整为默认值。
    如果你设置了背景图片，背景图片会覆盖背景色。
    BackgroundImageString否http://xxxx.svg背景图片的 URL。长度最大为 1024 byte。可以传入的图片的格式包括：JPG, JPEG, PNG。如果背景图片的宽高和整体屏幕的宽高不一致，背景图片会缩放到铺满屏幕。
    如果你设置了背景图片，背景图片会覆盖背景色。

    CustomRegion

    公共流自定义布局下视频流布局参数

    参数名类型必填示例值描述
    StreamIndexUint32是1流标识。
    StreamIndex 即 Stream.Index，用来指定布局设置将被应用到哪路流。
    LocationXfloat32是0视频流对应区域左上角的横坐标相对整体画面的比例，取值的范围为 [0.0, 1.0)。
    LocationYfloat32是0视频流对应区域左上角的纵坐标相对整体画面的比例，取值的范围为 [0.0, 1.0)。
    WidthProportionfloat32是0.5视频流对应区域宽度相对整体画面的比例，取值的范围为 (0.0, 1.0]。
    HeightProportionfloat32是0.5视频流对应区域高度相对整体画面的比例，取值的范围为 (0.0, 1.0]。
    ZOrderfloat32否0当画面有重叠时，使用此参数设置指定画面的图层顺序，取值范围为 [0, 100]：0 表示该区域图像位于最下层，100 表示该区域图像位于最上层, 默认值为 0。
    Alphafloat32否1.0画面的透明度，取值范围为 (0.0, 1.0]。0.0 表示完全透明，1.0 表示完全不透明，默认值为 1.0。
    RenderModeInt否0画面的渲染模式，值的范围为 {0, 1, 2，3}, 默认值为 0：
  • 0 表示按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同，就会导致画面变形
  • 1 表示按照显示区域的长宽比裁减视频，然后等比拉伸或缩小视频，占满显示区域。
  • 2 表示按照原始画面的宽高比缩放视频，在显示区域居中显示。如果原始画面宽高比与指定的宽高比不同，就会导致画面有空缺，空缺区域为填充的背景色值。值不合法时，自动调整为默认值。
  • 3 表示按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同，就会导致画面变形
    目前 0 和 3 均为按照指定的宽高直接缩放，但我们推荐你使用 3 以便与客户端实现相同逻辑。
    • AlternateImageString否https://xx.com/img/1.png占位图片的 url
    SourceCropSourceCrop否无源流剪切功能。公共流功能下， SourceCrop 对 AlternateImage 不生效。

    Encode

    公共流音视频编码参数

    参数名称类型必填描述
    VideoConfigVideoConfig否视频编码配置

    VideoConfig

    参数名称类型是否必填示例值描述
    WidthUint32否640输出画面的宽度。默认值为 640，范围为 [16, 1920]，必须是偶数。
    当公共流中只包含一路媒体流，并且 Layout.LayoutMode 不是 2时，此项设置无效。公共流的宽高为该路视频宽高。
    HeightUint32否480输出画面的高度，默认值为 480。范围为[16, 1920]，必须是偶数。
    当公共流中只包含一路媒体流，并且 Layout.LayoutMode 不是 2时，此项设置无效。公共流的宽高为该路视频宽高。
    FrameRateUint32否15输出视频帧率。默认为 15，取值范围为 [1,60]。单位 fps
    BitrateUint32否256最高输出视频码率。取值范围 [0,10000]，单位为 Kbps，默认值为 0，为 0时表示自适应码率。
    VideoCodecUint32否0视频编码协议。枚举值为 {0, 5}，默认值为 0。 
  • 0：H.264。
  • 5：VP8。 如果选择 VP8 格式，请先联系火山技术支持配置。

    • Control

    公共流控制参数

    参数名称类型必填示例值描述
    DataMsgString否/插入公共流的自定义信息，可用于随流信息同步，长度不超过 4 kB。
    数据会添加到当前视频帧开始的连续 30 个视频帧中。
    只在调用 UpdatePublicStreamParam 时有效。
    MaxIdleTimeUint32否180任务的空闲超时时间，超过此时间后，任务自动终止。单位为秒。取值范围为 [10, 86400]，默认值为 180。只在调用 StartPushPublicStream 时有效。
    VolumeIndicationModeBool否/是否开启音量指示模式。
  • true：开启音量提示。
  • false：不开启音量提示。
    • 默认值为false。
    VolumeIndicationIntervalUint32否/音量指示的回调间隔。单位为毫秒，最小值为 100，默认值为 2000。 值不合法时自动调整为默认值。
    VideoConfig.FrameRate 大于 10 fps 时，回调间隔才能达到 100ms。
    UserCaptureStatsModeBool否/是否开启房间用户采集状态回调。开启后会通过 onPublicStreamDataMessageReceived 回调。
  • true：开启房间用户采集状态回调。
  • false：不开启房间用户采集状态回调。
    • 默认值为false。
    UserCaptureStatsIntervalUint32否/房间用户采集状态回调间隔，仅在纯音频时触发。单位为毫秒，默认值为 2000，取值范围为 [1000,2147483647]。 值不合法时自动调整为默认值。
    StreamPublishStatsModeBool否/是否开启房间用户发布状态回调，仅在纯音频时触发。开启后会通过 onPublicStreamDataMessageReceived 回调。
  • true：开启房间用户发布状态回调。
  • false：不开启房间用户发布状态回调。
    • 默认值为false。
    StreamPublishStatsIntervalUint32否/房间用户发布状态回调间隔，仅在纯音频时触发。单位为毫秒，默认值为 2000，取值范围为 [1000,2147483647]。 值不合法时自动调整为默认值。

    云录屏相关

    VideoSolution

    参数名类型必填示例值描述
    WidthInt否1280视频宽度，单位为像素，范围为 [50,1920]，默认值为 1280。必须是偶数，值为奇数时自动调整为偶数。
    HeightInt否720视频高度，单位为像素，范围为 [50,1080]，默认值为 720。必须是偶数，值为奇数时自动调整为偶数。
    FrameRateInt否15发送帧率，单位为 帧/秒，范围为[1,60]，默认值为 15。帧率和码率设置建议参照视频发布参数对照表以获取最佳体验。
    BitrateInt否0最大发送码率。取值范围为 [0,10000]，单位为 Kbps，默认值 0，为 0 时表示自适应码率。

    MonitorConfig

    参数名类型必填示例值描述
    FreezeCheckIntervalInt否5 对页面内容是否无变化的检测间隔。取值范围为[2,30]，单位为秒。默认值为0，表示不启用。关于页面内容变化检测机制，请参看注释1。
    注意：页面无变化可能是您业务的正常场景，请谨慎评估页面实际内容情况后再开启此功能，以免任务提前退出。
    BlankCheckIntervalInt否 5对页面是否白屏的检测间隔。取值范围为[2,30]，单位为秒。默认值为0，表示不启用。关于页面白屏检测机制，请参看注释2
    注意：页面全白可能是您业务的正常场景，请谨慎评估页面实际内容情况后再开启此功能，以免任务提前退出。
    CrashCheckIntervalInt否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"。

    • EventNotifyConfig

    参数名类型必填示例值描述备注
    EnableEventNotifyBool否true是否启用页面主动事件通知, 默认值为false。
  • false：页面在打开后就会开始采集，在收到 StopWebCast openAPI 请求后结束采集。
  • true：在页面中注入两个 JS 函数：onWebcastStart()和 onWebcastEnd()。关于两个 JS 函数，参看注释3
    		• 开启页面主动事件通知后，通知采集开始构建，可参看注释4
    StartTimeoutInt否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>

    获取数据指标相关

    质量数据相关 Indicator

    参数名返回值描述
    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

    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

    Indicator 值解释返回值
    online_user_count在线用户数此 AppId 应用下在线用户数
    online_room_count在线房间数该此 AppId 应用下在线房间数

    单流转推相关

    Stream

    单流转推流的参数

    参数名称类型必填示例值描述
    UserIdString是 Your_UserId用户Id，表示这个流所属的用户。
    StreamTypeUint32否0流的类型，值可以取0或1，默认值为0。0表示普通音视频流，1表示屏幕流。

    Control

    单流转推 control 参数

    参数名类型必填示例值描述
    MediaTypeUint32否0流的类型，用于全局控制订阅的流的类型。默认值为 0，可以取0和1。0表示音视频，1表示纯音频，暂不支持纯视频。值不合法时，自动调整为默认值。
    MaxIdleTimeUint32否180任务的空闲超时时间，超过此时间后，任务自动终止。单位为秒。取值范围为 [10, 86400], 默认值为 180。

    歌曲查询相关

    List

    参数名类型示例值描述
    SongIdStringYour_SongId歌曲 ID
    SongnameString告白气球歌曲名称
    SingerString周杰伦歌曲歌手名
    VendorIdInt1供应商 ID
    VendorNameStringYour_VendorName供应商名称
    PosterUrlStringhttp://www.com/xxx.jpg歌曲封面地址
    LyricTypeArray of Int0歌词类型
  • 0： krc
  • 1： lrc
  • [0,1]： 两种歌词均有。
    • 若为空，则表示为无歌词。
    DurationInt200 歌曲时长，单位为秒
    BgmTypeInt2歌曲是否支持伴唱原唱切换。
  • 0： 不支持。
  • 1： 声道切换
  • 2： 音轨切换
    • PitchTypeInt1歌曲是否支持打分。
  • 0： 不支持
  • 1： 支持
    • RecordTypeInt1 歌曲是否支持录制。
  • 0： 不支持
  • 1： 支持
    • SegmentString"[65.088, 87.168]"歌曲高潮部分
    UpdateAtInt1670518801歌曲更新时间戳，unix 时间，单位为秒
    LyricUrlLyricUrl歌词文件地址。 建议优先使用 krc、不存在时下可选择 lrc

    LyricUrl

    参数名类型示例值描述
    KrcUrlStringhttp://www.xxx.krckrc 歌词地址
    LrcUrlStringhttp://www.xxx.lrclrc 歌词地址
    MidiUrlStringhttp://www.xxx.midmidi 文件地址