plexi-sdk 0.4.0__py3-none-any.whl

plexi_sdk/_types.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional
+
+
+class CapabilityDeniedError(RuntimeError):
+    """Raised when the host rejects a brokered call because the app's manifest
+    didn't declare the required capability. Distinct from generic RuntimeError
+    so apps can catch the gate-denial path explicitly."""
+
+
+# ── Video substrate (#345) types ──────────────────────────────────────────────
+
+@dataclass
+class VideoHandle:
+    """Result of `Emitter.open_video`. `handle_id` is opaque — pass it back to
+    `set_video_state` and `close_video`. The associated `Pipe` delivers
+    decoded RGBA8 frames (one frame per `pipe.read_frame()`) of length
+    `width * height * 4`."""
+    handle_id: int
+    width: int
+    height: int
+    fps: float
+    duration_ms: int
+    pipe: "object"  # Pipe — avoid circular import; typed as object here
+
+
+# ── Typed draw command dataclasses (#627) ─────────────────────────────────────
+
+_VALID_TEXT_ALIGN = {"top_left", "center", "top_center", "right"}
+
+
+@dataclass
+class RectCommand:
+    """Typed constructor for ctx.rect(). Validates geometry at construction."""
+    x: float
+    y: float
+    w: float
+    h: float
+    fill: str
+    radius: float = 0.0
+
+    def __post_init__(self) -> None:
+        if self.w < 0 or self.h < 0:
+            raise ValueError(f"RectCommand: w and h must be non-negative, got w={self.w}, h={self.h}")
+        if not self.fill.startswith("#"):
+            raise ValueError(f"RectCommand: fill must be a hex color string (e.g. '#1e1e2e'), got {self.fill!r}")
+
+
+@dataclass
+class TextCommand:
+    """Typed constructor for ctx.text(). Validates align at construction."""
+    x: float
+    y: float
+    text: str
+    size: float
+    color: str
+    monospace: bool = False
+    bold: bool = False
+    align: str = "top_left"
+    max_width: Optional[float] = None
+    elide: bool = True
+    selectable: bool = False
+
+    def __post_init__(self) -> None:
+        if self.align not in _VALID_TEXT_ALIGN:
+            raise ValueError(
+                f"TextCommand: align must be one of {sorted(_VALID_TEXT_ALIGN)}, got {self.align!r}"
+            )
+        if self.size <= 0:
+            raise ValueError(f"TextCommand: size must be positive, got {self.size}")
+
+
+@dataclass
+class BadgeCommand:
+    """Typed constructor for ctx.badge()."""
+    x: float
+    y_center: float
+    label: str
+    fill: str = "#89b4fa"  # ACCENT
+    fg: str = "#1e1e2e"    # BG
+    font_size: float = 11.0
+    radius: float = 8.0
+
+    def __post_init__(self) -> None:
+        if self.font_size <= 0:
+            raise ValueError(f"BadgeCommand: font_size must be positive, got {self.font_size}")
+        if self.radius < 0:
+            raise ValueError(f"BadgeCommand: radius must be non-negative, got {self.radius}")
+
+
+@dataclass
+class TextInputSpec:
+    """Typed constructor for ctx.text_input()."""
+    id: str
+    x: float
+    y: float
+    w: float
+    placeholder: str = ""
+    multiline: bool = False
+    h: float = 24.0
+
+    def __post_init__(self) -> None:
+        if not self.id:
+            raise ValueError("TextInputSpec: id must be a non-empty string")
+        if self.w <= 0:
+            raise ValueError(f"TextInputSpec: w must be positive, got {self.w}")
+
+
+@dataclass
+class ShortcutPair:
+    """Typed constructor for one entry in ctx.shortcuts() pairs."""
+    keys: List[str]
+    description: str = ""
+
+    def __post_init__(self) -> None:
+        if not self.keys:
+            raise ValueError("ShortcutPair: keys must be a non-empty list")
+
+
+@dataclass
+class NotifyOption:
+    """Typed constructor for one option in ctx.notify_choice()."""
+    label: str
+    value: Optional[str] = None
+    shortcut: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        if not self.label:
+            raise ValueError("NotifyOption: label must be a non-empty string")
+
+    def to_dict(self) -> dict:
+        d: dict = {"label": self.label}
+        if self.value is not None:
+            d["value"] = self.value
+        if self.shortcut is not None:
+            d["shortcut"] = self.shortcut
+        return d

