文档
开发
介绍
设计
运营
开发
开发者平台 社区
开发

开发 技术接口总览 直播弹幕技术基础能力 玩法主播双人连屏功能

# 快手直播弹幕玩法主播双人连屏文档

更新时间：2024-11-22 14:44:20

# 文档更新记录:

2023年08月04日10:36:27

1.由于推流的特殊原因，连线配置摄像头宽度和高度设置必须是偶数。

2023年08月01日14:44:13

1.连线配置要求更新，现在允许在一定范围内调整视频连线窗口大小了。

摄像头尺寸规范：最小宽高160x160px，最大宽高444x444px，即width, height ∈ [160,444]

建议4种比例尺寸：

方形230x230px

横屏282x160px

竖屏160x282px

方形444x444px（推荐）：能够获得更多的流量

原则，同屏出现的多个摄像头比例必须一致

2.功能已支持间内用户跳转到pk方（对面）主播直播间，需要更新快手app至最新版本。

2023年07月24日15:21:36

1.补充伴侣版本要求：最低要求伴侣版本4.47.0

2023年06月25日16:54:36

1.心跳及结束协议需要带上本次连线的roomCode

# 功能简介：

       弹幕玩法语音是一种常见的能力，此外，主播之间的隔空喊话，可以起到引导直播间氛围，拉动观众参与度的能力。快手在普通语音连线的基础上，对外开放快手直播独特的视频连线能力，实现弹幕玩法内主播同屏，进一步提升间内对抗氛围，提升观众参与度。

业务表现

       目前支持两种连线方式：

# 1.弹幕玩法内pk发起连线。

在主播弹幕玩法内匹配到对手开始pk时，快手会为当前两个主播建立视频连线。

此模式下，视频连线的生命周期与弹幕玩法pk生命周期一致，即当弹幕玩法开始pk时，连线会被发起，弹幕玩法pk结束时，连线结束，生命周期中，使用心跳兜底保证状态的最终一致。

此外，cp服务可根据游戏特点决定stop调用时机，比如玩法内pk结束后，延迟一定的时间调用stop，以给予一定的时间让主播进行战后交流。

由于弹幕玩法多样性，具体两个主播所在位置由弹幕玩法服务器决定，具体交互方式见下方接口。

# 2.主播伴侣发起连线。

主播在直播伴侣发起连线，主播可以选择当前正在玩同款弹幕玩法的主播进行连线，此时弹幕玩法内pk对象可能与连线对象并不一样，弹幕玩法可根据需要灵活开发玩法功能。

注意：两个子功能是互斥关系，即某个主播在同一时刻只能使用其中一种方式连线，且不会被另一个方式中断。

# 版本要求:

pc直播伴侣：4.47.0版本及以上

# 具体接口：

# 连线：

使用弹幕玩法内发起连线或者伴侣发起连线，均需要上传连线配置。连线配置中包含配置的版本号及连线窗口id及位置信息。调用时机推荐在本场直播开始时，可参考礼物置顶的调用时机。

# 请求地址

Method: POST

URL: https://open.kuaishou.com/openapi/developer/live/data/interactive/action/chat

"Content-Type": "application/json;charset=UTF-8"

# 请求参数

字段名数据类型是否必填是否参与签名说明
roomCodestring是是快手直播间绑定码，主播在打开弹幕玩法详情时可以获取
timestampint(64)是是建立连接时间戳，单位毫秒
signstring是否

开发者对核心字段签名，签名方式见 附录

注意：

app_id需要参与签名

app_secret直接追加在最后

签名的参数需要按首字母排序

bizTypestring是是业务类型：chat:连线，和url后缀一致
methodstring是是

业务方法：

config:连线配置上传，调用时机可参考礼物置顶

start: 开始连线，发起连线方调用即可

heartbeat:保活心跳。如果间隔20秒还未收到心跳，将断开连线，建议5-10秒发一次请求，发起连线方调用即可

stop: 结束连线，发起连线方调用即可

datastring是是业务参数，见下表

# 各method及data字段说明：

method请求示例字段说明
config


 

 

{
  "roomCode": "xxxx",
  "timestamp": 1678763332705,
  "sign": "xxxx",
  "method":"config",
  "bizType": "chat",
  "data": "{\"version\":\"1\",\"chatLayoutList\":[{\"windowId\":1,\"x\":334,\"y\":455,\"width\":184,\"height\":184},{\"windowId\":2,\"x\":560,\"y\":455,\"width\":184,\"height\":184}]}"
}

 

data转义前

 

{
  // 连线配置版本
  "version": "1",
  //注意：会对窗口大小和位置做校验
  //不允许超出画布
  //不允许两个窗口重叠
  //摄像头尺寸规范：最小宽高160x160px，最大宽高300x300px，推荐比例：方形230x230px 横屏282x160px 竖屏160x282px
  "chatLayoutList": [
    {
      // 连线视频窗口id
      "windowId": 1,
      // 连线视频窗口距离顶部坐标（画布大小1080*1920，下同）
      "x": 334,
      // 连线视频窗口距离左侧坐标
      "y": 456,
      // 连线视频窗口宽，width∈[160,300]
      "width": 184,
      // 连线视频窗口高，height∈[160,300]
      "height": 184
    },
    {
      "windowId": 2,
      "x": 560,
      "y": 456,
      "width": 184,
      "height": 184
    }
  ]
}

 

