Bitfocus Companion

Cliqer 与 Bitfocus Companion 集成。Bitfocus Companion 是一款广受欢迎的开源按键控制软件,专为现场制作而设计。当 Cliqer 检测到您的系统上已安装 Companion 时,会自动安装 Cliqer 模块,无需任何手动设置。
工作原理
Cliqer 运行两个供模块连接的本地回环服务器:一个是 127.0.0.1:24601 上的 HTTP 操作 API,用于按键操作;另一个是 127.0.0.1:9052 上的 WebSocket,实时推送计时器更新和应用状态,供反馈和变量使用。
设置
安装 Companion
安装 Bitfocus Companion 并至少启动一次
启动 Cliqer
启动 Cliqer,它会将 Cliqer 模块放入 Companion 的模块文件夹
添加 Cliqer 连接
重启一次 Companion 以加载该模块,然后添加一个 Cliqer 连接(指向 127.0.0.1,操作 API 端口为 24601)
可用操作
该模块提供 19 个操作,按类别分组:
| 类别 | 操作 |
|---|---|
| Click | Left Click、Right Click |
| Timer | Start / Pause Timer、Reset Timer、+1 / +2 / +5 Minutes、−1 / −2 / −5 Minutes |
| Presets | Timer Preset 1 / 2 / 3 / 4(5、10、15、20 分钟) |
| Callers | Caller to Program(选择连线嘉宾 1-9)、Clear Program(切黑) |
| Control | Stop Screen Share、Toggle Program NDI Output、Toggle Timer NDI Output |
反馈
反馈会根据实时状态改变按键外观。该模块定义了 11 种反馈:
| 反馈 | 为真条件 |
|---|---|
| Timer Running | 计时器正在计时 |
| Timer Stopped | 计时器已暂停 |
| Timer Green (Talk Phase) | 计时器正在运行,且时间充裕 |
| Timer Overtime | 倒计时模式下,计时器已超过 0:00 |
| Timer Yellow (Warning Phase) | 计时器接近时限,或已暂停 |
| Timer Red Flash (At Zero / Overtime) | 计时器归零 / 进入超时时闪烁 |
| Caller On Air (Program) | 所选连线嘉宾正在节目总线上直播 |
| Caller Connected | 所选连线嘉宾位已有嘉宾连接 |
| Screen Share Active | 节目画面中正在进行屏幕共享 |
| Program NDI Output Active | 节目 NDI 输出已开启 |
| Timer NDI Output Active | 计时器 NDI 输出已开启 |
变量
该模块提供 14 个变量,可用于按键文字和触发器。请通过连接标签引用它们,例如当连接命名为 Cliqer 时,使用 $(Cliqer:timer_display):
| 变量 | 说明 | 示例 |
|---|---|---|
timer_display | 当前计时器数值(MM:SS) | 14:30 |
timer_minutes | 分钟部分 | 14 |
timer_seconds | 秒部分 | 30 |
timer_state | 计时器状态 | running / stopped |
preset1_label … preset4_label | 预设时长(MM:SS) | 05:00 |
program_caller | 当前处于节目输出的连线嘉宾姓名 | Jane |
callers_count | 已连接的连线嘉宾数 | 3 |
viewers_count | 观众 / 观看人数 | 128 |
presenters_count | 已连接的演讲者数 | 2 |
room_id | 当前房间 ID | ABC123 |
room_url | 可分享的房间链接 | https://cliqer.io/ABC123 |
预设
该模块自带现成的按键预设,只需拖放即可搭建控制面板,其分组与操作类别相同:Click、Timer、Presets、Callers 和 Control。将它们拖到 Companion 页面上,即可立即控制幻灯片、计时器、连线嘉宾和输出。
平台支持
| 平台 | 自动安装位置 |
|---|---|
| macOS | ~/Library/Application Support/companion/modules/ |
| Windows | %APPDATA%\companion\modules\ |
该模块会放在该目录下的 cliqer-cliqer-<version> 文件夹中(例如 cliqer-cliqer-1.2.2)。Cliqer 安装更新时会先删除旧版本文件夹,因此只保留当前版本。
故障排除
Companion 中未显示模块
- 请确保已安装 Companion,并在启动 Cliqer 之前至少启动过一次
- Companion 仅在启动时扫描其模块文件夹,因此请在 Cliqer 首次启动后重启一次 Companion,Cliqer 连接类型便会出现
- Companion 中的 Refresh modules 按钮刷新的是其在线商店,而非本地模块文件夹,因此请重启 Companion 以显示新安装的模块
操作无法触发
- 请确认连接指向
127.0.0.1,操作 API 端口为24601 - 请保留模块的默认端口:Cliqer 在
24601上提供操作 API - 一台计算机上只能有一个 Cliqer 实例占用本地端口,请参阅Stream Deck 说明
计时器反馈或变量未更新
- 实时计时器和应用状态推送使用端口
9052上的本地回环 WebSocket,因此 Companion 必须与 Cliqer 运行在同一台计算机上 - 即使推送未连接,幻灯片和计时器操作仍可通过 HTTP 成功执行;因此,如果按键能触发但反馈保持不变,请检查 Companion 中的连接状态
另请参阅:Stream Deck 集成 · Timer