pyvmancer 0.1.0__py3-none-any.whl

pyvmancer/__init__.py

@@ -0,0 +1,67 @@
+"""Automate the LZX Industries Videomancer over USB MIDI and USB serial."""
+
+from .const import (
+    EMBEDDED_PROGRAMS,
+    OPERATORS,
+    PARAM_COUNT,
+    PARAM_DEFAULTS,
+    PARAM_MAX,
+    PARAM_MIN,
+    LogLevel,
+    Operator,
+    OperatorCategory,
+    ParamKind,
+    PresetBank,
+    TransportState,
+    param_kind,
+    resolve_operator,
+)
+from .device import Videomancer, open_midi, open_shell
+from .discovery import DeviceInfo, find_device, find_devices
+from .errors import (
+    DeviceNotFoundError,
+    ShellError,
+    ShellTimeoutError,
+    TransportError,
+    TransportUnavailableError,
+    VmancerError,
+)
+from .midi import MidiController
+from .shell import Reply, ShellClient, encode_preset, parse_line
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DeviceInfo",
+    "DeviceNotFoundError",
+    "EMBEDDED_PROGRAMS",
+    "LogLevel",
+    "MidiController",
+    "OPERATORS",
+    "Operator",
+    "OperatorCategory",
+    "PARAM_COUNT",
+    "PARAM_DEFAULTS",
+    "PARAM_MAX",
+    "PARAM_MIN",
+    "ParamKind",
+    "PresetBank",
+    "Reply",
+    "ShellClient",
+    "ShellError",
+    "ShellTimeoutError",
+    "TransportError",
+    "TransportState",
+    "TransportUnavailableError",
+    "Videomancer",
+    "VmancerError",
+    "__version__",
+    "encode_preset",
+    "find_device",
+    "find_devices",
+    "open_midi",
+    "open_shell",
+    "param_kind",
+    "parse_line",
+    "resolve_operator",
+]

pyvmancer/cli.py

@@ -0,0 +1,151 @@
+"""Command-line interface: ``vmancer <subcommand>``."""
+
+import argparse
+import json
+import sys
+
+from . import __version__
+from .const import OPERATORS, PARAM_COUNT
+from .device import open_midi, open_shell
+from .discovery import find_devices
+from .errors import VmancerError
+
+
+def _param_value(text):
+    """Parse a CLI parameter value as bool, float or device-unit int."""
+    lowered = text.strip().lower()
+    if lowered in ("on", "true", "yes"):
+        return True
+    if lowered in ("off", "false", "no"):
+        return False
+    if "." in lowered:
+        return float(lowered)
+    return int(lowered)
+
+
+def _assignment(text):
+    """Parse a ``P=V`` assignment into ``(param, value)``."""
+    key, sep, value = text.partition("=")
+    if not sep:
+        raise argparse.ArgumentTypeError(f"expected PARAM=VALUE, got {text!r}")
+    param = int(key)
+    if not 1 <= param <= PARAM_COUNT:
+        raise argparse.ArgumentTypeError(f"parameter must be 1..{PARAM_COUNT}, got {param}")
+    return param, _param_value(value)
+
+
+def _print_json(data):
+    """Emit a JSON document on stdout."""
+    print(json.dumps(data, indent=2, default=str))
+
+
+def build_parser():
+    """Construct the argument parser."""
+    parser = argparse.ArgumentParser(prog="vmancer", description=__doc__)
+    parser.add_argument("--version", action="version", version=f"pyvmancer {__version__}")
+    parser.add_argument("--serial", dest="serial_number", help="target a specific device serial")
+    parser.add_argument("--channel", type=int, help="MIDI channel 1-16 (default: omni/1)")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("devices", help="list attached Videomancers and their device nodes")
+    sub.add_parser("operators", help="list modulation operators and their ids")
+
+    setter = sub.add_parser("set", help="set parameters, e.g. set 1=0.5 7=on")
+    setter.add_argument("assignments", nargs="+", type=_assignment)
+
+    trigger = sub.add_parser("trigger", help="send a note trigger to a parameter")
+    trigger.add_argument("param", type=int)
+    trigger.add_argument("--velocity", type=int, default=127)
+
+    preset = sub.add_parser("preset", help="recall a preset by MIDI program change")
+    preset.add_argument("program", type=int)
+
+    clock = sub.add_parser("clock", help="emit MIDI clock at a tempo")
+    clock.add_argument("bpm", type=float)
+    clock.add_argument("--beats", type=float, default=4.0)
+
+    sub.add_parser("status", help="query device status over serial")
+    sub.add_parser("programs", help="list installed FPGA programs over serial")
+    sub.add_parser("presets", help="list factory and user presets over serial")
+
+    load = sub.add_parser("load", help="load an FPGA program by name over serial")
+    load.add_argument("name")
+
+    shell_cmd = sub.add_parser("shell", help="run a raw serial shell command")
+    shell_cmd.add_argument("words", nargs="+")
+    return parser
+
+
+def _run_midi(args):
+    """Handle subcommands that only need the MIDI link."""
+    with open_midi(serial_number=args.serial_number, channel=args.channel) as midi:
+        if args.command == "set":
+            midi.set_params(dict(args.assignments))
+            _print_json({"state": midi.state.tolist()})
+        elif args.command == "trigger":
+            midi.pulse(args.param, velocity=args.velocity)
+        elif args.command == "preset":
+            midi.select_preset(args.program)
+        elif args.command == "clock":
+            midi.run_clock(args.bpm, args.beats)
+    return 0
+
+
+def _run_shell(args):
+    """Handle subcommands that need the serial link."""
+    with open_shell(serial_number=args.serial_number) as shell:
+        if args.command == "status":
+            _print_json(shell.status())
+        elif args.command == "programs":
+            _print_json(shell.programs())
+        elif args.command == "presets":
+            _print_json(shell.presets())
+        elif args.command == "load":
+            shell.load_program(args.name)
+        elif args.command == "shell":
+            print(shell.command(*args.words).payload)
+    return 0
+
+
+def main(argv=None):
+    """Entry point for the ``vmancer`` console script."""
+    args = build_parser().parse_args(argv)
+    try:
+        if args.command == "devices":
+            _print_json([vars_of(d) for d in find_devices()])
+            return 0
+        if args.command == "operators":
+            _print_json(
+                {
+                    info.name: {
+                        "id": int(info.operator),
+                        "glyph": info.glyph,
+                        "category": info.category.value,
+                        "per_line": info.per_line,
+                        "transport": info.transport.value,
+                    }
+                    for info in OPERATORS.values()
+                }
+            )
+            return 0
+        if args.command in ("set", "trigger", "preset", "clock"):
+            return _run_midi(args)
+        return _run_shell(args)
+    except (VmancerError, ValueError) as err:
+        print(f"error: {err}", file=sys.stderr)
+        return 1
+
+
+def vars_of(info):
+    """Render a :class:`~pyvmancer.discovery.DeviceInfo` as a plain dict."""
+    return {
+        "serial": info.serial_number,
+        "rawmidi": info.rawmidi,
+        "tty": info.tty,
+        "block": info.block,
+        "usbfs": info.usbfs_path,
+    }
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pyvmancer/const.py

