qlcplus

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

QLC+ Lighting Programming Skill

QLC+灯光编程技能

You are helping with QLC+ (Q Light Controller Plus) v5 lighting automation. This covers everything from fixture setup through show programming.

您正在获取QLC+（Q Light Controller Plus）v5灯光自动化相关帮助，内容涵盖从灯具设置到演出编程的所有环节。

Key Concepts

核心概念

DMX Fundamentals

DMX基础

512 channels per universe, values 0-255
QLC+ supports unlimited universes (4 default)
Fixtures are patched at a universe + start address

每个DMX宇宙包含512个通道，取值范围0-255
QLC+支持无限个宇宙（默认4个）
灯具需映射到指定宇宙+起始地址

HTP vs LTP (Critical for understanding conflicts)

HTP vs LTP（理解冲突的关键）

Rule	Channel types	Behavior
HTP (Highest Takes Precedence)	Intensity, dimmer, color intensity (R/G/B/W/A)	Highest active value wins
LTP (Latest Takes Precedence)	Pan, tilt, gobo, strobe, speed, all non-intensity	Most recently started function wins

HTP means two active scenes both setting a dimmer will show the higher value. LTP means the last-started function controls non-intensity channels — order matters, and unexpected jumps can occur.

During crossfades: HTP levels transition smoothly. LTP levels may jump immediately (gobo) or transition (pan/tilt) depending on fade time.

规则	通道类型	行为
HTP（高值优先）	亮度、调光器、色彩亮度（R/G/B/W/A）	激活状态下的最高值生效
LTP（最新优先）	水平摇头、垂直摇头、图案盘、频闪、速度等所有非亮度通道	最近启动的功能生效

HTP意味着两个激活场景同时设置调光器时，会显示较高的数值。LTP意味着最后启动的功能控制非亮度通道——顺序至关重要，可能出现意外跳变。

淡入淡出过程中：HTP电平平滑过渡。LTP电平可能立即跳变（如图案盘）或根据淡入时间过渡（如摇头）。

Fade Out Only Affects HTP

仅HTP通道受淡出影响

This is a common source of confusion. A scene's Fade Out time only fades intensity/HTP channels to zero. LTP channels (strobe mode, gobo position, pan/tilt) retain their values until another function overwrites them.

这是常见的混淆点。场景的淡出时间仅会将亮度/HTP通道渐变为0。LTP通道（频闪模式、图案盘位置、摇头）会保持其值，直到被其他功能覆盖。

Grand Master

总控推子（Grand Master）

Final master slider before DMX output. Two modes:

Reduce: channels reduced by percentage (50% GM = all channels at 50% of current)
Limit: channels cannot exceed the GM value (GM at 127 = max output 127)

Usually affects only Intensity channels, but can be set to affect all.

DMX输出前的最终总控滑块，有两种模式：

Reduce（比例缩减）：所有通道按百分比缩减（总控设为50% = 所有通道为当前值的50%）
Limit（上限限制）：通道值不能超过总控值（总控设为127 = 最大输出为127）

通常仅影响亮度通道，但可设置为影响所有通道。

Blackout

全黑（Blackout）

Sets ALL HTP channels in ALL universes to zero. Channels stay at zero regardless of running functions. When switched off, functions resume control.

将所有宇宙中的所有HTP通道设为0。无论运行中的功能如何，通道均保持为0。关闭全黑后，功能恢复控制。

Palettes (v5)

调色板（Palettes，v5版本）

A Palette abstracts a fixture feature (color, position, zoom). Can be used in Scenes to make looks fixture-independent. If you change a Palette, all Scenes using it update.

调色板抽象了灯具的某项特性（颜色、位置、变焦），可在场景中使用，使灯光效果与灯具无关。若修改调色板，所有使用它的场景都会同步更新。

Function Types

功能类型

Scene

场景（Scene）

A snapshot of channel values. Key properties:

