OSCscript 是什么 · 工作原理
OSCscript 是一个 集成化操作平台。它启动后会打开一个网页操作界面，这个界面就是你的主操作台——你在里面完成发现设备、连接、播放控制、状态监控等所有操作。
它不是任何单一软件的辅助显示工具，而是把演出中所有支持 OSC 通信的软硬件集成到一个统一的操作界面里。你可以同时管理多台设备——比如 QLab 播放器、调音台、灯控台、灯杆、剧场大幕、其他播放器等，自定义按钮组合、一键执行多个操作。
理解 OSCscript 和配置文件的关系，可以打个比方：OSCscript 主程序就像手机，配置文件就像手机里的 App。
- 手机（OSCscript 主程序）：是平台，负责所有配置文件和操控指令的运作、设备连接、消息收发。没有手机，App 装不了也跑不起来。
- 手机里的 App（配置文件）：负责用户想要的控制功能和界面外观。你装什么 App，手机就有什么功能；你加载什么配置文件，OSCscript 就呈现什么操控界面。
OSCscript 有两类配置文件：
| 类型 | 作用 | 谁来读 |
|---|---|---|
| 设备模块 | 定义"怎么发现设备、怎么连接、怎么发命令、怎么处理回复" | OSCscript 主程序 |
| 界面配置 | 定义"界面长什么样、每个按钮对应什么操作、收到消息怎么显示" | 网页界面 |
这种设计的好处：换设备不改界面，换界面不改设备。同一份界面配置可以同时控制各种设备——比如 QLab 4 / QLab 5、调音台、灯控台、灯杆、剧场大幕、其他播放器等任何支持 OSC 通信的设备，OSCscript 会自动按模块分发指令。
可以，这是 OSCscript 最强大的特性之一。通过配置文件，一个按钮可以同时触发多个操作——比如点击一个"开场"按钮，可以同时：
- 播放 QLab 里的第一条 Cue
- 触发灯光控台的某个场景
- 向其他设备发送控制指令
这些组合完全由配置文件定义，你不需要写代码，只需要在界面配置里把一个按钮绑定到多个地址即可。
整个流程如下：
点击按钮
处理指令
发送到目标设备
（QLab 播放/灯光切换等）
反过来，设备的状态变化（比如 QLab 开始播放、灯控台切换场景）也会实时反馈到界面上：
（开始播放等）
状态推送
显示最新状态
主界面图解
演出前准备
OSCscript 通过编号来识别和管理你的每一个节目素材。编号是整个系统的"身份证"——没有编号，软件就无法知道当前播放的是哪个素材、下一个该播什么、时间进度该对应哪条节目。
以 QLab 为例，如果 Cue 没有编号，会出现以下问题：
- 界面上的"正在播放"和"下个准备"显示为空或错误
- 时间进度条不跳动，显示为 00:00:00
- 无法自动跟随设备软件的播放状态切换
OSCscript 通过编号识别每条 Cue，编号相当于节目素材的"身份证"。格式规范直接影响控制端能否正确读取、切换和显示进度。
推荐格式：
- 纯数字递增：1、2、3、4…（兼容性最好，最推荐）
- 分段编号：第一幕 101-110，第二幕 201-210，方便按场次快速定位
- 子编号：1.1、1.2、1.3，用于同一素材的多个段落
- 临时过渡音效可少量使用字母编号，如 A1、A2，但建议统一风格
快捷编号技巧：
- Command + D：在 QLab 中全选需要编号的 Cue，按 Command + D 可快速删除编号
- Command + R：全选 Cue 后按 Command + R，可打开快速编号窗口批量设置编号
快速编号使用方法：
- 在 QLab 中选中需要编号的 Cue（可按住 Shift 连续多选，或按住 Command 跳选）
- 按下 Command + R 打开快速编号窗口
- 设置起始编号、步长、前缀/后缀等规则
- 点击确认，QLab 会自动为选中的 Cue 分配连续编号
QLab 快速编号窗口示例
QLab 每个 Cue 都有一个 Notes 备注栏。OSCscript 可以读取并在界面上显示这个备注内容，方便操作人员在演出时快速确认每条节目的身份。
建议写入：
- 节目名称或曲目名（如"开场舞 - 春江花月夜"）
- 操作提示（如"淡入 3 秒""结尾渐弱"）
- 演员或灯光配合说明（如"演员上台后播放"）
安装与首次运行
OSCscript 支持多平台，分述如下：
macOS 版
- 从官方渠道获取
OSCscript.app应用文件 - 将应用拖入"应用程序"文件夹（推荐）
- 首次打开：右键点击应用 → 选择"打开" → 在弹窗中再次确认"打开"
- 如果系统提示"无法验证开发者"，前往 系统设置 → 隐私与安全性 → 点击"仍要打开"
Windows 版
首次启动后，应用会打开主界面。你可以按需选择：
- 免费使用：不登录也能使用基础功能
- 登录账号：登录后可试用 Pro 版功能，或激活已购买的授权
登录或选择免费使用后，按以下顺序完成初始化：
- 打开设备软件：先启动你要控制的设备软件（如 QLab、调音台软件、灯控台软件等），并打开演出工程文件
- 等待自动发现：OSCscript 会自动搜索局域网内支持 OSC 的设备，通常 3-5 秒内可在设备列表看到
- 点击连接：在设备列表中点击你要连接的设备，输入连接密码（如设置了的话）
- 加载界面配置：选择适合你演出的界面配置文件
- 浏览器打开操控页面：加载完成后，需要在任意电脑、手机或平板的浏览器中打开 OSCscript 显示的地址，才能看到对应的界面布局
登录激活时需要联网，验证通过后即可离线使用。演出过程中不需要外网，OSCscript 与 QLab 之间通过本地通信完成所有交互。
连接设备与基本操作
按以下顺序排查：
- 确认设备软件已启动：你要控制的设备软件（如 QLab、调音台软件、灯控台软件等）必须处于运行状态，并已打开工程文件
- 检查网络连接：OSCscript 和目标设备必须在同一台电脑，或同一局域网内
- 检查设备的 OSC 设置（不同设备开启方式不同，见下方 QLab 示例及第 5 章各设备说明）
- 检查防火墙：系统设置 → 网络 → 防火墙，确保没有阻止 OSCscript
- 重启尝试：先退出 OSCscript，再重新打开
| 密码类型 | 用途 | 在哪设置 |
|---|---|---|
| Web 访问密码 | 保护网页操控界面，防止同一网络内他人通过浏览器误操作 | OSCscript 底部功能栏的锁形图标 |
| 设备 OSC 密码（Passcode） | 设备端 OSC 通信的握手密码，连接设备时需输入 | 设备软件内（如 QLab 工作区设置） |
连接设备时提示的密码，是设备 OSC 密码（Passcode），不是 OSCscript 的账号密码，也不是 Web 访问密码。
QLab 5 设置路径：
- 打开 QLab 5 工作区
- 顶部菜单 Workspace → Workspace Settings
- 进入 Network 选项卡
- 选择 OSC 标签
- 在 Passcode 栏查看或设置密码
QLab 4 设置路径：
- 顶部菜单 Windows → Override Control（快捷键 Shift+Command+O）
- 在 OSC 区域查看或设置 Passcode
这种反复掉线通常有以下原因：
- 网络不稳定：如果是无线连接，建议改用网线直连演出电脑
- 设备软件工程被关闭或切换：如 QLab 工作区被关闭、灯控台工程被切换等，保持设备软件工程始终打开
- 电脑休眠：前往系统设置 → 电池/节能，关闭自动休眠
- 其他软件占用：检查是否有其他同类软件同时运行
各设备端应该做什么
OSCscript 是集成化操作平台，真正执行动作的是各设备端软件（如 QLab、调音台软件、灯控台软件等）。不同设备需要按各自的方式做好"能被外部控制"的准备，下面按设备类型分别说明。
1. 开启 OSC 通信
- QLab 5：Workspace → Workspace Settings → Network → OSC，确保监听和发送已启用
- QLab 4：Windows → Override Control（Shift+Command+O），OSC Input 设为 ON，OSC Output 设为 ON（两者缺一不可）
2. 给每条 Cue 编号
OSCscript 通过编号识别节目素材，编号是整个系统的"身份证"。推荐使用纯数字递增（1、2、3...），也可分段编号（第一幕 101-110，第二幕 201-210）。
3. 设置 Fade & Stop 选项
Fade & Stop 是 QLab 中每一个 Cue 的一个选项，只有"淡出停止"，没有"淡入"。它决定的是上一个 Cue 的命运——本 Cue 触发时，上一个 Cue 该怎么退场。
| 选项状态 | 效果 |
|---|---|
| 勾选 Fade & Stop | 触发本 Cue 时，上一个 Cue 会被淡出停止，再开始播放本 Cue |
| 不勾选 | 上一个 Cue 不会被停止，与本 Cue 重叠播放 |
设置位置：QLab 中每个 Cue 的 Trigger 标签里。这个设置是每个 Cue 独立的，不是全局设置。
4. 填写 Notes 备注
QLab 每个 Cue 都有 Notes 备注栏，OSCscript 可以读取并在界面上显示，方便演出时快速确认节目身份。建议写入节目名称、操作提示、演员灯光配合说明。
演出现场操作流程
建议按以下顺序操作：
- 开机：打开演出电脑，等待完全启动
- 关闭干扰：退出微信、QQ、邮件等通知类软件，关闭自动更新
- 打开设备软件：启动你要控制的设备软件（如 QLab、调音台软件、灯控台软件等），打开演出工程文件
- QLab 4 用户：记得检查 OSC 开关（Windows → Override Control → Input ON, Output ON）
- 打开 OSCscript：启动应用（已激活的可直接登录，未登录可免费使用基础功能）
- 连接设备：在设备列表点击连接，确认显示"已连接"
- 加载界面：选择演出用的界面配置
- 浏览器打开操控页面：在演出电脑或任意设备浏览器中打开 OSCscript 显示的地址，进入主操作界面
- 功能测试：在浏览器操控界面点击播放，确认一切正常
- 声卡检查：确认声音输出设备正确，音量正常
演出中主要在浏览器打开的 OSCscript 网页操控界面里操作。这是你的主操作台——播放、停止、切换节目等所有操作都在这里完成，不需要回到 OSCscript 主程序或 QLab。
OSCscript 的界面配置允许你把一个按钮绑定到多个操作上。比如你可以做一个"第二幕开始"按钮，点击后同时完成：停止第一幕的背景音乐、播放第二幕的开场音效、触发灯光切换——这些都在网页操控界面里一键完成，不需要在多个软件之间切换。
不要慌张，按以下步骤处理：
- 如果设备软件（如 QLab）还在正常运行，演出不中断——直接切到设备软件界面继续操作
- 趁节目间隙，在 OSCscript 网页界面点重新连接
- 如果重连无效，退出 OSCscript 重新打开
- 演出结束后再排查根本原因
不是，可以在任意电脑、手机、平板的浏览器里打开操作。只要这些设备和运行 OSCscript 的电脑在同一个局域网内，浏览器输入 OSCscript 显示的操控地址即可访问。
- 主操作员可以在演出电脑的浏览器里全屏操作
- 副操作员可以用平板、手机作为辅助操控位
- 导演或灯光师可以在自己的设备上查看实时状态
常见故障与解决方案
点击问题展开查看解决方案
界面完全不显示任何内容，一片空白
可能原因：
- 未连接设备，或连接已断开
- 设备软件工程没有打开
- 界面配置文件未正确加载
解决步骤：
- 检查设备列表，确认目标设备显示"已连接"
- 在设备软件中确认工程已打开（如 QLab 工作区、灯控台工程等）
- 重新选择并加载界面配置
- 如果以上都正常仍空白，退出重启 OSCscript
时间进度条不跳动，显示 00:00:00
可能原因：
- 当前没有正在播放的节目
- 节目编号缺失，无法被识别
- 连接不稳定，数据未同步
解决步骤：
- 在设备软件中播放一条有编号的节目（如 QLab 的 Cue）
- 观察 OSCscript 界面是否开始显示
- 如果仍不跳动，断开重连设备
"正在播放"显示的是上一个节目，不同步
原因一：网络延迟或连接不稳定
状态更新滞后，等待 2-3 秒通常会自动同步。如持续不同步，检查网络质量，改用网线直连。
原因二：节目名只在播放瞬间获取一次
节目名称是在 Cue 开始播放的那一瞬间获取的，只获取一次。如果当时网络有波动可能获取失败或获取到错误内容。
解决办法：在设备软件中再播放一个节目（如 QLab 的 Cue），触发新一轮获取，通常会自动修正。或者断开重连 OSCscript，让它重新同步当前状态。
设备能搜到但连接不上，提示失败
QLab 4 用户重点检查：
QLab 4 的 OSC 通信默认可能未开启。必须手动操作：
- 顶部菜单栏 → Windows → Override Control（快捷键 Shift+Command+O）
- 在弹出的控制面板里，确保 OSC Input 设为 ON
- 确保 OSC Output 设为 ON
- 两个都必须开，缺一不可
其他设备通用排查：
- OSC Passcode 错误（如设备 OSC 设置里设置了 Passcode，连接时需输入一致的密码）
- 设备版本不兼容（OSCscript 对不同设备使用不同模块，如 QLab 4 和 QLab 5 模块不同）
- 在设备软件中尝试重新打开工程，或新建空白工程测试连接
应用启动后白屏或闪退
可能原因：系统权限问题或应用损坏。
解决步骤：
- 系统设置 → 隐私与安全性 → 确认允许 OSCscript 运行
- 删除应用，重新下载安装最新版
- 重启电脑后再次尝试
- 如果仍闪退，联系技术支持并提供系统版本信息
登录提示账号未激活或授权过期
解决步骤：
- 确认已完成注册并购买了对应版本的授权
- 检查授权是否过期，如过期需续费
- 确认当前登录的账号与购买授权的账号一致
授权绑定在首次激活的设备上，不可迁移到其他电脑。如需在新电脑上使用，需重新购买授权。请务必在确认演出电脑后再激活。
备注内容显示为乱码或不完整
可能原因：备注中包含特殊字符或表情符号。
解决步骤：
- 检查 QLab 中 Notes 栏的内容，移除特殊符号和 emoji
- 使用纯文字描述
- 如果备注过长，适当精简（建议不超过 50 字）
进阶技巧与注意事项
- 专机专用：演出电脑不装其他无关软件，不做日常使用
- 关闭通知：系统设置 → 通知 → 为 OSCscript 和所有设备软件关闭所有通知，避免弹窗干扰
- 关闭蓝牙：如不用蓝牙设备，关闭蓝牙减少干扰
- 固定 IP：给演出电脑设置固定 IP 地址，避免地址分配变化
- 预演彩排：正式演出前用 OSCscript 完整走一遍流程，发现问题提前解决
- 准备预案：即使 OSCscript 完全不可用，也要确保操作员能独立用各设备软件完成演出
OSCscript 支持发现并显示局域网内的多台设备（如多台 QLab、调音台、灯控台等）。你可以同时连接多台，但建议演出时每种类型只连接一台主控设备，避免操作混乱。如果有主备双机需求，建议明确主备切换流程，并在彩排时反复演练。
授权绑定在首次激活的设备上，不可迁移。请在确认演出电脑后再激活授权。如果演出电脑更换，需要重新购买授权。
- 禁止在演出过程中更新 OSCscript 或任何设备软件
- 禁止在演出过程中更改网络设置（切 Wi-Fi、拔网线）
- 禁止在演出过程中关闭设备软件工程（如 QLab 工作区、灯控台工程等）
- 禁止在演出过程中调整系统声音输出设备
- 禁止让电脑进入睡眠或休眠
- 禁止在演出电脑上插入陌生 U 盘
QLab 4 因为原生系统不支持很多功能，导致匹配度较低，一些数据显示可能会有延迟，但控制不延迟，只影响返回数据的显示。