云直播云导播台 API 开发手册

导播台共有37个 API 接口，每个接口具有不同的参数，且参数的不同值具有不同的含义。为了降低 API 接口的使用门槛，本文档将以腾讯云控制台的 云导播台 功能为例，详细讲解云导播台页面功能对应的 API 调用方法，以便于参考。
在权限管理方面，主账号和子账号存在差异。为了简化 API 文档的描述，本文档将默认从主账号的角度进行分析，但子账号和主账号在 API 调用方式上没有本质的区别。
文档的结构是根据导播台页面上的操作顺序进行整理的，这样可以帮助用户根据文档和页面操作一起理解导播台 API 的调用顺序。
云导播 API 可以分为以下几个功能分组：
﻿导播台列表页﻿
﻿获取本账号下的导播台列表（查询导播台列表）﻿
﻿新建导播台（创建导播台 ）﻿
﻿修改导播台﻿
﻿删除导播台﻿
﻿复制导播台﻿
﻿获取导播台详细配置信息﻿
﻿查询基础配置（查询导播台信息）﻿
﻿查询导播台输入源列表（查询输入配置）﻿
﻿查询导播台的推流信息列表（查询推流配置）﻿
﻿查询导播台布局列表（查询布局配置）﻿
﻿查询导播台水印信息列表（查询水印配置）﻿
﻿查询导播台文本配置列表（查询文本配置）﻿
﻿获取导播台转场列表（查询支持的转场类型）﻿
﻿查询导播台当前的预监、主监信息（查询导播台展示信息）﻿
﻿获取导播台输入源、预监、主监的预览链接﻿
﻿获取导播台视频流播放url（获取输入源预览链接）﻿
﻿获取预监（PVW）预览链接﻿
﻿获取主监（PGM）预览链接﻿
﻿添加、修改、删除输入源﻿
﻿添加输入源﻿
﻿修改输入源﻿
﻿删除输入源﻿
﻿添加、修改、删除布局﻿
﻿添加布局﻿
﻿修改布局﻿
﻿删除布局﻿
﻿添加、修改、删除推流配置﻿
﻿添加推流配置﻿
﻿修改推流配置﻿
﻿删除推流配置﻿
﻿添加、修改、删除水印﻿
﻿添加水印﻿
﻿修改水印﻿
﻿删除水印﻿
﻿添加、修改、删除文本﻿
﻿添加文本﻿
﻿修改文本﻿
﻿删除文本﻿
﻿修改主监配置﻿
﻿启动、修改、停止预监﻿
﻿启动预监﻿
﻿修改预监﻿
﻿停止预监﻿
﻿启动、修改、停止主监﻿
﻿启动主监﻿
﻿修改主监﻿
﻿停止主监﻿
﻿进阶功能﻿
﻿音视频不同步切换﻿
﻿断流时设置备播﻿
﻿字幕功能﻿
﻿调整输入源音量﻿
﻿释放导播台﻿
导播台列表页
在云导播台列表页面，您可以查询本账号下现有的导播台列表。在此页面，您还可以新增、删除、修改或复制导播台。
﻿
获取本账号下的导播台列表（查询导播台列表）
调用接口：DescribeCasterList
请求示例：通过腾讯云API调用时，该接口不需要额外参数。                                     
响应示例：           
{
  "Response": {
    "CasterList": [
      {
        "CasterId": 10000, 
        "CasterName": "example", 
        "CreateTime": 1562832285,
        "Description": "示例导播台",
        "ExpireTime": -1, 
        "FeeType": 0,
        "StartBillingTime": 0, 
        "Status": 0,
        "StopBillingTime": 1592966057 
      },
    ],
    "RequestId": "4b2398e7-8351-4c7e-be8e-8fd3839a617e"
  }
}
﻿
页面字段与参数对应关系：
页面字段
参数
说明
ID
CasterId
-
名称
CasterName
-
描述
Description
-
计费状态
FeeType
通过 API 创建的均为后付费状态。
运行结束时间
ExpireTime
Unix 时间戳，-1代表永不过期。
运行状态
Status
当值非0时，状态为运行中；当值为0时，表示处于空闲状态。
新建导播台（创建导播台 ）
﻿
调用接口： CreateCaster      
请求示例：
响应示例：
{
  "CasterName": "example",
  "Description": "示例描述",
  "ExpireTime": 1727162903
}
{
    "Response": {
        "CasterId": 10000,
        "RequestId": "4b2398e7-8351-4c7e-be8e-8fd3839a617f"
    }
}
页面字段与参数对应关系：
页面字段
参数
说明
导播台名称
CasterName
-
导播台描述
Description
-
运行结束时间
ExpireTime
当值不等于-1时，表示运行结束的 Unix 时间戳。
设置运行结束时间
ExpireTime
将 ExpireTime 设置为-1，表示不设置运行结束时间。
注意：
响应中的CasterId是导播台的唯一 ID，对于导播台的大部分接口调用都需要该 ID。
修改导播台
修改导播台设置，请前往对应页面中的设置。
﻿
﻿
调用接口： ModifyCaster
请求示例：
响应示例：
{
    "CasterId": 10000,
    "CasterName": "修改示例",
    "Description": "modify_example",
    "ExpireTime": 1727190000
}
{
    "Response": {
        "RequestId": "4b2398e7-8351-4c7e-be8e-8fd3839a617g"
    }
}
页面字段与参数对应关系：
页面字段
参数
说明
导播台名称
CasterName
-
导播台描述
Description
-
运行结束时间
ExpireTime
当值不等于-1时，表示运行结束的 Unix 时间戳。
设置运行结束时间
ExpireTime
将 ExpireTime 设置为-1，表示不设置运行结束时间。
删除导播台
﻿
调用接口： DeleteCaster
请求示例：
响应示例：
{
    "CasterId": 10000
}
{
    "Response": {
        "RequestId": "4b2398e7-8351-4c7e-be8e-8fd3839a617g"
    }
}
页面字段与参数对应关系：无
注意：
删除导播台后，相关配置会被删除，推送到直播、转推到第三方均会停止。
复制导播台
复制导播台多应用在需要快速复制另一个导播台的场景中，如创建主、备导播台，主备导播台内的输入、布局等配置均保持一致。
﻿
﻿
调用接口： CopyCaster
请求示例：
响应示例：
{
    "CasterId": 10000,
    "CasterName": "复制示例"
}
{
    "Response": {
        "CasterId": 10001,
        "RequestId": "4b2398e7-8351-4c7e-be8e-8fd3839a617e"
    }
}
页面字段与参数对应关系：
页面字段
参数
说明
导播台名称
CasterName
-
注意：
响应中的CasterId是导播台的唯一ID，对于导播台的大部分接口调用都需要该ID。
获取导播台详细配置信息
点击列表页上的进入按钮后，您将进入导播台操作页面，该页面展示了导播台的所有配置。通常，导播台包括六种配置：基础配置、输入配置、输出配置、布局配置、水印配置和文本配置。其中，基础配置、输入配置和输出配置是任何正常运行的导播台所必需的。当进入导播台页面时，页面会调用查询接口查询相关配置并展示在页面上。在实际应用场景中，可能不需要所有类型的配置。因此，在使用API开发时，可以根据业务需求仅查询所需的配置信息。
﻿
查询基础配置（查询导播台信息）
调用接口： DescribeCaster
请求示例：
响应示例：
{
    "CasterId": 10000
}
{
    "Response": {
        "CasterInfo": {
            "CasterId": 10000,
            "CasterName": "示例",
            "StartLiveTime": 0,
            "Description": "",
            "CreateTime": 1603158528,
            "Status": 0,
            "ExpireTime": -1,
            "DelayTime": 0,
            "PgmWidth": 1920,
            "PgmHeight": 1080,
            "PgmFps": 30,
            "PgmBitRate": 2000,
            "PgmAudioBitRate": 256,
            "FeeType": 0,
            "RecordTemplateId": 0,
            "RecordStatus": 0,
            "RecordTaskId": ""
        },
        "RequestId": "90d50bb3-d184-4624-b820-21ad5f90d1cf"
    }
}
页面字段与参数对应关系：
基础配置信息在页面上出现在不同的区域，以下对主要字段进行说明。
设置页-设置输出规格：
﻿
页面字段
参数
说明
视频宽
PgmWidth
-
视频高
PgmHeight
-
视频帧率
PgmFps
-
视频码率
PgmBitRate
-
音频码率
PgmAudioBitRate
-
设置页 < 推流设置 < 延时播放。
﻿
页面字段
参数
说明
延时播放
DelayTime
单位为秒
主页面-PGM输出时长。
﻿
页面字段
参数
备注
PGM输出时长
StartLiveTime
使用当前 unix 时间戳减去该参数的值计算
主页面-预监、主监状态。
﻿
页面字段
参数
备注
-
Status
可能的取值及其含义：
0：预监未打开，主监未打开
1：预监未打开，主监已打开
2：预监已打开，主监未打开
3：预监已打开，主监已打开
查询导播台输入源列表（查询输入配置）
﻿
调用接口： DescribeCasterInputInfos
请求示例：
响应示例：
{
    "CasterId": 10000
}
{
    "Response": {
        "InputInfos": [
            {
                "InputIndex": 1,
                "InputType": 1,
                "InputUrl": "",
                "Description": "",
                "PullPushEnable": true,
                "LoopEnable": true,
                "LoopNumber": -1,
                "Volume": 100,
                "InputUrls": [
                    "https://www.example.com/example.mp4"
                ]
            }
        ],
        "RequestId": "c803aade-2ed3-4f58-8ab2-a5ab277e2dcf"
    }
}
页面字段与参数对应关系：
输入源配置各字段所代表含义，在后续输入源相关操作中展开讨论，或参考 API CasterInputInfo 类型文档。
查询导播台的推流信息列表（查询推流配置）
﻿
调用接口： DescribeCasterOutputInfos
请求示例：
响应示例：
{
    "CasterId": 10000
}
{
    "Response": {
        "OutputInfos": [
            {
                "OutputIndex": 0,
                "OutputType": 1,
                "OutputUrl": "",
                "Description": "",
                "OutputStreamId": "example_output_stream_id",
                "OutputDomainName": "example.domain.com",
                "OutputAppName": "live",
                "OutputParam": ""
            },
            {
                "OutputIndex": 1,
                "OutputType": 2,
                "OutputUrl": "rtmp://example.com/live/example",
                "Description": "第三方厂商",
                "OutputStreamId": "",
                "OutputDomainName": "",
                "OutputAppName": "",
                "OutputParam": ""
            }
        ],
        "RequestId": "d4c5c0bc-288b-4e48-9126-8b4d2265336c"
    }
}
页面字段与参数对应关系：
推流设置：OutputIndex 设置为 0，OutputType 设置为 1。
页面字段
参数
说明
腾讯云直播流名称
OutputStreamId
-
高级设置-域名设置-推流域名
OutputDomainName
-
高级设置-域名设置-AppName
OutputAppName
-
高级设置-参数设置-自定义参数
OutputParam
-
设置转推地址：OutputIndex为非0，OutputType为2。
页面字段
参数
说明
厂商
Description
-
转推地址
OutputUrl
-
查询导播台布局列表（查询布局配置）
﻿
调用接口： DescribeCasterLayoutInfos
请求示例：
响应示例：
{
    "CasterId": 10000
}
{
    "Response": {
        "LayoutInfos": [
            {
                "LayoutIndex": 1,
                "InputIndexList": "1|2",
                "LayoutTemplateId": 20,
                "LayoutParams": [
                    {
                        "LayerId": 1,
                        "LayerWidth": 0.5,
                        "LayerHeight": 1,
                        "LayerLocationX": 0,
                        "LayerLocationY": 0,
                        "UsePortraitSegment": false
                    },
                    {
                        "LayerId": 2,
                        "LayerWidth": 0.5,
                        "LayerHeight": 1,
                        "LayerLocationX": 0.5,
                        "LayerLocationY": 0,
                        "UsePortraitSegment": false
                    }
                ]
            }
        ],
        "RequestId": "34df44e7-b512-4b95-829c-b92e3e29ae44"
    }
}
页面字段与参数对应关系：
页面获取到布局配置后，根据布局参数字段渲染出布局样式，规则为，LayerId由小到大，向上层叠加，每一层的位置、宽高参数均为整个画面的百分比数据。
布局中的输入列表，与每一层的布局关系规则："InputIndexList"字段按"|"进行分拆，分拆后由左至右按 LayerId 从小到大填充到对应的层级中。
查询导播台水印信息列表（查询水印配置）
﻿
调用接口： DescribeCasterMarkPicInfos
请求示例：
响应示例：
{
    "CasterId": 10000
}
{
    "Response": {
        "MarkPicInfos": [
            {
                "MarkPicIndex": 1,
                "MarkPicId": 0,
                "MarkPicUrl": "https://example.com/example/watermark_example.gif",
                "MarkPicWidth": 0.2703,
                "MarkPicHeight": 0.3267,
                "MarkPicLocationX": 0,
                "MarkPicLocationY": 0,
                "Description": "",
                "IsEqualProportion": true
            }
        ],
        "RequestId": "48280e4c-f16b-4452-9a73-a9f83a91d40f"
    }
}
页面字段与参数对应关系：
﻿
在页面获取水印配置后，会根据 "MarkPicUrl" 字段获取水印图片并进行渲染。然后，根据"MarkPicWidth"、"MarkPicHeight"、"MarkPicLocationX"和"MarkPicLocationY"字段，确定并渲染水印在布局中的具体位置。
页面字段
参数
说明
水印名称
Description
-
相对位置X
MarkPicLocationX
-
相对位置Y
MarkPicLocationY
-
按比例缩放水印
IsEqualProportion
-
查询导播台文本配置列表（查询文本配置）
﻿
调用接口： DescribeCasterMarkWordInfos
请求示例：
响应示例：
{
    "CasterId": 10000
}
﻿
{
    "Response": {
        "MarkWordInfos": [
            {
                "MarkWordIndex": 1,
                "MarkWordText": "腾讯云直播导播台",
                "MarkWordFontSize": 60,
                "MarkWordFontColor": "0xd0021b",
                "MarkWordFontType": 2,
                "MarkWordLocationX": 0.058,
                "MarkWordLocationY": 0.317,
                "MarkWordRollEnable": false,
                "MarkWordRollDirection": 0,
                "MarkWordRollOnceTime": 5,
                "MarkWordRollStartLocationX": 0.058,
                "MarkWordRollEndLocationX": 0.308,
                "MarkWordType": 0,
                "Description": "",
                "MarkWordRollCount": -1,
                "CountDownTime": ""
            }
        ],
        "RequestId": "1bc0dab9-285a-4872-9893-a9078c2293b1"
    }
}
页面字段与参数对应关系：
﻿
页面字段
参数
说明
类型
MarkWordType
-
字体
MarkWordFontType
-
字号
MarkWordFontSize
-
字体颜色
MarkWordFontColor
-
文字位置X
MarkWordLocationX
-
文字位置Y
MarkWordLocationY
-
文本
MarkWordText
-
显示方式
MarkWordRollEnable
固定显示，循环显示
获取导播台转场列表（查询支持的转场类型）
﻿
导播台支持画面切换时，使用转场特效，可通过接口查询具体支持的转场类型。
调用接口： DescribeCasterTransitionTypes
请求示例：通过腾讯云API调用时，该接口不需要额外参数。
{
    "Response": {
        "TransitionTypes": [
            {
                "TransitionType": "heart",
                "SourceUrl": "https://livecastercutto-1252813850.cos.ap-guangzhou.myqcloud.com/transition/heart.mp4",
                "Index": 1
            },
            {
                "TransitionType": "fade",
                "SourceUrl": "https://livecastercutto-1252813850.cos.ap-guangzhou.myqcloud.com/transition/fade.mp4",
                "Index": 2
            },
            {
                "TransitionType": "doorway",
                "SourceUrl": "https://livecastercutto-1252813850.cos.ap-guangzhou.myqcloud.com/transition/doorway.mp4",
                "Index": 3
            },
            {
                "TransitionType": "crosswarp",
                "SourceUrl": "https://livecastercutto-1252813850.cos.ap-guangzhou.myqcloud.com/transition/crosswarp.mp4",
                "Index": 4
            },
            {
                "TransitionType": "Mosaic",
                "SourceUrl": "https://livecastercutto-1252813850.cos.ap-guangzhou.myqcloud.com/transition/Mosaic.mp4",
                "Index": 5
            },
            {
                "TransitionType": "InvertedPageCurl",
                "SourceUrl": "https://livecastercutto-1252813850.cos.ap-guangzhou.myqcloud.com/transition/InvertedPageCurl.mp4",
                "Index": 6
            },
            {
                "TransitionType": "GlitchMemories",
                "SourceUrl": "https://livecastercutto-1252813850.cos.ap-guangzhou.myqcloud.com/transition/GlitchMemories.mp4",
                "Index": 7
            },
            {
                "TransitionType": "DreamyZoom",
                "SourceUrl": "https://livecastercutto-1252813850.cos.ap-guangzhou.myqcloud.com/transition/DreamyZoom.mp4",
                "Index": 8
            },
            {
                "TransitionType": "Dreamy",
                "SourceUrl": "https://livecastercutto-1252813850.cos.ap-guangzhou.myqcloud.com/transition/Dreamy.mp4",
                "Index": 9
            },
            {
                "TransitionType": "CircleCrop",
                "SourceUrl": "https://livecastercutto-1252813850.cos.ap-guangzhou.myqcloud.com/transition/CircleCrop.mp4",
                "Index": 10
            },
            {
                "TransitionType": "BowTieVertical",
                "SourceUrl": "https://livecastercutto-1252813850.cos.ap-guangzhou.myqcloud.com/transition/BowTieVertical.mp4",
                "Index": 11
            },
            {
                "TransitionType": "BowTieHorizontal",
                "SourceUrl": "https://livecastercutto-1252813850.cos.ap-guangzhou.myqcloud.com/transition/BowTieHorizontal.mp4",
                "Index": 12
            }
        ],
        "RequestId": "8c07ddc5-73f1-4b74-acf0-3b836323a610"
    }
}
页面字段与参数对应关系：
页面字段
参数
说明
-
SourceUrl
效果展示文件 URL
注意：
该接口返回变更概率较小，业务可通过缓存的方式固定查询结果。
查询导播台当前的预监、主监信息（查询导播台展示信息）
进入导播台页面查询基础配置后，若Status字段非0，则说明导播台处于预监或主监打开的状态，此时需要查询导播台当前的主监、预监信息，获取主监、预监使用的布局、水印等信息。
﻿
调用接口： DescribeCasterDisplayInfo
请求示例：
响应示例：
{
    "CasterId": 10000
}
﻿
﻿
{
    "Response": {
        "PvwDisplayInfo": {
            "LayoutIndex": 1,
            "LayoutIndexType": 1,
            "MarkPicIndexList": [
﻿
            ],
            "MarkWordIndexList": [
﻿
            ],
            "TransitionType": "",
            "AudioIndexList": [
﻿
            ]
        },
        "PgmDisplayInfo": {
            "LayoutIndex": 1,
            "LayoutIndexType": 1,
            "MarkPicIndexList": [
﻿
            ],
            "MarkWordIndexList": [
﻿
            ],
            "TransitionType": "",
            "AudioIndexList": [
﻿
            ]
        },
        "Status": 3,
        "StartLiveTime": 1727177914,
        "RequestId": "f4f87c9a-3b5f-4041-b6d1-2222d587285a"
    }
}
页面字段与参数对应关系：
页面字段
参数
说明
-
Status
与基础配置中 Status 字段同含义
-
PvwDisplayInfo
若 Status为2或3，代表预监所使用的布局、水印、转场等信息
-
PgmDisplayInfo
若 Status 为1或3，代表主监所使用的布局、水印、转场等信息
 PvwDisplayInfo/PgmDisplayInfo内部参数          