Selective channel control: Only enabled channels are affected. Disabled channels are NEVER touched. This enables layering.
Fade In: Time to fade ALL channels (HTP AND LTP) to their target values. This is unique to Scenes — in other functions, Fade In only affects HTP.
Fade Out: Time to fade HTP/intensity channels back to zero. ONLY HTP channels are affected by Fade Out — LTP channels retain their values.
No duration: Scenes persist until stopped or overridden
Monolithic scenes (all channels enabled) work well for chaser-driven workflows where only one scene is active at a time
Partial scenes (only some channels) enable layering but require careful management
Crossfade blending: When a chaser transitions between two scenes, it calls
```
setBlendFunctionID
```
so the new scene reads starting values from the previous scene — enabling true crossfade without snapping.

通道值的快照，核心属性：

选择性通道控制：仅启用的通道会被影响，禁用的通道永远不会被修改，这实现了效果叠加。
淡入（Fade In）：将所有通道（HTP和LTP）渐变至目标值的时间。这是场景独有的特性——在其他功能中，淡入仅影响HTP通道。
淡出（Fade Out）：将HTP/亮度通道渐变为0的时间。仅HTP通道受淡出影响——LTP通道会保留其值。
无持续时间：场景会持续运行，直到被停止或覆盖
完整场景（所有通道启用）适用于追光序列驱动的工作流，同一时间仅一个场景激活
部分场景（仅启用部分通道）支持效果叠加，但需要谨慎管理
淡入淡出混合：当追光序列在两个场景间切换时，会调用
```
setBlendFunctionID
```
，使新场景从前一个场景读取起始值——实现无跳变的真正淡入淡出。

Chaser

追光序列（Chaser）

Runs steps sequentially. Each step is a Function (usually a Scene).

The timing model (from source code):

duration = fadeIn + hold

```
duration
```
is the TOTAL step time, not just hold
```
hold = duration - fadeIn
```
The step ends when
```
elapsed >= duration
```
On step end,
```
prevStepRoundElapsed = elapsed % duration
```
carries overshoot into the next step (prevents timing drift)
FadeOut is NOT included in duration — it overlaps with the next step or runs after stop

SpeedModes (on Chaser element) — precise behavior from source:

Mode	Meaning
Common	All steps use the chaser's own `<Speed>` values
PerStep	Each `<Step>` attribute is used directly
Default	Passes `Function::defaultSpeed()` (sentinel value UINT_MAX-1) to the child function, meaning the child uses its OWN fade times. The chaser does not override them.

For Duration mode specifically:

Default

and

Common

behave identically — both use the chaser's

duration()

Practical implications:

With
```
SpeedModes FadeIn="Default" Duration="PerStep"
```
: the step's Hold attribute IS the total step time. The child function's own FadeIn is used for crossfading. The Hold value is what contributes to the timeline.
With
```
SpeedModes FadeIn="PerStep" Duration="PerStep"
```
: the step's FadeIn overrides the child function's fade. Duration = FadeIn + Hold.

Run orders: Loop, SingleShot, PingPong, Random Direction: Forward, Backward

Beat tempo:

elapsedBeats

increments by 1000 on each beat. Duration in beats = multiples of 1000 (e.g., 4000 = 4 beats). Set

<Tempo Type="Beats"/>

Infinite speed (

Function::infiniteSpeed()

): Step never auto-advances. Used for manual cue lists. The runner checks:

if (duration != infiniteSpeed && elapsed >= duration)

按顺序运行步骤，每个步骤是一个功能（通常是场景）。

计时模型（来自源代码）：

duration = fadeIn + hold

```
duration
```
是步骤的总时长，而非仅保持时间
```
hold = duration - fadeIn
```
当
```
elapsed >= duration
```
时，步骤结束
步骤结束时，
```
prevStepRoundElapsed = elapsed % duration
```
将超出时长的部分带入下一个步骤（防止计时漂移）
淡出时间不包含在duration内——它会与下一个步骤重叠，或在停止后运行

速度模式（SpeedModes，追光序列元素）——源代码中的精确行为：

模式	含义
Common（通用）	所有步骤使用追光序列自身的 `<Speed>` 值
PerStep（每步骤）	直接使用每个 `<Step>` 的属性
Default（默认）	向子功能传递 `Function::defaultSpeed()` （标记值UINT_MAX-1），意味着子功能使用自身的淡入时间，追光序列不会覆盖这些时间。

对于Duration模式：

Default

和

Common

行为完全相同——均使用追光序列的

duration()

。

