【用户共创】Bitfocus Companion + QLab V5 + D200H配置教程
本教程目标：通过 Bitfocus Companion 中转，让 QLab V5 的实时播放状态（当前 cue 编号、名称、运行状态）通过 OSC 协议同步到 Ulanzi D200H 小屏显示。适用环境：macOS + QLab 5.x + D200H 同机直连（无需跨设备网络配置）
作者：Tim-Guo
前置条件：
[*]Ulanzi Studio 已安装且 D200H 已连接
[*]Companion 插件已安装升级至 V4.3.4 或以上
[*]QLab 5.x 已激活（OSC 功能需 Pro 授权）
[*]macOS 12+ 系统
一、整体架构完整数据流向：QLab V5 → OSC（UDP 53000）→ Bitfocus Companion → Connection 插件→ D200H 屏幕
架构特点：
[*]全本地通信，不依赖外部网络
[*]OSC 默认走 loopback（127.0.0.1），延迟 < 100ms
[*]Companion 作为中转站，提供变量绑定、Feedback、条件触发等丰富能力
二、安装与启动 Bitfocus Companion
2.1 下载与安装
[*]访问 Bitfocus Companion 官网：https://bitfocus.io/companion
[*]下载 macOS 版本（Universal 或 Apple Silicon，按需选择）
[*]解压后拖入 Applications 文件夹
[*]双击启动 Companion
2.2 验证启动
[*]启动后，浏览器自动打开 http://localhost:9999
[*]看到 Companion Web 配置界面即表示启动成功
[*]记住两个关键端口：
[*]52000：OSC 监听端口（接收 QLab 发送）
[*]9999：Web 配置界面 + API 端口
三、配置 QLab V5 OSC 发送
3.1 进入 OSC 设置
[*]打开 QLab 5
[*]顶部菜单 → QLab → Settings → OSC → Network 标签
3.2 关键配置项
配置项 设置值 说明
OSC Access 勾选 Enable OSC Access 必须开启，否则 QLab 不接收外部控制
Passcode 自定义 4 位数字（建议 1234） 记下来，Companion 端必须一致
Incoming Port 52000 Companion 监听端口相同即可
Outgoing Destination 1 - IP 127.0.0.1 本机 loopback（D200H 与 QLab 同机）
Outgoing Destination 1 - Port 52000 Outgoing 与 Incoming 端口相同
注意：QLab 5 默认会持续向已配置的 Outgoing 目标发送所有 cue 状态变化，无需手动触发。这是 OSC 协议的优势——状态驱动而非命令驱动。
四、Companion 添加 QLab V5 Connection
4.1 添加 Connection在 Companion Web 界面（localhost:9999）操作：
[*]左侧 Connections 标签
[*]点击 Add New Connection → 搜索 QLab
[*]选择 Figure 53：Qlab with feedback
[*]配置 Connection 参数：Host=127.0.0.1，Port=52000，Passcode=1234
[*]点击 Apply
4.2 验证连接
Companion 右上角 Status 区域，QLab V5 应显示绿色 Connected。
4.3 替换Connection文件官方提供的Qlab Connection文件没有可用的feedback预设，笔者基于Connection文件新增相关feedback预设，故需要替换原本的官方Qlab Connection文件。替换文件以及替换方式已打包在附件。
五、创建 Companion 显示页面与按钮
5.1 创建新 Buttons
[*]Companion 侧边栏→ Buttons
[*]点击空白的按钮
[*]点击Create button→feedbacks→红色文件夹→选择qlabfb→选择Running Cue Number→done
5.2 验证实时同步
[*]回到 QLab 5，选中一个 cue 点击 GO
[*]Companion 页面应显示该 cue 名称/编号
六、配置 Ulanzi Studio Companion 插件
6.1 添加 Companion 实例
[*]打开 Ulanzi Studio
[*]在 D200H 配置页 → 应用市场
[*]选择 Companion V4 插件（确保版本 V2.0.2 或以上）
6.2 添加 D200H 按键关联
[*]在 D200H 配置页 → 拖入Companion按钮
[*]选择拖入的按钮
[*]填写 Companion 连接信息：
[*]Host：127.0.0.1（Companion 在本机）
[*]Port：9999（Companion Web API 端口）
[*]显示：连接（已连接）
[*]填写 Companion中对应的页面、行、列
attach://1288.mp4
七、故障排查清单
8.1 Companion 无法启动 / 浏览器未打开
1. 检查 53000/9999 端口是否被其他程序占用
lsof -i :53000
lsof -i :9999
2. 如端口被占用，更换 Companion 配置中的端口
3. macOS 防火墙拦截：系统设置 → 网络 → 防火墙 → 允许 Companion
8.2 Companion 显示 QLab Disconnected
1. 检查 QLab OSC Access 是否开启
2. 检查 Passcode 是否一致（QLab 端 vs Companion 端
3. 检查端口是否一致（QLab Incoming Port = Companion 监听端口
4. 在终端运行 oscdump 53000 验证 QLab OSC 是否发送
5. 重启 QLab + Companion
8.3 macOS 启动后 Companion 自动连接失败
1. 系统设置 → 隐私与安全性 → 辅助功能：重新授权 Companion
2. 系统设置 → 隐私与安全性 → 输入监控：重新授权 Companion
3. 检查是否启用了 VPN（VPN 可能拦截 loopback）
4. 重启 macOS
8.4 D200H 按键无反应
1. 检查 D200H 是否被 Ulanzi Studio 正确识别
2. 检查 Companion 实例是否连接成功（绿色 ✓）
3. 检查 Page/Button 关联是否正确
4. 重新添加 Companion 实例
八、FAQ 常见问题
Q1: D200H 屏最大能显示多少字符？
D200H 小屏建议单屏不超过 20 个英文字符 / 10 个中文字符。超长 cue 名称会被截断，建议取前 N 字符显示。
Q2: Companion 是否支持多 QLab 实例？
支持。在 Companion 中创建多个 QLab V5 Connection 即可，每个 Connection 独立配置 IP/Port/Passcode。
Q3: 是否可以用同一台 Mac 控制多台 D200H？
可以。Ulanzi Studio 支持多设备同时管理，每台 D200H 独立配置 Companion 插件即可。
Q4: OSC 通信是否加密？
OSC 协议本身不加密，但本机 loopback 通信风险低。跨设备通信建议使用 VPN 或专用网络隔离。
Q5: QLab 4 是否兼容？
不兼容。QLab 4 和 QLab 5 的 OSC 协议差异较大，Companion Connection 中需选择 QLab V4 模块（与本文档配置不同）。
Q6: Companion 是否必须一直开着？
是的。Companion 是中转服务器，关闭后 QLab 与 D200H 的实时同步会中断。建议设为开机自启。
九、上线检查清单
完整配置完成后，按此清单逐项验证：
[*]Companion 已安装并启动，浏览器可访问 localhost:9999
[*]QLab V5 OSC Access 已开启，Passcode 已设置
[*]Companion QLab V5 Connection 状态为 Connected（绿色）
[*]Companion Page "QLab Live Display" 已创建
[*]Button Text 绑定 QLab 变量成功
[*]Ulanzi Studio Companion 插件实例连接成功
[*]D200H 屏实时显示 QLab 当前 cue
[*]Companion 已设为开机自启（系统设置 → 登录项）
附件：figure53-qlab-advance-2.14.1-running-cue-number.zip
页:
[1]