【用户共创】Bitfocus Companion + QLab V5 + D200H配置教程

Ulanzi

本教程目标：通过 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 端口
  

01

三、配置 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文件。替换文件以及替换方式已打包在附件。
插件写入操作手册.pdf (21.72 KB, 下载次数: 0)

前天 00:56 上传

点击文件名下载附件
07

五、创建 Companion 显示页面与按钮
5.1 创建新 Buttons

• Companion 侧边栏→ Buttons
• 点击空白的按钮
• 点击Create button→feedbacks→红色文件夹→选择qlabfb→选择Running Cue Number→done
  

08

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中对应的页面、行、列
  

如果无法播放，请点击此处在新窗口打开

七、故障排查清单
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
figure53-qlab-advance-2.14.1-running-cue-number.zip (319.65 KB, 下载次数: 1)

昨天 18:24 上传

点击文件名下载附件
11