Summary

Add Art-Net DMX input support to Scope, enabling live show professionals to control pipeline parameters from lighting consoles and DMX software. This follows the existing OSC architecture pattern.

Background

• Hypothesis: H174 — DMX In/Out support will unlock adoption among live show professionals
• Reference: Scope already has OSC support (src/scope/server/osc_server.py) which provides a clean template

Proposed Architecture

1. DMX Server (src/scope/server/dmx_server.py)

class DMXServer:
    """Art-Net UDP listener for DMX input."""
    
    def __init__(self, port: int = 6454):  # Art-Net default port
        self._mappings: dict[tuple[int, int], DMXMapping] = {}  # (universe, channel) → mapping
        self._webrtc_manager: WebRTCManager | None = None
    
    def _handle_artnet_frame(self, universe: int, channels: bytes):
        """Process incoming Art-Net DMX frame."""
        for (univ, ch), mapping in self._mappings.items():
            if univ == universe:
                raw_value = channels[ch]  # 0-255
                scaled = mapping.scale(raw_value)  # → param range
                self._webrtc_manager.broadcast_parameter_update({mapping.param_key: scaled})

2. Channel Mapping System

Unlike OSC (where the address tells you what to control), DMX requires explicit mapping:

@dataclass
class DMXMapping:
    universe: int
    channel: int  # 1-512
    param_key: str  # e.g. "noise_scale"
    min_value: float
    max_value: float
    
    def scale(self, raw: int) -> float:
        """Convert 0-255 to parameter range."""
        return self.min_value + (raw / 255.0) * (self.max_value - self.min_value)

3. Frontend (frontend/src/components/settings/DmxTab.tsx)

Settings tab showing:

• Art-Net listener status (port, listening/not)
• Channel mapping editor (universe, channel, target param, range)
• Live DMX monitor view (optional, shows incoming values)

4. API Endpoints

• GET /api/v1/dmx/status — Listener status
• GET /api/v1/dmx/mappings — Current channel mappings
• POST /api/v1/dmx/mappings — Add/update mapping
• DELETE /api/v1/dmx/mappings/{id} — Remove mapping

Implementation Plan

Phase 1: MVP (Art-Net In)

• Art-Net UDP listener on port 6454
• Basic channel → param mapping (config file or API)
• Integration with existing broadcast_parameter_update() path
• DmxTab.tsx status display

Phase 2: UX Polish

• Visual mapping editor in settings
• Live DMX monitor (show channel values updating)
• Import/export mapping presets
• Multi-universe support

Phase 3: DMX Out (Future)

• Send DMX based on pipeline state (e.g., motion detection → fixture intensity)
• Bi-directional feedback for lighting sync

Python Dependencies

stupidArtnet  # or python-artnet

Both are lightweight and mature.

Key Insight

The hard work is already done — OSC established the parameter registry (osc_docs.py), validation, and broadcast mechanism. DMX is primarily:

1. A new transport layer (Art-Net UDP)
2. A mapping layer (channel → param)

Related

• OSC implementation: src/scope/server/osc_server.py
• Parameter registry: src/scope/server/osc_docs.py
• H167: MIDI mapping (similar control protocol work)

/cc @thomshutt