Externe Steuerungsschnittstelle (REST & OSC)

PixDrive Studio lässt sich von externen Systemen über zwei Netzwerkschnittstellen steuern:

REST, eine einfache HTTP-API. Geeignet für Stream Deck, Bitfocus Companion, Home Assistant, Node-RED, Shell-Skripte und alles, was HTTP-Requests senden kann.
OSC, ein Open-Sound-Control-Empfänger über UDP. Geeignet für Lichtpulte, TouchOSC, QLab, Ableton und andere Showcontrol-Werkzeuge.

Beide Schnittstellen steuern Cues, die Wiedergabe und die Master-Helligkeit. Sie nutzen denselben Engine-Pfad wie die Oberfläche der App; ein externer Trigger verhält sich wie ein Klick in der App.

Für KI- und Agenten-Automatisierung bringt PixDrive zusätzlich einen MCP-Server mit. Die hier beschriebenen REST/OSC-APIs richten sich an Showcontrol-Hardware und Hausautomation.

Cues

Jedes Preset ist ein Cue. Es gibt nichts zu konfigurieren. Ein Cue ist auf zwei Arten adressierbar:

über den Namen des Presets (stabil, empfohlen) oder
über die Nummer, seine Position in der Preset-Liste (beginnend bei 1).

Es gibt zwei Arten von Cues:

Look: ein Schnappschuss eines oder mehrerer Effekte, erstellt auf der Control-Seite.
Show: eine komplette Sequencer-Timeline, erstellt auf der Sequencer-Seite. Das Auslösen einer Show startet sie von vorn und beginnt die Wiedergabe.

Externe Steuerung aktivieren

Die externe Steuerung ist ab Werk ausgeschaltet und nur in der Vollversion (mit Lizenz) verfügbar.

Settings → External Control öffnen.
HTTP/REST und/oder OSC einschalten.
Bei Bedarf Bind-Adresse, Port und (nur REST) ein Bearer-Token setzen.

Änderungen an Aktivierung, Port und Bind-Adresse greifen nach einem Neustart der App; das Token gilt ohne Neustart.

Standard-Endpunkte

Schnittstelle	Standard-Bind	Standard-Port	Basispfad
REST	`127.0.0.1`	`9848`	`/api`
OSC (UDP)	`127.0.0.1`	`9000`	–

Beide Server binden ab Werk an 127.0.0.1 und sind damit nur vom lokalen Rechner erreichbar. Für Trigger von anderen Geräten im Netzwerk die Bind-Adresse auf 0.0.0.0 (oder eine bestimmte Interface-IP) setzen. Siehe Sicherheit.

REST-API

Basis-URL: http://<host>:9848

Alle Antworten liegen im JSON-Format vor. Die meisten Endpunkte, die Daten ändern, akzeptieren sowohl GET als auch POST, sodass
Sie sie über Tools aufrufen können, die ausschließlich GET-Anfragen senden (z. B. einen Browser oder eine
einfache Schaltfläche). Eine Ausnahme bildet /api/brightness?value=<f>, das ausschließlich POST-Anfragen akzeptiert
(ein GET an /api/brightness liest immer den aktuellen Wert aus).

Endpunkte

Methode	Pfad	Beschreibung
`GET`	`/api/cues`	Alle Cues auflisten (Nummer, Label, Art).
`GET/POST`	`/api/cue/{id}/go`	Cue über Nummer oder Name auslösen.
`GET/POST`	`/api/playback/play`	Sequenz-Wiedergabe starten.
`GET/POST`	`/api/playback/pause`	Wiedergabe pausieren.
`GET/POST`	`/api/playback/stop`	Stoppen und an den Anfang zurücksetzen.
`GET/POST`	`/api/playback/position?ms=<n>`	Zu einer Position springen (Millisekunden).
`GET`	`/api/brightness`	Master-Helligkeit lesen (0.0–1.0).
`POST`	`/api/brightness?value=<f>`	Master-Helligkeit setzen (0.0–1.0).
`GET`	`/api/status`	Aktueller Wiedergabe- und Helligkeitszustand.

Cues auflisten

curl http://127.0.0.1:9848/api/cues

{
  "cues": [
    { "number": "1", "label": "Colors",  "kind": "look" },
    { "number": "2", "label": "Rainbow 2D", "kind": "look" },
    { "number": "3", "label": "Mexico",     "kind": "look" },
    { "number": "4", "label": "Show",       "kind": "show" }
  ]
}

Wer einen eigenen Controller bauen will, liest diese Liste aus und löst die Cues über number oder label aus.

Cue auslösen

Über die Nummer:

curl -X POST http://127.0.0.1:9848/api/cue/4/go

Über den Namen (Leerzeichen URL-kodieren):

curl -X POST "http://127.0.0.1:9848/api/cue/Show/go"
curl -X POST "http://127.0.0.1:9848/api/cue/Rainbow%202D/go"

{ "ok": true, "cue": "Show" }

Unbekannter Cue → 404:

{ "ok": false, "error": "Cue '99' not found" }

Wiedergabe

