PLAYDECK API
利用我们的标准 REST API（OpenAPI 3）和 WebSocket 接口，将 PLAYDECK 集成到脚本、自动化系统和自定义用户界面中，从而通过单个端口实现实时控制。.
本文内容：
→ 我需要哪种接口？
→ REST API 快速入门
→ 交互式 API 参考
→ WebSocket 实时通道
→ 传统 TCP 命令输入
→ 集成示例
我需要哪种接口？
PLAYDECK 会根据您的集成需求提供不同的接口。请参考以下概述，选择正确的协议和端口：
| 用例 | 推荐的界面 | 港口 |
|---|---|---|
| 脚本、cURL、Postman、自定义 HTTP 集成 | REST API /api/v1 (OpenAPI 3) | 11411 |
| 实时状态、事件、HTML 叠加层、Bitfocus Companion | WebSocket 通道 | 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 实例进行直接“试用”测试：
- 发布 PLAYDECK.
- 导航至 设置 ➔ 网络 ➔ 开发者 API 然后点击 开放式API参考文档.
- 或者，在同一网络内的任意一台机器上打开网页浏览器，访问以下网址：
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].
