Callaba Engine 文档

Callaba Engine 是你用来端到端运行直播视频工作流的 API：通过 SRT servers 和 RTMP servers 接收贡献流，使用 NDI discovered devices 与 NDI adapters，启动 Restreams 和 Recordings，发布到 Web players，创建 Video calls，并挂接 Storages 以获得持久化输出。

使用这套文档最快的方法，是沿着运营团队在搭建和排障时同样的路径去看：信号从哪里进入、如何流动、当前处于什么状态、下一步去哪里、哪些内容必须保存。下面的实时遥测模块之所以重要，是因为贡献流质量并不是静态的。SRT 码率、丢包、缓冲和时序这些信号，会告诉你问题究竟是出在发送端、网络路径，还是接收工作流内部。

沿着工作流理解模块

大多数集成都不只会碰一个模块。先从你系统里已经存在的第一个边界开始，再一路往下游走。

1. 接入：使用 SRT servers 或 RTMP servers 为现场编码器和合作方信号创建入口点。如果来源已经在 NDI 网络中，就从 NDI discovered devices 开始。
2. 路由或转换：当你需要受控的 SRT 转发时，使用 SRT routes；当你需要再发布、协议桥接、转码、叠加或多目标扇出时，使用 Restreams。如果工作流必须把托管源重新暴露回 NDI 制作环境，就使用 NDI adapters。
3. 保存或交付：使用 Recordings 从直播源生成文件，再用 Storages 定义这些文件存放的位置。当输出面向浏览器播放时，使用 Web players 和 Web player groups。当观众需要进入实时房间参与互动，而不是只看一条流时，使用 Video calls。

快速选对第一个模块

• 我需要让编码器或远端设备把信号推入平台：从 SRT servers 或 RTMP servers 开始。
• 我已经有一个直播源，只是要把它送去别处：从 Restreams 开始。
• 我需要看到或使用 NDI 网络中的源：从 NDI discovered devices 开始；然后按需使用 NDI adapters 或 NDI configuration。
• 我需要一个文件，而不仅仅是一条直播流：从 Recordings 开始，并确认目标 Storages。
• 我需要浏览器播放：从 Web players 开始。
• 我需要让人加入并进行实时互动：从 Video calls 开始。

如果你是在接入一个新系统，通常的顺序是先完成 installation or instant launch，然后做 authorization，再进入你工作流边界对应的模块。

模块模型如何对应生产工作

如果你把这些模块理解成不同类型的运营对象，而不是一张平铺的资源清单，API 会更容易上手。

• 边界资源 定义媒体从哪里进入或离开。示例：SRT servers 和 RTMP servers。
• 直播任务 会随着时间持续工作，通常也有值得监看的运行时状态。示例：Restreams 和 Recordings。
• 观察状态 表示系统“看到”的内容，而不是你一开始创建的对象。示例：NDI discovered devices。
• 桥接层 用来连接两个制作域。示例：把托管源再交回 NDI 的 NDI adapters。
• 环境设置 用来控制跨工作流的平台行为。示例：NDI configuration。
• 交付表面 把输出暴露给人或应用。示例：Web players、Web player groups 和 Video calls。
• 持久化目标 决定录制资产存在哪儿、从哪儿取回。示例：Storages。

这一区分对自动化尤其重要。你通常只需要为边界资源做一次配置，按事件或频道去操作直播任务，持续读取观察状态，并根据分发和保留策略把交付与存储接起来。

为什么实时遥测模块重要

对于 SRT 贡献流来说，一个绿色状态并不够。运营团队需要看到码率是否在塌陷、接收缓冲压力是否在升高、包投递是否不均匀、时序是否在漂移。这些信号会告诉你是该调整发送端、排查网络路径、增加弹性，还是要保护下游的 Restreams、Recordings 和 Web players，避免它们被不稳定的源拖垮。

把这个遥测视图当成早期预警层：在观众发现问题或归档文件受影响之前，它能帮助团队先把传输问题和应用问题分开。