实际应用：

当
```
SpeedModes FadeIn="Default" Duration="PerStep"
```
时：步骤的Hold属性即为步骤总时长，子功能自身的淡入时间用于淡入淡出，Hold值决定时间线进度。
当
```
SpeedModes FadeIn="PerStep" Duration="PerStep"
```
时：步骤的FadeIn会覆盖子功能的淡入时间，总时长=FadeIn + Hold。

运行顺序： 循环（Loop）、单次触发（SingleShot）、往返（PingPong）、随机（Random） 方向： 正向（Forward）、反向（Backward）

节拍速度： 每拍

elapsedBeats

增加1000。以节拍为单位的时长是1000的倍数（如4000=4拍），需设置

<Tempo Type="Beats"/>

。

无限速度（

Function::infiniteSpeed()

）：步骤不会自动推进，用于手动cue列表。运行器会检查：

if (duration != infiniteSpeed && elapsed >= duration)

。

Sequence

序列（Sequence）

A chaser bound to a single parent Scene — all steps control the same channels. Appears as a child of its parent Scene in the Function Manager.

Sequence step values format (inside

<Step Values="N">

fixtureID:channel,value,channel,value:fixtureID:channel,value,...

Fixture chunks separated by

, channel/value pairs by

. Only non-zero values saved.

绑定到单个父场景的追光序列——所有步骤控制相同的通道，在功能管理器中显示为父场景的子项。

序列步骤值格式（位于

<Step Values="N">

内）：

fixtureID:channel,value,channel,value:fixtureID:channel,value,...

灯具块之间用

分隔，通道/值对用

分隔，仅保存非零值。

Collection

集合（Collection）

Runs multiple functions simultaneously (parallel, not serial). All members start in

preRun()

. Collection stops when all children finish (

m_runningChildren

becomes empty).

Cannot contain itself (self-containment check in
```
postLoad
```
)
Duplicate function IDs are rejected
No speed settings of its own

同时运行多个功能（并行，非串行），所有成员在

preRun()

中启动。当所有子功能完成时（

m_runningChildren

为空），集合停止运行。

不能包含自身（
```
postLoad
```
中有自包含检查）
拒绝重复的功能ID
自身无速度设置

EFX

Automates pan/tilt (or RGB/dimmer) along mathematical paths. Algorithm types: Circle, Eight, Line, Line2, Diamond, Square, SquareChoppy, SquareTrue, Leaf, Lissajous.

Propagation modes: Parallel (all fixtures move together), Serial (offset start), Asymmetric (mirror offset).

沿数学路径自动控制摇头（或RGB/调光器），算法类型包括：Circle（圆形）、Eight（8字形）、Line（直线）、Line2（双向直线）、Diamond（菱形）、Square（方形）、SquareChoppy（断续方形）、SquareTrue（标准方形）、Leaf（叶形）、Lissajous（李萨如图形）。

传播模式： Parallel（所有灯具同步移动）、Serial（偏移启动）、Asymmetric（镜像偏移）。

RGB Matrix

RGB矩阵（RGB Matrix）

Graphic patterns/text on a grid of RGB fixtures. Requires a Fixture Group defining pixel layout. Has Fade In, Fade Out, Duration per frame. Extensible via ECMAScript RGB scripts.

在RGB灯具网格上显示图形图案/文字，需要定义像素布局的灯具组。支持每帧的淡入、淡出、时长设置，可通过ECMAScript RGB脚本扩展功能。

Show

演出（Show）

Timeline-based function (Show Manager). Places functions on time tracks with precise timing. Best for pre-programmed sequences synced to music or a metronome.

Show Manager key concepts:

Multitrack view similar to a DAW — each track is bound to a Scene
Sequences on a track can only control channels of that track's Scene
Functions can be placed at precise time positions, dragged, copied
Supports BPM grid (4/4, 3/4, 2/2) with snap-to-grid for music sync
Tracks support mute/solo states
Playback always starts from cursor position, can resume

Sequences vs Chasers in Show Manager:

Sequence steps are values of ONE Scene's channels (bound to track). Chaser steps can be ANY function.
Sequences in Show Manager always play Forward. Chasers support all run orders.
Sequence editing: new steps copy previous step's values (adjust differences). Chaser editing: pick existing functions.
Sequences are better for extending shows (add track + sequence for new fixtures). Chasers require complex Collections for sync.

基于时间线的功能（演出管理器），将功能放置在时间轨道上实现精确计时，最适合预编程的、与音乐或节拍器同步的序列。

演出管理器核心概念：

类似DAW的多轨视图——每个轨道绑定一个场景
轨道上的序列只能控制该轨道场景的通道
功能可放置在精确的时间位置，支持拖拽、复制
支持BPM网格（4/4、3/4、2/2），可吸附到网格实现音乐同步
轨道支持静音/独奏状态
播放始终从光标位置开始，可恢复播放

演出管理器中的序列与追光序列对比：

序列步骤是单个场景通道的取值（绑定到轨道），追光序列步骤可以是任意功能。
演出管理器中的序列始终正向播放，追光序列支持所有运行顺序。
序列编辑：新步骤复制上一步的取值（仅调整差异）；追光序列编辑：选择已有的功能。
序列更适合扩展演出（添加轨道+序列即可支持新灯具），追光序列需要复杂的集合来实现同步。

Script

脚本（Script）

ECMAScript-based automation of QLC+ functions in sequential order.

基于ECMAScript的QLC+功能自动化，按顺序执行。

Workspace XML (.qxw) Structure

工作区XML（.qxw）结构

The .qxw file is XML. Common attributes on

<Function>

ID

Type

Name

Path

(folder),

Hidden

BlendMode

xml

<Workspace>
  <Creator>...</Creator>
  <Engine>
    <InputOutputMap>...</InputOutputMap>
    <Fixture>...</Fixture>
    <FixtureGroup>...</FixtureGroup>
    <ChannelsGroup>...</ChannelsGroup>
    <Function ID="N" Type="Scene" Name="...">
      <Tempo Type="Time"/>
      <Speed FadeIn="0" FadeOut="0" Duration="0"/>
      <ChannelGroupsValues>id,level,id,level</ChannelGroupsValues>
      <FixtureVal ID="fixture_id">ch_num,value,ch_num,value,...</FixtureVal>
      <FixtureGroup ID="0"/>
      <Palette ID="0"/>
    </Function>
    <Function ID="N" Type="Chaser" Name="...">
      <Tempo Type="Time"/>
      <Speed FadeIn="0" FadeOut="0" Duration="0"/>
      <Direction>Forward</Direction>
      <RunOrder>SingleShot</RunOrder>
      <SpeedModes FadeIn="Default" FadeOut="Default" Duration="PerStep"/>
      <Step Number="0" FadeIn="0" Hold="8000" FadeOut="0" Note="">scene_id</Step>
    </Function>
    <Function ID="N" Type="Collection" Name="...">
      <Step Number="0">function_id</Step>
      <Step Number="1">function_id</Step>
    </Function>
    <Function ID="N" Type="EFX" Name="...">
      <PropagationMode>Parallel</PropagationMode>
      <Algorithm>Circle</Algorithm>
      <Width>127</Width>
      <Height>127</Height>
      <Rotation>0</Rotation>
      <Speed FadeIn="0" FadeOut="0" Duration="20000"/>
      <Direction>Forward</Direction>
      <RunOrder>Loop</RunOrder>
      <Fixture>...</Fixture>
    </Function>
  </Engine>
  <VirtualConsole>...</VirtualConsole>
</Workspace>

.qxw文件为XML格式，

<Function>

的常见属性包括：

ID

、

Type

、

Name

、

Path

（文件夹）、

Hidden

、

BlendMode

。

xml

<Workspace>
  <Creator>...</Creator>
  <Engine>
    <InputOutputMap>...</InputOutputMap>
    <Fixture>...</Fixture>
    <FixtureGroup>...</FixtureGroup>
    <ChannelsGroup>...</ChannelsGroup>
    <Function ID="N" Type="Scene" Name="...">
      <Tempo Type="Time"/>
      <Speed FadeIn="0" FadeOut="0" Duration="0"/>
      <ChannelGroupsValues>id,level,id,level</ChannelGroupsValues>
      <FixtureVal ID="fixture_id">ch_num,value,ch_num,value,...</FixtureVal>
      <FixtureGroup ID="0"/>
      <Palette ID="0"/>
    </Function>
    <Function ID="N" Type="Chaser" Name="...">
      <Tempo Type="Time"/>
      <Speed FadeIn="0" FadeOut="0" Duration="0"/>
      <Direction>Forward</Direction>
      <RunOrder>SingleShot</RunOrder>
      <SpeedModes FadeIn="Default" FadeOut="Default" Duration="PerStep"/>
      <Step Number="0" FadeIn="0" Hold="8000" FadeOut="0" Note="">scene_id</Step>
    </Function>
    <Function ID="N" Type="Collection" Name="...">
      <Step Number="0">function_id</Step>
      <Step Number="1">function_id</Step>
    </Function>
    <Function ID="N" Type="EFX" Name="...">
      <PropagationMode>Parallel</PropagationMode>
      <Algorithm>Circle</Algorithm>
      <Width>127</Width>
      <Height>127</Height>
      <Rotation>0</Rotation>
      <Speed FadeIn="0" FadeOut="0" Duration="20000"/>
      <Direction>Forward</Direction>
      <RunOrder>Loop</RunOrder>
      <Fixture>...</Fixture>
    </Function>
  </Engine>
  <VirtualConsole>...</VirtualConsole>
</Workspace>

Scene FixtureVal format

场景FixtureVal格式

<FixtureVal ID="fixture_id">channel,value,channel,value,...</FixtureVal>

Channel numbers are 0-indexed relative to the fixture
Values are 0-255
Empty FixtureVal (
```
<FixtureVal ID="3"/>
```
) means fixture participates but no values set

<FixtureVal ID="fixture_id">channel,value,channel,value,...</FixtureVal>

通道编号为相对于灯具的0索引
值范围0-255
空FixtureVal（
```
<FixtureVal ID="3"/>
```
）表示灯具参与但未设置任何值

Chaser Step format

追光序列Step格式

<Step Number="N" FadeIn="ms" Hold="ms" FadeOut="ms" Note="">function_id</Step>

Times in milliseconds
function_id references the Function ID of the step content
Tempo Type="Beats": values are multiples of 1000 (1000 = 1 beat)

<Step Number="N" FadeIn="ms" Hold="ms" FadeOut="ms" Note="">function_id</Step>

时间单位为毫秒
function_id引用步骤内容的功能ID
Tempo Type="Beats"时，值为1000的倍数（1000=1拍）

Virtual Console

虚拟控制台（Virtual Console）

Button

按钮（Button）

Triggers a function. Modes: toggle, flash (held), blackout.

触发功能，模式包括：切换、闪烁（按住时）、全黑。

Slider

滑块（Slider）

Direct channel control or playback fader (controls HTP intensity of a running function).

直接控制通道或播放推子（控制运行中功能的HTP亮度）。

Cue List

Cue列表（Cue List）

Can ONLY be assigned a Chaser
Steps through with Next/Previous/Play/Stop
Crossfade fader for manual transitions
Set step duration to infinite (∞) for manual crossfade control
Duration=0 causes frantic looping — always set explicit durations

仅可分配追光序列
通过Next/Previous/Play/Stop切换步骤
淡入淡出滑块用于手动过渡
将步骤时长设为无限（∞）可实现手动淡入淡出控制
时长设为0会导致疯狂循环——务必设置明确的时长

Solo Frame

单帧激活框（Solo Frame）

Only ONE button active at a time. Starting a new function stops the previous. Essential for mutually exclusive looks.

同一时间仅一个按钮激活，启动新功能会停止前一个功能，是实现互斥灯光效果的关键组件。

Frame

框架（Frame）

Visual grouping. Can collapse. No exclusive behavior.

视觉分组，可折叠，无互斥行为。

Fixture Definitions

灯具定义（Fixture Definitions）

Fixtures are defined in XML (.qxf) with:

Manufacturer, Model, Type
Physical properties (bulb, beam angle, dimensions)
Channels with groups (Intensity, Pan, Tilt, Gobo, Color, Speed)
Capabilities per channel (value ranges → names/functions)
Modes (different channel configurations for the same fixture)

灯具通过XML文件（.qxf）定义，包含：

制造商、型号、类型
物理属性（灯泡、光束角、尺寸）
带分组的通道（Intensity、Pan、Tilt、Gobo、Color、Speed）
每个通道的功能（取值范围→名称/功能）
模式（同一灯具的不同通道配置）

Fixture Modes

灯具模式

Many fixtures have multiple modes (e.g., 8-bit vs 16-bit pan/tilt). Each mode defines which channels are active and their order.

许多灯具支持多种模式（如8位vs16位摇头），每种模式定义激活的通道及其顺序。

Heads

灯头（Heads）

A head is an individual light output in a multi-head fixture (e.g., LED bar with 4 RGB segments). Heads share some properties but can be controlled individually.

灯头是多头灯具中的单个灯光输出（如带4个RGB段的LED条），灯头共享部分属性但可单独控制。

Input/Output & Plugins

输入/输出与插件

QLC+ supports:

Art-Net (network DMX)
E1.31/sACN (network DMX)
DMX USB (Enttec, FTDI adapters)
MIDI (input/output for controllers)
OSC (Open Sound Control)
HID (joysticks, gamepads)
Loopback (internal routing)

Input profiles map physical controller knobs/faders to QLC+ controls.

QLC+支持：

Art-Net（网络DMX）
E1.31/sACN（网络DMX）
DMX USB（Enttec、FTDI适配器）
MIDI（控制器输入/输出）
OSC（开放式声音控制）
HID（摇杆、游戏手柄）
Loopback（内部路由）

输入配置文件将物理控制器的旋钮/推子映射到QLC+控件。

Common Pitfalls

常见误区

Hold="0" on sub-chaser steps — causes them to be skipped entirely
SpeedModes FadeIn="PerStep" on main song chaser — causes timing drift vs "Default"
Fade Out expects LTP channels to fade — they don't; only HTP channels fade
Two scenes setting same LTP channel — last-started wins, can cause unexpected jumps
Cue List with duration=0 steps — frantic looping with no visible result
Forgetting channel enable/disable — a scene with a channel disabled will never touch that channel, even if it looks like it should
HTP conflicts when layering monolithic scenes — if both scenes set intensity, highest wins, not the "current" one

子追光序列步骤设为Hold="0"——会导致步骤被完全跳过
主歌曲追光序列设为SpeedModes FadeIn="PerStep"——会导致与"Default"模式相比出现计时漂移
认为淡出会影响LTP通道——实际不会，仅HTP通道会淡出
两个场景设置同一LTP通道——最后启动的场景生效，可能导致意外跳变
Cue列表步骤设为duration=0——疯狂循环且无可见效果
忘记启用/禁用通道——场景中禁用的通道永远不会被修改，即使看起来应该被修改
叠加完整场景时的HTP冲突——若两个场景都设置亮度，高值生效，而非“当前”场景的数值

Timing Calculations

计时计算

When programming song chasers, always verify:

sum(all step Hold values) == song duration

(for SingleShot chasers)

Sub-chaser Hold = sum of sub-chaser's own steps' total durations
FadeIn happens WITHIN the Hold window (with Default SpeedMode), not in addition to it

编程歌曲追光序列时，务必验证：

所有步骤Hold值之和 == 歌曲时长

（适用于SingleShot追光序列）

子追光序列的Hold值等于其子步骤总时长之和
淡入在Hold窗口内完成（使用Default速度模式），而非额外耗时

Best Practices

最佳实践

Use

SpeedModes FadeIn="Default" FadeOut="Default" Duration="PerStep"

for song chasers

Give sub-chaser steps explicit Hold values matching their total runtime
Never hold a single static scene longer than ~12s in performance
Create front/rear intensity contrast for depth (not symmetric values)
Use Solo Frames to prevent accidental scene stacking
Keep strobe for punctuation, not atmosphere

歌曲追光序列使用

SpeedModes FadeIn="Default" FadeOut="Default" Duration="PerStep"

给子追光序列步骤设置与其总运行时长匹配的明确Hold值
演出中单个静态场景的持续时间不要超过约12秒
创建前后亮度对比以增强层次感（避免对称取值）
使用单帧激活框防止意外场景叠加
频闪仅用于强调，不要用作氛围效果