@@ -0,0 +1,279 @@
+"""Videomancer protocol constants.
+
+Sourced from the LZX Industries Videomancer user manual, modulation guide and
+serial command guide. See ``docs/protocol.md`` for provenance of each table.
+"""
+
+from enum import Enum, IntEnum
+
+USB_VID = 0x16D0
+USB_PID = 0x14DB
+USB_MANUFACTURER = "LZX Industries"
+USB_PRODUCT = "Videomancer"
+
+PARAM_COUNT = 12
+PARAM_MIN = 0
+PARAM_MAX = 1023
+PARAM_CENTER = 512
+#: A toggle reads as "on" when its combined value is >= this midpoint.
+BOOL_THRESHOLD = 512
+
+#: Per-parameter values on a freshly loaded program.
+PARAM_DEFAULTS = (512, 512, 512, 512, 512, 512, 0, 0, 0, 0, 0, 512)
+
+#: Default CC (MSB) for parameters P1..P12.
+DEFAULT_CC_MSB = tuple(range(PARAM_COUNT))
+#: 14-bit CC pairing offset: the LSB controller is always MSB + 32.
+CC_LSB_OFFSET = 32
+CC_MIN = 0
+CC_MAX = 127
+
+#: MIDI notes 0..11 trigger modulators P1..P12.
+NOTE_BASE = 0
+
+MIDI_CLOCK_PPQN = 24
+BPM_MIN = 10.0
+BPM_MAX = 400.0
+#: ``transport bpm`` takes hundredths of a BPM.
+BPM_SCALE = 100
+
+SHELL_MAX_LINE = 511
+SHELL_OK = "ok"
+SHELL_PATH_PREFIX = "sd:/"
+
+
+class ParamKind(Enum):
+    """Physical control backing each parameter slot."""
+
+    KNOB = "knob"
+    TOGGLE = "toggle"
+    FADER = "fader"
+
+
+def param_kind(param):
+    """Return the :class:`ParamKind` for a 1-based parameter number."""
+    if not 1 <= param <= PARAM_COUNT:
+        raise ValueError(f"parameter must be 1..{PARAM_COUNT}, got {param}")
+    if param <= 6:
+        return ParamKind.KNOB
+    if param <= 11:
+        return ParamKind.TOGGLE
+    return ParamKind.FADER
+
+
+#: Parameters that render per-scanline when driven by a per-line operator.
+PER_LINE_PARAMS = frozenset({1, 2, 3, 4, 5, 6, 12})
+
+
+class Operator(IntEnum):
+    """Modulation operators, by the numeric id used in preset ``sr:`` fields.
+
+    Ids 23..28 are not documented and are intentionally absent; resolve those
+    from the device with ``program state`` rather than guessing.
+    """
+
+    DISABLED = 0
+    FREE_LFO = 1
+    RANDOM = 2
+    TURING_MACHINE = 3
+    BOUNCING_BALL = 4
+    LOGISTIC_MAP = 5
+    EUCLIDEAN_RHYTHM = 6
+    SYNC_LFO = 7
+    AUDIO_INPUT = 8
+    COMPARATOR = 9
+    PENDULUM = 10
+    DRIFT = 11
+    RING_MOD = 12
+    CELLULAR = 13
+    PULSE_WIDTH = 14
+    PEAK_HOLD = 15
+    FIELD_ACCUM = 16
+    SLEW_LIMITER = 17
+    PERLIN_NOISE = 18
+    WAVEFOLDER = 19
+    CLOCK_DIV = 20
+    PROB_GATE = 21
+    QUANTIZER = 22
+    MIDI_TURING = 29
+    CV_INPUT = 30
+
+
+class OperatorCategory(Enum):
+    """Grouping used by the modulation guide."""
+
+    NONE = "none"
+    OSCILLATORS = "oscillators"
+    RANDOM_CHAOS = "random & chaos"
+    EXTERNAL_INPUT = "external input"
+    PHYSICS = "physics"
+    SEQUENCING = "sequencing & rhythm"
+
+
+class Transport(Enum):
+    """Operator clocking: free-running, or gated by transport playback."""
+
+    FREE_RUN = "free-run"
+    TEMPO = "tempo"
+
+
+_OPS = (
+    # (operator, display glyph, category, per-line capable, transport)
+    (Operator.DISABLED, "·", OperatorCategory.NONE, False, Transport.FREE_RUN),
+    (Operator.FREE_LFO, "L", OperatorCategory.OSCILLATORS, False, Transport.FREE_RUN),
+    (Operator.RANDOM, "R", OperatorCategory.RANDOM_CHAOS, False, Transport.FREE_RUN),
+    (Operator.TURING_MACHINE, "U", OperatorCategory.RANDOM_CHAOS, False, Transport.FREE_RUN),
+    (Operator.BOUNCING_BALL, "B", OperatorCategory.PHYSICS, False, Transport.FREE_RUN),
+    (Operator.LOGISTIC_MAP, "X", OperatorCategory.RANDOM_CHAOS, False, Transport.FREE_RUN),
+    (Operator.EUCLIDEAN_RHYTHM, "Y", OperatorCategory.SEQUENCING, False, Transport.FREE_RUN),
+    (Operator.SYNC_LFO, "M", OperatorCategory.OSCILLATORS, False, Transport.TEMPO),
+    (Operator.AUDIO_INPUT, "A", OperatorCategory.EXTERNAL_INPUT, True, Transport.FREE_RUN),
+    (Operator.COMPARATOR, "K", OperatorCategory.EXTERNAL_INPUT, True, Transport.FREE_RUN),
+    (Operator.PENDULUM, "N", OperatorCategory.PHYSICS, False, Transport.FREE_RUN),
+    (Operator.DRIFT, "W", OperatorCategory.RANDOM_CHAOS, False, Transport.FREE_RUN),
+    (Operator.RING_MOD, "*", OperatorCategory.EXTERNAL_INPUT, True, Transport.FREE_RUN),
+    (Operator.CELLULAR, "#", OperatorCategory.RANDOM_CHAOS, False, Transport.FREE_RUN),
+    (Operator.PULSE_WIDTH, "P", OperatorCategory.OSCILLATORS, False, Transport.FREE_RUN),
+    (Operator.PEAK_HOLD, "J", OperatorCategory.EXTERNAL_INPUT, True, Transport.FREE_RUN),
+    (Operator.FIELD_ACCUM, "I", OperatorCategory.EXTERNAL_INPUT, False, Transport.FREE_RUN),
+    (Operator.SLEW_LIMITER, "/", OperatorCategory.EXTERNAL_INPUT, False, Transport.FREE_RUN),
+    (Operator.PERLIN_NOISE, "~", OperatorCategory.RANDOM_CHAOS, False, Transport.FREE_RUN),
+    (Operator.WAVEFOLDER, "Z", OperatorCategory.OSCILLATORS, False, Transport.FREE_RUN),
+    (Operator.CLOCK_DIV, "V", OperatorCategory.SEQUENCING, False, Transport.TEMPO),
+    (Operator.PROB_GATE, "p", OperatorCategory.SEQUENCING, False, Transport.FREE_RUN),
+    (Operator.QUANTIZER, "O", OperatorCategory.EXTERNAL_INPUT, True, Transport.FREE_RUN),
+    (Operator.MIDI_TURING, "T", OperatorCategory.RANDOM_CHAOS, False, Transport.FREE_RUN),
+    (Operator.CV_INPUT, "C", OperatorCategory.EXTERNAL_INPUT, True, Transport.FREE_RUN),
+)
+
+
+#: Words that keep their casing in operator display names.
+_ACRONYMS = {"LFO": "LFO", "CV": "CV", "MIDI": "MIDI", "ACCUM": "Accum", "PROB": "Prob"}
+
+
+class OperatorInfo:
+    """Static metadata for one modulation operator."""
+
+    __slots__ = ("operator", "glyph", "category", "per_line", "transport")
+
+    def __init__(self, operator, glyph, category, per_line, transport):
+        self.operator = operator
+        self.glyph = glyph
+        self.category = category
+        self.per_line = per_line
+        self.transport = transport
+
+    @property
+    def name(self):
+        """Human-readable operator name, e.g. ``"Free LFO"``."""
+        words = self.operator.name.split("_")
+        return " ".join(_ACRONYMS.get(word, word.title()) for word in words)
+
+    def __repr__(self):
+        return f"OperatorInfo({self.name!r}, id={int(self.operator)})"
+
+
+OPERATORS = {row[0]: OperatorInfo(*row) for row in _OPS}
+
+_OPERATOR_BY_NAME = {}
+for _info in OPERATORS.values():
+    _OPERATOR_BY_NAME[_info.operator.name.lower()] = _info.operator
+    _OPERATOR_BY_NAME[_info.name.lower()] = _info.operator
+
+
+def resolve_operator(value):
+    """Coerce an int, :class:`Operator` or name string to an :class:`Operator`."""
+    if isinstance(value, Operator):
+        return value
+    if isinstance(value, int):
+        return Operator(value)
+    key = str(value).strip().lower().replace("-", " ")
+    try:
+        return _OPERATOR_BY_NAME[key]
+    except KeyError:
+        raise ValueError(f"unknown operator {value!r}") from None
+
+
+#: Operators triggered by MIDI note-on for their parameter slot.
+NOTE_TRIGGERED = frozenset({Operator.BOUNCING_BALL, Operator.PENDULUM, Operator.MIDI_TURING})
+
+#: Modulation knobs shared by every operator.
+MOD_KNOBS = ("time", "space", "slope")
+
+#: Preset payload field names used by ``program presets save``.
+PRESET_FIELDS = {
+    "manual": "m",
+    "time": "t",
+    "space": "sp",
+    "slope": "sl",
+    "source": "sr",
+}
+
+
+class PresetBank(Enum):
+    """Preset storage bank."""
+
+    FACTORY = "factory"
+    USER = "user"
+
+
+class TransportState(Enum):
+    """Values reported by ``transport status``."""
+
+    STOPPED = "stopped"
+    PLAYING = "playing"
+    PAUSED = "paused"
+
+
+class LogLevel(Enum):
+    """Argument to the ``log level`` command."""
+
+    TRACE = "trace"
+    DEBUG = "debug"
+    INFO = "info"
+    WARN = "warn"
+    ERROR = "error"
+    NONE = "none"
+
+
+class ShellErrorCode(IntEnum):
+    """Numeric error codes returned as ``!<code>:<message>``."""
+
+    UNKNOWN_COMMAND = 1
+    PARSE_ERROR = 2
+    SERVICE_UNAVAILABLE = 3
+    BUFFER_OVERFLOW = 4
+    NOT_CONNECTED = 5
+    FILE_NOT_FOUND = 6
+    IO_ERROR = 7
+    SD_NOT_MOUNTED = 8
+    PATH_TOO_LONG = 9
+    INVALID_PATH = 10
+
+
+#: Firmware-embedded programs; query ``programs list`` for the full SD-backed set.
+EMBEDDED_PROGRAMS = (
+    "bitcullis",
+    "corollas",
+    "delirium",
+    "elastica",
+    "faultplane",
+    "fauxtress",
+    "glorious",
+    "howler",
+    "isotherm",
+    "kintsugi",
+    "lumarian",
+    "moire",
+    "mycelium",
+    "perlin",
+    "pinwheel",
+    "pong",
+    "sabattier",
+    "scramble",
+    "shadebob",
+    "stic",
+    "stipple",
+    "yuv_amplifier",
+    "yuv_phaser",
+)