plexi_sdk/midi.py

@@ -0,0 +1,222 @@
+"""plexi_sdk.midi — MIDI 1.0 message constructors + decoders.
+
+Apps construct MIDI byte streams with these helpers and pass them to
+`emit.send_midi(port_id, bytes)`. Apps decode incoming pipe frames with
+`decode(bytes)` to get a structured `MidiMessage`.
+
+Spec reference: MIDI 1.0 detailed specification (channel-voice 0x80..=0xEF,
+system real-time 0xF8..=0xFF). SysEx (0xF0..0xF7) is out of scope for v3.4.
+
+All channel arguments are 0-indexed (channel 0 = MIDI channel 1 in DAWs).
+All note / CC / value arguments are 0..=127.
+"""
+
+from dataclasses import dataclass
+
+
+# ── Message constructors ─────────────────────────────────────────────────────
+
+
+def note_on(channel: int, note: int, velocity: int) -> bytes:
+    """NoteOn: 0x9c, note, velocity. velocity=0 is canonically NoteOff."""
+    _check_channel(channel)
+    _check_byte(note, "note")
+    _check_byte(velocity, "velocity")
+    return bytes([0x90 | (channel & 0x0F), note, velocity])
+
+
+def note_off(channel: int, note: int, velocity: int = 0) -> bytes:
+    """NoteOff: 0x8c, note, velocity. velocity=0 is the conventional value."""
+    _check_channel(channel)
+    _check_byte(note, "note")
+    _check_byte(velocity, "velocity")
+    return bytes([0x80 | (channel & 0x0F), note, velocity])
+
+
+def cc(channel: int, controller: int, value: int) -> bytes:
+    """Control Change: 0xBc, controller, value."""
+    _check_channel(channel)
+    _check_byte(controller, "controller")
+    _check_byte(value, "value")
+    return bytes([0xB0 | (channel & 0x0F), controller, value])
+
+
+def program_change(channel: int, program: int) -> bytes:
+    """Program Change: 0xCc, program. 2-byte message (no second data byte)."""
+    _check_channel(channel)
+    _check_byte(program, "program")
+    return bytes([0xC0 | (channel & 0x0F), program])
+
+
+def pitch_bend(channel: int, value: int) -> bytes:
+    """Pitch Bend: 0xEc, lsb, msb. `value` is a 14-bit unsigned integer
+    (0..=16383). 8192 is centre (no bend). Maps to (lsb=value & 0x7F,
+    msb=(value >> 7) & 0x7F).
+    """
+    _check_channel(channel)
+    if not 0 <= value <= 16383:
+        raise ValueError(f"pitch_bend value must be 0..=16383, got {value}")
+    lsb = value & 0x7F
+    msb = (value >> 7) & 0x7F
+    return bytes([0xE0 | (channel & 0x0F), lsb, msb])
+
+
+def clock_tick() -> bytes:
+    """MIDI Clock pulse (0xF8). 24 ticks per quarter note. System real-time."""
+    return bytes([0xF8])
+
+
+def start() -> bytes:
+    """MIDI Start (0xFA). System real-time."""
+    return bytes([0xFA])
+
+
+def stop() -> bytes:
+    """MIDI Stop (0xFC). System real-time."""
+    return bytes([0xFC])
+
+
+def continue_() -> bytes:
+    """MIDI Continue (0xFB). System real-time. Trailing underscore avoids the
+    Python keyword."""
+    return bytes([0xFB])
+
+
+# ── Decoder ──────────────────────────────────────────────────────────────────
+
+
+@dataclass
+class MidiMessage:
+    """Decoded MIDI 1.0 message. `kind` is one of:
+
+        "note_on"     — channel, note, velocity
+        "note_off"    — channel, note, velocity
+        "cc"          — channel, controller, value
+        "program"     — channel, program (note: data2 is None)
+        "pitch_bend"  — channel, value (14-bit)
+        "clock"       — no data
+        "start"       — no data
+        "stop"        — no data
+        "continue"    — no data
+        "unknown"     — raw bytes preserved in `raw`
+
+    Fields not relevant to the message kind are None.
+    """
+    kind: str
+    raw: bytes
+    channel: "int | None" = None
+    note: "int | None" = None
+    velocity: "int | None" = None
+    controller: "int | None" = None
+    value: "int | None" = None
+    program: "int | None" = None
+
+
+def decode(data: bytes) -> MidiMessage:
+    """Parse one MIDI 1.0 byte stream into a structured MidiMessage. Returns a
+    `MidiMessage(kind="unknown", raw=data)` for anything not in the v3.4
+    supported set."""
+    if not data:
+        return MidiMessage(kind="unknown", raw=bytes(data))
+    status = data[0]
+    raw = bytes(data)
+
+    # System real-time (1 byte).
+    if status == 0xF8:
+        return MidiMessage(kind="clock", raw=raw)
+    if status == 0xFA:
+        return MidiMessage(kind="start", raw=raw)
+    if status == 0xFB:
+        return MidiMessage(kind="continue", raw=raw)
+    if status == 0xFC:
+        return MidiMessage(kind="stop", raw=raw)
+
+    # Channel voice.
+    high = status & 0xF0
+    channel = status & 0x0F
+    if high == 0x90:  # NoteOn (NoteOn with velocity 0 is conventionally NoteOff)
+        if len(data) < 3:
+            return MidiMessage(kind="unknown", raw=raw)
+        note, vel = data[1], data[2]
+        if vel == 0:
+            return MidiMessage(
+                kind="note_off", raw=raw, channel=channel, note=note, velocity=0
+            )
+        return MidiMessage(
+            kind="note_on", raw=raw, channel=channel, note=note, velocity=vel
+        )
+    if high == 0x80:  # NoteOff
+        if len(data) < 3:
+            return MidiMessage(kind="unknown", raw=raw)
+        return MidiMessage(
+            kind="note_off",
+            raw=raw,
+            channel=channel,
+            note=data[1],
+            velocity=data[2],
+        )
+    if high == 0xB0:  # CC
+        if len(data) < 3:
+            return MidiMessage(kind="unknown", raw=raw)
+        return MidiMessage(
+            kind="cc",
+            raw=raw,
+            channel=channel,
+            controller=data[1],
+            value=data[2],
+        )
+    if high == 0xC0:  # Program Change (2 bytes)
+        if len(data) < 2:
+            return MidiMessage(kind="unknown", raw=raw)
+        return MidiMessage(
+            kind="program", raw=raw, channel=channel, program=data[1]
+        )
+    if high == 0xE0:  # Pitch bend
+        if len(data) < 3:
+            return MidiMessage(kind="unknown", raw=raw)
+        lsb, msb = data[1], data[2]
+        value14 = (msb << 7) | lsb
+        return MidiMessage(
+            kind="pitch_bend", raw=raw, channel=channel, value=value14
+        )
+
+    return MidiMessage(kind="unknown", raw=raw)
+
+
+def describe(data: bytes) -> str:
+    """One-line human-readable form of a MIDI message — useful for logs and
+    in-pane debug output."""
+    m = decode(data)
+    hex_str = " ".join(f"{b:02X}" for b in data)
+    if m.kind == "note_on":
+        return f"NoteOn  ch={m.channel} note={m.note} vel={m.velocity}    [{hex_str}]"
+    if m.kind == "note_off":
+        return f"NoteOff ch={m.channel} note={m.note} vel={m.velocity}    [{hex_str}]"
+    if m.kind == "cc":
+        return f"CC      ch={m.channel} num={m.controller} val={m.value}    [{hex_str}]"
+    if m.kind == "program":
+        return f"Program ch={m.channel} prog={m.program}                  [{hex_str}]"
+    if m.kind == "pitch_bend":
+        return f"PitchBd ch={m.channel} val={m.value}                     [{hex_str}]"
+    if m.kind == "clock":
+        return f"Clock                                                  [{hex_str}]"
+    if m.kind == "start":
+        return f"Start                                                  [{hex_str}]"
+    if m.kind == "stop":
+        return f"Stop                                                   [{hex_str}]"
+    if m.kind == "continue":
+        return f"Continue                                               [{hex_str}]"
+    return f"Unknown                                                   [{hex_str}]"
+
+
+# ── Validation helpers ───────────────────────────────────────────────────────
+
+
+def _check_channel(channel: int) -> None:
+    if not 0 <= channel <= 15:
+        raise ValueError(f"channel must be 0..=15, got {channel}")
+
+
+def _check_byte(value: int, name: str) -> None:
+    if not 0 <= value <= 127:
+        raise ValueError(f"{name} must be 0..=127, got {value}")

