diff --git a/.cursor/mcp.json b/.cursor/mcp.json new file mode 100644 index 0000000..c39c531 --- /dev/null +++ b/.cursor/mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "qlcplus-show": { + "command": "python3", + "args": ["-m", "showfile.mcp"] + } + } +} diff --git a/showfile/__init__.py b/showfile/__init__.py new file mode 100644 index 0000000..be1f04d --- /dev/null +++ b/showfile/__init__.py @@ -0,0 +1,23 @@ +"""Build QLC+ workspaces and play their animations.""" + +from .model import ArtNetOutput, MidiBinding, MidiInput, Show, midi_cc, midi_note +from .play import frame_at, play +from .spec import SpecError, from_spec, show_schema +from .xmlutil import qlc_color + +Show.from_spec = staticmethod(from_spec) # type: ignore[method-assign] + +__all__ = [ + "ArtNetOutput", + "MidiBinding", + "MidiInput", + "Show", + "SpecError", + "frame_at", + "from_spec", + "midi_cc", + "midi_note", + "play", + "qlc_color", + "show_schema", +] diff --git a/showfile/__main__.py b/showfile/__main__.py new file mode 100644 index 0000000..d5eebfe --- /dev/null +++ b/showfile/__main__.py @@ -0,0 +1,74 @@ +"""Command line for the show tools. Each command prints one JSON object.""" + +from __future__ import annotations + +import argparse +import json +import sys +from pathlib import Path +from typing import Any + +from .spec import PROJECT_ROOT +from .tools import list_fixtures, run_script, sample_animation, show_schema, validate_show, write_show + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser(prog="showfile", description="Build and test QLC+ shows.") + sub = parser.add_subparsers(dest="cmd", required=True) + + sub.add_parser("list-fixtures", help="List fixture modes and channel numbers.") + sub.add_parser("schema", help="Print the show spec JSON Schema.") + + validate = sub.add_parser("validate", help="Validate a show spec without writing.") + validate.add_argument("spec") + + write = sub.add_parser("write", help="Compile a show spec to a .qxw.") + write.add_argument("spec") + write.add_argument("-o", "--output", required=True) + + sample = sub.add_parser("sample", help="Sample an efx or path block.") + sample.add_argument("block") + sample.add_argument("--steps", type=int, default=32) + + run = sub.add_parser("run", help="Play a Python animation script or a JSON show.") + run.add_argument("script") + run.add_argument("--ip", help="Art-Net destination. Omit to print samples.") + run.add_argument("--seconds", type=float) + run.add_argument("--hz", type=float, default=40.0) + run.add_argument("--universe", type=int, default=0) + + args = parser.parse_args(argv) + try: + payload = _dispatch(args) + except (OSError, json.JSONDecodeError) as exc: + payload = {"ok": False, "errors": [{"path": "", "message": str(exc)}]} + json.dump(payload, sys.stdout, indent=2) + sys.stdout.write("\n") + return 0 if payload.get("ok", True) else 1 + + +def _dispatch(args: argparse.Namespace) -> dict[str, Any]: + if args.cmd == "list-fixtures": + return list_fixtures() + if args.cmd == "schema": + return show_schema() + if args.cmd == "validate": + return validate_show(_load(args.spec)) + if args.cmd == "write": + return write_show(_load(args.spec), args.output) + if args.cmd == "sample": + return sample_animation(_load(args.block), args.steps) + if args.cmd == "run": + return run_script(args.script, seconds=args.seconds, ip=args.ip, universe=args.universe, hz=args.hz) + raise AssertionError(args.cmd) + + +def _load(path: str) -> dict[str, Any]: + source = Path(path) + if not source.is_absolute(): + source = PROJECT_ROOT / source + return json.loads(source.read_text(encoding="utf-8")) + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/showfile/animate.py b/showfile/animate.py new file mode 100644 index 0000000..a10764d --- /dev/null +++ b/showfile/animate.py @@ -0,0 +1,666 @@ +"""EFX, sequences, paths, and chasers.""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import Any + +from patternstudio.efx import ( + ALGORITHMS, + DIRECTIONS, + PROPAGATIONS, + RELATIVE_ZERO, + RUN_ORDERS, + Efx, + EfxFixture, + Path, + PathFixture, + PathPoint, + clamp8, +) + +from .model import Show, blend_maps +from .xmlutil import attr + +Axis = tuple[int | None, int | None, int | None, int | None] + + +def locate( + steps: list[Any], + elapsed_ms: float, + run_order: str, + direction: str, +) -> tuple[int, float, int | None, float]: + """Return step index, fade progress, previous index, and ms into the step. + + A looping timeline treats the last step as the fade source for the first, + so a loop is seamless. Single Shot fades the first step up from black and + holds the last step after the end. + """ + spans = [max(0, s.fade_ms) + max(0, s.hold_ms) + max(0, s.fade_out_ms) for s in steps] + total = float(sum(spans)) + count = len(steps) + if count == 0 or total <= 0: + return 0, 1.0, None, 0.0 + elapsed = max(0.0, float(elapsed_ms)) + seamless = run_order != "SingleShot" + if run_order == "SingleShot" and elapsed >= total: + prev = count - 2 if count > 1 else None + return count - 1, 1.0, prev, spans[-1] + if run_order == "PingPong": + cycle = int(elapsed // total) + pos = elapsed % total + if cycle % 2 == 1: + pos = total - pos + elif run_order == "SingleShot": + pos = elapsed + else: + pos = elapsed % total + if direction == "Backward": + pos = total - pos + if pos >= total: + pos = total - 1e-6 + if pos < 0: + pos = 0.0 + acc = 0.0 + for index, span in enumerate(spans): + fade = max(0, steps[index].fade_ms) + prev = None if index == 0 and not seamless else (index - 1) % count + if pos < acc + fade or span == 0: + prog = 1.0 if fade <= 0 else (pos - acc) / fade + return index, min(1.0, max(0.0, prog)), prev, pos - acc + if pos < acc + span or index == count - 1: + return index, 1.0, prev, pos - acc + acc += span + return count - 1, 1.0, None, spans[-1] + + +def _fixture(show: Show, item: Any) -> Any: + if isinstance(item, str): + return show.fixtures_by_key[item] + if isinstance(item, int) and not isinstance(item, bool): + return next(fx for fx in show.fixtures if fx.id == item) + return item + + +@dataclass +class EfxFunction: + id: int + key: str + name: str + pattern: Efx + homes: dict[int, tuple[int, int]] + relative: bool + axes: dict[int, Axis] + preview: dict[int, dict[int, int]] + primary: bool = True + type: str = "EFX" + + def duration_ms(self, _show: Show) -> int: + return self.pattern.duration_ms + + def apply(self, _show: Show, elapsed_ms: float, into: dict[int, dict[int, int]]) -> None: + for serial, fx in enumerate(self.pattern.fixtures): + bucket = into.setdefault(fx.id, {}) + for ch, val in self.preview.get(fx.id, {}).items(): + bucket.setdefault(ch, val) + point = self.pattern.live_point(serial, elapsed_ms) + if point is None: + continue + pan, tilt = point + if self.relative: + home_pan, home_tilt = self.homes.get(fx.id, (RELATIVE_ZERO, RELATIVE_ZERO)) + pan = home_pan + (pan - RELATIVE_ZERO) + tilt = home_tilt + (tilt - RELATIVE_ZERO) + pan_msb, pan_lsb, tilt_msb, tilt_lsb = self.axes[fx.id] + _write_axis(bucket, pan_msb, pan_lsb, pan) + _write_axis(bucket, tilt_msb, tilt_lsb, tilt) + + def render(self) -> str: + pattern = self.pattern + fixtures = "\n".join( + " \n" + f" {fx.id}\n" + f" {fx.head}\n" + f" {fx.direction}\n" + f" {fx.start_offset}\n" + " " + for fx in pattern.fixtures + ) + return ( + f' \n' + f"{fixtures}\n" + f" {pattern.propagation}\n" + f' \n' + f" {pattern.direction}\n" + f" {pattern.run_order}\n" + f" {pattern.algorithm}\n" + f" {pattern.width}\n" + f" {pattern.height}\n" + f" {pattern.rotation}\n" + f" {pattern.start_offset}\n" + f" {1 if self.relative else 0}\n" + " \n" + f" {pattern.x_offset}\n" + f" {pattern.x_frequency}\n" + f" {pattern.x_phase}\n" + " \n" + " \n" + f" {pattern.y_offset}\n" + f" {pattern.y_frequency}\n" + f" {pattern.y_phase}\n" + " \n" + " " + ) + + +@dataclass +class SequenceStep: + values: dict[int, dict[int, int]] + fade_ms: int = 0 + hold_ms: int = 0 + fade_out_ms: int = 0 + + +@dataclass +class SequenceFunction: + id: int + key: str + name: str + bound_id: int + steps: list[SequenceStep] + direction: str = "Forward" + run_order: str = "Loop" + primary: bool = True + type: str = "Sequence" + + def duration_ms(self, _show: Show) -> int: + return sum(step.fade_ms + step.hold_ms + step.fade_out_ms for step in self.steps) + + def apply(self, _show: Show, elapsed_ms: float, into: dict[int, dict[int, int]]) -> None: + index, prog, prev, _local = locate(self.steps, elapsed_ms, self.run_order, self.direction) + if not self.steps: + return + current = self.steps[index].values + previous = {} if prev is None else self.steps[prev].values + blend_maps(into, previous, current, prog) + + def render(self) -> str: + lines = [] + for index, step in enumerate(self.steps): + body, count = _step_values(step.values) + lines.append( + f' {body}' + ) + first = self.steps[0] if self.steps else SequenceStep({}) + fade_mode, duration_mode = _speed_modes(self.steps) + return ( + f' \n' + f' \n' + f" {self.direction}\n" + f" {self.run_order}\n" + f' \n' + + "\n".join(lines) + + "\n " + ) + + +@dataclass +class ChaserStep: + function_id: int + fade_ms: int = 0 + hold_ms: int = 0 + fade_out_ms: int = 0 + + +@dataclass +class ChaserFunction: + id: int + key: str + name: str + steps: list[ChaserStep] + direction: str = "Forward" + run_order: str = "Loop" + primary: bool = True + type: str = "Chaser" + + def duration_ms(self, _show: Show) -> int: + return sum(step.fade_ms + step.hold_ms + step.fade_out_ms for step in self.steps) + + def apply(self, show: Show, elapsed_ms: float, into: dict[int, dict[int, int]]) -> None: + from .model import Scene + + if not self.steps: + return + index, prog, prev, local = locate(self.steps, elapsed_ms, self.run_order, self.direction) + current = show.functions_by_id[self.steps[index].function_id] + if isinstance(current, Scene): + previous: dict[int, dict[int, int]] = {} + if prev is not None: + prev_fn = show.functions_by_id[self.steps[prev].function_id] + if isinstance(prev_fn, Scene): + previous = prev_fn.values + else: + prev_fn.apply(show, prev_fn.duration_ms(show), previous) + blend_maps(into, previous, current.values, prog) + return + current.apply(show, local, into) + + def render(self) -> str: + lines = [ + f' {step.function_id}' + for i, step in enumerate(self.steps) + ] + first = self.steps[0] if self.steps else ChaserStep(0) + fade_mode, duration_mode = _speed_modes(self.steps) + return ( + f' \n' + f' \n' + f" {self.direction}\n" + f" {self.run_order}\n" + f' \n' + + "\n".join(lines) + + "\n " + ) + + +def add_efx(show: Show, name: str, fixtures: list[Any], **kwargs: Any) -> Any: + key = kwargs.pop("key", None) or _auto_key(show, name) + relative = bool(kwargs.pop("relative", False)) + homes_in = kwargs.pop("homes", None) or {} + entries = [_efx_entry(show, item, homes_in) for item in fixtures] + if not entries: + raise ValueError("efx has no fixtures") + for fixture, _direction, _offset, _pan, _tilt in entries: + if fixture.pan_msb is None or fixture.tilt_msb is None: + raise ValueError(f"{fixture.key} has no pan/tilt in mode {fixture.mode}") + pattern = _build_efx(entries, relative=relative, **kwargs) + homes = {fixture.id: (pan, tilt) for fixture, _d, _o, pan, tilt in entries} + axes = { + fixture.id: (fixture.pan_msb, fixture.pan_lsb, fixture.tilt_msb, fixture.tilt_lsb) + for fixture, *_rest in entries + } + preview = {fixture.id: fixture.preview_channels() for fixture, *_rest in entries} + if relative: + home_values = {} + for fixture, _d, _o, pan, tilt in entries: + channels: dict[int, int] = {} + if fixture.pan_msb is not None: + channels[fixture.pan_msb] = pan + if fixture.pan_lsb is not None: + channels[fixture.pan_lsb] = 0 + if fixture.tilt_msb is not None: + channels[fixture.tilt_msb] = tilt + if fixture.tilt_lsb is not None: + channels[fixture.tilt_lsb] = 0 + home_values[fixture.id] = channels + show.scene(f"{name} (home)", home_values, key=f"{key}.home", primary=False) + efx = EfxFunction( + id=show.alloc_function(), + key=f"{key}.efx", + name=f"{name} (EFX)", + pattern=pattern, + homes=homes, + relative=True, + axes=axes, + preview=preview, + primary=False, + ) + show._add_function(efx) + return show.collection(name, [f"{key}.home", f"{key}.efx"], key=key, primary=True) + efx = EfxFunction( + id=show.alloc_function(), + key=key, + name=name, + pattern=pattern, + homes=homes, + relative=False, + axes=axes, + preview=preview, + ) + return show._add_function(efx) + + +def add_sequence( + show: Show, + name: str, + steps: list[Any], + *, + direction: str = "Forward", + run_order: str = "Loop", + key: str | None = None, + primary: bool = True, +) -> SequenceFunction: + _check_choice("direction", direction, DIRECTIONS) + _check_choice("run_order", run_order, RUN_ORDERS) + fn_key = key or _auto_key(show, name) + norm = [_sequence_step(show, step) for step in steps] + if not norm: + raise ValueError("sequence has no steps") + show.scene(f"{name} (base)", norm[0].values, key=f"{fn_key}.base", primary=False) + bound = show.functions_by_key[f"{fn_key}.base"] + seq = SequenceFunction( + id=show.alloc_function(), + key=fn_key, + name=name, + bound_id=bound.id, + steps=norm, + direction=direction, + run_order=run_order, + primary=primary, + ) + return show._add_function(seq) + + +def add_path( + show: Show, + name: str, + fixtures: list[Any], + points: list[Any], + *, + smooth: bool = False, + subdivisions: int = 6, + closed: bool = True, + run_order: str = "Loop", + direction: str = "Forward", + key: str | None = None, +) -> SequenceFunction: + entries = [_path_entry(show, item) for item in fixtures] + if not entries: + raise ValueError("path has no fixtures") + path_points = [_path_point(point) for point in points] + if len(path_points) < 1: + raise ValueError("path has no points") + for fixture, *_rest in entries: + if fixture.pan_msb is None or fixture.tilt_msb is None: + raise ValueError(f"{fixture.key} has no pan/tilt in mode {fixture.mode}") + path = Path( + points=path_points, + smooth=smooth, + subdivisions=int(subdivisions), + closed=closed, + run_order=run_order, + direction=direction, + fixtures=[ + PathFixture( + id=fixture.id, + pan_offset=pan_offset, + tilt_offset=tilt_offset, + mirror_pan=mirror_pan, + mirror_tilt=mirror_tilt, + ) + for fixture, pan_offset, tilt_offset, mirror_pan, mirror_tilt in entries + ], + ) + resolved = path.steps() + by_id = {fixture.id: fixture for fixture, *_rest in entries} + steps = [] + for point in resolved: + values: dict[int, dict[int, int]] = {} + for cfg in path.fixtures: + fixture = by_id[cfg.id] + pan, tilt = cfg.apply(point.pan, point.tilt) + channels: dict[int, int] = {} + _write_axis(channels, fixture.pan_msb, fixture.pan_lsb, pan) + _write_axis(channels, fixture.tilt_msb, fixture.tilt_lsb, tilt) + values[fixture.id] = channels + steps.append(SequenceStep(values, fade_ms=point.fade_ms, hold_ms=point.hold_ms)) + return add_sequence(show, name, steps, direction=direction, run_order=run_order, key=key) + + +def add_chaser( + show: Show, + name: str, + steps: list[Any], + *, + direction: str = "Forward", + run_order: str = "Loop", + key: str | None = None, + primary: bool = True, +) -> ChaserFunction: + _check_choice("direction", direction, DIRECTIONS) + _check_choice("run_order", run_order, RUN_ORDERS) + norm = [_chaser_step(show, step) for step in steps] + if not norm: + raise ValueError("chaser has no steps") + fn_key = key or _auto_key(show, name) + chaser = ChaserFunction( + id=show.alloc_function(), + key=fn_key, + name=name, + steps=norm, + direction=direction, + run_order=run_order, + primary=primary, + ) + return show._add_function(chaser) + + +def add_colour_chase( + show: Show, + name: str, + fixtures: list[Any], + channels: dict[str, int], + frames: list[Any], + *, + fade_ms: int = 0, + hold_ms: int = 0, + run_order: str = "Loop", + key: str | None = None, +) -> ChaserFunction: + if not frames: + raise ValueError("colour chase has no frames") + fn_key = key or _auto_key(show, name) + names = list(channels) + scene_keys = [] + for index, frame in enumerate(frames): + if len(frame) != len(fixtures): + raise ValueError(f"frame {index} has {len(frame)} colours for {len(fixtures)} fixtures") + values: dict[int, dict[int, int]] = {} + for fixture_item, colour in zip(fixtures, frame): + fixture = _fixture(show, fixture_item) + if isinstance(colour, dict): + values[fixture.id] = {int(ch): int(val) for ch, val in colour.items()} + else: + if len(colour) != len(names): + raise ValueError( + f"frame {index} colour has {len(colour)} values for channels {names}" + ) + values[fixture.id] = {int(channels[names[i]]): int(colour[i]) for i in range(len(names))} + scene_key = f"{fn_key}.{index}" + show.scene(f"{name} {index + 1}", values, key=scene_key, primary=False) + scene_keys.append(scene_key) + steps = [ + ChaserStep(show.functions_by_key[scene_key].id, fade_ms=int(fade_ms), hold_ms=int(hold_ms)) + for scene_key in scene_keys + ] + return add_chaser(show, name, steps, run_order=run_order, key=fn_key) + + +def _write_axis(bucket: dict[int, int], msb: int | None, lsb: int | None, value: float) -> None: + if msb is not None: + bucket[msb] = clamp8(value) + if lsb is not None: + bucket[lsb] = clamp8((value - int(value)) * 255) + + +def _step_values(values: dict[int, dict[int, int]]) -> tuple[str, int]: + chunks = [] + count = 0 + for fid, channels in sorted(values.items()): + if not channels: + continue + count += len(channels) + body = ",".join(f"{ch},{val}" for ch, val in sorted(channels.items())) + chunks.append(f"{fid}:{body}") + return ":".join(chunks), count + + +def _speed_modes(steps: list[Any]) -> tuple[str, str]: + if not steps: + return "Common", "Common" + first = (steps[0].fade_ms, steps[0].hold_ms, steps[0].fade_out_ms) + if all((step.fade_ms, step.hold_ms, step.fade_out_ms) == first for step in steps): + return "Common", "Common" + return "PerStep", "PerStep" + + +def _check_choice(label: str, value: str, allowed: tuple[str, ...]) -> None: + if value not in allowed: + raise ValueError(f"{label} must be one of {', '.join(allowed)}") + + +def _check_range(label: str, value: int, lo: int, hi: int) -> int: + number = int(value) + if not lo <= number <= hi: + raise ValueError(f"{label} must be {lo}–{hi}") + return number + + +def _build_efx(entries: list[tuple[Any, str, int, int, int]], *, relative: bool, **kwargs: Any) -> Efx: + algorithm = kwargs.get("algorithm", "Circle") + _check_choice("algorithm", algorithm, ALGORITHMS) + direction = kwargs.get("direction", "Forward") + run_order = kwargs.get("run_order", "Loop") + propagation = kwargs.get("propagation", "Parallel") + _check_choice("direction", direction, DIRECTIONS) + _check_choice("run_order", run_order, RUN_ORDERS) + _check_choice("propagation", propagation, PROPAGATIONS) + duration = int(kwargs.get("duration_ms", 8000)) + if duration < 20: + raise ValueError("duration_ms must be at least 20") + x_offset = RELATIVE_ZERO if relative else _check_range("x_offset", kwargs.get("x_offset", 128), 0, 255) + y_offset = RELATIVE_ZERO if relative else _check_range("y_offset", kwargs.get("y_offset", 128), 0, 255) + return Efx( + algorithm=algorithm, + width=_check_range("width", kwargs.get("width", 40), 0, 127), + height=_check_range("height", kwargs.get("height", 40), 0, 127), + rotation=int(kwargs.get("rotation", 0)) % 360, + start_offset=int(kwargs.get("start_offset", 0)) % 360, + x_offset=x_offset, + y_offset=y_offset, + x_frequency=_check_range("x_frequency", kwargs.get("x_frequency", 1), 0, 5), + y_frequency=_check_range("y_frequency", kwargs.get("y_frequency", 1), 0, 5), + x_phase=int(kwargs.get("x_phase", 0)) % 360, + y_phase=int(kwargs.get("y_phase", 0)) % 360, + duration_ms=duration, + fade_in_ms=max(0, int(kwargs.get("fade_in_ms", 0))), + fade_out_ms=max(0, int(kwargs.get("fade_out_ms", 0))), + direction=direction, + run_order=run_order, + propagation=propagation, + relative=relative, + fixtures=[ + EfxFixture(id=fixture.id, direction=direction, start_offset=offset, pan=pan, tilt=tilt) + for fixture, direction, offset, pan, tilt in entries + ], + ) + + +def _efx_entry(show: Show, item: Any, homes: dict[Any, Any]) -> tuple[Any, str, int, int, int]: + if isinstance(item, str) or (isinstance(item, int) and not isinstance(item, bool)): + fixture = _fixture(show, item) + direction, offset, pan, tilt = "Forward", 0, 128, 128 + home_key: Any = item + elif hasattr(item, "pan_msb"): + fixture = item + direction, offset, pan, tilt = "Forward", 0, 128, 128 + home_key = fixture.key + else: + fixture = _fixture(show, item["fixture"]) + direction = item.get("direction", "Forward") + offset = int(item.get("start_offset", 0)) + pan = int(item.get("pan", 128)) + tilt = int(item.get("tilt", 128)) + home_key = item["fixture"] + home = _home_for(homes, fixture, home_key) + if home is not None: + pan, tilt = int(home[0]), int(home[1]) + return fixture, direction, offset, pan, tilt + + +def _home_for(homes: dict[Any, Any], fixture: Any, home_key: Any) -> Any: + if not homes: + return None + for candidate in (home_key, fixture.key, fixture.id): + if candidate in homes: + return homes[candidate] + for key, value in homes.items(): + if key is fixture: + return value + return None + + +def _sequence_step(show: Show, step: Any) -> SequenceStep: + if isinstance(step, SequenceStep): + values = { + show.fixture_id(fid): {int(ch): int(val) for ch, val in channels.items()} + for fid, channels in step.values.items() + } + return SequenceStep(values, step.fade_ms, step.hold_ms, step.fade_out_ms) + values = { + show.fixture_id(fid): {int(ch): int(val) for ch, val in channels.items()} + for fid, channels in step["values"].items() + } + return SequenceStep( + values, + fade_ms=int(step.get("fade_ms", 0)), + hold_ms=int(step.get("hold_ms", 0)), + fade_out_ms=int(step.get("fade_out_ms", 0)), + ) + + +def _path_entry(show: Show, item: Any) -> tuple[Any, int, int, bool, bool]: + if isinstance(item, str) or hasattr(item, "pan_msb"): + return _fixture(show, item), 0, 0, False, False + return ( + _fixture(show, item["fixture"]), + int(item.get("pan_offset", 0)), + int(item.get("tilt_offset", 0)), + bool(item.get("mirror_pan", False)), + bool(item.get("mirror_tilt", False)), + ) + + +def _path_point(point: Any) -> PathPoint: + if isinstance(point, PathPoint): + return point + return PathPoint( + pan=float(point["pan"]), + tilt=float(point["tilt"]), + fade_ms=int(point.get("fade_ms", 1000)), + hold_ms=int(point.get("hold_ms", 0)), + ) + + +def _chaser_step(show: Show, step: Any) -> ChaserStep: + if isinstance(step, ChaserStep): + return ChaserStep(_function_id(show, step.function_id), step.fade_ms, step.hold_ms, step.fade_out_ms) + if isinstance(step, tuple): + function, fade, hold = step[0], step[1], step[2] if len(step) > 2 else 0 + fade_out = step[3] if len(step) > 3 else 0 + return ChaserStep(_function_id(show, function), int(fade), int(hold), int(fade_out)) + return ChaserStep( + _function_id(show, step["function"] if isinstance(step, dict) else step), + fade_ms=int(step.get("fade_ms", 0)) if isinstance(step, dict) else 0, + hold_ms=int(step.get("hold_ms", 0)) if isinstance(step, dict) else 0, + fade_out_ms=int(step.get("fade_out_ms", 0)) if isinstance(step, dict) else 0, + ) + + +def _function_id(show: Show, function: Any) -> int: + if isinstance(function, int) and not isinstance(function, bool): + return function + if isinstance(function, str): + return show.functions_by_key[function].id + return function.id + + +def _auto_key(show: Show, name: str) -> str: + from .model import _key_for + + return _key_for(name, show.functions_by_key) diff --git a/showfile/mcp.py b/showfile/mcp.py new file mode 100644 index 0000000..e3a0522 --- /dev/null +++ b/showfile/mcp.py @@ -0,0 +1,187 @@ +"""MCP stdio server for the show tools. + +Cursor starts this with `python3 -m showfile.mcp`. The process speaks MCP +over Content-Length framing and does not require the third-party mcp package. +""" + +from __future__ import annotations + +import json +import sys +from typing import Any + +from .tools import list_fixtures, run_script, sample_animation, show_schema, validate_show, write_show + +_TOOLS = [ + { + "name": "list_fixtures", + "description": ( + "List fixture definitions in fixtures/. Each mode includes channel index, name, " + "preset, and which channels are pan and tilt. Use these channel numbers in a show spec." + ), + "inputSchema": {"type": "object", "properties": {}, "additionalProperties": False}, + }, + { + "name": "show_schema", + "description": "Return the JSON Schema for a QLC+ show spec. Keys are strings; ids are assigned on write.", + "inputSchema": {"type": "object", "properties": {}, "additionalProperties": False}, + }, + { + "name": "validate_show", + "description": ( + "Validate a show spec. Returns {ok, errors: [{path, message}]} and writes nothing. " + "Error paths look like functions.eight.fixtures." + ), + "inputSchema": { + "type": "object", + "properties": {"spec": {"type": "object", "description": "Show spec."}}, + "required": ["spec"], + }, + }, + { + "name": "write_show", + "description": ( + "Write a show spec to a .qxw inside the project. Returns {ok, path, fixtures, functions, widgets} " + "with the QLC+ ids that were assigned. Refuses paths outside the project." + ), + "inputSchema": { + "type": "object", + "properties": { + "spec": {"type": "object"}, + "path": {"type": "string", "description": "Project-relative .qxw path, for example shows/look.qxw."}, + }, + "required": ["spec", "path"], + }, + }, + { + "name": "sample_animation", + "description": ( + "Sample pan/tilt for one efx or path block so the shape can be checked before writing a show. " + "Returns tracks of points. Relative EFX points are the fixture's real pan/tilt, including its home." + ), + "inputSchema": { + "type": "object", + "properties": { + "block": {"type": "object", "description": "An efx or path function object."}, + "steps": {"type": "integer", "minimum": 1, "maximum": 128, "description": "EFX samples along one loop. Default 32."}, + }, + "required": ["block"], + }, + }, + { + "name": "run_animation", + "description": ( + "Run an animation Python script (a file that defines build() -> Show) or a JSON show spec. " + "Without ip, returns DMX samples for testing and sends nothing. " + "With ip, streams Art-Net for `seconds` (or until the client cancels — prefer a short seconds value)." + ), + "inputSchema": { + "type": "object", + "properties": { + "path": {"type": "string", "description": "Project-relative .py script or .json spec."}, + "seconds": {"type": "number"}, + "ip": {"type": "string", "description": "Art-Net destination. Omit for a dry run."}, + "universe": {"type": "integer"}, + "hz": {"type": "number"}, + }, + "required": ["path"], + }, + }, +] + + +def serve() -> None: + framed = False + while True: + message, framed = _read(framed) + if message is None: + return + response = _handle(message) + if response is not None: + _write(response, framed) + + +def _handle(message: dict[str, Any]) -> dict[str, Any] | None: + method = message.get("method") + mid = message.get("id") + if method == "notifications/initialized" or method and method.startswith("notifications/"): + return None + if method == "initialize": + return _result( + mid, + { + "protocolVersion": "2024-11-05", + "capabilities": {"tools": {"listChanged": False}}, + "serverInfo": {"name": "qlcplus-show", "version": "1.0.0"}, + }, + ) + if method == "ping": + return _result(mid, {}) + if method == "tools/list": + return _result(mid, {"tools": _TOOLS}) + if method == "tools/call": + params = message.get("params") or {} + try: + payload = _call(str(params.get("name")), params.get("arguments") or {}) + return _result(mid, {"content": [{"type": "text", "text": json.dumps(payload, indent=2)}], "isError": False}) + except Exception as exc: # noqa: BLE001 — reported to the MCP client + return _result(mid, {"content": [{"type": "text", "text": str(exc)}], "isError": True}) + if mid is not None: + return {"jsonrpc": "2.0", "id": mid, "error": {"code": -32601, "message": f"unknown method {method}"}} + return None + + +def _call(name: str, arguments: dict[str, Any]) -> Any: + if name == "list_fixtures": + return list_fixtures() + if name == "show_schema": + return show_schema() + if name == "validate_show": + return validate_show(arguments["spec"]) + if name == "write_show": + return write_show(arguments["spec"], arguments["path"]) + if name == "sample_animation": + return sample_animation(arguments["block"], int(arguments.get("steps", 32))) + if name == "run_animation": + return run_script( + arguments["path"], + seconds=arguments.get("seconds"), + ip=arguments.get("ip"), + universe=int(arguments.get("universe", 0)), + hz=float(arguments.get("hz", 40)), + ) + raise KeyError(f"unknown tool {name}") + + +def _result(mid: Any, result: Any) -> dict[str, Any]: + return {"jsonrpc": "2.0", "id": mid, "result": result} + + +def _read(framed: bool) -> tuple[dict[str, Any] | None, bool]: + line = sys.stdin.buffer.readline() + if not line: + return None, framed + if line.lower().startswith(b"content-length:"): + length = int(line.split(b":", 1)[1].strip()) + while True: + header = sys.stdin.buffer.readline() + if header in (b"\r\n", b"\n", b""): + break + body = sys.stdin.buffer.read(length) + return json.loads(body), True + if not line.strip(): + return _read(framed) + return json.loads(line), framed + + +def _write(message: dict[str, Any], framed: bool) -> None: + data = json.dumps(message).encode() + if framed: + sys.stdout.buffer.write(f"Content-Length: {len(data)}\r\n\r\n".encode() + data) + else: + sys.stdout.buffer.write(data + b"\n") + sys.stdout.buffer.flush() + + +if __name__ == "__main__": + serve() diff --git a/showfile/model.py b/showfile/model.py new file mode 100644 index 0000000..c5502cd --- /dev/null +++ b/showfile/model.py @@ -0,0 +1,584 @@ +"""QLC+ show model: universes, fixtures, scenes, and the virtual-console root.""" + +from __future__ import annotations + +from dataclasses import dataclass, field +from pathlib import Path +from typing import Any + +from patternstudio.fixturedefs import FixtureLibrary, ModeInfo + +from .xmlutil import appearance, attr, text + +QLC_VERSION = "4.12.7" +INVALID_FUNCTION = 4294967295 + + +def midi_note(channel: int, note: int) -> int: + """QLC+ input channel for a MIDI note. Channel is 0–15.""" + return (int(channel) << 12) | (128 + int(note)) + + +def midi_cc(channel: int, cc: int) -> int: + """QLC+ input channel for a MIDI control change. Channel is 0–15.""" + return (int(channel) << 12) | int(cc) + + +def blend_maps( + into: dict[int, dict[int, int]], + prev: dict[int, dict[int, int]], + curr: dict[int, dict[int, int]], + prog: float, +) -> None: + """Write prev→curr into `into`. Channels fade up from 0 when prev lacks them.""" + prog = max(0.0, min(1.0, prog)) + for fid in set(prev) | set(curr): + bucket = into.setdefault(fid, {}) + channels = set(prev.get(fid, {})) | set(curr.get(fid, {})) + for ch in channels: + start = prev.get(fid, {}).get(ch, 0) + end = curr.get(fid, {}).get(ch, 0) + bucket[ch] = int(round(start + (end - start) * prog)) + + +@dataclass +class MidiBinding: + universe: int + channel: int + + +@dataclass +class ArtNetOutput: + uid: str + ip: str + universe: int = 0 + line: int = 0 + + +@dataclass +class MidiInput: + uid: str + profile: str + channel: int = 0 + line: int = 0 + + +@dataclass +class Universe: + id: int + name: str + output: ArtNetOutput | None = None + midi: MidiInput | None = None + + +@dataclass +class Fixture: + id: int + key: str + manufacturer: str + model: str + mode: str + name: str + universe: int + address: int + channels: int + mode_info: ModeInfo | None = None + x: float | None = None + y: float | None = None + direction: float | None = None + zero: float | None = None + kind: str = "" + + def named(self, name: str) -> list[int]: + """Channel indexes for a name. "Red" is Red, or Red 1 … Red N when those exist.""" + if self.mode_info is None: + raise ValueError(f"{self.key} has no channel map") + query = name.strip().lower() + exact: list[int] = [] + numbered: list[tuple[int, int]] = [] + for channel in self.mode_info.channels: + label = channel.name.strip() + if label.lower() == query: + exact.append(channel.index) + continue + head, sep, tail = label.rpartition(" ") + if sep and head.lower() == query and tail.isdigit(): + numbered.append((int(tail), channel.index)) + if exact: + return exact + if numbered: + numbered.sort() + return [index for _, index in numbered] + raise KeyError(f"{self.key} has no channel {name!r}") + + def channel(self, name: str) -> int: + return self.named(name)[0] + + @property + def pan_msb(self) -> int | None: + return None if self.mode_info is None else self.mode_info.pan_msb + + @property + def pan_lsb(self) -> int | None: + return None if self.mode_info is None else self.mode_info.pan_lsb + + @property + def tilt_msb(self) -> int | None: + return None if self.mode_info is None else self.mode_info.tilt_msb + + @property + def tilt_lsb(self) -> int | None: + return None if self.mode_info is None else self.mode_info.tilt_lsb + + def preview_channels(self) -> dict[int, int]: + if self.mode_info is None: + return {} + return self.mode_info.preview_channels() + + +@dataclass +class FixtureGroup: + id: int + name: str + columns: int + fixture_ids: list[int] + head: int = 0 + + +@dataclass +class Scene: + id: int + key: str + name: str + values: dict[int, dict[int, int]] + fade_in: int = 0 + fade_out: int = 0 + duration: int = 0 + primary: bool = True + type: str = "Scene" + + def duration_ms(self, _show: Show) -> int: + return max(0, self.fade_in) + max(0, self.duration) + + def apply(self, _show: Show, elapsed_ms: float, into: dict[int, dict[int, int]]) -> None: + prog = 1.0 if self.fade_in <= 0 else min(1.0, elapsed_ms / self.fade_in) + blend_maps(into, {}, self.values, prog) + + def render(self) -> str: + vals = [] + for fid, channels in sorted(self.values.items()): + if not channels: + continue + body = ",".join(f"{ch},{val}" for ch, val in sorted(channels.items())) + vals.append(f' {body}') + inner = ("\n" + "\n".join(vals)) if vals else "" + return ( + f' \n' + f' ' + f"{inner}\n" + f" " + ) + + +@dataclass +class Collection: + id: int + key: str + name: str + members: list[int] + primary: bool = True + type: str = "Collection" + + def duration_ms(self, show: Show) -> int: + return max((show.functions_by_id[mid].duration_ms(show) for mid in self.members), default=0) + + def apply(self, show: Show, elapsed_ms: float, into: dict[int, dict[int, int]]) -> None: + for mid in self.members: + show.functions_by_id[mid].apply(show, elapsed_ms, into) + + def render(self) -> str: + steps = "\n".join(f' {mid}' for i, mid in enumerate(self.members)) + return ( + f' \n' + f"{steps}\n" + f" " + ) + + +@dataclass +class RawFunction: + id: int + key: str + name: str + xml: str + primary: bool = True + type: str = "Raw" + + def duration_ms(self, _show: Show) -> int: + return 0 + + def apply(self, _show: Show, _elapsed_ms: float, _into: dict[int, dict[int, int]]) -> None: + return None + + def render(self) -> str: + return self.xml + + +@dataclass +class Show: + author: str = "Jimmy" + version: str = QLC_VERSION + root: Path | None = None + universes: list[Universe] = field(default_factory=list) + fixtures: list[Fixture] = field(default_factory=list) + groups: list[FixtureGroup] = field(default_factory=list) + functions: list[Any] = field(default_factory=list) + playback: list[str] = field(default_factory=list) + vc_size: tuple[int, int] | None = None + + def __post_init__(self) -> None: + from .vc import Frame + + self._fixture_seq = 0 + self._function_seq = 0 + self._widget_seq = 0 + self._group_seq = 0 + self.fixtures_by_key: dict[str, Fixture] = {} + self.functions_by_key: dict[str, Any] = {} + self.functions_by_id: dict[int, Any] = {} + project = self.root or Path(__file__).resolve().parents[1] + self.library = FixtureLibrary(project) + self.vc = Frame(self, "", root=True) + + # -- allocation ------------------------------------------------------- + + def alloc_fixture(self) -> int: + value = self._fixture_seq + self._fixture_seq += 1 + return value + + def alloc_function(self) -> int: + value = self._function_seq + self._function_seq += 1 + return value + + def alloc_widget(self) -> int: + value = self._widget_seq + self._widget_seq += 1 + return value + + def _add_function(self, fn: Any) -> Any: + if fn.key in self.functions_by_key: + raise ValueError(f"duplicate function key {fn.key!r}") + self.functions.append(fn) + self.functions_by_key[fn.key] = fn + self.functions_by_id[fn.id] = fn + return fn + + def fixture_id(self, fx: Fixture | int | str) -> int: + if isinstance(fx, Fixture): + return fx.id + if isinstance(fx, int) and not isinstance(fx, bool): + return fx + try: + return self.fixtures_by_key[str(fx)].id + except KeyError as exc: + raise KeyError(f"no fixture {fx!r}") from exc + + # -- patch ------------------------------------------------------------ + + def universe( + self, + uid: int, + name: str | None = None, + *, + output: ArtNetOutput | None = None, + midi: MidiInput | None = None, + ) -> Universe: + uni = Universe(int(uid), name or f"Universe {int(uid) + 1}", output, midi) + self.universes.append(uni) + return uni + + def patch( + self, + manufacturer: str, + model: str, + mode: str, + *, + address: int, + name: str | None = None, + universe: int = 0, + channels: int | None = None, + key: str | None = None, + ) -> Fixture: + definition = self.library.find(manufacturer, model) + mode_info = definition.mode(mode) if definition is not None else None + if channels is None: + if mode_info is None: + raise ValueError( + f"no fixture definition for {manufacturer} {model} mode {mode!r}; pass channels=" + ) + channels = len(mode_info.channels) + elif mode_info is not None and channels != len(mode_info.channels): + mode_info = None + fid = self.alloc_fixture() + fx_key = key or f"fixture{fid}" + if fx_key in self.fixtures_by_key: + raise ValueError(f"duplicate fixture key {fx_key!r}") + fixture = Fixture( + id=fid, + key=fx_key, + manufacturer=manufacturer, + model=model, + mode=mode, + name=name or f"{model} #{fid + 1}", + universe=int(universe), + address=int(address), + channels=int(channels), + mode_info=mode_info, + ) + self.fixtures.append(fixture) + self.fixtures_by_key[fx_key] = fixture + return fixture + + def group(self, name: str, fixtures: list[Fixture | str | int], *, columns: int | None = None) -> FixtureGroup: + ids = [self.fixture_id(fx) for fx in fixtures] + group = FixtureGroup( + id=self._group_seq, + name=name, + columns=columns or max(1, len(ids)), + fixture_ids=ids, + ) + self._group_seq += 1 + self.groups.append(group) + return group + + def patch_stage(self, path: str | Path | None = None) -> Any: + """Patch every fixture in a stage map. Keys are the map ids, such as "#1" and "M1".""" + from .stage import patch_stage + + return patch_stage(self, path) + + def scene( + self, + name: str, + values: dict[Any, dict[Any, int]], + *, + key: str | None = None, + fade_in: int = 0, + fade_out: int = 0, + duration: int = 0, + primary: bool = True, + ) -> Scene: + norm = _channel_map(self, values) + fn_key = key or _key_for(name, self.functions_by_key) + scene = Scene( + id=self.alloc_function(), + key=fn_key, + name=name, + values=norm, + fade_in=int(fade_in), + fade_out=int(fade_out), + duration=int(duration), + primary=primary, + ) + return self._add_function(scene) + + def collection( + self, + name: str, + members: list[Any], + *, + key: str | None = None, + primary: bool = True, + ) -> Collection: + ids = [] + for member in members: + if isinstance(member, int) and not isinstance(member, bool): + ids.append(member) + elif isinstance(member, str): + ids.append(self.functions_by_key[member].id) + else: + ids.append(member.id) + fn_key = key or _key_for(name, self.functions_by_key) + coll = Collection( + id=self.alloc_function(), + key=fn_key, + name=name, + members=ids, + primary=primary, + ) + return self._add_function(coll) + + def function_xml(self, xml: str, *, key: str | None = None, name: str = "Function") -> RawFunction: + fid = self.alloc_function() + fn_key = key or f"function{fid}" + stamped = _stamp_function_id(xml.strip(), fid) + raw = RawFunction(id=fid, key=fn_key, name=name, xml=stamped) + return self._add_function(raw) + + def run(self, *keys: str) -> None: + missing = [key for key in keys if key not in self.functions_by_key] + if missing: + raise KeyError(f"no function {missing[0]!r}") + self.playback = list(keys) + + def efx(self, name: str, fixtures: list[Any], **kwargs: Any) -> Any: + from .animate import add_efx + + return add_efx(self, name, fixtures, **kwargs) + + def sequence(self, name: str, steps: list[Any], **kwargs: Any) -> Any: + from .animate import add_sequence + + return add_sequence(self, name, steps, **kwargs) + + def path_sequence(self, name: str, fixtures: list[Any], points: list[Any], **kwargs: Any) -> Any: + from .animate import add_path + + return add_path(self, name, fixtures, points, **kwargs) + + def chaser(self, name: str, steps: list[Any], **kwargs: Any) -> Any: + from .animate import add_chaser + + return add_chaser(self, name, steps, **kwargs) + + def colour_chase(self, name: str, fixtures: list[Any], channels: dict[str, int], frames: list[Any], **kwargs: Any) -> Any: + from .animate import add_colour_chase + + return add_colour_chase(self, name, fixtures, channels, frames, **kwargs) + + # -- output ----------------------------------------------------------- + + def size(self) -> tuple[int, int]: + if self.vc_size is not None: + return self.vc_size + max_x = max_y = 0 + for widget in self.vc.children: + max_x = max(max_x, widget.x + widget.w) + max_y = max(max_y, widget.y + widget.h) + return max_x + 16, max_y + 16 + + def xml(self) -> str: + from .xml import render_show + + return render_show(self) + + def write(self, path: Path | str) -> Path: + target = Path(path) + target.parent.mkdir(parents=True, exist_ok=True) + target.write_text(self.xml(), encoding="utf-8") + return target + + def summary(self) -> dict[str, Any]: + return { + "fixtures": { + fx.key: { + "id": fx.id, + "name": fx.name, + "address": fx.address, + "channels": fx.channels, + "universe": fx.universe, + } + for fx in self.fixtures + }, + "functions": { + fn.key: {"id": fn.id, "type": fn.type, "name": fn.name} + for fn in self.functions + }, + "widgets": _widgets(self.vc), + } + + +def _channel_map(show: Show, values: Any) -> dict[int, dict[int, int]]: + pairs = values if isinstance(values, list) else values.items() + norm: dict[int, dict[int, int]] = {} + for fx, channels in pairs: + norm[show.fixture_id(fx)] = {int(ch): int(val) for ch, val in channels.items()} + return norm + + +def _widgets(frame: Any) -> list[dict[str, Any]]: + found: list[dict[str, Any]] = [] + for child in frame.children: + found.append({"id": child.id, "type": child.type_name, "caption": child.caption}) + if child.type_name in ("Frame", "SoloFrame"): + found.extend(_widgets(child)) + return found + + +def _key_for(name: str, existing: dict[str, Any]) -> str: + base = "".join(ch.lower() if ch.isalnum() else "-" for ch in name).strip("-") or "function" + key = base + n = 2 + while key in existing: + key = f"{base}-{n}" + n += 1 + return key + + +def _stamp_function_id(xml: str, fid: int) -> str: + import re + + if re.search(r"\bID=\"\d+\"", xml): + return re.sub(r"\bID=\"\d+\"", f'ID="{fid}"', xml, count=1) + return xml.replace(" str: + return ( + " \n" + f" {text(fx.manufacturer)}\n" + f" {text(fx.model)}\n" + f" {text(fx.mode)}\n" + f" {fx.id}\n" + f" {text(fx.name)}\n" + f" {fx.universe}\n" + f"
{fx.address}
\n" + f" {fx.channels}\n" + "
" + ) + + +def group_xml(group: FixtureGroup) -> str: + columns = max(1, group.columns) + rows = max(1, (len(group.fixture_ids) + columns - 1) // columns) + heads = [] + for index, fid in enumerate(group.fixture_ids): + heads.append( + f' {group.head}' + ) + body = "\n".join(heads) + return ( + f' \n' + f" {text(group.name)}\n" + f' \n' + f"{body}\n" + " " + ) + + +def universe_xml(uni: Universe) -> str: + if uni.output is None and uni.midi is None: + return f' ' + parts = [f' '] + if uni.output is not None: + out = uni.output + parts.append( + f' \n' + f' \n' + " " + ) + if uni.midi is not None: + midi = uni.midi + parts.append( + f' \n' + f' \n' + " " + ) + parts.append(" ") + return "\n".join(parts) + + +def root_appearance() -> str: + return appearance(frame="None", indent=" ") diff --git a/showfile/play.py b/showfile/play.py new file mode 100644 index 0000000..67bfc20 --- /dev/null +++ b/showfile/play.py @@ -0,0 +1,160 @@ +"""Play a show's animations without QLC+. + +Dry-run returns DMX samples. Pass an IP to send Art-Net. A Python script +exposes this by defining build() -> Show and calling script_main(build). +""" + +from __future__ import annotations + +import argparse +import importlib.util +import json +import socket +import sys +import time +from pathlib import Path +from typing import Any + +from patternstudio.artnet import ARTNET_PORT, build_artdmx + +from .model import Show +from .spec import SpecError, from_spec + + +def active_keys(show: Show, keys: list[str] | None = None) -> list[str]: + if keys is not None: + return list(keys) + if show.playback: + return list(show.playback) + return [fn.key for fn in show.functions if getattr(fn, "primary", False)] + + +def frame_at(show: Show, elapsed_ms: float, keys: list[str] | None = None) -> dict[str, dict[int, int]]: + """Fixture key → channel → value at `elapsed_ms` for the functions being played.""" + into: dict[int, dict[int, int]] = {} + for key in active_keys(show, keys): + show.functions_by_key[key].apply(show, elapsed_ms, into) + names = {fx.id: fx.key for fx in show.fixtures} + return {names[fid]: dict(channels) for fid, channels in into.items() if fid in names} + + +def dmx_frames(show: Show, values: dict[str, dict[int, int]]) -> dict[int, bytearray]: + """QLC+ universe → 512-channel frame.""" + frames: dict[int, bytearray] = {} + for key, channels in values.items(): + fixture = show.fixtures_by_key[key] + frame = frames.setdefault(fixture.universe, bytearray(512)) + for channel, value in channels.items(): + slot = fixture.address + int(channel) + if 0 <= slot < 512: + frame[slot] = max(0, min(255, int(value))) + return frames + + +def sample_playback(show: Show, *, seconds: float | None = None, hz: float = 40.0) -> dict[str, Any]: + keys = active_keys(show) + if seconds is None: + duration = max((show.functions_by_key[key].duration_ms(show) for key in keys), default=0) + times = [0] if duration <= 0 else [int(duration * i / 4) for i in range(4)] + if duration > 0: + times.append(max(0, duration - 1)) + else: + count = max(1, int(float(seconds) * hz)) + times = [int(i * (1000.0 / hz)) for i in range(min(count, 500))] + duration = int(float(seconds) * 1000) + return { + "ok": True, + "functions": keys, + "duration_ms": duration, + "samples": [{"time_ms": t, "values": frame_at(show, t, keys)} for t in times], + } + + +def play( + show: Show, + *, + seconds: float | None = None, + ip: str | None = None, + universe: int = 0, + hz: float = 40.0, +) -> dict[str, Any]: + """Sample the running functions, or stream them as Art-Net when `ip` is set.""" + if not ip: + return sample_playback(show, seconds=seconds, hz=hz) + return _send(show, ip=ip, universe=universe, seconds=seconds, hz=hz) + + +def load_show(path: Path | str) -> Show: + """Load a show from a build() script or a JSON spec.""" + source = Path(path).resolve() + if source.suffix == ".json": + return from_spec(json.loads(source.read_text(encoding="utf-8"))) + spec = importlib.util.spec_from_file_location(f"showfile_script_{source.stem}", source) + if spec is None or spec.loader is None: + raise SpecError([{"path": str(source), "message": "could not load the script"}]) + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + if not hasattr(module, "build"): + raise SpecError([{"path": str(source), "message": "script must define build() -> Show"}]) + show = module.build() + if not isinstance(show, Show): + raise SpecError([{"path": str(source), "message": "build() must return a Show"}]) + return show + + +def script_main(build: Any, argv: list[str] | None = None) -> None: + """Entry point for `python animation.py`. Prints one JSON object.""" + args = _parser().parse_args(argv) + _emit(play(build(), seconds=args.seconds, ip=args.ip, universe=args.universe, hz=args.hz)) + + +def _parser() -> argparse.ArgumentParser: + parser = argparse.ArgumentParser(description="Play this animation and print DMX samples, or send Art-Net.") + parser.add_argument("--ip", help="Art-Net destination. Omit to print samples and exit.") + parser.add_argument("--seconds", type=float, help="How long to play. Omit with --ip to run until Ctrl+C.") + parser.add_argument("--hz", type=float, default=40.0) + parser.add_argument("--universe", type=int, default=0, help="Art-Net universe for QLC+ universe 0.") + return parser + + +def _emit(payload: dict[str, Any]) -> None: + json.dump(payload, sys.stdout, indent=2) + sys.stdout.write("\n") + + +def _send(show: Show, *, ip: str, universe: int, seconds: float | None, hz: float) -> dict[str, Any]: + keys = active_keys(show) + period = 1.0 / hz if hz > 0 else 0.025 + print( + f"Art-Net {ip} universe {universe} {', '.join(keys) or '(no functions)'} (Ctrl+C to stop)", + file=sys.stderr, + ) + sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM) + sock.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1) + sequence = 1 + sent = 0 + stopped = False + started = time.monotonic() + try: + while True: + elapsed_ms = (time.monotonic() - started) * 1000.0 + if seconds is not None and elapsed_ms >= seconds * 1000.0: + break + frames = dmx_frames(show, frame_at(show, elapsed_ms, keys)) + if not frames: + frames = {0: bytearray(512)} + for qlc_universe, frame in frames.items(): + packet = build_artdmx(bytes(frame), universe + qlc_universe, sequence) + sock.sendto(packet, (ip, ARTNET_PORT)) + sequence = 1 if sequence >= 255 else sequence + 1 + sent += 1 + time.sleep(period) + except KeyboardInterrupt: + stopped = True + finally: + for qlc_universe in dmx_frames(show, frame_at(show, 0, keys)) or {0: bytearray()}: + for _ in range(3): + sock.sendto(build_artdmx(bytes(512), universe + qlc_universe, sequence), (ip, ARTNET_PORT)) + sequence = 1 if sequence >= 255 else sequence + 1 + sock.close() + return {"ok": True, "ip": ip, "universe": universe, "functions": keys, "frames": sent, "stopped": stopped} diff --git a/showfile/spec.py b/showfile/spec.py new file mode 100644 index 0000000..784514d --- /dev/null +++ b/showfile/spec.py @@ -0,0 +1,862 @@ +"""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"}, + "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, + **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)), + **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 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}) diff --git a/showfile/stage.py b/showfile/stage.py new file mode 100644 index 0000000..a3cf8b5 --- /dev/null +++ b/showfile/stage.py @@ -0,0 +1,79 @@ +"""Patch a Show from a stage map.""" + +from __future__ import annotations + +import json +from dataclasses import dataclass, field +from pathlib import Path + +from .model import Fixture, Show + +PROJECT_ROOT = Path(__file__).resolve().parents[1] + + +@dataclass +class StageRig: + path: Path + name: str + cans: list[Fixture] = field(default_factory=list) + movers: list[Fixture] = field(default_factory=list) + + def __getitem__(self, key: str) -> Fixture: + for fixture in (*self.cans, *self.movers): + if fixture.key == key: + return fixture + raise KeyError(key) + + +def patch_stage(show: Show, path: str | Path | None = None) -> StageRig: + """Patch every fixture in the stage map and group cans and movers.""" + source = _map_path(path, show.root or PROJECT_ROOT) + document = json.loads(source.read_text(encoding="utf-8")) + definitions = document.get("definitions") + fixtures = document.get("fixtures") + if not isinstance(definitions, dict) or not isinstance(fixtures, dict): + raise ValueError(f"{source} needs definitions and fixtures") + rig = StageRig(path=source, name=str(document.get("name") or source.stem)) + for key, raw in fixtures.items(): + if not isinstance(raw, dict): + raise ValueError(f"{key} is not a fixture") + defin = definitions.get(raw.get("def")) + if not isinstance(defin, dict): + raise ValueError(f"{key} has no definition {raw.get('def')!r}") + fixture = show.patch( + str(defin["manufacturer"]), + str(defin["model"]), + str(defin["mode"]), + address=int(raw["address"]), + universe=int(raw.get("universe", 0)), + name=str(raw.get("label") or key), + key=str(key), + ) + listed = raw.get("channels") + if isinstance(listed, int) and listed != fixture.channels: + raise ValueError(f"{key} says {listed} channels; {defin['mode']} has {fixture.channels}") + fixture.x = float(raw["x"]) if "x" in raw else None + fixture.y = float(raw["y"]) if "y" in raw else None + fixture.direction = float(raw["direction"]) if "direction" in raw else None + fixture.zero = float(raw["zero"]) if "zero" in raw else None + fixture.kind = str(raw.get("kind") or "") + if fixture.kind == "mover": + rig.movers.append(fixture) + else: + rig.cans.append(fixture) + if rig.cans: + show.group("Cans", rig.cans, columns=len(rig.cans)) + if rig.movers: + show.group("Movers", rig.movers, columns=len(rig.movers)) + return rig + + +def _map_path(path: str | Path | None, root: Path) -> Path: + source = Path(path) if path is not None else root / "stage" / "map.json" + base = root.resolve() + target = source.resolve() if source.is_absolute() else (base / source).resolve() + if target != base and base not in target.parents: + raise ValueError(f"{path} is outside the project") + if not target.is_file(): + raise ValueError(f"stage map not found: {path or target}") + return target diff --git a/showfile/tools.py b/showfile/tools.py new file mode 100644 index 0000000..90cea2c --- /dev/null +++ b/showfile/tools.py @@ -0,0 +1,252 @@ +"""Operations behind the CLI and the MCP server.""" + +from __future__ import annotations + +from pathlib import Path +from typing import Any + +from patternstudio.efx import ( + ALGORITHMS, + DIRECTIONS, + PROPAGATIONS, + RUN_ORDERS, + Efx, + EfxFixture, + Path as EfxPath, + PathFixture, + PathPoint, +) +from patternstudio.fixturedefs import load_fixture_def + +from .play import load_show, play +from .spec import PROJECT_ROOT, SpecError, collect_errors, from_spec, show_schema + +__all__ = [ + "list_fixtures", + "sample_animation", + "show_schema", + "validate_show", + "write_show", + "run_script", +] + + +def list_fixtures(root: Path | None = None) -> dict[str, Any]: + """Manufacturer, model, modes, and channel maps from the project's fixtures/ directory.""" + folder = (root or PROJECT_ROOT) / "fixtures" + fixtures = [] + if folder.is_dir(): + for path in sorted(folder.glob("*.qxf")): + definition = load_fixture_def(str(path)) + fixtures.append( + { + "manufacturer": definition.manufacturer, + "model": definition.model, + "type": definition.type, + "modes": [ + { + "name": mode.name, + "pan_msb": mode.pan_msb, + "pan_lsb": mode.pan_lsb, + "tilt_msb": mode.tilt_msb, + "tilt_lsb": mode.tilt_lsb, + "channels": [ + {"index": ch.index, "name": ch.name, "preset": ch.preset, "group": ch.group} + for ch in mode.channels + ], + } + for mode in definition.modes.values() + ], + } + ) + return {"fixtures": fixtures} + + +def validate_show(spec: dict[str, Any], root: Path | None = None) -> dict[str, Any]: + """Check a show spec. Writes nothing.""" + errors = collect_errors(spec, root=root) + return {"ok": not errors, "errors": errors} + + +def write_show(spec: dict[str, Any], path: str, root: Path | None = None) -> dict[str, Any]: + """Write a .qxw inside the project and return the ids that were assigned.""" + base = (root or PROJECT_ROOT).resolve() + try: + target = _inside(base, path) + show = from_spec(spec, root=base) + except SpecError as exc: + return {"ok": False, "errors": exc.errors} + target.parent.mkdir(parents=True, exist_ok=True) + show.write(target) + return {"ok": True, "path": str(target.relative_to(base)), **show.summary()} + + +def sample_animation(block: dict[str, Any], steps: int = 32) -> dict[str, Any]: + """Pan/tilt samples for one efx or path block, before it is written into a show.""" + if not isinstance(block, dict) or block.get("type") not in ("efx", "path"): + return {"ok": False, "errors": [{"path": "type", "message": "sample an efx or path block"}]} + count = max(1, min(128, int(steps))) + try: + if block["type"] == "efx": + return {"ok": True, **_sample_efx(block, count)} + return {"ok": True, **_sample_path(block)} + except (KeyError, TypeError, ValueError) as exc: + return {"ok": False, "errors": [{"path": "", "message": str(exc)}]} + + +def run_script( + path: str, + *, + seconds: float | None = None, + ip: str | None = None, + universe: int = 0, + hz: float = 40.0, + root: Path | None = None, +) -> dict[str, Any]: + """Play a Python build() script, or a JSON spec, and return samples or send Art-Net.""" + base = (root or PROJECT_ROOT).resolve() + try: + source = _inside(base, path) + show = load_show(source) + return play(show, seconds=seconds, ip=ip, universe=universe, hz=hz) + except SpecError as exc: + return {"ok": False, "errors": exc.errors} + + +def _inside(root: Path, rel: str) -> Path: + candidate = Path(rel) + target = candidate.resolve() if candidate.is_absolute() else (root / candidate).resolve() + if target != root and root not in target.parents: + raise SpecError([{"path": "path", "message": f"{rel} is outside the project"}]) + return target + + +def _sample_efx(block: dict[str, Any], steps: int) -> dict[str, Any]: + algorithm = block.get("algorithm", "Circle") + if algorithm not in ALGORITHMS: + raise ValueError(f"unknown algorithm {algorithm!r}") + _choice(block.get("direction", "Forward"), DIRECTIONS, "direction") + _choice(block.get("run_order", "Loop"), RUN_ORDERS, "run_order") + _choice(block.get("propagation", "Parallel"), PROPAGATIONS, "propagation") + entries = block.get("fixtures") or [] + if not entries: + raise ValueError("efx has no fixtures") + relative = bool(block.get("relative")) + homes = block.get("homes") or {} + fixtures = [] + keys = [] + for index, item in enumerate(entries): + if isinstance(item, str): + key, direction, offset = item, "Forward", 0 + pan = tilt = 128 + elif isinstance(item, dict) and "fixture" in item: + key = str(item["fixture"]) + direction = item.get("direction", "Forward") + offset = int(item.get("start_offset", 0)) + pan = int(item.get("pan", 128)) + tilt = int(item.get("tilt", 128)) + else: + raise ValueError("each efx fixture is a key or {fixture, ...}") + if key in homes: + pan, tilt = int(homes[key][0]), int(homes[key][1]) + keys.append(key) + fixtures.append(EfxFixture(id=index, direction=direction, start_offset=offset, pan=pan, tilt=tilt)) + width = _bounded(block.get("width", 40), 0, 127, "width") + height = _bounded(block.get("height", 40), 0, 127, "height") + duration = int(block.get("duration_ms", 8000)) + if duration < 20: + raise ValueError("duration_ms must be at least 20") + pattern = Efx( + algorithm=algorithm, + width=width, + height=height, + rotation=int(block.get("rotation", 0)) % 360, + start_offset=int(block.get("start_offset", 0)) % 360, + x_offset=127 if relative else _bounded(block.get("x_offset", 128), 0, 255, "x_offset"), + y_offset=127 if relative else _bounded(block.get("y_offset", 128), 0, 255, "y_offset"), + x_frequency=_bounded(block.get("x_frequency", 1), 0, 5, "x_frequency"), + y_frequency=_bounded(block.get("y_frequency", 1), 0, 5, "y_frequency"), + x_phase=int(block.get("x_phase", 0)) % 360, + y_phase=int(block.get("y_phase", 0)) % 360, + duration_ms=duration, + direction=block.get("direction", "Forward"), + run_order=block.get("run_order", "Loop"), + propagation=block.get("propagation", "Parallel"), + relative=relative, + fixtures=fixtures, + ) + sampled = pattern.sample(steps=steps) + for track, fx in zip(sampled["tracks"], fixtures): + track["key"] = keys[fx.id] + if relative: + track["points"] = [ + [ + round(max(0.0, min(255.0, fx.pan + (x - 127))), 2), + round(max(0.0, min(255.0, fx.tilt + (y - 127))), 2), + ] + for x, y in track["points"] + ] + return sampled + + +def _sample_path(block: dict[str, Any]) -> dict[str, Any]: + entries = block.get("fixtures") or [] + points = block.get("points") or [] + if not entries or not points: + raise ValueError("path needs fixtures and points") + fixtures = [] + keys = [] + for index, item in enumerate(entries): + if isinstance(item, str): + key, pan_offset, tilt_offset, mirror_pan, mirror_tilt = item, 0, 0, False, False + elif isinstance(item, dict): + key = str(item["fixture"]) + pan_offset = int(item.get("pan_offset", 0)) + tilt_offset = int(item.get("tilt_offset", 0)) + mirror_pan = bool(item.get("mirror_pan", False)) + mirror_tilt = bool(item.get("mirror_tilt", False)) + else: + raise ValueError("each path fixture is a key or {fixture, mirror_pan}") + keys.append(key) + fixtures.append( + PathFixture( + id=index, + pan_offset=pan_offset, + tilt_offset=tilt_offset, + mirror_pan=mirror_pan, + mirror_tilt=mirror_tilt, + ) + ) + path = EfxPath( + points=[ + PathPoint( + pan=float(point["pan"]), + tilt=float(point["tilt"]), + fade_ms=int(point.get("fade_ms", 1000)), + hold_ms=int(point.get("hold_ms", 0)), + ) + for point in points + ], + smooth=bool(block.get("smooth", False)), + subdivisions=int(block.get("subdivisions", 6)), + closed=bool(block.get("closed", True)), + run_order=block.get("run_order", "Loop"), + direction=block.get("direction", "Forward"), + fixtures=fixtures, + ) + sampled = path.sample() + for track in sampled["tracks"]: + track["key"] = keys[track["id"]] + return sampled + + +def _choice(value: str, allowed: tuple[str, ...], label: str) -> None: + if value not in allowed: + raise ValueError(f"{label} must be one of {', '.join(allowed)}") + + +def _bounded(value: Any, lo: int, hi: int, label: str) -> int: + number = int(value) + if not lo <= number <= hi: + raise ValueError(f"{label} must be {lo}–{hi}") + return number diff --git a/showfile/vc.py b/showfile/vc.py new file mode 100644 index 0000000..b2b29a9 --- /dev/null +++ b/showfile/vc.py @@ -0,0 +1,300 @@ +"""Virtual console widgets.""" + +from __future__ import annotations + +from dataclasses import dataclass, field +from typing import TYPE_CHECKING, Any + +from .model import INVALID_FUNCTION, MidiBinding +from .xmlutil import appearance, attr + +if TYPE_CHECKING: + from .model import Show + + +@dataclass +class Slider: + id: int + caption: str + channels: list[tuple[int, int]] + x: int + y: int + w: int + h: int + value: int = 0 + fg: Any = "Default" + cng: str = "None" + inverted: bool = False + binding: MidiBinding | None = None + type_name: str = "Slider" + + def render(self, indent: str = " ") -> str: + inner = indent + " " + inv = "true" if self.inverted else "false" + channels = "\n".join( + f'{inner} {ch}' for fid, ch in self.channels + ) + extra = _input_xml(self.binding, inner) + return ( + f"{indent}\n' + f'{inner}\n' + f"{appearance(fg=self.fg, indent=inner)}\n" + f'{inner}Level\n' + f"{inner}\n" + f'{inner}\n' + f"{channels}\n" + f"{inner}\n" + f"{inner}\n" + f"{inner} {INVALID_FUNCTION}\n" + f"{inner}{extra}\n" + f"{indent}" + ) + + +@dataclass +class Button: + id: int + caption: str + function_id: int + x: int + y: int + w: int + h: int + fg: Any = "4294967295" + bg: Any = "Default" + action: str = "Toggle" + binding: MidiBinding | None = None + type_name: str = "Button" + + def render(self, indent: str = " ") -> str: + inner = indent + " " + extra = _input_xml(self.binding, inner) + return ( + f"{indent}" + ) + + +@dataclass +class XYPad: + id: int + caption: str + fixture_id: int + x: int + y: int + w: int + h: int + reverse_pan: bool = False + reverse_tilt: bool = False + pan: int = 128 + tilt: int = 128 + binding: MidiBinding | None = None + type_name: str = "XYPad" + + def render(self, indent: str = " ") -> str: + inner = indent + " " + pan_rev = "True" if self.reverse_pan else "False" + tilt_rev = "True" if self.reverse_tilt else "False" + extra = _input_xml(self.binding, inner) + return ( + f"{indent}\n" + f'{inner}\n' + f"{appearance(indent=inner)}\n" + f'{inner}\n' + f'{inner} \n' + f'{inner} \n' + f"{inner}\n" + f'{inner}\n' + f'{inner}\n' + f'{inner}{extra}\n' + f"{indent}" + ) + + +@dataclass +class Frame: + show: Show + caption: str + x: int = 0 + y: int = 0 + w: int = 0 + h: int = 0 + solo: bool = False + root: bool = False + show_header: bool = True + children: list[Any] = field(default_factory=list) + id: int | None = None + type_name: str = "Frame" + + def __post_init__(self) -> None: + self.type_name = "SoloFrame" if self.solo else "Frame" + if not self.root and self.id is None: + self.id = self.show.alloc_widget() + + def slider( + self, + caption: str, + channels: list[tuple[Any, int]], + *, + x: int, + y: int, + w: int, + h: int, + value: int = 0, + fg: Any = "Default", + cng: str = "None", + inverted: bool = False, + input: MidiBinding | None = None, + ) -> Slider: + widget = Slider( + id=self.show.alloc_widget(), + caption=caption, + channels=[(self.show.fixture_id(fx), int(ch)) for fx, ch in channels], + x=x, + y=y, + w=w, + h=h, + value=int(value), + fg=fg, + cng=cng, + inverted=inverted, + binding=input, + ) + self.children.append(widget) + return widget + + def button( + self, + caption: str, + function: Any, + *, + x: int, + y: int, + w: int, + h: int, + fg: Any = "4294967295", + bg: Any = "Default", + action: str = "Toggle", + input: MidiBinding | None = None, + ) -> Button: + if isinstance(function, int): + fid = function + elif isinstance(function, str): + fid = self.show.functions_by_key[function].id + else: + fid = function.id + widget = Button( + id=self.show.alloc_widget(), + caption=caption, + function_id=fid, + x=x, + y=y, + w=w, + h=h, + fg=fg, + bg=bg, + action=action, + binding=input, + ) + self.children.append(widget) + return widget + + def xypad( + self, + caption: str, + fixture: Any, + *, + x: int, + y: int, + w: int, + h: int, + reverse_pan: bool = False, + reverse_tilt: bool = False, + pan: int = 128, + tilt: int = 128, + input: MidiBinding | None = None, + ) -> XYPad: + widget = XYPad( + id=self.show.alloc_widget(), + caption=caption, + fixture_id=self.show.fixture_id(fixture), + x=x, + y=y, + w=w, + h=h, + reverse_pan=reverse_pan, + reverse_tilt=reverse_tilt, + pan=int(pan), + tilt=int(tilt), + binding=input, + ) + self.children.append(widget) + return widget + + def frame( + self, + caption: str, + *, + x: int, + y: int, + w: int, + h: int, + solo: bool = False, + header: bool = True, + ) -> Frame: + child = Frame(self.show, caption, x, y, w, h, solo=solo, show_header=header) + self.children.append(child) + return child + + def solo_frame(self, caption: str, *, x: int, y: int, w: int, h: int) -> Frame: + return self.frame(caption, x=x, y=y, w=w, h=h, solo=True) + + def render(self, indent: str = " ") -> str: + inner = indent + " " + if self.root: + body = "\n".join(child.render(inner) for child in self.children) + parts = [ + f"{indent}", + appearance(frame="None", indent=inner), + ] + if body: + parts.append(body) + parts.append(f"{indent}") + return "\n".join(parts) + tag = "SoloFrame" if self.solo else "Frame" + flags = [ + f"{inner}True", + f"{inner}True", + f"{inner}{'True' if self.show_header else 'False'}", + f"{inner}False", + ] + if not self.solo: + flags.append(f"{inner}False") + flags.append(f"{inner}False") + nested = "\n".join(child.render(inner) for child in self.children) + parts = [ + f"{indent}<{tag} Caption={attr(self.caption)} ID=\"{self.id}\">", + appearance(indent=inner), + f'{inner}', + *flags, + ] + if nested: + parts.append(nested) + parts.append(f"{indent}") + return "\n".join(parts) + + +def _input_xml(binding: MidiBinding | None, indent: str) -> str: + if binding is None: + return "" + return f'\n{indent}' diff --git a/showfile/xml.py b/showfile/xml.py new file mode 100644 index 0000000..22bdf7f --- /dev/null +++ b/showfile/xml.py @@ -0,0 +1,48 @@ +"""Serialize a Show to a QLC+ 4.12 workspace.""" + +from __future__ import annotations + +from .model import Show, Universe, fixture_xml, group_xml, universe_xml + + +def render_show(show: Show) -> str: + universes = list(show.universes) or [Universe(i, f"Universe {i + 1}") for i in range(4)] + universes.sort(key=lambda uni: uni.id) + width, height = show.size() + engine = [" "] + engine.extend(universe_xml(uni) for uni in universes) + engine.append(" ") + engine.extend(fixture_xml(fx) for fx in show.fixtures) + engine.extend(group_xml(group) for group in show.groups) + engine.extend(fn.render() for fn in show.functions) + widgets = show.vc.render(" ") + return ( + '\n' + "\n" + '\n' + " \n" + " Q Light Controller Plus\n" + f" {show.version}\n" + f" {_author(show.author)}\n" + " \n" + " \n" + + "\n".join(engine) + + "\n \n" + " \n" + + widgets + + "\n \n" + f' \n' + ' \n' + " \n" + " \n" + " \n" + " \n" + " \n" + "\n" + ) + + +def _author(name: str) -> str: + from .xmlutil import text + + return text(name) diff --git a/showfile/xmlutil.py b/showfile/xmlutil.py new file mode 100644 index 0000000..1e80060 --- /dev/null +++ b/showfile/xmlutil.py @@ -0,0 +1,48 @@ +"""Small XML helpers shared by the workspace writer.""" + +from __future__ import annotations + +from xml.sax.saxutils import escape, quoteattr + + +def attr(value: object) -> str: + return quoteattr(str(value)) + + +def text(value: object) -> str: + return escape(str(value)) + + +def qlc_color(r: int, g: int, b: int) -> str: + """QLC+ widget colour as a decimal ARGB word.""" + return str((0xFF << 24) | ((int(r) & 255) << 16) | ((int(g) & 255) << 8) | (int(b) & 255)) + + +def colour(value: object, default: str = "Default") -> str: + if value is None: + return default + if isinstance(value, str): + return value + if isinstance(value, int) and not isinstance(value, bool): + return str(value) + if isinstance(value, (list, tuple)) and len(value) == 3: + return qlc_color(int(value[0]), int(value[1]), int(value[2])) + raise TypeError(f"colour must be 'Default', an ARGB decimal, or [r, g, b], not {value!r}") + + +def appearance( + fg: object = "Default", + bg: object = "Default", + frame: str = "Sunken", + indent: str = " ", +) -> str: + inner = indent + " " + return ( + f"{indent}\n" + f"{inner}{text(frame)}\n" + f"{inner}{text(colour(fg))}\n" + f"{inner}{text(colour(bg))}\n" + f"{inner}None\n" + f"{inner}Default\n" + f"{indent}" + ) diff --git a/tests/test_showfile.py b/tests/test_showfile.py new file mode 100644 index 0000000..f558a64 --- /dev/null +++ b/tests/test_showfile.py @@ -0,0 +1,448 @@ +"""Show engine: workspace XML, spec validation, animations, and the agent tools.""" + +from __future__ import annotations + +import json +import subprocess +import sys +import unittest +import xml.etree.ElementTree as ET +from pathlib import Path + +from showfile import Show, midi_note +from showfile.play import load_show +from showfile.tools import list_fixtures, sample_animation, show_schema, validate_show, write_show + +ROOT = Path(__file__).resolve().parents[1] +NS = {"q": "http://www.qlcplus.org/Workspace"} + + +def _xml(spec: dict) -> ET.Element: + show = Show.from_spec(spec) + return ET.fromstring(show.xml()) + + +def _text(root: ET.Element, path: str) -> list[str]: + return [el.text or "" for el in root.findall(path, NS)] + + +class ShowFileTest(unittest.TestCase): + def spec(self) -> dict: + return { + "author": "Jimmy", + "universes": [ + { + "id": 0, + "name": "Universe 1", + "output": { + "plugin": "ArtNet", + "uid": "192.168.1.92", + "ip": "192.168.1.228", + "universe": 0, + "line": 7, + }, + } + ], + "fixtures": [ + { + "key": "m1", + "manufacturer": "Small Eye 7", + "model": "Mover", + "mode": "43 Channel", + "name": "Small Eye 7 #1", + "address": 0, + }, + { + "key": "m2", + "manufacturer": "Small Eye 7", + "model": "Mover", + "mode": "43 Channel", + "name": "Small Eye 7 #2", + "address": 44, + }, + { + "key": "can1", + "manufacturer": "beamZ", + "model": "BCC145", + "mode": "8 Channel", + "address": 87, + }, + ], + "functions": [ + { + "key": "eight", + "type": "efx", + "name": "Figure of 8", + "algorithm": "Eight", + "fixtures": ["m1", "m2"], + "width": 40, + "height": 30, + "x_offset": 128, + "y_offset": 140, + "duration_ms": 8000, + }, + { + "key": "rel", + "type": "efx", + "name": "Rel", + "algorithm": "Circle", + "fixtures": ["m1"], + "width": 20, + "height": 0, + "relative": True, + "homes": {"m1": [100, 140]}, + "duration_ms": 4000, + }, + { + "key": "focus", + "type": "sequence", + "name": "Colour Focus", + "run_order": "SingleShot", + "steps": [ + {"fade_ms": 100, "values": {"m1": {"10": 0}}}, + {"fade_ms": 100, "values": {"m1": {"10": 255}}}, + ], + }, + { + "key": "sweep", + "type": "path", + "name": "Sweep", + "closed": False, + "fixtures": [{"fixture": "m2", "mirror_pan": True}], + "points": [ + {"pan": 80, "tilt": 160, "fade_ms": 1000}, + {"pan": 180, "tilt": 40, "fade_ms": 1000}, + ], + }, + {"key": "red", "type": "scene", "name": "Red", "values": {"can1": {"2": 255, "4": 0}}}, + {"key": "blue", "type": "scene", "name": "Blue", "values": {"can1": {"2": 0, "4": 255}}}, + { + "key": "collapse", + "type": "chaser", + "name": "Ring Collapse", + "run_order": "SingleShot", + "steps": [ + {"function": "red", "fade_ms": 100, "hold_ms": 0}, + {"function": "blue", "fade_ms": 100, "hold_ms": 0}, + ], + }, + { + "key": "cols", + "type": "colour_chase", + "name": "Can Chase", + "fixtures": ["can1"], + "channels": {"r": 2, "g": 3, "b": 4}, + "fade_ms": 0, + "hold_ms": 100, + "frames": [[[255, 0, 0]], [[0, 0, 255]]], + }, + ], + "vc": [ + { + "type": "slider", + "caption": "Dim", + "channels": [["can1", 0]], + "x": 10, + "y": 28, + "w": 44, + "h": 240, + "value": 255, + "fg": [255, 255, 255], + }, + { + "type": "button", + "caption": "Red", + "function": "red", + "x": 20, + "y": 300, + "w": 110, + "h": 60, + "bg": [255, 0, 0], + "input": {"universe": 1, "note": [9, 36]}, + }, + { + "type": "xypad", + "caption": "M1", + "fixture": "m1", + "x": 10, + "y": 28, + "w": 240, + "h": 240, + }, + { + "type": "solo", + "caption": "Looks", + "x": 0, + "y": 400, + "w": 200, + "h": 80, + "children": [ + { + "type": "button", + "caption": "Blue", + "function": "blue", + "x": 4, + "y": 24, + "w": 60, + "h": 40, + } + ], + }, + ], + "run": ["eight"], + } + + def test_workspace_xml_has_patch_widgets_and_animations(self): + show = Show.from_spec(self.spec()) + root = ET.fromstring(show.xml()) + addresses = [int(el.text or "0") for el in root.findall(".//q:Fixture/q:Address", NS)] + self.assertEqual(addresses, [0, 44, 87]) + output = root.find(".//q:Output", NS) + self.assertEqual(output.get("Plugin"), "ArtNet") + self.assertEqual(output.get("Line"), "7") + self.assertEqual(output.find("q:PluginParameters", NS).get("outputIP"), "192.168.1.228") + self.assertEqual(_text(root, ".//q:Algorithm"), ["Eight", "Circle"]) + self.assertEqual(_text(root, ".//q:IsRelative"), ["0", "1"]) + self.assertIn("127", _text(root, ".//q:Axis/q:Offset")) + self.assertIn("0,100", "".join(_text(root, ".//q:FixtureVal"))) + steps = root.findall(".//q:Function[@Type='Sequence']/q:Step", NS) + joined = " ".join(step.text or "" for step in steps) + self.assertIn("0,175", joined) + self.assertIn("10,255", joined) + chaser = root.find(".//q:Function[@Name='Ring Collapse']", NS) + self.assertEqual( + [step.text for step in chaser.findall("q:Step", NS)], + [str(show.functions_by_key["red"].id), str(show.functions_by_key["blue"].id)], + ) + self.assertEqual(show.summary()["functions"]["rel"]["type"], "Collection") + self.assertIsNotNone(root.find(".//q:SoloFrame", NS)) + button = root.find(".//q:Button[@Caption='Red']", NS) + self.assertEqual(button.find("q:Input", NS).get("Channel"), str(midi_note(9, 36))) + self.assertEqual(button.find("q:Function", NS).get("ID"), str(show.functions_by_key["red"].id)) + slider = root.find(".//q:Slider", NS) + self.assertEqual(slider.find("q:Level", NS).get("Value"), "255") + self.assertEqual(slider.find("q:Level/q:Channel", NS).text, "0") + + def test_playback_moves_and_fades(self): + show = Show.from_spec(self.spec()) + pans = {show_frame(show, t, ["eight"])["m1"][0] for t in range(0, 8000, 500)} + self.assertGreater(len(pans), 1) + self.assertEqual(show_frame(show, 0, ["eight"])["m1"][8], 255) + relative = {show_frame(show, t, ["rel"])["m1"][0] for t in range(0, 4000, 250)} + self.assertIn(100, relative) + self.assertGreater(len(relative), 1) + self.assertEqual(show_frame(show, 0, ["collapse"])["can1"][2], 0) + self.assertEqual(show_frame(show, 100, ["collapse"])["can1"][2], 255) + self.assertEqual(show_frame(show, 150, ["collapse"])["can1"], {2: 128, 4: 128}) + self.assertEqual(show_frame(show, 200, ["collapse"])["can1"], {2: 0, 4: 255}) + self.assertEqual(show_frame(show, 0, ["cols"])["can1"][2], 255) + self.assertEqual(show_frame(show, 100, ["cols"])["can1"][2], 0) + self.assertEqual(show_frame(show, 50, ["focus"])["m1"][10], 0) + self.assertEqual(show_frame(show, 150, ["focus"])["m1"][10], 128) + + def test_validation_names_the_key_and_write_stays_inside_the_project(self): + result = validate_show( + { + "fixtures": [ + {"key": "can1", "manufacturer": "beamZ", "model": "BCC145", "mode": "nope", "address": 0} + ], + "functions": [{"key": "eight", "type": "efx", "name": "E", "fixtures": ["missing"]}], + } + ) + self.assertFalse(result["ok"]) + self.assertIn("fixtures.can1.mode", [item["path"] for item in result["errors"]]) + self.assertIn("functions.eight.fixtures", [item["path"] for item in result["errors"]]) + refused = write_show({}, "/tmp/showfile-outside.qxw") + self.assertFalse(refused["ok"]) + self.assertFalse(Path("/tmp/showfile-outside.qxw").exists()) + + def test_tools_list_schema_sample_and_write(self): + fixtures = list_fixtures() + bcc = next(item for item in fixtures["fixtures"] if item["model"] == "BCC145") + mode = next(item for item in bcc["modes"] if item["name"] == "8 Channel") + self.assertEqual(mode["channels"][0]["name"], "Dimmer") + self.assertIn("fixtures", show_schema()["properties"]) + sample = sample_animation( + { + "type": "efx", + "algorithm": "Eight", + "fixtures": ["m1", "m2"], + "width": 40, + "height": 30, + "duration_ms": 8000, + "relative": True, + "homes": {"m1": [128, 140], "m2": [100, 140]}, + }, + steps=8, + ) + self.assertTrue(sample["ok"]) + self.assertEqual([track["key"] for track in sample["tracks"]], ["m1", "m2"]) + self.assertGreater(len({point[0] for point in sample["tracks"][0]["points"]}), 1) + target = ROOT / "shows" / "_showfile_test.qxw" + try: + written = write_show(self.spec(), "shows/_showfile_test.qxw") + self.assertTrue(written["ok"]) + self.assertEqual(written["fixtures"]["can1"]["address"], 87) + self.assertEqual(written["functions"]["eight"]["type"], "EFX") + self.assertEqual(written["functions"]["rel"]["type"], "Collection") + self.assertTrue(target.is_file()) + finally: + target.unlink(missing_ok=True) + + def test_animation_script_dry_run(self): + show = load_show(ROOT / "scripts" / "anim_eight.py") + frames = [show_frame(show, t) for t in (0, 2000)] + self.assertNotEqual(frames[0]["m1"][2], frames[1]["m1"][2]) + self.assertEqual(frames[0]["m1"][8], 255) + completed = subprocess.run( + [sys.executable, "-m", "showfile", "run", "scripts/anim_eight.py", "--seconds", "0.1"], + cwd=ROOT, + check=False, + capture_output=True, + text=True, + ) + self.assertEqual(completed.returncode, 0, completed.stderr) + payload = json.loads(completed.stdout) + self.assertTrue(payload["ok"]) + self.assertEqual(payload["functions"], ["eight"]) + self.assertGreaterEqual(len(payload["samples"]), 1) + + def test_simple_board_matches_the_stage_patch(self): + spec = json.loads((ROOT / "shows" / "simple.show.json").read_text(encoding="utf-8")) + show = Show.from_spec(spec) + root = ET.fromstring(show.xml()) + addresses = [int(el.text or "0") for el in root.findall(".//q:Fixture/q:Address", NS)] + self.assertEqual(addresses, [87, 95, 103, 111, 119, 127, 135, 143, 0, 44]) + captions = [el.get("Caption") for el in root.findall(".//q:XYPad", NS)] + self.assertEqual(captions, ["M1 Position", "M2 Position"]) + sliders = root.findall(".//q:Slider", NS) + self.assertEqual(len(sliders), 50) + dim = next(el for el in sliders if el.get("Caption") == "C Dim") + self.assertEqual(dim.find("q:Level", NS).get("Value"), "255") + self.assertEqual(len(dim.findall("q:Level/q:Channel", NS)), 8) + self.assertEqual( + [el.get("Caption") for el in root.findall(".//q:Frame", NS) if el.get("Caption")], + ["Cans individual RGBW", "Movers individual RGBW"], + ) + size = root.find(".//q:Properties/q:Size", NS) + self.assertEqual((size.get("Width"), size.get("Height")), ("1654", "480")) + + def test_stage_map_drives_the_whole_rig(self): + stage = json.loads((ROOT / "stage" / "map.json").read_text(encoding="utf-8")) + show = load_show(ROOT / "scripts" / "anim_stage.py") + self.assertEqual([fx.key for fx in show.fixtures], list(stage["fixtures"])) + for key, raw in stage["fixtures"].items(): + fixture = show.fixtures_by_key[key] + self.assertEqual(fixture.address, raw["address"]) + self.assertEqual(fixture.x, raw["x"]) + self.assertEqual(fixture.y, raw["y"]) + if "direction" in raw: + self.assertEqual(fixture.direction, raw["direction"]) + if "zero" in raw: + self.assertEqual(fixture.zero, raw["zero"]) + self.assertEqual(show.fixtures_by_key["#1"].channel("Red"), 2) + self.assertEqual(len(show.fixtures_by_key["M1"].named("Red")), 7) + self.assertEqual([group.name for group in show.groups], ["Cans", "Movers"]) + from showfile.play import dmx_frames + + frame = show_frame(show, 100) + dmx = dmx_frames(show, frame) + self.assertEqual(dmx[0][87], 255) + self.assertEqual(dmx[0][300 + 8], 255) + self.assertEqual(frame["M1"][show.fixtures_by_key["M1"].channel("Zoom")], 40) + colour = sum( + frame[key][2] + frame[key][3] + frame[key][4] + for key, raw in stage["fixtures"].items() + if raw["kind"] == "can" + ) + self.assertGreater(colour, 0) + tracks = [] + for key in ("M1", "M3"): + tracks.append([(show_frame(show, t)[key][0], show_frame(show, t)[key][2]) for t in range(0, 3000, 250)]) + self.assertGreater(len(set(tracks[0])), 1) + self.assertNotEqual(tracks[0], tracks[1]) + spec = Show.from_spec({"stage": "stage/map.json", "run": []}) + self.assertEqual(spec.fixtures_by_key["M4"].address, 300) + self.assertEqual(spec.fixtures_by_key["#15"].address, 199) + missing = validate_show({"stage": "stage/no-such.json"}) + self.assertFalse(missing["ok"]) + self.assertEqual(missing["errors"][0]["path"], "stage") + outside = validate_show({"stage": "/etc/passwd"}) + self.assertFalse(outside["ok"]) + completed = subprocess.run( + [sys.executable, "-m", "showfile", "run", "scripts/anim_stage.py", "--seconds", "0.1"], + cwd=ROOT, + check=False, + capture_output=True, + text=True, + ) + self.assertEqual(completed.returncode, 0, completed.stderr) + payload = json.loads(completed.stdout) + self.assertTrue(payload["ok"]) + self.assertEqual(payload["functions"], ["stage"]) + + def test_mcp_lists_and_calls_a_tool(self): + proc = subprocess.Popen( + [sys.executable, "-m", "showfile.mcp"], + cwd=ROOT, + stdin=subprocess.PIPE, + stdout=subprocess.PIPE, + ) + assert proc.stdin and proc.stdout + try: + _mcp(proc, {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}}) + _mcp(proc, {"jsonrpc": "2.0", "method": "notifications/initialized"}) + listed = _mcp(proc, {"jsonrpc": "2.0", "id": 2, "method": "tools/list"}) + names = [tool["name"] for tool in listed["result"]["tools"]] + self.assertEqual( + names, + ["list_fixtures", "show_schema", "validate_show", "write_show", "sample_animation", "run_animation"], + ) + called = _mcp( + proc, + { + "jsonrpc": "2.0", + "id": 3, + "method": "tools/call", + "params": {"name": "list_fixtures", "arguments": {}}, + }, + ) + body = json.loads(called["result"]["content"][0]["text"]) + self.assertIn("BCC145", [item["model"] for item in body["fixtures"]]) + finally: + if proc.stdin: + proc.stdin.close() + try: + proc.wait(timeout=2) + except subprocess.TimeoutExpired: + proc.kill() + proc.wait(timeout=5) + if proc.stdout: + proc.stdout.close() + + +def show_frame(show: Show, elapsed: float, keys: list[str] | None = None) -> dict: + from showfile import frame_at + + return frame_at(show, elapsed, keys) + + +def _mcp(proc: subprocess.Popen, message: dict) -> dict: + data = json.dumps(message).encode() + assert proc.stdin and proc.stdout + proc.stdin.write(f"Content-Length: {len(data)}\r\n\r\n".encode() + data) + proc.stdin.flush() + if "id" not in message: + return {} + headers = {} + while True: + line = proc.stdout.readline() + if line in (b"\r\n", b"\n"): + break + key, _, value = line.decode().partition(":") + headers[key.strip().lower()] = value.strip() + return json.loads(proc.stdout.read(int(headers["content-length"]))) + + +if __name__ == "__main__": + unittest.main()