Skip to content

v2.9.0 — Cue lists · audio-synced show programming

Choose a tag to compare

View all tags
@gfargo gfargo released this 16 May 22:12
· 33 commits to main since this release
v2.9.0
b3799c1
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Highlights

Audio-synced cue lists — the QLab / ETC Ion "cue stack" model. An ordered list of cues with absolute timestamps; press GO and the server fires each cue at its time. The missing "build a show" primitive.

create_cue_list("YouTube Intro", cues=[
  { "at": "0:00",     "scene":  "Daylight" },
  { "at": "0:08",     "chase":  "Sunset" },
  { "at": "0:15.500", "scene":  "Warm" },
  { "at": "0:22",     "action": "strobe",   "parameters": { "rate": 8 } },
  { "at": "0:24",     "action": "strobe",   "parameters": { "rate": "off" } },
  { "at": "0:28",     "action": "fade",     "parameters": { "target": "0", "duration": "2" } },
  { "at": "0:30",     "action": "blackout" }
])

go_cue_list("YouTube Intro")

Closes #8. MCP catalog 40 → 48.

Scope change from the original issue

Original #8 was scoped as wall-clock cron-style scheduling. After discussion the audience-fit angle won: audio-synced cue lists is the QLab / ETC Ion model that studio video, photography, and theatre operators actually live in. Cron-style scheduling can be revisited as a separate issue if it ever comes up.

API surface (8 tools)

Tool Effect
list_cue_lists Every saved cue list with runtime status
describe_cue_list Full cue array + runtime status for one list
get_active_cue_lists Only currently-playing lists, with elapsed time
create_cue_list Build from name + cues array
update_cue_list Rename, change description, or replace cues
delete_cue_list Remove (stops playback first if running)
go_cue_list GO from the top
stop_cue_list Halt; fixtures hold last fired state

Cue shape

Timestamps accept five forms:

Form Example
Integer ms 32500
"ms" suffix "32500ms"
"s" suffix "32s"
MM:SS[.mmm] "0:32.500"
HH:MM:SS[.mmm] "1:23:45.250"

Actions accept three forms:

Form Resolves to
{ "scene": "Chorus" } activate_scene
{ "chase": "Sunset" } start_chase
{ "action": "strobe", "parameters": {...} } any dispatcher action

Plus optional groups: [...] per cue.

Sync mode

The server doesn't play audio itself — sync your audio source (OBS, Logic, Premiere, a phone, whatever) by triggering GO at the moment the track starts. Pros already have audio rigs; this lets the lighting layer integrate with whatever's running.

Playback engine

One asyncio task per running list on the existing QLC+ background event loop (no separate threading concerns). Tolerates per-cue dispatch failures — one bad cue prints a warning, the rest still fire on schedule. Pressing GO on a running list cancels the previous run and restarts (matches "press GO twice = restart" intuition).

Composability — dispatcher gained two actions

Added start_chase and stop_chase to execute_lighting_action's vocabulary so cues + batch_action can fire chases composably. Existing /api/chases/<id>/start endpoint is unchanged.

Reference validation at create time

create_cue_list and update_cue_list cross-check every scene name and chase name against the workspace. Broken refs return a structured 400 listing which cues are bad — agents get an immediate signal instead of discovering at GO time.

Upgrade

git pull
./lightsctl.sh control-restart   # picks up the new endpoints
./lightsctl.sh mcp-restart       # picks up the new MCP tools

No package dependency changes.

Compatibility

  • No breaking changes. All existing endpoints + MCP tools behave identically.
  • New routes live under /api/cue_lists — a previously-unused path.
  • Persistence is ~/.qlcplus/cue_lists.json (separate from the QLC+ workspace, mirrors how fixture_groups.json works).
  • start_chase / stop_chase joining the action vocabulary is additive — no existing action names collide.

Documentation

  • docs/MCP_SERVER.md — new "Cue lists" section
  • docs/CONTROL_SERVER_ARCHITECTURE.md — API surface table extended (8 new rows)
  • mcp-server/README.md + root README.md — refreshed
  • Wiki MCP-Server.md + Control-Server.md updated
  • Marketing site: the editorial CueSheet section name finally matches a real tool. Header gains a tungsten create_cue_list(...) callout, subtitle naming the new tools. AiConversation's final exchange is the headline cue-list flow (build + GO). New FAQ entry. Tool catalog renders 48.

Roadmap status

1 of 4 Tier 3 items complete:

  • ✅ #8 cue lists (this — repurposed scope)
  • ⏳ #10 SSE event stream
  • ⏳ #11 multi-workspace switching
  • ⏳ #12 audio-reactive mode
Assets 2
Loading