plexi_sdk/py.typed

@@ -0,0 +1 @@
+

plexi_sdk/templates/app_init.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""
+__DISPLAY_NAME__ — generated by `plexi app init`.
+
+Delete what you don't need.
+"""
+from plexi_sdk import App, RenderContext
+from plexi_sdk.ui import (
+    AppBar,
+    ButtonRow,
+    Card,
+    Column,
+    FooterKeys,
+    InfoTable,
+    KeyRow,
+    Label,
+    Section,
+    Spacer,
+)
+
+
+class __CLASS_NAME__(App):
+    async def on_init(self, ctx: RenderContext) -> None:
+        state = ctx.load_state()
+        self.click_count = state.get("clicks", 0)
+        self._btn = ButtonRow("action", "Click me")
+        ctx.status_summary("Ready")
+        self.emit.info("__DISPLAY_NAME__ initialized")
+
+    def on_render(self, ctx: RenderContext) -> None:
+        if self._btn.clicked:
+            self.click_count += 1
+            ctx.save_state({"clicks": self.click_count})
+            ctx.status_summary(f"Clicked {self.click_count} time(s)")
+
+        ctx.render(Column([
+            AppBar(title="__DISPLAY_NAME__", subtitle="Edit main.py to build your app"),
+            Section("APP INFO"),
+            InfoTable([
+                ("app_id", self.app_id),
+                ("workspace", ctx.workspace_root or "(none)"),
+                ("dimensions", f"{ctx.w:.0f} × {ctx.h:.0f}"),
+                ("capabilities", ", ".join(ctx.capabilities) or "none"),
+            ]),
+            Section("ACTIONS"),
+            Card([
+                self._btn,
+                Label(f"Clicks: {self.click_count}", tone="caption"),
+                Label(f"state stored in app_states/{self.app_id}.json — survives hot reload", tone="muted"),
+            ]),
+            Section("KEYBOARD SHORTCUTS"),
+            Card([
+                KeyRow("esc", "close"),
+                KeyRow("i", "increment counter"),
+            ]),
+            Spacer(grow=True),
+            FooterKeys([
+                ("esc", "close"),
+                ("i", "increment"),
+            ]),
+        ]))
+
+    def on_key(self, ctx: RenderContext, key: str, _mods: dict) -> None:
+        if key == "Escape":
+            self.emit.close_self()
+        elif key == "i":
+            self.click_count += 1
+            ctx.save_state({"clicks": self.click_count})
+            ctx.status_summary(f"Clicked {self.click_count} time(s)")
+
+
+__CLASS_NAME__().run()