页面字段
参数
说明
-
LayoutIndex
布局 Index
-
LayoutIndexType
布局 Index 类型，可代表单输入布局和画中画布局，具体含义在创建主监、预监章节展开。
-
MarkPicIndexList
所使用的水印 Index 列表
-
MarkWordIndexList
所使用的文本 Index 列表
-
TransitionType
所使用的转场
-
AudioIndexList
音视频分离时，所使用的音频列表，具体含义在创建主监、预监章节展开。
获取导播台输入源、预监、主监的预览链接
﻿
在输入源被添加到云导播台之后，所有操作都将通过云导播台的后台进行统一处理。为了方便操作者进行预览，导播台提供了输入源、预监和主监的预览链接。这些预览链接实质上是直播播放地址。
注意：
预览链接仅供单人操作预览，不支持调整清晰度、分辨率和并发等自定义功能，不可用作最终直播的播放链接。
获取导播台视频流播放url（获取输入源预览链接）
调用接口： DescribeCasterPlayUrl
请求示例
响应示例：
{
    "CasterId": 10000,
    "PlayUrlType": 1,
    "PlayUrlIndex": 1
}
{
    "Response": {
        "PlayUrl": "rtmp://play.caster.tlivesource.com/merge/10000_251195401_1253817691_1_749994094_500?secret=xxx&ma=xxx",
        "WebRTCPlayUrl": "webrtc://play.caster.tlivesource.com/live/15368_251195401_1253817691_1_749994094_webrtc_500?txTime=66f2a03c&txSecret=xxx",
        "StreamId": "10000_251195401_1253817691_1_749994094",
        "RequestId": "cac6aead-2007-48dd-807b-2697a94afedc"
    }
}
﻿
页面字段与参数对应关系：
请求参数：
页面字段
参数
说明
-
PlayUrlType
查询输入源的预览信息时，固定为1
-
PlayUrlIndex
输入源的 InputIndex，此时必填
 响应参数：
PlayUrl 页面字段
参数
说明
-
PlayUrl
rtmp 协议预览地址
-
WebRTCPlayUrl
腾讯云快直播播放地址，若使用该地址，需接入腾讯云快直播sdk
-
StreamId
输入源在云导播台系统的内部流id，可供查询输入源质量数据
注意：
如果输入源刚被添加到云导播台系统，调用该接口时可能会出现 FailedOperation.InputIsNotActive 错误。这种情况通常是因为云导播台系统正在处理输入源，或者输入源没有有效数据所致。如果确认输入源是可访问的，可以每5秒重试调用接口一次，直到成功获取到预览链接。
获取预监（PVW）预览链接
在调用之前，请确保查询基础配置时的Status字段值为2或3。如果不是这两个值，调用该接口将返回 FailedOperation.InputIsNotActive 错误。
调用接口： DescribeCasterPlayUrl
请求示例
响应示例
{
    "CasterId": 10000,
    "PlayUrlType": 2
}
{
    "Response": {
        "PlayUrl": "rtmp://playtest.caster.tlivesource.com/merge/251195401_1253817691_10000_pvw_1024?secret=xxx&ma=xxx",
        "WebRTCPlayUrl": "webrtc://playtest.caster.tlivesource.com/live/251195401_1253817691_10000_pvw_webrtc_1024?txTime=66f2a25e&txSecret=xxx",
        "StreamId": "251195401_1253817691_1000_pvw",
        "RequestId": "c2bd1da9-fca4-40c9-9613-c4ba7c0e8a13"
    }
}
﻿
页面字段与参数对应关系：
请求参数：
页面字段
参数
说明
-
PlayUrlType
查询预监的预览信息时，固定为2
 响应参数：
页面字段
参数
说明
-
PlayUrl
rtmp协议预览地址
-
WebRTCPlayUrl
腾讯云快直播播放地址，若使用该地址，需接入腾讯云快直播sdk
-
StreamId
预监在云导播台系统的内部流id
获取主监（PGM）预览链接
在调用前，请确保在查询基础配置时，Status 字段的值为1或3。如果不是这两个数值，调用该接口会出现 FailedOperation.InputIsNotActive 错误。
调用接口： DescribeCasterPlayUrl
请求示例
响应示例
{
    "CasterId": 10000,
    "PlayUrlType": 3
}
{
    "Response": {
        "PlayUrl": "rtmp://playtest.caster.tlivesource.com/merge/251195401_1253817691_10000_pgm_1024?secret=xxx&ma=xxx",
        "WebRTCPlayUrl": "webrtc://playtest.caster.tlivesource.com/live/251195401_1253817691_10000_pgm_webrtc_1024?txTime=66f2a352&txSecret=xxx",
        "StreamId": "251195401_1253817691_10000_pgm",
        "RequestId": "3a807906-45e4-41e8-bd5a-849ae879ddef"
    }
}
页面字段与参数对应关系：
请求参数：
页面字段
参数
说明
-
PlayUrlType
查询主监的预览信息时，固定为3
 响应参数：
