未分类

PLAYDECK API

2025年10月26日 作者：

利用我们的标准 REST API（OpenAPI 3）和 WebSocket 接口，将 PLAYDECK 集成到脚本、自动化系统和自定义用户界面中，从而通过单个端口实现实时控制。.

本文内容：
→ 我需要哪种接口？
→ REST API 快速入门
→ 交互式 API 参考
→ WebSocket 实时通道
→ 传统 TCP 命令输入
→ 集成示例

我需要哪种接口？

PLAYDECK 会根据您的集成需求提供不同的接口。请参考以下概述，选择正确的协议和端口：

用例推荐的界面港口
脚本、cURL、Postman、自定义 HTTP 集成REST API /api/v1 (OpenAPI 3)11411
实时状态、事件、HTML 叠加层、Bitfocus CompanionWebSocket 通道11411
现成的控制面Bitfocus Companion（通过 WebSocket）11411
传统 TCP 客户端 / 现有自动化管道TCP 命令11375

建议： 大多数新的集成项目都应从 REST API. 切换至或与之结合使用 WebSocket 仅当您需要持续、低延迟的状态更新或实时事件触发时才适用。.

REST API 快速入门

在 PLAYDECK 运行期间，HTTP REST API 会自动在端口 11411 （与内置的 Web Remote 使用相同的服务）。.

基础网址

http://HOST:11411/api/v1


替换 主持人 请将此处替换为您 PLAYDECK 设备的实际 IP 地址，该地址位于 设置 ➔ 网络 ➔ 开发者 API.

PLAYDECK 内部测试

您无需使用外部工具即可开始测试。打开 设置 ➔ 网络 ➔ 开发者 API 在软件应用程序内，可直接从用户界面发送示例请求或打开交互式文档。.

HTTP 请求示例

1. 服务健康检查：

GET /api/v1/health HTTP/1.1
Host: HOST:11411


2. 查询 Playout 状态（JSON 响应）：

GET /api/v1/status HTTP/1.1
Host: HOST:11411


3. 在 Playout 通道 1 上触发播放：

POST /api/v1/channels/1/play HTTP/1.1
Host: HOST:11411


4. 在 Playout 频道 1 上播放第 1 块、第 2 个片段：

POST /api/v1/channels/1/play/1/2 HTTP/1.1
Host: HOST:11411


许多操作都支持可选的路径参数，以便进行精准控制（例如块/片段 ID、时间码偏移量或叠加层 ID）。.

经典命令逃生舱口

如果您需要通过 HTTP 全面支持经典的 PLAYDECK 命令语言，可以将采用管道格式的命令传递到专用的命令端点：

POST /api/v1/commands HTTP/1.1
Host: HOST:11411
Content-Type: application/json

{
  "command": "play",
  "args": ["1", "1", "2"]
}


注意：在当前版本中，局域网（LAN）操作无需 API 密钥或身份验证令牌。.

交互式 API 参考

该接口的完整机器可读合同以 OpenAPI 3 规范文档的形式提供。.

➔ 下载： OpenAPI 规范（YAML）

用于交互式浏览、有效载荷检查，以及针对您正在运行的 PLAYDECK 实例进行直接“试用”测试：

  1. 发布 PLAYDECK.
  2. 导航至 设置 ➔ 网络 ➔ 开发者 API 然后点击 开放式API参考文档.
  3. 或者，在同一网络内的任意一台机器上打开网页浏览器，访问以下网址： http://HOST:11411/api/v1/docs

该文档页面会动态列出所有可用的 REST 端点、必需参数、模式定义以及预期的响应有效载荷。.

    WebSocket 实时通道

    港口 11411 同时处理 WebSocket 连接。该双向通道专为需要持续数据流的操作而设计：

    • Playout 持续状态： 高频播放位置跟踪和时间码更新。.
    • 事件触发器： 当片段、音频块或播放列表开始、停止或循环播放时，立即发送通知。.
    • 经典管道命令： 直接处理格式为 <play|1|...>.

    该官员 Bitfocus Companion PLAYDECK 模块, ，该 Web 远程用户界面, 自定义 HTML 图形叠加层以及 Director View 模板均使用此特定实时通道。有关命令和事件类型的完整语法文档，可直接在应用程序包中或您的本地模板目录中找到：

    Web 远程用户界面：
c:\Program Files\JoyEventMedia\Playdeck\html\webremote.html

HTML 模板：
C:\Users\Public\Documents\JoyEventMedia\Playdeck\HTML-Templates\
或
c:\Users\\AppData\Local

    传统 TCP 命令输入

    为了与现有的广播自动化基础设施保持向后兼容性，PLAYDECK 继续接受通过端口 11375.

    此设置由以下部分管理： 设置 ➔ 网络 ➔ 入站 ➔ TCP 命令 入. 有效载荷的语法与 WebSocket 通道和 REST 所使用的以竖线分隔的格式一致 /api/v1/commands 端点。.

    • 开发者说明： 对于所有从零开始的开发项目以及新的脚本集成，我们强烈建议使用 REST API，而不是原始的 TCP 套接字。.

    集成示例

    • Bitfocus Companion： 利用我们通过 WebSockets 提供的、已准备好投入生产的原生模块，快速部署物理硬件控制面板。.
    • Web Remote： 功能齐全的生产控制界面，可通过任何浏览器访问该端口 11411.
    • 导演视角与HTML叠加层： 内置的网页模板，展示了实时状态绑定。.
    • 定制软件工具： 利用根据我们的 OpenAPI 规范生成的标准 HTTP 客户端进行快速应用程序开发，可选地通过 WebSockets 支持遥测功能。.

    有任何疑问或定制工作流需求？请联系我们的工程团队： [email protected].