Zum Inhalt springen
PixDrive
Alle Artikel

Externe Steuerungsschnittstelle (REST & OSC)

PixDrive Studio per REST-API und OSC steuern – für Stream Deck, Companion, Home Assistant, Node-RED, Lichtpulte und QLab.

Aktualisiert am

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.

  1. Settings → External Control öffnen.
  2. HTTP/REST und/oder OSC einschalten.
  3. 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 du sie auch mit Tools aufrufen kannst, die nur GET-Anfragen senden (z. B. ein 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.