页面字段
参数
说明
-
PlayUrl
rtmp 协议预览地址
-
WebRTCPlayUrl
腾讯云快直播播放地址，若使用该地址，需接入腾讯云快直播sdk
--
StreamId
主监在云导播台系统的内部流id
添加、修改、删除输入源
云导播台支持多种类型的输入源，包括推流、直播、点播和图片等。不同类型的输入源对应不同的API参数。
注意：
本地推流需使用快直播推流SDK，属于高阶功能，在API使用文档上暂不做展开描述。
添加输入源
﻿
在添加输入源时，用户需要自行指定 InputIndex。该 InputIndex 在API层面的限制为1000以内。然而，较大的 InputIndex 值（例如300）可能会导致在页面上无法正常显示。
如果需要同时进行API操作和页面操作，建议将 InputIndex 的范围限制在1到30之间。
添加输入源时，必须确保该 InputIndex 尚未被配置。
添加直播推流URL
﻿
导播台内部采用了一套输入管理机制，因此业务无法自行生成推流地址以进行推流。因此，在添加直播推流URL时，首先需要请求以获取推流地址。
第一步，获取推流URL
调用接口： CreateCasterInputPushUrl
请求示例
响应示例
{
    "CasterId": 10000,
    "InputIndex": 1
}
{
    "Response": {
        "PushUrl": "rtmp://push.caster.tlivepush.com/live/10000_251195401_1253817691_1_1298170007?bizid=1253817691&secret=xxx",
        "RequestId": "90091bf4-5c93-414b-b42d-1ae072652340"
    }
}
﻿
﻿
其中，PushUrl 是生成的推流URL，其有效期为5分钟，请在5分钟内完成添加输入和推流操作。
第二步，新增导播台输入源（将推流URL添加到输入源中）
调用接口： AddCasterInputInfo
请求示例：
{
    "CasterId": 10000,
    "InputInfo": {
        "InputIndex": 1,
        "InputType": 0,
        "InputUrl": "rtmp://push.caster.tlivepush.com/live/10000_251195401_1253817691_1_1298170007?bizid=1253817691&secret=xxx"，
        "Description":""
    }
}
在请求参数中，当InputType为推流URL时，应固定设置为0，并将第一步中获取到的 PushUrl 填充到 InputUrl 字段中。同时，InputIndex 的设置应与第一步中的 InputIndex 保持一致。
响应示例：
{
    "Response": {
        "InputPlayUrl": "",
        "InputWebRTCPlayUrl": "webrtc://playtest.caster.tlivesource.com/live/10000_251195401_1253817691_1_1298170007_webrtc_500?txTime=66f37892&txSecret=xxx",
        "InputStreamId": "10000_251195401_1253817691_1_1298170007",
        "RequestId": "73a16ac5-5287-4f24-a14e-7a84ab944506"
    }
}
如果使用快直播进行预览，请使用InputWebRTCPlayUrl。如果选择 RTMP 协议进行预览，请先判断InputPlayUrl字段是否有值。若此字段已有内容，则可直接进行播放；若为空，请参考 获取输入源的预览链接 的指南操作。
页面字段与参数对应关系：
页面字段
参数
说明
备注名
Description
-
 添加直播拉流URL
