Files
qlcplus/showfile/spec.py
T

874 lines
39 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""JSON show spec: schema, validation, and Show.from_spec."""
from __future__ import annotations
import json
from pathlib import Path
from typing import Any
from patternstudio.efx import ALGORITHMS, DIRECTIONS, PROPAGATIONS, RUN_ORDERS
from patternstudio.fixturedefs import FixtureLibrary
from .model import ArtNetOutput, MidiBinding, MidiInput, Show, midi_cc, midi_note
PROJECT_ROOT = Path(__file__).resolve().parents[1]
class SpecError(Exception):
def __init__(self, errors: list[dict[str, str]]):
self.errors = errors
detail = "; ".join(f"{item['path']}: {item['message']}" for item in errors)
super().__init__(detail or "invalid show spec")
def show_schema() -> dict[str, Any]:
"""JSON Schema for the document accepted by validate_show and write_show."""
return {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "qlcplus://show",
"title": "QLC+ show",
"type": "object",
"description": (
"A QLC+ workspace. Fixture, function, and widget ids are assigned on write. "
"Refer to fixtures and functions by their string keys. Channel numbers come from list_fixtures. "
"Addresses are 0-based, matching QLC+ (address 87 is DMX channel 88). "
"Set stage to a stage map path to patch that rig; fixture keys are the map ids."
),
"properties": {
"stage": {
"type": "string",
"description": "Stage map inside the project, for example stage/map.json. Patches every fixture before fixtures.",
},
"author": {"type": "string"},
"vc_size": {
"type": "array",
"items": {"type": "integer"},
"minItems": 2,
"maxItems": 2,
"description": "Virtual console width and height. Omitted means fit the widgets plus a 16px margin.",
},
"run": {
"type": "array",
"items": {"type": "string"},
"description": "Function keys to play when the show is run as a script. Defaults to every top-level function.",
},
"universes": {"type": "array", "items": {"$ref": "#/$defs/universe"}},
"fixtures": {"type": "array", "items": {"$ref": "#/$defs/fixture"}},
"groups": {"type": "array", "items": {"$ref": "#/$defs/group"}},
"functions": {"type": "array", "items": {"$ref": "#/$defs/function"}},
"vc": {"type": "array", "items": {"$ref": "#/$defs/widget"}},
},
"$defs": {
"universe": {
"type": "object",
"required": ["id"],
"properties": {
"id": {"type": "integer", "minimum": 0},
"name": {"type": "string"},
"output": {
"type": "object",
"required": ["uid", "ip"],
"properties": {
"plugin": {"const": "ArtNet"},
"uid": {"type": "string"},
"ip": {"type": "string"},
"universe": {"type": "integer"},
"line": {"type": "integer"},
},
},
"input": {
"type": "object",
"required": ["uid", "profile"],
"properties": {
"plugin": {"const": "MIDI"},
"uid": {"type": "string"},
"profile": {"type": "string"},
"channel": {"type": "integer", "description": "QLC+ MIDI plugin channel. 16 is omni."},
"line": {"type": "integer"},
},
},
},
},
"fixture": {
"type": "object",
"required": ["key", "manufacturer", "model", "mode", "address"],
"properties": {
"key": {"type": "string"},
"manufacturer": {"type": "string"},
"model": {"type": "string"},
"mode": {"type": "string"},
"name": {"type": "string"},
"universe": {"type": "integer"},
"address": {"type": "integer", "minimum": 0},
"channels": {"type": "integer", "minimum": 1, "description": "Required only when the fixture is not in the library."},
},
},
"group": {
"type": "object",
"required": ["name", "fixtures"],
"properties": {
"name": {"type": "string"},
"fixtures": {"type": "array", "items": {"type": "string"}},
"columns": {"type": "integer", "minimum": 1},
},
},
"function": {
"type": "object",
"required": ["key", "type", "name"],
"description": "type is scene, efx, sequence, path, chaser, colour_chase, or collection.",
"properties": {
"key": {"type": "string"},
"type": {"enum": ["scene", "efx", "sequence", "path", "chaser", "colour_chase", "collection"]},
"name": {"type": "string"},
},
},
"widget": {
"type": "object",
"required": ["type", "caption", "x", "y", "w", "h"],
"properties": {
"type": {"enum": ["slider", "button", "xypad", "frame", "solo"]},
"caption": {"type": "string"},
"x": {"type": "integer"},
"y": {"type": "integer"},
"w": {"type": "integer"},
"h": {"type": "integer"},
"pages": {"type": "integer", "minimum": 1, "description": "Frame only. More than 1 makes it a multipage frame."},
"loop": {"type": "boolean", "description": "Frame only. Next page after the last wraps to the first."},
"page": {"type": "integer", "minimum": 0, "description": "Frame inside a multipage frame: which page it is on, from 0."},
"fg": {"$ref": "#/$defs/colour"},
"bg": {"$ref": "#/$defs/colour"},
"function": {"type": "string", "description": "Function key for a button."},
"fixture": {"type": "string", "description": "Fixture key for an XY pad."},
"channels": {
"type": "array",
"items": {
"type": "array",
"prefixItems": [{"type": "string"}, {"type": "integer"}],
"minItems": 2,
"maxItems": 2,
},
},
"input": {
"type": "object",
"properties": {
"universe": {"type": "integer"},
"note": {"type": "array", "items": {"type": "integer"}, "minItems": 2, "maxItems": 2},
"cc": {"type": "array", "items": {"type": "integer"}, "minItems": 2, "maxItems": 2},
"channel": {"type": "integer"},
},
},
},
},
"colour": {
"description": "[r, g, b], or the string Default, or a QLC+ ARGB decimal.",
"oneOf": [
{"type": "array", "items": {"type": "integer"}, "minItems": 3, "maxItems": 3},
{"type": "string"},
{"type": "integer"},
],
},
},
}
def validate(data: Any, *, root: Path | None = None) -> None:
errors = collect_errors(data, root=root)
if errors:
raise SpecError(errors)
def collect_errors(data: Any, *, root: Path | None = None) -> list[dict[str, str]]:
errors: list[dict[str, str]] = []
if not isinstance(data, dict):
return [{"path": "", "message": "show spec must be an object"}]
project = root or PROJECT_ROOT
library = FixtureLibrary(project)
_check_universes(data.get("universes", []), errors)
fixtures = _check_stage(data.get("stage", None), project, library, errors)
for key, info in _check_fixtures(data.get("fixtures", []), library, errors).items():
if key in fixtures:
_err(errors, f"fixtures.{key}", "duplicate fixture key")
else:
fixtures[key] = info
keys = set(fixtures)
_check_groups(data.get("groups", []), keys, errors)
functions = data.get("functions", [])
fn_keys = _check_functions(functions, fixtures, errors)
_check_widgets(data.get("vc", []), keys, fn_keys, fixtures, errors, "vc")
run = data.get("run", [])
if run is not None and not isinstance(run, list):
_err(errors, "run", "must be a list of function keys")
elif isinstance(run, list):
for index, key in enumerate(run):
if key not in fn_keys:
_err(errors, f"run.{index}", f"unknown function {key!r}")
if "vc_size" in data:
size = data["vc_size"]
if not (isinstance(size, list) and len(size) == 2 and all(isinstance(n, int) for n in size)):
_err(errors, "vc_size", "must be [width, height]")
return errors
def from_spec(data: dict[str, Any], *, root: Path | None = None) -> Show:
validate(data, root=root)
try:
return _build(data, root=root)
except SpecError:
raise
except (ValueError, KeyError) as exc:
raise SpecError([{"path": "", "message": str(exc)}]) from exc
def _build(data: dict[str, Any], *, root: Path | None) -> Show:
show = Show(author=str(data.get("author") or "Jimmy"), root=root)
if "vc_size" in data:
show.vc_size = (int(data["vc_size"][0]), int(data["vc_size"][1]))
universes = data.get("universes")
if not universes:
for index in range(4):
show.universe(index, f"Universe {index + 1}")
else:
for uni in universes:
output = None
midi = None
if uni.get("output"):
out = uni["output"]
output = ArtNetOutput(
uid=str(out["uid"]),
ip=str(out["ip"]),
universe=int(out.get("universe", 0)),
line=int(out.get("line", 0)),
)
if uni.get("input"):
inp = uni["input"]
midi = MidiInput(
uid=str(inp["uid"]),
profile=str(inp["profile"]),
channel=int(inp.get("channel", 0)),
line=int(inp.get("line", 0)),
)
show.universe(int(uni["id"]), uni.get("name"), output=output, midi=midi)
if data.get("stage"):
show.patch_stage(data["stage"])
for fx in data.get("fixtures", []):
show.patch(
fx["manufacturer"],
fx["model"],
fx["mode"],
address=int(fx["address"]),
name=fx.get("name"),
universe=int(fx.get("universe", 0)),
channels=int(fx["channels"]) if "channels" in fx else None,
key=fx["key"],
)
for group in data.get("groups", []):
show.group(group["name"], list(group["fixtures"]), columns=group.get("columns"))
pending = []
for fn in data.get("functions", []):
if fn["type"] in ("chaser", "collection"):
pending.append(fn)
else:
_add_function(show, fn)
while pending:
ready = [fn for fn in pending if _refs_ready(show, fn)]
if not ready:
missing = pending[0]
raise SpecError([{"path": f"functions.{missing['key']}", "message": "references a function that is not defined"}])
for fn in ready:
_add_function(show, fn)
pending = [fn for fn in pending if fn not in ready]
_add_widgets(show, show.vc, data.get("vc", []))
if data.get("run"):
show.run(*data["run"])
return show
Show.from_spec = staticmethod(from_spec) # type: ignore[method-assign]
def _refs_ready(show: Show, fn: dict[str, Any]) -> bool:
if fn["type"] == "collection":
return all(key in show.functions_by_key for key in fn.get("members", []))
return all(step["function"] in show.functions_by_key for step in fn.get("steps", []))
def _add_function(show: Show, fn: dict[str, Any]) -> None:
kind = fn["type"]
key = fn["key"]
name = fn["name"]
if kind == "scene":
show.scene(name, fn.get("values") or {}, key=key, fade_in=int(fn.get("fade_in", 0)), fade_out=int(fn.get("fade_out", 0)), duration=int(fn.get("duration", 0)))
elif kind == "efx":
show.efx(name, fn.get("fixtures") or [], key=key, **_efx_kwargs(fn))
elif kind == "sequence":
show.sequence(name, fn.get("steps") or [], key=key, direction=fn.get("direction", "Forward"), run_order=fn.get("run_order", "Loop"))
elif kind == "path":
show.path_sequence(
name,
fn.get("fixtures") or [],
fn.get("points") or [],
key=key,
smooth=bool(fn.get("smooth", False)),
subdivisions=int(fn.get("subdivisions", 6)),
closed=bool(fn.get("closed", True)),
direction=fn.get("direction", "Forward"),
run_order=fn.get("run_order", "Loop"),
)
elif kind == "colour_chase":
show.colour_chase(
name,
fn.get("fixtures") or [],
fn.get("channels") or {},
fn.get("frames") or [],
key=key,
fade_ms=int(fn.get("fade_ms", 0)),
hold_ms=int(fn.get("hold_ms", 0)),
run_order=fn.get("run_order", "Loop"),
)
elif kind == "chaser":
show.chaser(name, fn.get("steps") or [], key=key, direction=fn.get("direction", "Forward"), run_order=fn.get("run_order", "Loop"))
elif kind == "collection":
show.collection(name, list(fn.get("members") or []), key=key)
def _efx_kwargs(fn: dict[str, Any]) -> dict[str, Any]:
fields = (
"algorithm", "width", "height", "rotation", "start_offset",
"x_offset", "y_offset", "x_frequency", "y_frequency", "x_phase", "y_phase",
"duration_ms", "fade_in_ms", "fade_out_ms", "direction", "run_order", "propagation",
"relative", "homes",
)
return {field: fn[field] for field in fields if field in fn}
def _add_widgets(show: Show, frame: Any, widgets: list[dict[str, Any]]) -> None:
for widget in widgets:
kind = widget["type"]
box = dict(x=int(widget["x"]), y=int(widget["y"]), w=int(widget["w"]), h=int(widget["h"]))
binding = _binding(widget["input"]) if widget.get("input") else None
if kind == "slider":
frame.slider(
widget["caption"],
[(pair[0], int(pair[1])) for pair in widget.get("channels", [])],
value=int(widget.get("value", 0)),
fg=widget.get("fg", "Default"),
cng=str(widget.get("cng", "None")),
inverted=bool(widget.get("inverted", False)),
input=binding,
function=widget.get("function"),
**box,
)
elif kind == "button":
frame.button(
widget["caption"],
widget["function"],
fg=widget.get("fg", "4294967295"),
bg=widget.get("bg", "Default"),
action=str(widget.get("action", "Toggle")),
input=binding,
**box,
)
elif kind == "xypad":
frame.xypad(
widget["caption"],
widget["fixture"],
reverse_pan=bool(widget.get("reverse_pan", False)),
reverse_tilt=bool(widget.get("reverse_tilt", False)),
pan=int(widget.get("pan", 128)),
tilt=int(widget.get("tilt", 128)),
input=binding,
**box,
)
else:
child = frame.frame(
widget["caption"],
solo=kind == "solo" or bool(widget.get("solo", False)),
header=bool(widget.get("header", True)),
pages=int(widget.get("pages", 1)),
loop=bool(widget.get("loop", False)),
page=int(widget.get("page", 0)),
**box,
)
_add_widgets(show, child, widget.get("children") or [])
def _binding(raw: dict[str, Any]) -> MidiBinding:
if "channel" in raw:
channel = int(raw["channel"])
elif "note" in raw:
channel = midi_note(int(raw["note"][0]), int(raw["note"][1]))
else:
channel = midi_cc(int(raw["cc"][0]), int(raw["cc"][1]))
return MidiBinding(int(raw["universe"]), channel)
def _check_universes(universes: Any, errors: list[dict[str, str]]) -> None:
if not isinstance(universes, list):
_err(errors, "universes", "must be a list")
return
for index, uni in enumerate(universes):
path = f"universes.{index}"
if not isinstance(uni, dict) or not isinstance(uni.get("id"), int):
_err(errors, path, "must be an object with an integer id")
continue
output = uni.get("output")
if output is not None:
if not isinstance(output, dict) or "uid" not in output or "ip" not in output:
_err(errors, f"{path}.output", "Art-Net output needs uid and ip")
midi = uni.get("input")
if midi is not None:
if not isinstance(midi, dict) or "uid" not in midi or "profile" not in midi:
_err(errors, f"{path}.input", "MIDI input needs uid and profile")
def _check_stage(
stage: Any,
root: Path,
library: FixtureLibrary,
errors: list[dict[str, str]],
) -> dict[str, dict[str, Any]]:
found: dict[str, dict[str, Any]] = {}
if stage is None:
return found
if not isinstance(stage, str) or not stage.strip():
_err(errors, "stage", "must be a path to a stage map")
return found
target = _stage_file(stage, root, errors)
if target is None:
return found
try:
document = json.loads(target.read_text(encoding="utf-8"))
except json.JSONDecodeError as exc:
_err(errors, "stage", f"invalid JSON: {exc}")
return found
if not isinstance(document, dict):
_err(errors, "stage", "stage map must be an object")
return found
definitions = document.get("definitions")
fixtures = document.get("fixtures")
if not isinstance(definitions, dict) or not isinstance(fixtures, dict):
_err(errors, "stage", "stage map needs definitions and fixtures")
return found
for key, raw in fixtures.items():
path = f"stage.fixtures.{key}"
if not isinstance(raw, dict):
_err(errors, path, "must be an object")
continue
defin = definitions.get(raw.get("def"))
if not isinstance(defin, dict):
_err(errors, f"{path}.def", "unknown definition")
continue
if not isinstance(raw.get("address"), int) or raw["address"] < 0:
_err(errors, f"{path}.address", "must be an address of 0 or more")
continue
manufacturer = defin.get("manufacturer")
model = defin.get("model")
mode = defin.get("mode")
if not all(isinstance(item, str) and item for item in (manufacturer, model, mode)):
_err(errors, f"{path}.def", "definition needs manufacturer, model, and mode")
continue
definition = library.find(manufacturer, model)
mode_info = definition.mode(mode) if definition is not None else None
if mode_info is None:
_err(errors, path, f"unknown fixture {manufacturer} {model} mode {mode!r}")
continue
count = len(mode_info.channels)
if raw["address"] + count > 512:
_err(errors, f"{path}.address", "fixture extends past DMX channel 512")
if key in found:
_err(errors, path, "duplicate fixture key")
continue
found[key] = {"channels": count, "mover": mode_info.is_mover}
return found
def _stage_file(stage: str, root: Path, errors: list[dict[str, str]]) -> Path | None:
candidate = Path(stage)
base = root.resolve()
target = candidate.resolve() if candidate.is_absolute() else (base / candidate).resolve()
if target != base and base not in target.parents:
_err(errors, "stage", f"{stage} is outside the project")
return None
if not target.is_file():
_err(errors, "stage", f"stage map not found: {stage}")
return None
return target
def _check_fixtures(fixtures: Any, library: FixtureLibrary, errors: list[dict[str, str]]) -> dict[str, dict[str, Any]]:
found: dict[str, dict[str, Any]] = {}
if not isinstance(fixtures, list):
_err(errors, "fixtures", "must be a list")
return found
for index, fx in enumerate(fixtures):
path = f"fixtures.{index}"
if not isinstance(fx, dict):
_err(errors, path, "must be an object")
continue
key = fx.get("key")
if not isinstance(key, str) or not key:
_err(errors, f"{path}.key", "must be a non-empty string")
continue
path = f"fixtures.{key}"
if key in found:
_err(errors, path, "duplicate fixture key")
continue
for field in ("manufacturer", "model", "mode"):
if not isinstance(fx.get(field), str) or not fx[field]:
_err(errors, f"{path}.{field}", "must be a non-empty string")
if not isinstance(fx.get("address"), int) or fx["address"] < 0:
_err(errors, f"{path}.address", "must be an address of 0 or more")
continue
definition = None
if isinstance(fx.get("manufacturer"), str) and isinstance(fx.get("model"), str):
definition = library.find(fx["manufacturer"], fx["model"])
mode_info = definition.mode(fx["mode"]) if definition is not None and isinstance(fx.get("mode"), str) else None
if definition is None and "channels" not in fx:
_err(errors, path, "unknown fixture; add it under fixtures/ or set channels")
elif definition is not None and mode_info is None:
_err(errors, f"{path}.mode", f"unknown mode {fx.get('mode')!r}")
count = None
if mode_info is not None:
count = len(mode_info.channels)
if "channels" in fx and fx["channels"] != count:
_err(errors, f"{path}.channels", f"mode {fx['mode']} has {count} channels")
elif isinstance(fx.get("channels"), int) and fx["channels"] > 0:
count = fx["channels"]
elif "channels" in fx:
_err(errors, f"{path}.channels", "must be a positive integer")
if count is not None and fx["address"] + count > 512:
_err(errors, f"{path}.address", "fixture extends past DMX channel 512")
mover = bool(mode_info and mode_info.pan_msb is not None and mode_info.tilt_msb is not None)
found[key] = {"channels": count or 0, "mover": mover}
return found
def _check_groups(groups: Any, fixtures: set[str], errors: list[dict[str, str]]) -> None:
if not isinstance(groups, list):
_err(errors, "groups", "must be a list")
return
for index, group in enumerate(groups):
path = f"groups.{index}"
if not isinstance(group, dict) or not isinstance(group.get("name"), str):
_err(errors, path, "must be an object with a name")
continue
members = group.get("fixtures")
if not isinstance(members, list) or not members:
_err(errors, f"{path}.fixtures", "must list fixture keys")
continue
for member in members:
if member not in fixtures:
_err(errors, f"{path}.fixtures", f"unknown fixture {member!r}")
def _check_functions(
functions: Any,
fixtures: dict[str, dict[str, Any]],
errors: list[dict[str, str]],
) -> set[str]:
keys: set[str] = set()
if not isinstance(functions, list):
_err(errors, "functions", "must be a list")
return keys
for index, fn in enumerate(functions):
path = f"functions.{index}"
if not isinstance(fn, dict):
_err(errors, path, "must be an object")
continue
key = fn.get("key")
if not isinstance(key, str) or not key:
_err(errors, f"{path}.key", "must be a non-empty string")
continue
path = f"functions.{key}"
if key in keys:
_err(errors, path, "duplicate function key")
continue
keys.add(key)
kind = fn.get("type")
if kind not in ("scene", "efx", "sequence", "path", "chaser", "colour_chase", "collection"):
_err(errors, f"{path}.type", "must be scene, efx, sequence, path, chaser, colour_chase, or collection")
continue
if not isinstance(fn.get("name"), str) or not fn["name"]:
_err(errors, f"{path}.name", "must be a non-empty string")
if kind == "scene":
_check_values(fn.get("values") or {}, fixtures, errors, f"{path}.values")
elif kind == "efx":
_check_efx(fn, fixtures, errors, path)
elif kind == "sequence":
_check_sequence(fn, fixtures, errors, path)
elif kind == "path":
_check_path(fn, fixtures, errors, path)
elif kind == "colour_chase":
_check_chase(fn, fixtures, errors, path)
elif kind == "chaser":
_check_chaser_steps(fn.get("steps"), errors, path)
elif kind == "collection":
members = fn.get("members")
if not isinstance(members, list) or not members:
_err(errors, f"{path}.members", "must list function keys")
for fn in functions if isinstance(functions, list) else []:
if not isinstance(fn, dict) or fn.get("type") not in ("chaser", "collection"):
continue
path = f"functions.{fn.get('key')}"
if fn["type"] == "collection":
for member in fn.get("members") or []:
if member not in keys:
_err(errors, f"{path}.members", f"unknown function {member!r}")
else:
for index, step in enumerate(fn.get("steps") or []):
if isinstance(step, dict) and step.get("function") not in keys:
_err(errors, f"{path}.steps.{index}.function", f"unknown function {step.get('function')!r}")
return keys
def _check_values(values: Any, fixtures: dict[str, dict[str, Any]], errors: list[dict[str, str]], path: str) -> None:
if not isinstance(values, dict):
_err(errors, path, "must map fixture keys to channel values")
return
for key, channels in values.items():
if key not in fixtures:
_err(errors, f"{path}.{key}", f"unknown fixture {key!r}")
continue
if not isinstance(channels, dict):
_err(errors, f"{path}.{key}", "must map channel numbers to values")
continue
count = fixtures[key]["channels"]
for ch, val in channels.items():
try:
index = int(ch)
number = int(val)
except (TypeError, ValueError):
_err(errors, f"{path}.{key}.{ch}", "channel and value must be integers")
continue
if count and not 0 <= index < count:
_err(errors, f"{path}.{key}.{ch}", f"channel {index} is outside 0–{count - 1}")
if not 0 <= number <= 255:
_err(errors, f"{path}.{key}.{ch}", "value must be 0–255")
def _check_efx(fn: dict[str, Any], fixtures: dict[str, dict[str, Any]], errors: list[dict[str, str]], path: str) -> None:
entries = fn.get("fixtures")
if not isinstance(entries, list) or not entries:
_err(errors, f"{path}.fixtures", "must list fixture keys")
return
for item in entries:
key = item if isinstance(item, str) else item.get("fixture") if isinstance(item, dict) else None
if key not in fixtures:
_err(errors, f"{path}.fixtures", f"unknown fixture {key!r}")
elif not fixtures[key]["mover"]:
_err(errors, f"{path}.fixtures", f"{key} has no pan/tilt in this mode")
algorithm = fn.get("algorithm", "Circle")
if algorithm not in ALGORITHMS:
_err(errors, f"{path}.algorithm", f"must be one of {', '.join(ALGORITHMS)}")
_choice(errors, fn, "direction", DIRECTIONS, path, "Forward")
_choice(errors, fn, "run_order", RUN_ORDERS, path, "Loop")
_choice(errors, fn, "propagation", PROPAGATIONS, path, "Parallel")
_range(errors, fn, "width", 0, 127, path)
_range(errors, fn, "height", 0, 127, path)
_range(errors, fn, "x_offset", 0, 255, path)
_range(errors, fn, "y_offset", 0, 255, path)
_range(errors, fn, "x_frequency", 0, 5, path)
_range(errors, fn, "y_frequency", 0, 5, path)
if "duration_ms" in fn and (not isinstance(fn["duration_ms"], int) or fn["duration_ms"] < 20):
_err(errors, f"{path}.duration_ms", "must be at least 20")
homes = fn.get("homes") or {}
if homes and not isinstance(homes, dict):
_err(errors, f"{path}.homes", "must map fixture keys to [pan, tilt]")
elif isinstance(homes, dict):
for key, home in homes.items():
if key not in fixtures:
_err(errors, f"{path}.homes.{key}", f"unknown fixture {key!r}")
elif not (isinstance(home, list) and len(home) == 2 and all(isinstance(n, int) and 0 <= n <= 255 for n in home)):
_err(errors, f"{path}.homes.{key}", "must be [pan, tilt] in 0–255")
def _check_sequence(fn: dict[str, Any], fixtures: dict[str, dict[str, Any]], errors: list[dict[str, str]], path: str) -> None:
steps = fn.get("steps")
if not isinstance(steps, list) or not steps:
_err(errors, f"{path}.steps", "must be a list of steps")
return
_choice(errors, fn, "direction", DIRECTIONS, path, "Forward")
_choice(errors, fn, "run_order", RUN_ORDERS, path, "Loop")
for index, step in enumerate(steps):
if not isinstance(step, dict):
_err(errors, f"{path}.steps.{index}", "must be an object")
continue
_check_values(step.get("values") or {}, fixtures, errors, f"{path}.steps.{index}.values")
for field in ("fade_ms", "hold_ms", "fade_out_ms"):
if field in step and (not isinstance(step[field], int) or step[field] < 0):
_err(errors, f"{path}.steps.{index}.{field}", "must be 0 or more")
def _check_path(fn: dict[str, Any], fixtures: dict[str, dict[str, Any]], errors: list[dict[str, str]], path: str) -> None:
entries = fn.get("fixtures")
points = fn.get("points")
if not isinstance(entries, list) or not entries:
_err(errors, f"{path}.fixtures", "must list fixtures")
else:
for item in entries:
key = item if isinstance(item, str) else item.get("fixture") if isinstance(item, dict) else None
if key not in fixtures:
_err(errors, f"{path}.fixtures", f"unknown fixture {key!r}")
elif not fixtures[key]["mover"]:
_err(errors, f"{path}.fixtures", f"{key} has no pan/tilt in this mode")
if not isinstance(points, list) or not points:
_err(errors, f"{path}.points", "must list pan/tilt points")
else:
for index, point in enumerate(points):
if not isinstance(point, dict) or "pan" not in point or "tilt" not in point:
_err(errors, f"{path}.points.{index}", "must have pan and tilt")
_choice(errors, fn, "direction", DIRECTIONS, path, "Forward")
_choice(errors, fn, "run_order", RUN_ORDERS, path, "Loop")
def _check_chase(fn: dict[str, Any], fixtures: dict[str, dict[str, Any]], errors: list[dict[str, str]], path: str) -> None:
members = fn.get("fixtures")
frames = fn.get("frames")
channels = fn.get("channels")
if not isinstance(members, list) or not members:
_err(errors, f"{path}.fixtures", "must list fixture keys")
members = []
else:
for key in members:
if key not in fixtures:
_err(errors, f"{path}.fixtures", f"unknown fixture {key!r}")
if not isinstance(channels, dict) or not channels:
_err(errors, f"{path}.channels", "must map names such as r, g, b to channel numbers")
channels = {}
if not isinstance(frames, list) or not frames:
_err(errors, f"{path}.frames", "must list colour frames")
return
for index, frame in enumerate(frames):
if not isinstance(frame, list) or len(frame) != len(members):
_err(errors, f"{path}.frames.{index}", f"must have one colour for each of {len(members)} fixtures")
continue
for colour in frame:
if isinstance(colour, dict):
continue
if not isinstance(colour, list) or len(colour) != len(channels):
_err(errors, f"{path}.frames.{index}", f"colour must have {len(channels)} values")
break
if any(not isinstance(n, int) or not 0 <= n <= 255 for n in colour):
_err(errors, f"{path}.frames.{index}", "colour values must be 0–255")
def _check_chaser_steps(steps: Any, errors: list[dict[str, str]], path: str) -> None:
if not isinstance(steps, list) or not steps:
_err(errors, f"{path}.steps", "must list steps")
return
for index, step in enumerate(steps):
if not isinstance(step, dict) or not isinstance(step.get("function"), str):
_err(errors, f"{path}.steps.{index}.function", "must name a function key")
for field in ("fade_ms", "hold_ms", "fade_out_ms"):
if isinstance(step, dict) and field in step and (not isinstance(step[field], int) or step[field] < 0):
_err(errors, f"{path}.steps.{index}.{field}", "must be 0 or more")
def _check_widgets(
widgets: Any,
fixtures: set[str],
functions: set[str],
fixture_info: dict[str, dict[str, Any]],
errors: list[dict[str, str]],
path: str,
) -> None:
if not isinstance(widgets, list):
_err(errors, path, "must be a list")
return
for index, widget in enumerate(widgets):
here = f"{path}.{index}"
if not isinstance(widget, dict):
_err(errors, here, "must be an object")
continue
kind = widget.get("type")
if kind not in ("slider", "button", "xypad", "frame", "solo"):
_err(errors, f"{here}.type", "must be slider, button, xypad, frame, or solo")
continue
if not isinstance(widget.get("caption"), str):
_err(errors, f"{here}.caption", "must be a string")
for field in ("x", "y", "w", "h"):
if not isinstance(widget.get(field), int):
_err(errors, f"{here}.{field}", "must be an integer")
if kind == "slider":
channels = widget.get("channels")
if "function" in widget:
if widget["function"] not in functions:
_err(errors, f"{here}.function", f"unknown function {widget['function']!r}")
channels = []
elif not isinstance(channels, list) or not channels:
_err(errors, f"{here}.channels", "must list [fixture, channel] pairs")
else:
for pair in channels:
if not (isinstance(pair, list) and len(pair) == 2 and isinstance(pair[1], int)):
_err(errors, f"{here}.channels", "each entry is [fixture key, channel]")
continue
if pair[0] not in fixtures:
_err(errors, f"{here}.channels", f"unknown fixture {pair[0]!r}")
elif fixture_info[pair[0]]["channels"] and not 0 <= pair[1] < fixture_info[pair[0]]["channels"]:
_err(errors, f"{here}.channels", f"channel {pair[1]} is outside {pair[0]}")
elif kind == "button":
if widget.get("function") not in functions:
_err(errors, f"{here}.function", f"unknown function {widget.get('function')!r}")
if "action" in widget and widget["action"] not in ("Toggle", "Flash"):
_err(errors, f"{here}.action", "must be Toggle or Flash")
elif kind == "xypad":
if widget.get("fixture") not in fixtures:
_err(errors, f"{here}.fixture", f"unknown fixture {widget.get('fixture')!r}")
elif not fixture_info[widget["fixture"]]["mover"]:
_err(errors, f"{here}.fixture", f"{widget['fixture']} has no pan/tilt in this mode")
else:
_check_widgets(widget.get("children") or [], fixtures, functions, fixture_info, errors, f"{here}.children")
if "input" in widget:
_check_input(widget["input"], errors, f"{here}.input")
for field in ("fg", "bg"):
if field in widget:
_check_colour(widget[field], errors, f"{here}.{field}")
def _check_input(raw: Any, errors: list[dict[str, str]], path: str) -> None:
if not isinstance(raw, dict) or not isinstance(raw.get("universe"), int):
_err(errors, path, "must have a universe")
return
kinds = [name for name in ("note", "cc", "channel") if name in raw]
if len(kinds) != 1:
_err(errors, path, "set one of note, cc, or channel")
return
if "note" in raw:
pair = raw["note"]
if not (isinstance(pair, list) and len(pair) == 2 and all(isinstance(n, int) for n in pair)):
_err(errors, f"{path}.note", "must be [channel 0–15, note 0–127]")
elif not 0 <= pair[0] <= 15 or not 0 <= pair[1] <= 127:
_err(errors, f"{path}.note", "must be [channel 0–15, note 0–127]")
elif "cc" in raw:
pair = raw["cc"]
if not (isinstance(pair, list) and len(pair) == 2 and all(isinstance(n, int) for n in pair)):
_err(errors, f"{path}.cc", "must be [channel 0–15, cc 0–127]")
elif not 0 <= pair[0] <= 15 or not 0 <= pair[1] <= 127:
_err(errors, f"{path}.cc", "must be [channel 0–15, cc 0–127]")
def _check_colour(value: Any, errors: list[dict[str, str]], path: str) -> None:
if isinstance(value, str) or isinstance(value, int):
return
if isinstance(value, list) and len(value) == 3 and all(isinstance(n, int) and 0 <= n <= 255 for n in value):
return
_err(errors, path, "must be [r, g, b], Default, or an ARGB decimal")
def _choice(errors: list[dict[str, str]], fn: dict[str, Any], field: str, allowed: tuple[str, ...], path: str, default: str) -> None:
value = fn.get(field, default)
if value not in allowed:
_err(errors, f"{path}.{field}", f"must be one of {', '.join(allowed)}")
def _range(errors: list[dict[str, str]], fn: dict[str, Any], field: str, lo: int, hi: int, path: str) -> None:
if field not in fn:
return
value = fn[field]
if not isinstance(value, int) or not lo <= value <= hi:
_err(errors, f"{path}.{field}", f"must be {lo}–{hi}")
def _err(errors: list[dict[str, str]], path: str, message: str) -> None:
errors.append({"path": path, "message": message})