start


 

 

{
  "roomCode": "xxxx",
  "timestamp": 1678763332705,
  "sign": "xxxx",
  "method":"start",
  "bizType": "chat",
  "data": "{\"cpPkId\":\"kfcv50\",\"hostAuthor2Layout\":{\"roomCode2\":{\"roomCode2\":1,\"roomCode1\":2},\"roomCode1\":{\"roomCode2\":2,\"roomCode1\":1}},\"timestamp\":1687160372038}"
}

 

data转义前

 

{
  // 弹幕玩法内pkId，唯一id，长度尽可能短且唯一
  "cpPkId": "kfcvme50",
  // 不同直播间视角下，参与连线主播视频布局id
  // Key:当前视角roomCode，value:所有参与连线主播布局
  // ***把roomCode1xxx和roomCode2xxx替换成真实的roomCode。可看下面的例子
  "hostAuthor2Layout": {
    "roomCode1xxx": {
      "roomCode1xxx": 2, // key:参与连线的roomcode,vaule:config接口的window id
      "roomCode2xxx": 1
    },
    "roomCode2xxx": {
      "roomCode1xxx": 1,
      "roomCode2xxx": 2
    }
  },
  "timestamp": 1687160372038
}

 

hostAuthor2Layout举例：


 

 

"hostAuthor2Layout": {
"868s3eoyGpQFJLzyk0FcV1AAUyH6bRjMdHiAD9yWUvz2pDo28dNVeVO4aM7qbXxR": {
"868s3eoyGpQFJLzyk0FcV1AAUyH6bRjMdHiAD9yWUvz2pDo28dNVeVO4aM7qbXxR": 2,
"5+RCmSUOhoiEud7gyJ3QAKzQIlRr8rb549+JaRNiH+FwqhIQ6pxPiDGUrIpVn3b1": 1
},
"5+RCmSUOhoiEud7gyJ3QAKzQIlRr8rb549+JaRNiH+FwqhIQ6pxPiDGUrIpVn3b1": {
"868s3eoyGpQFJLzyk0FcV1AAUyH6bRjMdHiAD9yWUvz2pDo28dNVeVO4aM7qbXxR": 1,
"5+RCmSUOhoiEud7gyJ3QAKzQIlRr8rb549+JaRNiH+FwqhIQ6pxPiDGUrIpVn3b1": 2
}
}

 

heartbeat


 

 

{
  "roomCode": "xxxx",
  "timestamp": 1678763332705,
  "sign": "xxxx",
  "method":"heartbeat",
  "bizType": "chat",
  "data": "{\"cpPkId\":\"kfcvme50\",\"roomCodes\":[\"RoomCode1\",\"RoomCode2\"],\"timestamp\":1687683193812}"
}

 

data转义前

 

{
  "cpPkId": "kfcvme50",
  "roomCodes": [
    "RoomCode1",
    "RoomCode2"
  ],
  "timestamp": 1687683193812
}

 

stop

 

{
  "roomCode": "xxxx",
  "timestamp": 1678763332705,
  "sign": "xxxx",
  "method":"stop",
  "bizType": "chat",
  "data": "{\"cpPkId\":\"kfcvme50\",\"roomCodes\":[\"RoomCode1\",\"RoomCode2\"],\"timestamp\":1687683193812}"
}

 

data转义前

 

{
  "cpPkId": "kfcvme50",
  "roomCodes": [
    "RoomCode1",
    "RoomCode2"
  ],
  "timestamp": 1687683193812
}

 

# 请求response示例

{
  "result": 1,
  // 如果result 不是 1， 会有error_msg
  "errorMsg": "xxxx"
}

# 错误码

错误码错误文案
21

access-token校验失败

无权限访问该路径

未接入的appId

房间码不合法

直播不存在

直播已关播

220361系统异常
220362操作频繁
220363APP限流
220365无弹幕玩法中记录
220368appId与弹幕玩法记录不一致
220931连线配置错误
220932连线配置不存在
220933所有的roomCode无效
220934意料外错误，请联系快手接口人
220935连线roomCode或cpPkId错误
220936连线类型错误
220937关闭连线失败，请稍后重试
220938开启连线失败，请稍后重试
220939连线已关闭
220940主播连线配置不同
220941服务异常
220942直播和连线不匹配
220943不是占位连线
220944未开启弹幕玩法
220945伴侣版本不支持
220946主播正在连线
220947主播正在其他互动，无法连线
220948连线参数检验失败
220949未知method
220950未知Biz
220951不允许连线，详情请联系快手对接人
220952cpPkId重复

# FAQ

心跳需要连线双方都发吗？

答：不需要，连线发起方发起心跳即可

心跳正常但连线断开常见原因有哪些？

答：可能原因如下

a. 两个主播其中一个主动关闭了连线

b. 主播进入自己的直播间触发连线关闭（概率性）

c. 任意一方直播异常断开

d. 心跳时间过长

e. 并行请求心跳，会有一个失败

平台是否支持多人连屏能力？

答：目前平台支持的基础功能，双人连屏能力。暂未支持多人连屏。

连屏使用场景有哪些？

双人pk场景

两方主播共同合作模式等

具体使用场景，可根据玩法内容进行相关设计

仍有疑问? 前往社区提问
Copyright ©2025, All Rights Reserved