﻿
在添加直播拉流 URL 之前，请确保播放链接可以正常播放。云导播台在处理直播拉流 URL 时的行为类似于播放器，如果无法通过拉流 URL 获取数据，则无法正常处理输入源或生成预览。
不同的协议会影响播放体验，建议使用 FLV 协议。
调用接口： AddCasterInputInfo
请求示例：
{
    "CasterId": 10000,
    "InputInfo": {
        "InputIndex": 1,
        "InputType": 2,
        "InputUrl": "http://example.com/live/example.flv"，
        "Description":"拉流示例"
    }
}
﻿
请求参数中，InputType 是拉流 url 时，固定为2，InputUrl 填充可用的拉流播放 URL。
响应示例：
{
    "Response": {
        "InputPlayUrl": "",
        "InputWebRTCPlayUrl": "webrtc://playtest.caster.tlivesource.com/live/10000_251195401_1253817691_1_22222222_webrtc_500?txTime=66f37892&txSecret=xxx",
        "InputStreamId": "10000_251195401_1253817691_1_22222222",
        "RequestId": "73a16ac5-5287-4f24-a14e-7a84ab944507"
    }
}
﻿
如果使用快直播进行预览，则使用 InputWebRTCPlayUrl。若使用 RTMP 协议预览，则先判断 InputPlayUrl 是否有值。若字段非空，则可直接播放。若字段为空，请参考 获取导播台视频流播放 URL（获取输入源预览链接）章节以获取输入源的预览链接。
页面字段与参数对应关系：
页面字段
参数
说明
备注名
Description
-
添加点播URL
﻿
注意：
URL 需要保证可被外网访问，点播文件需封装规范、交织良好，使用mp4等通用封装格式，多个 URL 时，导播台将按照 URL 顺序，逐个播放。
调用接口： AddCasterInputInfo
请求示例：
{
    "CasterId": 10000,
    "InputInfo": {
        "InputIndex": 1,
        "InputType": 1,
        "InputUrls": [
            "http://example.com/content/example.mp4",
            "http://example.com/content/another_example.mp4"
        ],
        "Description": "点播示例"
    }
}
﻿
请求参数中，InputType是点播url时，固定为1，InputUrls填充点播文件URL，此时需注意不再使用InputUrl字段。
{
    "Response": {
        "InputPlayUrl": "",
        "InputWebRTCPlayUrl": "webrtc://playtest.caster.tlivesource.com/live/10000_251195401_1253817691_1_3333333_webrtc_500?txTime=66f37892&txSecret=xxx",
        "InputStreamId": "10000_251195401_1253817691_1_3333333",
        "RequestId": "73a16ac5-5287-4f24-a14e-7a84ab944508"
    }
}
﻿
如果使用快直播进行预览，则使用InputWebRTCPlayUrl，若使用 RTMP 协议预览，则先判断 InputPlayUrl 是否有值，若字段非空，则可直接播放，若字段为空，参考 获取输入源预览链接 章节获取输入源的预览链接。
页面字段与参数对应关系：
页面字段
参数
说明
备注名
Description
-
添加图片URL
﻿
注意：
云导播台支持 PNG、JPG、JPEG、BMP、GIF 五种图片格式。图片 URL 必须可以通过公网访问，且 URL 后缀需以这五种格式之一结尾。
要使用本地图片，首先需要将其上传到图床以获取一“”个可用的 URL。
调用接口： AddCasterInputInfo
请求示例：
{
    "CasterId": 10000,
    "InputInfo": {
        "InputIndex": 1,
        "InputType": 3,
        "InputUrl": "http://example.com/picture/p1.jpg"，
        "Description":"图片示例"
    }
}
﻿
当请求参数中的 InputType 为图片URL时，应固定设置为3，并在 InputUrl 中填入图片文件的URL。
响应示例：
{
    "Response": {
        "InputPlayUrl": "http://example.com/picture/p1.jpg",
        "InputWebRTCPlayUrl": "webrtc://playtest.caster.tlivesource.com/live/_webrtc_500?txTime=66f38515&txSecret=xxx",
        "InputStreamId": "",
        "RequestId": "d844f691-dc3e-4951-a09c-c8ae475c36ed"
    }
}
﻿
与其他几种输入不同，图片 URL 没有预览链接。当输入为图片URL时，通过 获取导播台视频流播放 URL（获取输入源的预览链接）章节得到的 PlayUrl 实际上就是原始的图片 URL。而 InputWebRTCPlayUrl 所提供的地址则不可用。
页面字段与参数对应关系：
页面字段
参数
说明
备注名
Description
-
修改输入源
﻿
注意：
修改输入源时，请确保需要修改的InputIndex已有输入源，若没有，请参考上一节添加输入源。
在修改输入源时，请确保当前输入源未被预监或主监使用（包括单画面和画中画布局）。如果输入源正在被使用，修改接口将报错。
在修改输入源后，预览链接将发生变化。因此，在调用修改输入源后，请及时参照 获取导播台视频流播放URL（获取输入源的预览链接）以获取新的预览链接。
调用接口： ModifyCasterInputInfo
请求示例：
{
    "CasterId": 10000,
    "InputInfo": {
        "InputIndex": 1,
        "InputType": 1,
        "InputUrls": [
            "http://example.com/content/example.mp4",
            "http://example.com/content/another_example.mp4"
        ],
        "Description": "修改为点播文件示例"
    }
}
﻿
在请求参数中，根据新的输入源类型和URL等信息，直接覆盖填充InputType、InputUrl、InputUrls等信息。具体规则，请参考上一节“添加输入源”部分中的参数填充规则。
响应示例：
{
    "Response": {
        "InputPlayUrl": "",
        "InputWebRTCPlayUrl": "webrtc://playtest.caster.tlivesource.com/live/10000_251195401_1253817691_1_3333333_webrtc_500?txTime=66f37892&txSecret=xxx",
        "InputStreamId": "10000_251195401_1253817691_1_3333333",
        "RequestId": "73a16ac5-5287-4f24-a14e-7a84ab944508"
    }
}
﻿
﻿
如果使用快直播进行预览，则使用 InputWebRTCPlayUrl。若使用 RTMP 协议预览，则先判断 InputPlayUrl 是否有值。若字段非空，则可直接播放。若字段为空，请参考 获取导播台视频流播放URL（获取输入源的预览链接）章节以获取输入源的预览链接。
删除输入源
﻿
注意：
在删除输入源之前，请确认输入源当前并未被预监、主监所使用（包括单画面和画中画布局）。若被使用，删除接口将会报错。
删除输入源后，预览链接将失效。
调用接口： DeleteCasterInputInfo
请求示例：
响应示例：
{
    "CasterId": 10000,
    "InputIndex": 1
}
﻿
{
    "Response": {
        "RequestId": "d03ebf60-3734-4d64-9751-b19eaa6c4868"
    }
}
﻿
添加、修改、删除布局
云导播台支持多种布局，不仅提供了一系列现成的布局模板，供客户快速使用，还支持自定义布局。除了常规的画中画布局，还提供虚拟背景布局，适用于演播室等场景。
添加布局
﻿
在添加布局时，需要业务自行指定 LayoutIndex。LayoutIndex在API 层面的限制为1000以内。若同时需要进行 API 操作和页面操作，建议将LayoutIndex 的范围限制在1到30之间。
添加布局时，LayoutIndex 不能已存在配置。
添加模版布局
导播台支持的模版 ID 及对应的布局：
模版 ID
布局
模版所需输入个数
20
﻿
﻿
2
31
﻿
﻿
3
32
﻿
﻿
3
41
﻿
﻿
4
21
﻿
﻿
2
调用接口： AddCasterLayoutInfo
请求示例：
{
    "CasterId": 10000,
    "LayoutInfo": {
        "InputIndexList": "1|2",
        "LayoutIndex": 1,
        "LayoutTemplateId": 20
    }
}
﻿
InputIndexList 字段规则：
InputIndexList 由模板布局所需的输入源 InputIndex 组成，根据布局示例中按 A|B|C|D 顺序排列，生成的字符串即为 InputIndexList 字段值。
注意：
在InputIndexList中，输入源的数量（InputIndex个数）必须与模板所需的输入数量相匹配，并且不能有重复。
在页面模板布局41的示例中，InputIndexList的值应该是A|C|B|D，这与上述规则不同。
响应示例：
{
    "Response": {
        "RequestId": "5bd19641-da10-4f6c-955f-2da11e5196ab"
    }
}
﻿
添加自定义布局
﻿
调用接口： AddCasterLayoutInfo
请求示例：
{
    "CasterId": 1000,
    "LayoutInfo": {
        "InputIndexList": "1|2|3",
        "LayoutIndex": 1,
        "LayoutParams": [
            {
                "LayerHeight": 0.5,
                "LayerId": 1,
                "LayerLocationX": 0.0111,
                "LayerLocationY": 0.0247,
                "LayerWidth": 0.5,
                "UsePortraitSegment": false
            },
            {
                "LayerHeight": 0.5,
                "LayerId": 2,
                "LayerLocationX": 0.4554,
                "LayerLocationY": 0.1524,
                "LayerWidth": 0.5,
                "UsePortraitSegment": false
            },
            {
                "LayerHeight": 0.5,
                "LayerId": 3,
                "LayerLocationX": 0.202,
                "LayerLocationY": 0.4607,
                "LayerWidth": 0.5,
                "UsePortraitSegment": false
            }
        ]
    }
}
﻿
LayoutParams 字段规则：
LayoutParams字段类型为 CasterLayoutInfo 列表。对于普通的自定义布局，需要填充以下5个 CasterLayoutInfo 参数。
页面字段
参数
备注
-
LayerId
层级信息，表示前后关系
-
LayerHeight
高
-
LayerWidth
宽
-
LayerLocationX
X 轴坐标
-
LayerLocationY
Y 轴坐标
注意：
LayerId越小，表示该层越靠近底层；因此，在多层覆盖的情况下，具有较大 LayerId 的层会覆盖具有较小 LayerId 的层。
LayerHeight、LayerWidth、LayerLocationX、和LayerLocationY都使用比例值来表示，这些值代表了输入在整个布局中所占的大小和位置的相对关系。
单个输入不得超出布局范围，因此必须同时满足以下条件：
LayerHeight + LayerLocationY ≤ 1.0
LayerWidth + LayerLocationX ≤ 1.0
布局参考系为：
﻿
若有页面渲染需求，可参照以上规则进行自定义布局效果渲染。
InputIndexList 字段规则：
当使用自定义布局时，InputIndexList 字段的设置较为简单，需要按照 LayerId 的大小顺序排列，对应每一层的输入。
例如，如果A的输入 LayerId=1，B的输入 LayerId=2，C的输入 LayerId=3，则 InputIndexList 字段应设置为"A|B|C"。
响应示例：
{
    "Response": {
        "RequestId": "5bd19641-da10-4f6c-955f-2da11e5196ab"
    }
}
﻿
添加虚拟背景布局
虚拟背景功能一般多用于虚拟演播厅场景下，需要将抠像后的流信息与其他背景图片等进行混合输出。因此，云导播台提供虚拟背景抠像功能。
添加色度抠像布局
﻿
调用接口： AddCasterLayoutInfo
请求示例：
{
    "CasterId": 10000,
    "LayoutInfo": {
        "InputIndexList": "1|2",
        "LayoutIndex": 1,
        "LayoutParams": [
            {
                "LayerHeight": 1,
                "LayerId": 1,
                "LayerLocationX": 0,
                "LayerLocationY": 0,
                "LayerWidth": 1,
                "UsePortraitSegment": false
            },
            {
                "LayerHeight": 0.5,
                "LayerId": 2,
                "LayerLocationX": 0.4,
                "LayerLocationY": 0.4,
                "LayerWidth": 0.5,
                "PortraitSegmentParam": {
                    "Color": "0x00b241",
                    "Similarity": 20
                },
                "UsePortraitSegment": true
            }
        ]
    }
}
﻿
InputIndexList 字段规则：
与普通自定义布局规则一致，使用时，请注意要抠图的输入与 LayerId 的对应关系。
LayoutParams 字段规则：
其他参数与普通自定义布局规则一致，仅在 UsePortraitSegment和PortraitSegmentParam 参数上有所区别。
页面字段
参数
说明
-
UsePortraitSegment
绿幕抠图时，该字段为true
-
PortraitSegmentParam.Color
抠像背景的16进制颜色代码
-
PortraitSegmentParam.Similarity
一致性，允许范围[10,40]。数值越大，允许的颜色偏差越大，即更多的颜色可被抠除。数值越小，允许的颜色偏差越小，抠除的颜色范围越小。
响应示例：
{
    "Response": {
        "RequestId": "5bd19641-da10-4f6c-955f-2da11e5196ab"
    }
}
﻿
添加AI抠像布局
某些场景下无法获得有统一背景颜色的视频，也需要进行抠像时，可使用 AI 抠像布局。
﻿
调用接口： AddCasterLayoutInfo
请求示例：
{
    "CasterId": 10000,
    "LayoutInfo": {
        "InputIndexList": "1|2",
        "LayoutIndex": 1,
        "LayoutParams": [
            {
                "LayerHeight": 1,
                "LayerId": 1,
                "LayerLocationX": 0,
                "LayerLocationY": 0,
                "LayerWidth": 1,
                "UsePortraitSegment": false
            },
            {
                "LayerHeight": 0.5,
                "LayerId": 2,
                "LayerLocationX": 0.4,
                "LayerLocationY": 0.4,
                "LayerWidth": 0.5,
                "UsePortraitSegment": true
            }
        ]
    }
}
﻿
InputIndexList 字段规则：
与普通自定义布局规则一致。使用时，请注意要抠图的输入与LayerId的对应关系。
LayoutParams 字段规则：
其他参数与普通自定义布局规则一致，仅需要UsePortraitSegment字段。不需要填充PortraitSegmentParam参数。
﻿
页面字段
参数
说明
-
UsePortraitSegment
AI 抠像时，该字段为 true
响应示例：
{
    "Response": {
        "RequestId": "5bd19641-da10-4f6c-955f-2da11e5196ab"
    }
}
﻿
修改布局
﻿
注意：
在修改布局时，请确保需要修改的LayoutIndex已经存在。若没有，请参考上一节添加布局。
修改布局时，请确认布局当前并未被预监、主监所使用，若被使用，修改接口将会报错。
调用接口： ModifyCasterLayoutInfo
请求示例：
{
    "CasterId": 10000,
    "LayoutInfo": {
        "InputIndexList": "1|2",
        "LayoutIndex": 1,
        "LayoutTemplateId": 20
    }
}
﻿
请求参数中，直接根据新布局生成参数即可，具体的参数规则，请参考上节中添加布局部分的参数填入规则。
响应示例：
{
    "Response": {
        "RequestId": "3d81f9e3-bebb-4890-854f-065f2e6a9cee"
    }
}
﻿
删除布局
﻿
注意：
删除布局时，请确认布局当前并未被预监、主监所使用。若被使用，删除接口将会报错。
调用接口： DeleteCasterLayoutInfo
请求示例：
请求示例：
响应示例：
{
    "CasterId": 10000,
    "LayoutIndex": 1
}
﻿
{
    "Response": {
        "RequestId": "14b40b21-0efd-41dd-90a8-2c69cb0069d6"
    }
}
﻿
添加、修改、删除推流配置
云导播台是一种视频处理工具，它本身不具备大规模分发的能力。启动主监后，需要将云导播台输出的视频推流至腾讯云等源站，然后通过 CDN 进行分发以供观看。
注意：
在主监启动后，云导播台默认将一条流推送到腾讯云直播。如果业务尚未配置推送到腾讯云的流ID、域名等信息，云导播台将自动生成流 ID，并随机选择一个可用的推流域名。推流的 AppName 默认设置为“live”。
添加推流配置
新增导播台推流信息(添加推流到腾讯云)
若创建导播台后未开启过主监（PGM）,则推流到腾讯云的配置为空，可添加推流到腾讯云配置。若开启过主监（PGM），则将生成默认推流配置，此时请参见 修改推流配置 章节修改推流配置，因为直接调用添加配置的操作将会报错。
调用接口： AddCasterOutputInfo
请求示例：
{
    "CasterId": 10000,
    "OutputInfo": {
        "Description": "腾讯云直播",
        "OutputIndex": 0,
        "OutputStreamId": "example_output_stream_id",
        "OutputType": 1,
        "OutputDomainName": "yourpushdomain",
        "OutputAppName": "live",
        "OutputParam": ""
    }
}
﻿
参数说明：
页面字段
参数
说明
-
OutputIndex
推流到腾讯云，该值固定为0
-
OutputType
推流到腾讯云，该值固定为1
-
OutputStreamId
推送到腾讯云的流 ID
-
OutputDomainName
推流到腾讯云时使用的推流域名，该域名必须属于当前导播台所属账号
-
OutputAppName
推流到腾讯云时所使用的 AppName，不填默认为 live
-
OutputParam
推流到腾讯云时添加的推流参数
响应示例：
{
    "Response": {
        "RequestId": "90382b39-45fd-44e4-b5e5-89ca93738ca7"
    }
}
﻿
注意：
新配置将在下次启动主监时生效。
添加推流到第三方
调用接口： AddCasterOutputInfo
请求示例：
{
    "CasterId": 10000,
    "OutputInfo": {
        "Description": "第三方地址",
        "OutputIndex": 1,
        "OutputType": 2,
        "OutputUrl": "rtmp://third-push-domain/path/stream_id?param=param"
    }
}
﻿
参数说明：
页面字段
参数
说明
-
OutputIndex
推流到第三方，OutputIndex 不能为0
-
OutputType
推流到第三方，该值固定为2
-
OutputUrl
第三方推流地址
响应示例：
{
    "Response": {
        "RequestId": "90382b39-45fd-44e4-b5e5-89ca93738ca8"
    }
}
﻿
注意：
新配置将在下次启动主监时生效。
第三方推流地址不能使用本账号下的腾讯云直播推流域名。即如账号下有腾讯云直播推流域名A，则第三方推流地址URL中的域名不能为A。
修改推流配置
修改推流配置前，请确认OutputIndex对应的推流配置已经存在。若不存在，请参照 添加推流配置 部分以新增推流配置。
修改推流到腾讯云配置
调用接口： ModifyCasterOutputInfo
请求示例：
{
    "CasterId": 10000,
    "OutputInfo": {
        "Description": "腾讯云直播",
        "OutputIndex": 0,
        "OutputStreamId": "example_output_stream_id",
        "OutputType": 1,
        "OutputDomainName": "modify.example.domain",
        "OutputAppName": "live",
        "OutputParam": "exampleparam=param"
    }
}
﻿
参数说明：
页面字段
参数
说明
-
OutputIndex
推流到腾讯云配置，该值固定为0
-
OutputType
推流到腾讯云配置，该值固定为1
腾讯云直播流名称
OutputStreamId
推送到腾讯云的流 ID
推流域名
OutputDomainName
推流到腾讯云时使用的推流域名，该域名必须属于当前导播台所属账号
AppName
OutputAppName
当推流到腾讯云时，若不填写 AppName，默认值为 live。
自定义参数
OutputParam
在推流到腾讯云时添加的推流参数
响应示例：
{
    "Response": {
        "RequestId": "d5af495f-07ae-4770-b836-686167c826fe"
    }
}
﻿
注意：
修改后的新配置将在下次启动主监时生效。
修改推流到第三方配置
﻿
调用接口： ModifyCasterOutputInfo
请求示例：
{
    "CasterId": 10000,
    "OutputInfo": {
        "Description": "第三方厂商",
        "OutputIndex": 1,
        "OutputType": 2,
        "OutputUrl": "rtmp://modify.example.com/live/stream_id?param=param"
    }
}
﻿
参数说明：
页面字段
参数
说明
-
OutputIndex
推流到第三方，OutputIndex 不能为0
-
OutputType
推流到第三方，该值固定为2
转推地址
OutputUrl
第三方推流地址
厂商
Description
-
响应示例：
{
    "Response": {
        "RequestId": "90382b39-45fd-44e4-b5e5-89ca93738ca8"
    }
}
﻿
注意：
修改后的新配置将在下次启动主监时生效。
第三方推流地址不能使用本账号下的腾讯云直播推流域名。也就是说，如果账号下已有腾讯云直播推流域名 A，则第三方推流地址 URL 中的域名不能是A。
删除推流配置
注意：
推流到腾讯云的配置，在启动主监时不存在也会自动生成，因此一般不删除推流到腾讯云配置。
此处仅示例删除推流第三方配置。
﻿
调用接口： DeleteCasterOutputInfo
请求示例：
响应示例：
{
    "CasterId": 10000,
    "OutputIndex": 1
}
﻿
{
    "Response": {
        "RequestId": "2e157e05-dd3e-43ae-bd81-e75567f32a97"
    }
}
﻿
注意：
若主监正在运行，删除推流到第三方配置不会中断当前的转推。主监下次重新启动时，删除配置生效。
添加、修改、删除水印
在云导播台页面上，您可以上传本地文件。这一功能通过调用腾讯云直播的水印功能实现，以上传文件并获取访问 URL。同样地，当使用导播台 API 添加或修改水印时，您也需要上传图片以获取腾讯云水印 URL。具体操作步骤请参阅腾讯云直播水印功能的相关文档，本文档不再详述。
云导播台支持PNG、JPG、JPEG、BMP、GIF这五种格式的水印图片。
添加水印
添加水印，位置使用百分比信息
﻿
调用接口： AddCasterMarkPicInfo
请求示例：
响应示例：
{
    "CasterId": 10000,
    "MarkPicInfo": {
        "MarkPicIndex": 1,
        "Description": "",
        "MarkPicHeight": 0.2,
        "MarkPicWidth": 0.15,
        "MarkPicLocationX": 0.0297,
        "MarkPicLocationY": 0.0503,
        "MarkPicUrl": "https://livewatermark.com/xxx/watermark_img_xxx.png",
        "IsEqualProportion": true
    }
}
﻿
{
    "Response": {
        "RequestId": "99054fb5-4a33-4271-9773-99e032ad0b29"
    }
}
﻿
页面字段与参数对应关系：
页面字段
参数
说明
-
MarkPicIndex
非0值，建议在100以内
水印名称
Description
-
-
MarkPicHeight
坐标系与布局一致，值为比例值
-
MarkPicWidth
坐标系与布局一致，值为比例值
相对位置X
MarkPicLocationX
坐标系与布局一致，值为比例值
相对位置Y
MarkPicLocationY
坐标系与布局一致，值为比例值
-
MarkPicUrl
域名必须为腾讯云直播的水印域名，后缀为图片格式
按比例缩放水印
IsEqualProportion
仅作为状态保存，代表是否启用了按比例缩放水印
添加水印，位置使用精确像素信息
在某些情况下，水印的位置需要精确到像素级别，此时可以使用精确像素调整功能。
﻿
调用接口： AddCasterMarkPicInfo
请求示例：
响应示例：
{
    "CasterId": 10000,
    "MarkPicInfo": {
        "Description": "",
        "IsEqualProportion": true,
        "MarkPicHeight": 270,
        "MarkPicIndex": 1,
        "MarkPicLocationX": 38,
        "MarkPicLocationY": 43,
        "MarkPicUrl": "https://livewatermark.com/xxx/watermark_img_xxx.png",
        "MarkPicWidth": 330
    }
}
﻿
{
    "Response": {
        "RequestId": "99054fb5-4a33-4271-9773-99e032ad0b30"
    }
}
﻿
﻿
页面字段与参数对应关系：
页面字段
参数
说明
-
MarkPicIndex
非0值，建议在100以内
水印名称
Description
-
水印尺寸高
MarkPicHeight
坐标系与布局一致，值为像素值
水印尺寸宽
MarkPicWidth
坐标系与布局一致，值为像素值绝对位置X
绝对位置X
MarkPicLocationX
坐标系与布局一致，值为像素值
绝对位置Y
MarkPicLocationY
坐标系与布局一致，值为像素值
-
MarkPicUrl
域名必须为腾讯云直播的水印域名，后缀为图片格式
按比例缩放水印
IsEqualProportion
仅作为状态保存，代表是否启用了按比例缩放水印
注意：
若要使用精确像素位置，需保证水印的位置不会溢出到整体布局之外，若水印位置溢出，则无法正常显示水印。
修改水印
注意：
修改水印时，请确保MarkPicIndex存在对应的水印配置，若不存在，请使用参考上节添加水印。
修改水印时，请确认水印当前并未被预监、主监所使用，若被使用，修改接口将会报错。
﻿
以修改水印相对位置和大小为例。修改水印精确像素位置和大小参数参考添加水印，位置使用精确像素信息章节。
调用接口： ModifyCasterMarkPicInfo
请求示例：
响应示例：
{
    "CasterId": 10000,
    "MarkPicInfo": {
        "MarkPicIndex": 1,
        "Description": "",
        "MarkPicHeight": 0.4,
        "MarkPicWidth": 0.3,
        "MarkPicLocationX": 0.05,
        "MarkPicLocationY": 0.10,
        "MarkPicUrl": "https://livewatermark.com/xxx/watermark_img_xxx.png",
        "IsEqualProportion": true
    }
}
﻿
{
    "Response": {
        "RequestId": "15054fb5-4a33-4271-9773-99e032ad0b29"
    }
}
﻿
页面字段与参数对应关系：
页面字段
参数
说明
-
MarkPicIndex
修改时对应的配置需存在
水印名称
Description
-
-
MarkPicHeight
坐标系与布局一致，值为比例值
-
MarkPicWidth
坐标系与布局一致，值为比例值
相对位置X
MarkPicLocationX
坐标系与布局一致，值为比例值
相对位置Y
MarkPicLocationY
坐标系与布局一致，值为比例值
-
MarkPicUrl
域名必须为腾讯云直播的水印域名，后缀为图片格式
按比例缩放水印
IsEqualProportion
仅作为状态保存，代表是否启用了按比例缩放水印
删除水印
﻿
注意：
删除水印时，请确认水印当前并未被预监、主监所使用，若被使用，删除接口将会报错。
调用接口： DeleteCasterMarkPicInfo
请求示例：
响应示例：
{
    "CasterId": 10000,
    "MarkPicIndex": 1
}
{
    "Response": {
        "RequestId": "24b40b21-0efd-41dd-90a8-2c69cb0069d6"
    }
}
﻿
添加、修改、删除文本
云导播台的文本功能最多支持512个字符，支持将文本固定显示或滚动展示，并且可以在布局内随意调整其位置。
添加文本
在添加文本前，请确认MarkWordIndex没有对应的配置。如果有，请参考修改文本章节进行调整。
添加普通类型固定文本
﻿
调用接口： AddCasterMarkWordInfo
请求示例：
响应示例：
{
    "CasterId": 10000,
    "MarkWordInfo": {
        "MarkWordFontColor": "0xd0021b",
        "MarkWordFontSize": 60,
        "MarkWordFontType": 2,
        "MarkWordIndex": 1,
        "MarkWordLocationX": 0.0198,
        "MarkWordLocationY": 0.0678,
        "MarkWordRollEnable": false,
        "MarkWordRollEndLocationX": 0.0,
        "MarkWordRollStartLocationX": 0.0,
        "MarkWordRollCount": -1,
        "MarkWordText": "腾讯云导播台欢迎您！",
        "MarkWordType": 0
    }
}
﻿
{
    "Response": {
        "RequestId": "a906895f-9988-42f7-95fd-194200df1fb4"
    }
}
﻿
页面字段与参数对应关系：
页面字段
参数
说明
类型
MarkWordType
普通文本类型，值默认为0
-
MarkWordText
文本内容，上限512个字符
字体
MarkWordFontType
1：宋体，2：黑体
字号
MarkWordFontSize
字体大小，范围为16至60
-
MarkWordFontColor
字体颜色的十六进制颜色代码
文字位置X
MarkWordLocationX
坐标系与布局一致，值为比例值
文字位置Y
MarkWordLocationY
坐标系与布局一致，值为比例值
显示方式
MarkWordRollEnable
固定显示时，该值固定为false
注意：
在请求中，可以暂时忽略 MarkWordRollCount、MarkWordRollEndLocationX、MarkWordRollStartLocationX 参数，按照示例进行填写即可。
添加普通类型滚动文本
﻿
调用接口： AddCasterMarkWordInfo
请求示例：
响应示例：
{
    "CasterId": 10000,
    "MarkWordInfo": {
        "MarkWordFontColor": "0xd0021b",
        "MarkWordFontSize": 60,
        "MarkWordFontType": 1,
        "MarkWordIndex": 1,
        "MarkWordLocationX": 0.0198,
        "MarkWordLocationY": 0.0352,
        "MarkWordRollCount": -1,
        "MarkWordRollEnable": true,
        "MarkWordRollStartLocationX": 0.02,
        "MarkWordRollEndLocationX": 0.25,
        "MarkWordText": "腾讯云导播台欢迎您！",
        "MarkWordType": 0
    }
}
﻿
{
    "Response": {
        "RequestId": "6dfe2386-da11-4ff4-8db6-ae7bcbfece2e"
    }
}
﻿
页面字段与参数对应关系：
页面字段
参数
说明
类型
MarkWordType
普通文本类型，值默认为0
-
MarkWordText
文本内容，上限512个字符
字体
MarkWordFontType
1：宋体，2：黑体
字号
MarkWordFontSize
字体大小，范围为16至60
-
MarkWordFontColor
字体颜色的十六进制颜色代码
文字位置X
MarkWordLocationX
坐标系与布局一致，值为比例值
文字位置Y
MarkWordLocationY
坐标系与布局一致，值为比例值
显示方式
MarkWordRollEnable
当循环滚动显示时，该值始终为true
-
MarkWordRollStartLocationX
坐标系与布局一致，值为比例值，表示滚动的起始X轴坐标
-
MarkWordRollEndLocationX
坐标系与布局一致，值为比例值，表示滚动的结束X轴坐标
-
MarkWordRollCount
循环滚动时，该值固定为-1，单次循环时为1
添加时钟
云导播台的时钟功能是基于文本功能实现的，因此添加时钟配置时使用的也是添加文本的接口。
﻿
调用接口： AddCasterMarkWordInfo
请求示例：
响应示例：
{
    "CasterId": 10000,
    "MarkWordInfo": {
        "MarkWordFontColor": "0xd0021b",
        "MarkWordFontSize": 60,
        "MarkWordFontType": 1,
        "MarkWordIndex": 1,
        "MarkWordLocationX": 0.0156,
        "MarkWordLocationY": 0.0428,
        "MarkWordRollEnable": false,
        "MarkWordRollCount": -1,
        "MarkWordRollEndLocationX": 0.0,
        "MarkWordRollStartLocationX": 0.0,
        "MarkWordText": "HH:mm:ss",
        "MarkWordType": 2
    }}