curl -X POST http://127.0.0.1:9848/api/playback/play
curl -X POST http://127.0.0.1:9848/api/playback/pause
curl -X POST http://127.0.0.1:9848/api/playback/stop
curl -X POST "http://127.0.0.1:9848/api/playback/position?ms=5000"

Jeder Aufruf liefert bei Erfolg { "ok": true }.

Master-Helligkeit

Der globale Dimmer skaliert die gesamte Ausgabe (alle Effekte und den Sequencer), 0.0–1.0. PixDrive begrenzt Werte auf diesen Bereich.

# lesen
curl http://127.0.0.1:9848/api/brightness
# → { "value": 1.0 }

# auf 50 % setzen
curl -X POST "http://127.0.0.1:9848/api/brightness?value=0.5"
# → { "ok": true, "value": 0.5 }

Wird die Helligkeit über die API gesetzt, wandert auch der Schieberegler in der Toolbar der App mit.

Status

curl http://127.0.0.1:9848/api/status

{
  "has_sequence": true,
  "state": "Running",
  "position_ms": 3430,
  "duration_ms": 36000,
  "active_segment_ids": ["10d55fa9-…"],
  "loop_active": false,
  "master_brightness": 1.0
}

state ist Stopped, Running oder Paused.

Sicherheit

Lokal ab Werk. Beide Server binden an 127.0.0.1; bis zur Änderung der Bind-Adresse erreicht sie nur der lokale Rechner.
Optionales Bearer-Token (REST). Token in Settings → External Control setzen. Danach muss jeder Request es mitschicken: curl -H "Authorization: Bearer <dein-token>" \ -X POST http://127.0.0.1:9848/api/cue/1/go Requests ohne gültiges Token bekommen 401.
Demo-Modus. Die Demoversion weist alle Requests mit 403 ab; die Server laufen nur in der Vollversion.
OSC hat keine Authentifizierung (das Protokoll sieht keine vor). Zugriff über die Bind-Adresse einschränken und nur in einem vertrauenswürdigen Netz/LAN betreiben.

Wer REST im LAN freigibt (bind = 0.0.0.0), sollte ein Bearer-Token setzen.

OSC-API

OSC-Nachrichten gehen per UDP an <host>:9000. OSC ist Fire-and-forget: keine Antwort, kein Listing-Endpunkt. Die Cue-Liste liefert bei Bedarf REST über GET /api/cues.

Adresse	Argument	Beschreibung
`/pixdrive/cue/<id>/go`	–	Cue über Nummer/Name auslösen.
`/pixdrive/playback/play`	–	Wiedergabe starten.
`/pixdrive/playback/pause`	–	Wiedergabe pausieren.
`/pixdrive/playback/stop`	–	Stoppen und zurücksetzen.
`/pixdrive/playback/position`	`int`/`float` (ms)	Zu einer Position springen.
`/pixdrive/brightness`	`float` (0.0–1.0)	Master-Helligkeit setzen.

Die Cue-<id> ist Teil der OSC-Adresse, z. B. /pixdrive/cue/4/go oder /pixdrive/cue/Show/go.

Schnelltest im Terminal (Python, ohne Abhängigkeiten):

import socket, struct

def osc(addr, *args):
    # Adresse, nullterminiert + auf 4 Bytes aufgefüllt
    a = addr.encode() + b"\x00"
    a += b"\x00" * ((4 - len(a) % 4) % 4)
    if not args:
        return a + b",\x00\x00\x00"
    # einzelnes Float-Argument
    return a + b",f\x00\x00" + struct.pack(">f", float(args[0]))

s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
s.sendto(osc("/pixdrive/cue/Show/go"), ("127.0.0.1", 9000))
s.sendto(osc("/pixdrive/brightness", 0.5), ("127.0.0.1", 9000))

Integrationsbeispiele

Bitfocus Companion / Stream Deck: eine Generic-HTTP-Aktion anlegen:

POST http://<pixdrive-host>:9848/api/cue/1/go

Bei gesetztem Token den Header Authorization: Bearer <token> ergänzen. Da die Endpunkte auch GET akzeptieren, funktioniert ebenso ein „Open URL“-Button.

Home Assistant: ein REST-Command:

rest_command:
  pixdrive_cue:
    url: "http://<pixdrive-host>:9848/api/cue/{{ cue }}/go"
    method: POST
    headers:
      Authorization: "Bearer !secret pixdrive_token"

# Aufruf
service: rest_command.pixdrive_cue
data:
  cue: "Show"

TouchOSC / Lichtpult: einen Button auf /pixdrive/cue/1/go legen und einen Fader (0.0–1.0) auf /pixdrive/brightness.

Hinweise und Grenzen

PixDrive leitet Cues aus den Presets ab und aktualisiert die Liste bei jeder Preset-Änderung; eine handgepflegte Cue-Liste gibt es nicht.
Shows besser über den Namen auslösen; Nummern verschieben sich beim Hinzufügen, Entfernen oder Umsortieren von Presets.
Wiedergabe und Seek wirken auf die geladene Sequenz. Ein Show-Cue lädt seine Show und startet sie bei 0.
REST und OSC sind unabhängig; eins oder beide aktivieren.