﻿
{
    "Response": {
        "RequestId": "a44b1cba-fa5f-4c0f-800c-b1e9098bd9ff"
    }
}
﻿
页面字段与参数对应关系：
页面字段
参数
说明
类型
MarkWordType
时钟类型，值默认为2
时钟类型
MarkWordText
时钟类型时，仅允许填入以下两种格式：
HH:mm:ss：表示时间。
yyyy-MM-dd HH:mm:ss：表示日期+时间。
字体
MarkWordFontType
1：宋体，2：黑体
字号
MarkWordFontSize
字体大小，范围为16至60
-
MarkWordFontColor
字体颜色的十六进制颜色代码
文字位置X
MarkWordLocationX
坐标系与布局一致，值为比例值
文字位置Y
MarkWordLocationY
坐标系与布局一致，值为比例值
-
MarkWordRollEnable
时钟，该值固定为false
注意：
请求中的MarkWordRollCount、MarkWordRollEndLocationX、MarkWordRollStartLocationX参数可暂时忽略，按示例填即可。
修改文本
注意：
修改文本时，请确保 MarkWordIndex 存在对应的文本配置，若不存在，请使用参考上节添加文本。
修改文本时，请确认文本当前并未被预监、主监所使用，若被使用，修改接口将会报错。
﻿
调用接口： ModifyCasterMarkWordInfo
请求示例：
响应示例：
{
    "CasterId": 10000,
    "MarkWordInfo": {
        "MarkWordFontColor": "0xd0021b",
        "MarkWordFontSize": 60,
        "MarkWordFontType": 2,
        "MarkWordIndex": 1,
        "MarkWordLocationX": 0.0255,
        "MarkWordLocationY": 0.0931,
        "MarkWordRollEnable": false,
        "MarkWordRollEndLocationX": 0.0,
        "MarkWordRollStartLocationX": 0.0,
        "MarkWordRollCount": -1,
        "MarkWordText": "腾讯云直播导播台",
        "MarkWordType": 0
    }
}
﻿
{
    "Response": {
        "RequestId": "01059da3-ae42-4508-92ea-e1a209e6aedd"
    }
}
﻿
页面字段与参数对应关系：与添加文本中的参数含义一致，不再赘述。
删除文本
﻿
注意：
删除文本时，请确认文本当前并未被预监、主监所使用，若被使用，删除接口将会报错。
调用接口： DeleteCasterMarkWordInfo
请求示例：
响应示例：
{
    "CasterId": 10000,
    "MarkWordIndex": 1
}
﻿
{
    "Response": {
        "RequestId": "08a035a2-03bc-43dc-ac5a-aec556fb61c9"
    }
}
﻿
修改主监配置
﻿
调用接口： ModifyCaster
请求示例：
响应示例：
{
    "CasterId": 10000,
    "DelayTime": 60,
    "PgmAudioBitRate": 12,
    "PgmBitRate": 0,
    "PgmFps": 0,
    "PgmHeight": 1080,
    "PgmWidth": 1920
}
﻿
延时播放{
    "Response": {
        "RequestId": "86f6611d-4691-4907-93a1-5e68ff1a1033"
    }
}
﻿
页面字段与参数对应关系：
页面字段
参数
说明
延时播放
DelayTime
允许范围0到600，支持10分钟内延时播放
视频宽
PgmWidth
填0时表示随源输出，PgmWidth 和 PgmHeight 需同时为0或同时非0
视频高
PgmHeight
填0时表示随源输出，PgmWidth 和 PgmHeight 需同时为0或同时非0
视频帧率
PgmFps
填0时表示随源输出
视频码率
PgmBitRate
填0时表示随源输出
音频码率
PgmAudioBitRate
填0时表示随源输出
注意：
若 DelayTime不为0，例如设为60秒，则在启动主监控后，需要等待60秒才能获取到主监控的预览链接，并且在这60秒之后，主监控才开始向腾讯云直播和第三方推流。
若在启动主监后修改了主监的配置，这些配置将在下一次启动时生效。若需要配置立即生效，必须先关闭主监，然后再重新打开。
启动、修改、停止预监
在云导播台中，主监负责最终输出到直播的画面，即观众所看到的内容，而预监则是操作者自己观看的画面。预监和主监的内容可以相同，也可以不同。例如，如果需要检查切换布局或添加水印后的效果，同时又不希望影响观众观看体验，就可以先在预监上进行调整，完成后再将配置复制到主监。
启动预监
启动单画面布局预监
在添加、修改、删除布局章节的布局管理中，您可能已经注意到，我们创建或修改的布局至少都包含两个输入源。这样设计是有意为之，因为如果仅使用单个画面，则还需创建一个单画面布局，这在使用流程上显得过于复杂。对于仅需使用单画面的场景，只需在参数中进行相应设置即可。
﻿
调用接口： CreateCasterPvw
请求示例：
{
    "CasterId": 10000,
    "PvwDisplayInfo": {
        "LayoutIndex": 1,
        "LayoutIndexType": 1,
        "TransitionType": ""
    }
}
﻿
当使用单画面布局时，LayoutIndexType 字段设置为1。此时，LayoutIndex 代表的是输入源 InputIndex，而非布局 LayoutIndex。
如上设置即代表使用预监画面使用输入1的画面。
响应示例：
{
    "Response": {
        "PvwPlayUrl": "rtmp://play.caster.tlivesource.com/merge/251195401_1253817691_10000_pvw_1024?secret=xxx&ma=xxx",
        "PvwWebRTCPlayUrl": "webrtc://play.caster.tlivesource.com/live/251195401_1253817691_10000_pvw_webrtc_1024?txTime=66f3d31a&txSecret=xxx",
        "RequestId": "4b9f4974-b42e-4324-9bed-b6e278369c53"
    }
}
﻿
﻿
在响应参数中，PvwPlayUrl 字段表示的是使用 RTMP 协议的预览链接，PvwWebRTCPlayUrl字段表示的是预监的快直播预览链接，需通过快直播播放sdk播放。预览链接都有有效期。若过期，可以参考 获取预监（PVW）预览链接 章节，以重新获取预览链接。
启动普通布局预监
﻿
调用接口： CreateCasterPvw
请求示例：
{
    "CasterId": 10000,
    "PvwDisplayInfo": {
        "LayoutIndex": 1,
        "LayoutIndexType": 0,
        "TransitionType": ""
    }
}
﻿
当使用普通布局时，LayoutIndexType 字段设置为0，此时LayoutIndex代表的是布局的LayoutIndex。
如上设置即代表使用预监画面使用布局1的画面。
响应示例：
{
    "Response": {
        "PvwPlayUrl": "rtmp://play.caster.tlivesource.com/merge/251195401_1253817691_10000_pvw_1024?secret=xxx&ma=xxx",
        "PvwWebRTCPlayUrl": "webrtc://play.caster.tlivesource.com/live/251195401_1253817691_10000_pvw_webrtc_1024?txTime=66f3d31a&txSecret=xxx",
        "RequestId": "4b9f4974-b42e-4324-9bed-b6e278369c54"
    }
}
﻿
响应参数中与上小节相同，后续不再赘述。
启动预监时使用水印：
﻿
调用接口： CreateCasterPvw
请求示例：
{
    "CasterId": 10000,
    "PvwDisplayInfo": {
        "LayoutIndex": 1,
        "LayoutIndexType": 0,
        "MarkPicIndexList": [
            1
        ],
        "TransitionType": ""
    }
}
﻿
MarkPicIndexList字段即为需要使用的水印MarkPicIndex，最多同时允许使用5个水印。
响应示例：
{
    "Response": {
        "PvwPlayUrl": "rtmp://play.caster.tlivesource.com/merge/251195401_1253817691_10000_pvw_1024?secret=xxx&ma=xxx",
        "PvwWebRTCPlayUrl": "webrtc://play.caster.tlivesource.com/live/251195401_1253817691_10000_pvw_webrtc_1024?txTime=66f3d31a&txSecret=xxx",
        "RequestId": "4347e12f-f807-4913-96d4-80f6619f0131"
    }
}
﻿
启动预监时使用文本
﻿
调用接口： CreateCasterPvw
请求示例：
{
    "CasterId": 10000,
    "PvwDisplayInfo": {
        "LayoutIndex": 1,
        "LayoutIndexType": 0,
        "MarkWordIndexList": [
            1
        ],
        "TransitionType": ""
    }
}
﻿
MarkWordIndexList字段即为需要使用的文字 MarkWordIndex，最多同时允许使用5个文本。
响应示例：
{
    "Response": {
        "PvwPlayUrl": "rtmp://play.caster.tlivesource.com/merge/251195401_1253817691_10000_pvw_1024?secret=xxx&ma=xxx",
        "PvwWebRTCPlayUrl": "webrtc://play.caster.tlivesource.com/live/251195401_1253817691_10000_pvw_webrtc_1024?txTime=66f3d31a&txSecret=xxx",
        "RequestId": "1fa1afe6-023d-462e-9305-9b6a04a2de5e"
    }
}
﻿
注意：
水印和文本可以同时在预览中使用。
{
    "CasterId": 10000,
    "PvwDisplayInfo": {
        "LayoutIndex": 1,
        "LayoutIndexType": 0,
        "MarkWordIndexList": [
            1
        ],
        "MarkPicIndexList": [
            1
        ],
        "TransitionType": ""
    }
}
﻿
修改预监
与输入、布局、推流等配置不同，修改预监没有单独的修改接口，其修改功能仍然通过CreateCasterPvw接口实现。这主要是因为，与其他配置相比，预监使用的布局参数较少，使用同一接口并在每次调用时利用 PvwDisplayInfo 中的参数，这样做更加易于理解且效率更高。
切换预监布局
以从单画面布局1切换到单画面布局2为例：
调用接口： CreateCasterPvw
请求示例：
响应示例：
{
    "CasterId": 10000,
    "PvwDisplayInfo": {
        "LayoutIndex": 2,
        "LayoutIndexType": 1,
        "TransitionType": ""
    }
}
﻿
{
    "Response": {
        "PvwPlayUrl": "rtmp://play.caster.tlivesource.com/merge/251195401_1253817691_10000_pvw_1024?secret=xxx&ma=xxx",
        "PvwWebRTCPlayUrl": "webrtc://play.caster.tlivesource.com/live/251195401_1253817691_10000_pvw_webrtc_1024?txTime=66f3d31a&txSecret=xxx",
        "RequestId": "4b9f4974-b42e-4324-9bed-b6e278369c53"
    }
}
﻿
修改预监时，响应中同样也会返回PvwPlayUrl和PvwWebRTCPlayUrl，正常情况下，这两个URL与创建预监时返回的URL除了query param不同，其他均相同。
业务可根据预监预览链接的播放状态判断是否需要重新拉流，若预览链接播放已经停止，可使用新返回的预览链接播放，若预览链接播放正常，则可继续使用原有预览链接。
切换预监布局，画面切换时使用转场
﻿
以单画面布局1切换单画面布局2，使用 heart 转场效果为例：
调用接口： CreateCasterPvw
请求示例：
响应示例：
{
    "CasterId": 10000,
    "PvwDisplayInfo": {
        "LayoutIndex": 2,
        "LayoutIndexType": 1,
        "TransitionType": "heart"
    }
}
﻿
{
    "Response": {
        "PvwPlayUrl": "rtmp://play.caster.tlivesource.com/merge/251195401_1253817691_10000_pvw_1024?secret=xxx&ma=xxx",
        "PvwWebRTCPlayUrl": "webrtc://play.caster.tlivesource.com/live/251195401_1253817691_10000_pvw_webrtc_1024?txTime=66f3d31a&txSecret=xxx",
        "RequestId": "4b9f4974-b42e-4324-9bed-b6e278369c53"
    }
}
﻿
响应参数与上一小节一致。
停止预监
﻿
调用接口： StopCasterPvw
请求示例：
响应示例：
{
    "CasterId": 10000
}
﻿
{
    "Response": {
        "RequestId": "33978bfc-8fb4-4409-ae45-2ea6409bfdef"
    }
}
﻿
注意：
停止预监后，预监的所有预览链接将无法播放。
启动、修改、停止主监
主监任务影响着云导播台的输出，对主监的任何修改都将影响到最终观众所看到的画面。
注意：
启动主监后，将会开启计费，关闭主监后停止计费。
主监可单独启动，不要求一定要有预监，业务可根据自己的业务特点，判断是否需要启动预监任务。
推流到腾讯云直播和推流到第三方都需要在主监启动后才可正常运行。
启动主监
复制预监配置启动主监
应用场景为先在预监上调整好所需的输入、水印等效果，再一键将配置复制到主监上进行输出。
注意：
需保证预监任务已经存在。
﻿
调用接口： CreateCasterPgmFromPvw
请求示例：
响应示例：
{
    "CasterId": 10000
}
﻿
{
    "Response": {
        "PgmPlayUrl": "rtmp://playtest.caster.tlivesource.com/merge/251195401_1253817691_15368_pgm_1024?secret=xxx&ma=xxx",
        "PgmWebRTCPlayUrl": "webrtc://playtest.caster.tlivesource.com/live/251195401_1253817691_15368_pgm_webrtc_1024?txTime=66f3f466&txSecret=xxx",
        "CdnStreamId": "1253817691_9de458965db9c80e1afc5af36a8f93b6",
        "RequestId": "d9684fea-7998-4f5d-b96b-58feb1b36715"
    }
}
﻿
响应参数中，PgmPlayUrl字段表示的是主监的 RTMP 协议预览链接，PgmWebRTCPlayUrl 字段表示的是主监的快直播预览链接，需通过快直播播放sdk播放。
主监预览链接都有有效期，若过期，可参考“获取主监（PGM）预览链接”章节重新获取主监预览链接。
CdnStreamId 为主监推送到腾讯云直播时，在腾讯云直播上的流ID，可通过该流ID生成腾讯云CDN播放链接。
复制预监配置启动主监，启动时单画面输入源从头开始播放
某些场景中，预监当前正在使用一个单画面点播输入源。在启动主监任务时，希望主监任务可以从头开始播放该输入源。
注意：
需保证预监任务已经存在。
﻿
调用接口： CreateCasterPgmFromPvw
请求示例：
{
    "CasterId": 10000,
    "InputStartType": 1
}
﻿
注意：
当InputStartType为1，代表启用单画面点播输入从头开始播放功能。若布局非单画面点播输入，则不从头播放，从当前进度继续播放。
响应示例：
{
    "Response": {
        "PgmPlayUrl": "rtmp://playtest.caster.tlivesource.com/merge/251195401_1253817691_15368_pgm_1024?secret=xxx&ma=xxx",
        "PgmWebRTCPlayUrl": "webrtc://playtest.caster.tlivesource.com/live/251195401_1253817691_15368_pgm_webrtc_1024?txTime=66f3f466&txSecret=xxx",
        "CdnStreamId": "1253817691_9de458965db9c80e1afc5af36a8f93b6",
        "RequestId": "a7322f29-e462-4251-8fb3-a73f57dba0a5"
    }
}
﻿
响应参数与上一小节相同，不再赘述。
单独启动主监
除了从预监复制配置启动主监，主监也可单独启动。启动主监时所需的参数与预监字段名、含义均相同，此处以单独启动单画面布局1，使用水印1，文字1的主监为例。
调用接口： CreateCasterPgm
请求示例：
响应示例：
{
    "CasterId": 10000,
    "PgmDisplayInfo": {
        "LayoutIndex": 1,
        "LayoutIndexType": 1,
        "TransitionType": "",
        "MarkWordIndexList": [
            1
        ],
        "MarkPicIndexList": [
            1
        ]
    }
}
﻿
{
    "Response": {
        "PgmPlayUrl": "rtmp://playtest.caster.tlivesource.com/merge/251195401_1253817691_15368_pgm_1024?secret=xxx&ma=xxx",
        "PgmWebRTCPlayUrl": "webrtc://playtest.caster.tlivesource.com/live/251195401_1253817691_15368_pgm_webrtc_1024?txTime=66f3f466&txSecret=xxx",
        "CdnStreamId": "1253817691_9de458965db9c80e1afc5af36a8f93b6",
        "RequestId": "a7322f29-e462-4251-8fb3-a73f57dba0a6"
    }
}
﻿
单独启动主监，启动时单画面输入源从头开始播放
调用接口： CreateCasterPgm
请求示例：
{
    "CasterId": 10000,
    "PgmDisplayInfo": {
        "LayoutIndex": 1,
        "LayoutIndexType": 1,
        "TransitionType": "",
        "MarkWordIndexList": [
            1
        ],
        "MarkPicIndexList": [
            1
        ],
        "InputStartType": 1
    }
}
﻿
注意：
当InputStartType为1，代表启用单画面点播输入从头开始播放功能。若布局非单画面点播输入，则不从头播放，从当前进度继续播放。
响应示例：
{
    "Response": {
        "PgmPlayUrl": "rtmp://playtest.caster.tlivesource.com/merge/251195401_1253817691_15368_pgm_1024?secret=xxx&ma=xxx",
        "PgmWebRTCPlayUrl": "webrtc://playtest.caster.tlivesource.com/live/251195401_1253817691_15368_pgm_webrtc_1024?txTime=66f3f466&txSecret=xxx",
        "CdnStreamId": "1253817691_9de458965db9c80e1afc5af36a8f93b6",
        "RequestId": "a7322f29-e462-4251-8fb3-a73f57dba0a7"
    }
}
﻿
修改主监
与修改预监类似，修改主监也不提供新的接口，修改主监功能同样使用CreateCasterPgm接口完成。
切换主监布局
以从单画面布局1切换到单画面布局2为例：
调用接口： CreateCasterPgm
请求示例：
响应示例：
{
    "CasterId": 10000,
    "PgmDisplayInfo": {
        "LayoutIndex": 2,
        "LayoutIndexType": 1,
        "TransitionType": ""
    }
}
﻿
{
    "Response": {
        "PgmPlayUrl": "rtmp://playtest.caster.tlivesource.com/merge/251195401_1253817691_15368_pgm_1024?secret=xxx&ma=xxx",
        "PgmWebRTCPlayUrl": "webrtc://playtest.caster.tlivesource.com/live/251195401_1253817691_15368_pgm_webrtc_1024?txTime=66f3f466&txSecret=xxx",
        "CdnStreamId": "1253817691_9de458965db9c80e1afc5af36a8f93b6",
        "RequestId": "a7322f29-e462-4251-8fb3-a73f57dba0a8"
    }
}
﻿
与预监类似，PgmPlayUrl和PgmWebRTCPlayUrl，正常情况下，这两个URL与创建主监时返回的URL除了query param不同，其他均相同。
业务可根据主监预览链接的播放状态判断是否需要重新拉流，若预览链接播放已经停止，可使用新返回的预览链接播放，若预览链接播放正常，则可继续使用原有预览链接。
修改主监布局，画面切换时使用转场
﻿
以单画面布局1切换单画面布局2，使用heart转场效果为例：
调用接口： CreateCasterPgm
请求示例：
响应示例：
{
    "CasterId": 10000,
    "PgmDisplayInfo": {
        "LayoutIndex": 2,
        "LayoutIndexType": 1,
        "TransitionType": "heart"
    }
}
﻿
{
    "Response": {
        "PgmPlayUrl": "rtmp://playtest.caster.tlivesource.com/merge/251195401_1253817691_15368_pgm_1024?secret=xxx&ma=xxx",
        "PgmWebRTCPlayUrl": "webrtc://playtest.caster.tlivesource.com/live/251195401_1253817691_15368_pgm_webrtc_1024?txTime=66f3f466&txSecret=xxx",
        "CdnStreamId": "1253817691_9de458965db9c80e1afc5af36a8f93b6",
        "RequestId": "a7322f29-e462-4251-8fb3-a73f57dba0a9"
    }
}
﻿
修改主监，切换到单画面输入源时，从头开始播放
以单画面布局1切换单画面布局2为例：
调用接口： CreateCasterPgm
请求示例：
响应示例：
{
    "CasterId": 10000,
    "PgmDisplayInfo": {
        "LayoutIndex": 2,
        "LayoutIndexType": 1,
        "TransitionType": "",
        "InputStartType": 1
    }
}
﻿
{
    "Response": {
        "PgmPlayUrl": "rtmp://playtest.caster.tlivesource.com/merge/251195401_1253817691_15368_pgm_1024?secret=xxx&ma=xxx",
        "PgmWebRTCPlayUrl": "webrtc://playtest.caster.tlivesource.com/live/251195401_1253817691_15368_pgm_webrtc_1024?txTime=66f3f466&txSecret=xxx",
        "CdnStreamId": "1253817691_9de458965db9c80e1afc5af36a8f93b6",
        "RequestId": "a7322f29-e462-4251-8fb3-a73f57dba0aa"
    }
}
﻿
停止主监
﻿
调用接口： StopCasterPgm
请求示例：
响应示例：
{
    "CasterId": 10000
}
﻿
{
    "Response": {
        "RequestId": "931b97fc-7f06-4ae6-9d36-157577324a25"
    }
}
﻿
注意：
停止主监后，主监的所有预览链接将无法播放。
停止主监后，推流到腾讯云和第三方地址将会停止。
停止主监后，将停止计费。
进阶功能
文档的前述部分介绍了导播台的基础功能及其相应的API调用方法。然而，并未覆盖导播台页面上的所有功能。因为某些高级功能的调用和理解相对复杂，所以将在本节中进行详细讲解。如果您的业务场景中不需要这些高级功能，可以跳过本节。
音视频不同步切换
应用场景：多视角演唱会。在多视角源流之间，进度可能不一致（受限于非可控直播环境等情况）。默认情况下，从画面1切换到画面2时，音频也会从画面1的音频切换到画面2的音频。在多个画面之间切换时，就可能会出现音频不连贯的情况。使用音视频不同步切换功能，可以实现仅将画面从1切换到2，同时继续使用画面1的音频，以保持音频输出的连贯性。
﻿
﻿
上图表示的是使用输入1的画面和输入2的音频。
以切换从单画面布局1到单画面布局2，同时继续使用画面1的音频为例：
调用接口： CreateCasterPgm
请求示例：
{
    "CasterId": 10000,
    "PgmDisplayInfo": {
        "LayoutIndex": 2,
        "LayoutIndexType": 1,
        "TransitionType": "",
        "AudioIndexList": [
            1
        ]
    }
}
﻿
页面字段与参数对应关系：
页面字段
参数
说明
-
AudioIndexList
使用哪些输入的音频，当该字段非空，且与 LayoutIndex 中代表的输入不同时，代表使用音视频不同步切换。
响应示例：
{
    "Response": {
        "PgmPlayUrl": "rtmp://playtest.caster.tlivesource.com/merge/251195401_1253817691_15368_pgm_1024?secret=xxx&ma=xxx",
        "PgmWebRTCPlayUrl": "webrtc://playtest.caster.tlivesource.com/live/251195401_1253817691_15368_pgm_webrtc_1024?txTime=66f3f466&txSecret=xxx",
        "CdnStreamId": "1253817691_9de458965db9c80e1afc5af36a8f93b6",
        "RequestId": "cd322f29-e462-4251-8fb3-a73f57dba0a8"
    }
}
﻿
断流时设置备播
应用场景：在一些重要的直播场景下，如果正在直播的源发生断流等情况时，需要快速切换到备流或垫场图片。导播台备播在输入源中断时，会按优先备播视频、次优先备播图片、保底黑屏的优先级进行切换，并在源恢复后迅速切换到源画面上。
﻿
注意：
备播视频和备播图片底层仍是两个输入源，因此除了InputIndex外的参数与普通输入源并无区别，新增、修改、删除的接口与输入源新增、修改、删除接口一致。
新增断流时备播视频
以新增一个点播备播视频为例，新增直播备播URL参考添加直播拉流URL章节类推。
调用接口： AddCasterInputInfo
{
    "CasterId": 10000,
    "InputInfo": {
        "InputIndex": 98765,
        "InputType": 1,
        "InputUrls": [
            "http://example.com/content/back_example.mp4"
        ],
        "Description": "备播视频"
    }
}
﻿
参数与添加一个普通输入源并没有太大区别，仅在 InputIndex 字段不太一致。
页面字段
参数
说明
-
InputIndex
设置备播视频时，固定98765
响应示例：
{
    "Response": {
        "InputPlayUrl": "",
        "InputWebRTCPlayUrl": "webrtc://playtest.caster.tlivesource.com/live/10000_251195401_1253817691_1_3333333_webrtc_500?txTime=66f37892&txSecret=xxx",
        "InputStreamId": "10000_251195401_1253817691_98765_3333333",
        "RequestId": "83a16ac5-5287-4f24-a14e-7a84ab944508"
    }
}
﻿
新增断流时备播图片
播放前的图片格式要求应与输入的图片格式保持一致。
调用接口： AddCasterInputInfo
请求示例：
{
    "CasterId": 10000,
    "InputInfo": {
        "InputIndex": 98766,
        "InputType": 3,
        "InputUrl": "http://example.com/picture/back.jpg"，
        "Description":"备播图片"
    }
}
﻿
当请求参数中的InputType为图片URL时，其值固定为3，且InputUrl应填入图片文件的URL。
响应示例：
{
    "Response": {
        "InputPlayUrl": "http://example.com/picture/back.jpg",
        "InputWebRTCPlayUrl": "webrtc://playtest.caster.tlivesource.com/live/_webrtc_500?txTime=66f38515&txSecret=xxx",
        "InputStreamId": "",
        "RequestId": "f844f691-dc3e-4951-a09c-c8ae475c36ed"
    }
}
﻿
参数与添加一个普通图片输入源并没有太大区别，仅在InputIndex字段不太一致。
页面字段
参数
说明
-
InputIndex
设置备播图片时，固定98766
注意：
从示例参数可知，备播视频和备播图片可同时使用，按示例调用两次即可。
字幕功能
﻿
虽然文本功能允许在视频中添加文字，其效果相对简单，难以满足一些更复杂需求。字幕功能在文本功能的基础上进行了扩展，支持边框、背景，并可以组合使用以创建标题栏和字幕栏。
注意：
字幕功能底层是文本功能，对字幕的增删改查接口与文本的增删改查接口一致。
一个字幕配置可以包含一个标题栏和一个字幕文本栏，标题栏和字幕文本栏可以同时存在。
在实现上，标题栏和字幕文本栏是两个单独的文本配置，业务通过Description字段来判定文本配置是否属于同一个字幕配置。即若两个Description相同，则认为这两个文本配置属于同一个字幕配置。
添加固定显示字幕
﻿
需添加两次文本配置
第一步，添加标题栏。
调用接口： AddCasterMarkWordInfo
请求示例：
响应示例：
{
    "CasterId": 10000,
    "MarkWordInfo": {
        "Description": "字幕示例",
        "MarkWordIndex": 11,
        "MarkWordType": 4,
        "DrawBoxInfo": {
            "DrawBoxBorder": 1,
            "DrawBoxBorderColor": "0xDAE0E7",
            "DrawBoxColor": "0xDAE0E7",
            "DrawBoxHeight": 0.05,
            "DrawBoxWidth": 0.08,
            "DrawBoxLocationX": 0.085,
            "DrawBoxLocationY": 0.8,
            "DrawBoxRoundRadius": 0,
            "DrawBoxTransparency": 1
        },
        "MarkWordFontColor": "0x374E6A",
        "MarkWordFontSize": 32,
        "MarkWordFontType": 1,
        "MarkWordLocationX": 0.0933,
        "MarkWordLocationY": 0.8093,
        "MarkWordRollEnable": false,
        "MarkWordRollStartLocationX": 0,
        "MarkWordRollEndLocationX": 0,
        "MarkWordRollOnceTime": 5,
        "MarkWordText": "示例标题"
    }
}
﻿
{
    "Response": {
        "RequestId": "18e5c09a-34df-4f12-8eae-5ab04e13f936"
    }
}
﻿
页面字段与参数对应关系：
页面字段
参数
说明
字幕备注
Description
-
类型
MarkWordType
标题栏，值默认为4
-
MarkWordText
文本内容，上限512字符
字体
MarkWordFontType
1：宋体，2：黑体
字号
MarkWordFontSize
字体大小，范围为16至60
-
MarkWordFontColor
字体颜色的十六进制颜色代码
文字位置X
MarkWordLocationX
坐标系与布局一致，值为比例值
文字位置Y
MarkWordLocationY
坐标系与布局一致，值为比例值
显示方式
MarkWordRollEnable
固定显示时，该值固定为 false
请求中包含了DrawBoxInfo配置，可对标题栏的边框、背景等进行控制，相关参数如下：
页面字段与参数对应
页面字段
参数
说明
-
DrawBoxBorder
固定为1
-
DrawBoxBorderColor
标题栏边框颜色
-
DrawBoxColor
标题栏填充颜色
-
DrawBoxHeight
标题栏高度，值为比例值
-
DrawBoxWidth
标题栏宽度，值为比例值
-
DrawBoxLocationX
坐标系与布局一致，值为比例值
-
DrawBoxLocationY
坐标系与布局一致，值为比例值
-
DrawBoxRoundRadius
标题栏拐角圆角半径
-
DrawBoxTransparency
透明度的范围是[0,1]，其中0代表完全透明，1代表不透明。
注意：
在请求中，可以暂时忽略MarkWordRollCount、MarkWordRollEndLocationX、MarkWordRollStartLocationX、MarkWordRollOnceTime参数，按照示例进行填写即可。
标题栏的控制参数较多，其展示效果（例如边框与文字之间的距离、位置关系等）需要根据业务需求进行自行计算。
第二步，添加字幕文本栏。
调用接口： AddCasterMarkWordInfo
请求示例：
响应示例：
{
    "CasterId": 10000,
    "MarkWordInfo": {
        "Description": "字幕示例",
        "MarkWordType": 4,
        "MarkWordIndex": 12,
        "DrawBoxInfo": {
            "DrawBoxBorder": 1,
            "DrawBoxBorderColor": "0x374E6A",
            "DrawBoxColor": "0x374E6A",
            "DrawBoxHeight": 0.05,
            "DrawBoxWidth": 0.8,
            "DrawBoxLocationX": 0.085,
            "DrawBoxLocationY": 0.85,
            "DrawBoxRoundRadius": 0,
            "DrawBoxTransparency": 1
            
        },
        "MarkWordFontColor": "0xFFFFFF",
        "MarkWordFontSize": 34,
        "MarkWordFontType": 1,
        "MarkWordLocationX": 0.0933,
        "MarkWordLocationY": 0.8631,
        "MarkWordRollCount": -1,
        "MarkWordRollDirection": 0,
        "MarkWordRollEnable": false,
        "MarkWordRollEndLocationX": 0,
        "MarkWordRollOnceTime": 5,
        "MarkWordRollStartLocationX": 0,
        "MarkWordText": "示例字幕内容示例字幕内容"
    }
}
﻿
{
    "Response": {
        "RequestId": "27dcfb19-7ecb-41d5-89fa-36ac1a1a497e"
    }
}
﻿
注意：
字幕文本栏配置参数与标题栏参数含义一致。
标题栏和字幕文本栏的展示效果，如两个栏之间的距离、位置关系等依赖业务需要自行计算。
添加单次滚动字幕
与固定显示字幕相比，单次滚动字幕更为常见。在请求参数中，标题栏和字幕文本栏的基本参数与固定显示时的参数含义一致，只在滚动相关的设置参数上有所区别。
﻿
﻿
第一步，添加标题栏，标题栏一般不滚动，因此请求参数与上节相同。
第二步，添加字幕文本栏。
调用接口： AddCasterMarkWordInfo
请求示例：
响应示例：
{
    "CasterId": 10000,
    "MarkWordInfo": {
        "Description": "字幕示例",
        "MarkWordType": 4,
        "MarkWordIndex": 12,
        "DrawBoxInfo": {
            "DrawBoxBorder": 1,
            "DrawBoxBorderColor": "0x374E6A",
            "DrawBoxColor": "0x374E6A",
            "DrawBoxHeight": 0.05,
            "DrawBoxWidth": 0.8,
            "DrawBoxLocationX": 0.085,
            "DrawBoxLocationY": 0.85,
            "DrawBoxRoundRadius": 0,
            "DrawBoxTransparency": 1
        },
        "MarkWordFontColor": "0xFFFFFF",
        "MarkWordFontSize": 34,
        "MarkWordFontType": 1,
        "MarkWordLocationX": 0.09,
        "MarkWordLocationY": 0.86,
        "MarkWordRollCount": 1,
        "MarkWordRollDirection": 0,
        "MarkWordRollEnable": true,
        "MarkWordRollEndLocationX": 0.90,
        "MarkWordRollOnceTime": 5,
        "MarkWordRollStartLocationX": 0.10,
        "MarkWordText": "示例字幕内容示例字幕内容"
    }
}
﻿
{
    "Response": {
        "RequestId": "27dcfb19-7ecb-41d5-89fa-36ac1a1a497e"
    }
}
﻿
单次滚动相关参数：
页面字段
参数
说明
-
MarkWordRollEnable
单次滚动时，固定为 true
-
MarkWordRollCount
单次滚动时，固定为1
-
MarkWordRollDirection
滚动方向
0：从左往右
1：从右往左
滚动速度
MarkWordRollOnceTime
文字从出现到滚动结束的时间范围为5至600秒。
-
MarkWordRollStartLocationX
坐标系与布局一致，值为比例值，表示滚动的起始X轴坐标
-
MarkWordRollEndLocationX
坐标系与布局一致，值为比例值，表示滚动的结束X轴坐标
注意：
单次字幕滚动结束后，标题栏和字幕文本栏将同时消失。
调整输入源音量
应用场景：在有多个输入源的情况下，由于采集设备的差异，音量听感可能不一致，因此需要调整音量以使多个输入源之间的音量尽可能保持一致。或者，在直播过程中，可能需要临时关闭某个输入源的声音。
﻿
注意：
输入源的音量应该在页面刷新等情况下也能记住之前设置的音量，因此音量信息保存在输入源信息中，修改音量实际就是在修改输入源。
若在添加输入时就已知某个输入源需要使用多大的音量，可以在添加输入源时就带上音量信息。
修改音量后，若预监中使用了该输入，则立刻生效，可在预览链接中查看效果。若需要主监生效，则需重新调用CreateCasterPgm接口。
  以修改输入1的音量到70%为例：
  调用接口： ModifyCasterInputInfo
  请求示例：
{
    "CasterId": 10000,
    "InputInfo": {
        "InputIndex": 1,
        "InputType": 1,
        "Volume": 70
    }
}
﻿
由于只修改音量，不修改URL等信息，可不带InputUrl字段。
页面字段
参数
说明
-
Volume
音量百分比，范围范围：0至200
响应示例：
{
    "Response": {
        "InputPlayUrl": "",
        "InputWebRTCPlayUrl": "webrtc://playtest.caster.tlivesource.com/live/10000_251195401_1253817691_1_3333333_webrtc_500?txTime=66f37892&txSecret=xxx",
        "InputStreamId": "10000_251195401_1253817691_1_3333333",
        "RequestId": "73a16ac5-5287-4f24-a14e-7a84ab944508"
    }
}
﻿
﻿
释放导播台
应用场景：
在涉及的布局、水印、推流等配置比较复杂的情况下，单次直播结束后，想保留这些配置避免重复设置，或者觉得停止预监、停止主监的动作过于繁杂，可使用释放导播台。
导播台释放后，将会关闭预监、主监、推流，停止输入源预览和处理任务，但是输入源、推流、水印、文本等配置将全部保留。
﻿
﻿
调用接口： ReleaseCaster
请求示例：
响应示例：
{
    "CasterId": 10000
}
﻿
{
    "Response": {
        "RequestId": "ff24f691-dc3e-4951-a09c-c8ae475c36ed"
    }
}
﻿
页面字段	参数	说明
ID	CasterId	-
名称	CasterName	-
描述	Description	-
计费状态	FeeType	通过 API 创建的均为后付费状态。
运行结束时间	ExpireTime	Unix 时间戳，-1代表永不过期。
运行状态	Status	当值非0时，状态为运行中；当值为0时，表示处于空闲状态。
页面字段	参数	备注
PGM输出时长	StartLiveTime	使用当前 unix 时间戳减去该参数的值计算
PlayUrl 页面字段	参数	说明
-	PlayUrl	rtmp 协议预览地址
-	WebRTCPlayUrl	腾讯云快直播播放地址，若使用该地址，需接入腾讯云快直播sdk
-	StreamId	输入源在云导播台系统的内部流id，可供查询输入源质量数据
云导播台 API 开发手册

本页目录：

导播台列表页

获取本账号下的导播台列表（查询导播台列表）

新建导播台（创建导播台 ）

修改导播台

删除导播台

复制导播台

获取导播台详细配置信息

查询基础配置（查询导播台信息）

查询导播台输入源列表（查询输入配置）

查询导播台的推流信息列表（查询推流配置）

查询导播台布局列表（查询布局配置）

查询导播台水印信息列表（查询水印配置）

查询导播台文本配置列表（查询文本配置）

获取导播台转场列表（查询支持的转场类型）

查询导播台当前的预监、主监信息（查询导播台展示信息）

获取导播台输入源、预监、主监的预览链接

获取导播台视频流播放url（获取输入源预览链接）

获取预监（PVW）预览链接

获取主监（PGM）预览链接

添加、修改、删除输入源

添加输入源

添加直播推流URL

添加直播拉流URL

添加点播URL

添加图片URL

修改输入源

删除输入源

添加、修改、删除布局

添加布局

添加模版布局

添加自定义布局

添加虚拟背景布局

添加色度抠像布局

添加AI抠像布局

修改布局

删除布局

添加、修改、删除推流配置

添加推流配置

新增导播台推流信息(添加推流到腾讯云)

添加推流到第三方

修改推流配置

修改推流到腾讯云配置

修改推流到第三方配置

删除推流配置

添加、修改、删除水印

添加水印

添加水印，位置使用百分比信息

添加水印，位置使用精确像素信息

修改水印

删除水印

添加、修改、删除文本

添加文本

添加普通类型固定文本

添加普通类型滚动文本

添加时钟

修改文本

删除文本

修改主监配置

启动、修改、停止预监

启动预监

启动单画面布局预监

启动普通布局预监

启动预监时使用水印：

启动预监时使用文本

修改预监

切换预监布局

切换预监布局，画面切换时使用转场

停止预监

启动、修改、停止主监

启动主监

复制预监配置启动主监

复制预监配置启动主监，启动时单画面输入源从头开始播放

单独启动主监

单独启动主监，启动时单画面输入源从头开始播放

修改主监

切换主监布局

修改主监布局，画面切换时使用转场

修改主监，切换到单画面输入源时，从头开始播放

新建导播台（创建导播台）
