Externes SDK / API
Middle Control stellt eine TCP-API bereit, über die jedes externe Gerät oder jede Software Befehle an Middle Control senden — und live Kamera- sowie Gimbal-Daten auslesen kann.
Das ist nützlich, wenn du:
- Presets auslösen, die Aufnahme starten/stoppen oder einen Gimbal von einem eigenen Gerät oder Skript aus steuern möchtest
- Middle Control in einen Broadcast-Automatisierungs-Workflow integrieren möchtest
- Ein benutzerdefiniertes Bedienpanel (Hardware oder Software) aufbauen möchtest, das direkt mit Middle Control kommuniziert
Diese API war bisher auf Port 11581 dokumentiert. Dieser Port wird gemeinsam mit der Middle Remote (Glue)-Verbindung genutzt und wird abgelehnt, wenn Middle Remote im Direct-Modus ist — der standardmäßig unter macOS gilt. Wenn deine Integration auf 11581 aufgebaut wurde, ändere den Port einfach auf 11584: Befehle und Feedback-Frame sind identisch. (Diese externe API ist ein macOS-Feature. Unter Windows verwende den Companion-Port 11580 und den Glue-/Remote-Port 11581.)
Es gibt kein SDK, das direkt mit APC-R Geräten kommuniziert. Alle Befehle laufen über die Middle Control App auf deinem Computer.
🔌 Verbindung
Dein Gerät oder deine Software sendet einfache TCP-Befehle im Klartext an den Computer, auf dem Middle Control läuft. Jeder Befehl ist eine kurze Zeichenkette (z. B. CAM3, PRESET1, P500), die mit einem Zeilenumbruchzeichen abgeschlossen wird — ein Befehl pro Zeile.
Host: IP-Adresse des Computers, auf dem Middle Control läuft
(verwende 127.0.0.1, wenn deine Software auf demselben Rechner läuft)
Port: 11584
Abschlusszeichen: \n (LF oder CRLF)
Wissenswert:
- Befehle sind Groß-/Kleinschreibung-sensitiv — sende sie genau so, wie sie auf dieser Seite angegeben sind.
- Die API ist Fire-and-Forget: Ein fehlerhafter oder unbekannter Befehl wird stillschweigend ignoriert (es gibt keine Fehlerantwort). Verwende das Live-Feedback, um den Zustand zu bestätigen.
- Wenn deine Integration verbunden ist, erscheint ein External API-Eintrag in der linken Seitenleiste von Middle Control unter Controllers — er bleibt sichtbar, solange die Verbindung offen ist.
Schnelltest aus einem Terminal — Kamera 1 auswählen und ihr Preset 1 auslösen:
printf 'CAM1\nPRESET1\n' | nc <MIDDLE_CONTROL_IP> 11584
🎯 Kameras auswählen und ansprechen
Jeder Befehl auf dieser Seite wirkt auf eine Kamera-ID (1–99). Es gibt zwei Möglichkeiten, die Kamera anzugeben:
- Kamera auswählen mit
CAMx— die folgenden Befehle wirken auf sie, und der Feedback-Frame meldet sie. Das ändert die ausgewählte Kamera in Middle Control, ähnlich wie ein Klick in der Seitenleiste. - Einen einzelnen Befehl gezielt richten, indem du
@Cxans Ende anhängst — der Befehl geht an Kamerax, ohne die Auswahl zu ändern.
| Befehl | Beschreibung |
|---|---|
CAM3 | Kamera/Gimbal 3 auswählen — nachfolgende Befehle wirken auf sie |
REC_START@C2 | Aufnahme auf Kamera 2 starten, Auswahl bleibt unverändert |
AUTOFOCUS@C5 | Autofokus auf Kamera 5 auslösen, Auswahl bleibt unverändert |
P500@C1 | Pan-Befehl an Kamera 1 senden, Auswahl bleibt unverändert |
Gezielte Befehle erleichtern Mehrfachkamera-Aktionen — sende REC_START@C1, REC_START@C2 und REC_START@C3 schnell nacheinander, um die Aufnahme auf den Kameras 1, 2 und 3 gleichzeitig zu starten.
🕹️ Gimbal- & PTZ-Steuerung
Variable Geschwindigkeit
Eine Achse mit einer bestimmten Geschwindigkeit antreiben — die Achse bewegt sich so lange, bis du 0 auf ihr sendest:
| Befehl | Beschreibung |
|---|---|
Pxx | Pan-Geschwindigkeit, xx zwischen -2048 und +2048 (INT16) |
Txx | Tilt-Geschwindigkeit, xx zwischen -2048 und +2048 (INT16) |
Rxx | Roll-Geschwindigkeit, xx zwischen -2048 und +2048 (INT16) |
Zxx | Zoom-Geschwindigkeit, xx zwischen -2048 und +2048 (INT16) |
P500 startet das Schwenken und P0 stoppt es. Sicherheitsnetz: Wenn deine TCP-Verbindung abbricht, während eine Achse noch in Bewegung ist, stoppt Middle Control diese Achse automatisch.
Geschwindigkeitseinstellungen, die von den Schaltflächenbefehlen und Presets verwendet werden:
| Befehl | Beschreibung |
|---|---|
PTSxx | Pan/Tilt-Geschwindigkeitseinstellung, xx zwischen 1 und 100 (INT8) |
ZSxx | Zoom-Geschwindigkeitseinstellung, xx zwischen 1 und 100 (INT8) |
Absolute Position
Den Gimbal mit einem einzelnen Befehl auf eine genaue Position fahren, mit folgendem Frame-Format:
aGLOB;aPxx;aTxx;aRxx;aZxx;ss
| Teil | Beschreibung |
|---|---|
aGLOB | Muss am Anfang des Frames stehen |
aPxx | Absolute Pan-Position, in 1/10 Grad (INT16) |
aTxx | Absolute Tilt-Position, in 1/10 Grad (INT16) |
aRxx | Absolute Roll-Position, in 1/10 Grad (INT16) |
aZxx | Absolute Zoom-Position, zwischen 0 und 4096 (INT16) |
ss | Übergangsdauer in Sekunden |
Beispiel: Fahrt zu Pan 20°, Roll 2°, Tilt 7,5°, Zoom Mitte, über 5 Sekunden:
aGLOB;aP200;aR20;aT75;aZ2500;5
Du kannst auch eine einzelne Achse allein ansprechen, mit der aktuellen Übergangsgeschwindigkeit:
| Befehl | Beschreibung |
|---|---|
aPxx / aTxx / aRxx | Eine Achse auf xx fahren, in 1/10 Grad |
aZxx | Den Zoom auf xx fahren, zwischen 0 und 4096 |
Schaltflächen & Hilfsfunktionen
Diese Befehle wirken wie Schaltflächendrücke:
| Befehl | Beschreibung |
|---|---|
PAN_L / PAN_R | Gimbal nach links / rechts schwenken |
TILT_U / TILT_D | Gimbal nach oben / unten neigen |
ROLL_L / ROLL_R | Gimbal nach links / rechts rollen |
Nach jedem der obigen Bewegungsbefehle musst du den passenden Stoppbefehl nach einer Verzögerung von mindestens 70 ms senden:
| Bewegung | Stoppbefehl |
|---|---|
PAN_L / PAN_R | PAN_IDLE |
TILT_U / TILT_D | TILT_IDLE |
ROLL_L / ROLL_R | ROLL_IDLE |
Wenn die Verbindung vor dem Stoppbefehl abbricht, stoppt Middle Control die Bewegung automatisch.
| Befehl | Beschreibung |
|---|---|
ZOOM+ / ZOOM- | Um einen Schritt herein-/herauszoomen |
SPEED+ / SPEED- | Pan/Tilt-Geschwindigkeit erhöhen / verringern |
ZSPEED+ / ZSPEED- | Zoom-Geschwindigkeit erhöhen / verringern |
Gimbal-Hilfsfunktionen:
| Befehl | Beschreibung |
|---|---|
RECENTER | Gimbal zentrieren |
ACTIVETRACK | Active Track aktivieren / deaktivieren |
GIMBALSLEEP / GIMBALWAKE | Gimbal in Schlafmodus versetzen / aufwecken |
GIMBALAUTOCALIB | Gimbal-Autokalibrierung (Autotune) starten |
MOTORAUTOCALIB | Fokusmotor-Autokalibrierung starten |
🎥 Kamerasteuerung
Die Verfügbarkeit hängt von der Kameramarke und der Verbindungsart ab (einige Befehle sind nur für Sony, andere benötigen einen ATEM-Link).
Absolute Werte
Einen Kamerawert direkt setzen:
| Befehl | Beschreibung |
|---|---|
aFxx | Fokus, xx zwischen 0,0 und 1,0 (FLOAT) |
aIxx | Iris, xx = f-Zahl (FLOAT) — wird auf den nächsten unterstützten f-Stop gerundet (ca. f/1,2 bis f/22) |
aWBxx | Weißabgleich, xx zwischen 2500 und 10000 Kelvin (INT16 — nur ganze Zahlen) |
aTINTxx | Tint, xx zwischen -100 und +100 (INT8) |
aISOxx | ISO / Gain in dB, xx zwischen -12 und +36 (INT8) |
aSHUTxx | Verschlusszeit, xx = Nenner (INT16 — z. B. aSHUT50 für 1/50 s) |
NDxx / NDCLEAR | ND Filter, xx = Nenner: ND4 = 1/4, ND16, ND64, ND256, ND1024 (Standardstufen, jede Marke mit eingebautem ND); beliebiger anderer Wert 2 – 4096 bei Sony-Kameras mit variablem ND; NDCLEAR (oder ND0) entfernt den Filter. Wird im Feedback-Frame als aND zurückgemeldet |
Für Kameras, die über einen ATEM Switcher gesteuert werden (Farbkorrektur-Werte):
| Befehl | Beschreibung |
|---|---|
aSATxx | Sättigung, xx zwischen 0 und 100 |
aCONTxx | Kontrast, xx zwischen 0 und 100 |
aBLACKLEVxx | Schwarzpegel (Lift Luma), xx zwischen -2,0 und +2,0 |
aMIDLEVxx | Mittelpegel (Gamma Luma), xx zwischen -4,0 und +4,0 |
aWHITELEVxx | Weißpegel (Gain Luma), xx zwischen 0 und 16,0 |
Für VISCA Kameras, die Red/Blue Gain statt Kelvin/Tint verwenden:
| Befehl | Beschreibung |
|---|---|
aRGAINxx | Rotverstärkung, xx zwischen 0 und 255 |
aBGAINxx | Blauverstärkung, xx zwischen 0 und 255 |
Schritte & Umschalter
Ein Schritt pro Befehl:
| Befehl | Beschreibung |
|---|---|
FOCUS+ / FOCUS- | Fokus rein-/rausfahren — verhält sich wie die Fokus-Taste in der App: ein Befehl = ein feiner Schritt; eine Befehlsfolge (Taste gehalten, Encoder schnell gedreht) beschleunigt und stoppt 200 ms nach dem letzten Befehl |
FOCUS+0.002 / FOCUS-0.002 | Fokus um genau diesen Bruchteil des Objektivwegs rein-/rausfahren, ohne Rampe (0 < size ≤ 1; FOCUS+0.01 ist der Schritt, den der einfache Befehl vor 4.0.4 verwendet hat) |
IRIS+ / IRIS- | Iris erhöhen / verringern |
WB+ / WB- | Weißabgleich erhöhen / verringern |
ISO+ / ISO- | ISO erhöhen / verringern |
TINT+ / TINT- | Tint erhöhen / verringern |
SHUTTER+ / SHUTTER- | Verschlusszeit erhöhen / verringern |
ND+ / ND- | ND Filter erhöhen / verringern |
SHARP+ / SHARP- | Schärfe erhöhen / verringern |
CONT+ / CONT- | Kontrast erhöhen / verringern (ATEM) |
SAT+ / SAT- | Sättigung erhöhen / verringern (ATEM) |
BLEV+ / BLEV- | Schwarzpegel erhöhen / verringern (ATEM) |
Fokus bei gedrückter Taste
Für eine Gedrückthalten-Taste (Stream Deck, eine Controller-Taste) sendest du den Startbefehl beim Drücken und den Stoppbefehl beim Loslassen — der Fokus bewegt sich dann genau wie die Fokus-Taste der App, die mit der Maus gehalten wird: ein feiner erster Schritt, dann eine Rampe.
| Befehl | Beschreibung |
|---|---|
FOCUS_IN / FOCUS_OUT | Fokus rein-/rausfahren beginnen (gleiche Richtung wie FOCUS+ / FOCUS-) |
FOCUS_IDLE | Stoppen |
Wenn die Verbindung vor FOCUS_IDLE abbricht, stoppt Middle Control die Bewegung automatisch; ein Halten wird auch nach 10 s ohne Stoppbefehl beendet. Alle drei Befehle akzeptieren das @C<n>-Kamera-Suffix.
Automatik-Modi und Monitoring-Umschalter:
| Befehl | Beschreibung |
|---|---|
AUTOFOCUS | Autofokus auslösen |
AUTOIRIS | Automatische Iris auslösen |
AUTOSHUTTER | Automatische Verschlusszeit umschalten |
AUTOGAIN | Automatischen Gain / ISO umschalten |
AUTOWB | Automatischen Weißabgleich umschalten |
COLORBARS | Farbbalken anzeigen |
ZEBRA | Zebra-Hilfe anzeigen |
FALSECOLORS | Falschfarben-Hilfe anzeigen |
FOCUSPEAKING | Focus Peaking umschalten |
STATUSVIEW | Statusansicht am HDMI Ausgang der Kamera anzeigen |
DIGITAL_ZOOM | Digitalen Zoom umschalten (Sony) |
RESETCCU | CCU / Farbkorrektur-Werte zurücksetzen |
Menünavigation (Sony)
| Befehl | Beschreibung |
|---|---|
BTN_MENU | Menü-Taste drücken |
BTN_OK | OK-Taste drücken |
BTN_LEFT / BTN_RIGHT / BTN_UP / BTN_DOWN | Pfeiltasten drücken |
MULTISEL_LEFT / MULTISEL_RIGHT / MULTISEL_UP / MULTISEL_DOWN | MultiSelector bewegen |
MULTISEL_PRESS | MultiSelector drücken |
CUSTOM_C1 … CUSTOM_C6 | Benutzerdefinierte Funktion C1 … C6 auslösen |
Aufnahme
| Befehl | Beschreibung |
|---|---|
REC_START | Aufnahme starten (aktuell ausgewählte Kamera) |
REC_STOP | Aufnahme stoppen (aktuell ausgewählte Kamera) |
REC_START_ALL | Aufnahme auf allen Kameras starten |
REC_STOP_ALL | Aufnahme auf allen Kameras stoppen |
Der Feedback-Frame listet die aktuell aufnehmenden Kameras in REC_LIST[…].
📌 Presets
| Befehl | Beschreibung |
|---|---|
PRESET1 … PRESET12 | Preset 1 … 12 der aktuell ausgewählten Kamera auslösen |
PRESET1@C5 … PRESET12@C5 | Preset 1 … 12 von Kamera 5 auslösen (Presets 5.1 – 5.12 in Middle Control) |
SPRESET1@C5 … SPRESET12@C5 | Preset 1 … 12 von Kamera 5 speichern (Presets 5.1 – 5.12 in Middle Control) |
Preset-Wiedergabe steuern:
| Befehl | Beschreibung |
|---|---|
STOPPRESET | Laufende Preset-Bewegung stoppen (füge @Cx hinzu, um eine bestimmte Kamera zu stoppen) |
PRES_Dxx | Preset-Übergangsdauer setzen, xx in Sekunden |
PRES_Exx | Preset-Übergangs-Easing setzen, xx zwischen 0 (linear) und 100 — ein Wert für alle Kameras, wie PRES_D (APC-R Firmware 2.0 oder neuer) |
🔁 Automatisierungen
Automatisierungen der Seite Automations starten, stoppen und anpassen. Alle Befehle unterstützen @Cx-Targeting.
Camera Shake
| Befehl | Beschreibung |
|---|---|
SHAKE-START / SHAKE-STOP | Camera Shake starten / stoppen |
SHAKE-SPEEDxx | Shake-Geschwindigkeit, xx zwischen 1 und 100 |
SHAKE-AMPLxx | Shake-Amplitude, xx zwischen 1 und 100 |
Zoom Loop
| Befehl | Beschreibung |
|---|---|
ZLOOP-START / ZLOOP-STOP | Zoom Loop starten / stoppen |
ZLOOP-SPEEDxx | Zoom-Geschwindigkeit, xx zwischen 1 und 100 |
ZLOOP-DURATIONxx | Zoom-Verfahrzeit, xx in Sekunden (0,1 – 60) |
ZLOOP-RESTDURATIONxx | Pause zwischen den Loops, xx in Sekunden (0,1 – 15) |
Presets Sequence
| Befehl | Beschreibung |
|---|---|
PRESETSEQ-START / PRESETSEQ-STOP | Preset-Sequenz starten / stoppen |
PRESETSEQ-BANKx | Aktive Sequenzbank auswählen, x zwischen 1 und 7 |
PRESETSEQ-SPEEDxx | Übergangsgeschwindigkeit der Sequenz, xx in Sekunden (0,1 – 15) |
PRESETSEQ-RESTDURATIONxx | Verweildauer auf jedem Preset, xx in Sekunden (0,1 – 15) |
Der Feedback-Frame meldet den Live-Zustand jeder Automatisierung für die ausgewählte Kamera: SHAKE_RUN, ZLOOP_RUN, PRESETSEQ_RUN (1 während sie läuft) und PRESETSEQ_BANK (aktive Bank).
🖥️ Live View & Multi View
Überwachungsfenster auf dem Computer, auf dem Middle Control läuft, öffnen und schließen:
| Befehl | Beschreibung |
|---|---|
LIVEVIEW_OPEN / LIVEVIEW_CLOSE | Live View Fenster der aktuell ausgewählten Kamera öffnen / schließen (vorher mit CAMx auswählen) |
MULTIVIEW_OPEN / MULTIVIEW_CLOSE | Multi View Fenster öffnen / schließen (Middle Control Pro — ohne es wird der Befehl ignoriert) |
📡 Live-Feedback
Middle Control sendet über dieselbe TCP-Verbindung einen Live-Status-Frame, ca. 4-mal pro Sekunde. Der Frame spiegelt die aktuell ausgewählte Kamera wider. Damit lässt sich der aktuelle Zustand von Gimbal und Kamera auslesen — nützlich für Feedback-Displays oder reaktive Workflows.
Kamerawert-Feedback ist verfügbar, wenn Middle Control mit einem ATEM Switcher oder einer Kamera über kabelgebundenes LAN verbunden ist. Gimbal-Winkel werden eingeschlossen, wenn ein APC-R mit der Kamera verknüpft ist.
{CAM5;REC1;AF0;DZOOM0;aWB5600;aF0.45;aI6.5;aUI5.4;aTINT10;aISO12;aSHUT1/50;aSAT50;aCONT50;aBLACKLEV0.4;SHAKE_RUN0;ZLOOP_RUN0;PRESETSEQ_RUN1;BRANG_RUN0;PRESETSEQ_BANK1;aPAN523;aTILT124;aROLL890;aZOOM3992;PTS85;ZS24;PRES_D8.0;PRES_ACTIVE0;PRES_E50;REC_LIST[5];CAM_CON_LIST[1,2,5];APCR_CON_LIST[5]}
Jeder Frame ist eine einzelne Zeile, die mit \n endet: {CAM<id>, gefolgt von durch ; getrennten Token, abgeschlossen durch }. Token in der Reihenfolge:
| Token | Bedeutung |
|---|---|
CAM | ID der ausgewählten Kamera |
REC / AF / DZOOM | Aufnahme / Autofokus / Digitaler Zoom der ausgewählten Kamera (1 oder 0) |
aWB | Weißabgleich in Kelvin |
aF | Fokusposition, 0,0 – 1,0 |
aI / aUI | Iris-f-Zahl (an Stops gebunden / frei) |
aTINT | Tint (vorzeichenbehaftet) |
aISO | Gain in dB |
aSHUT | Verschlusszeit (Nenner, z. B. 50 oder 1/50) |
aND | ND Filter als Nenner (4 = 1/4, 16, 64 …); - wenn der Filter deaktiviert ist oder die Kamera keinen hat |
aSAT / aCONT / aBLACKLEV | Sättigung, Kontrast, Schwarzpegel (ATEM-verknüpfte Kameras) |
SHAKE_RUN / ZLOOP_RUN / PRESETSEQ_RUN | 1, während die jeweilige Automatisierung auf der ausgewählten Kamera läuft, sonst 0 (BRANG_RUN ist reserviert, immer 0) |
PRESETSEQ_BANK | Aktive Preset-Sequenzbank, 1 – 7 |
aPAN / aTILT / aROLL | Gimbal-Winkel in 1/10 Grad (APC-R verknüpft) |
aZOOM | Zoom-Motorposition, 0 – 4096 (APC-R verknüpft) |
PTS / ZS | Aktuelle Pan/Tilt-Geschwindigkeits- und Zoom-Geschwindigkeitseinstellungen |
PRES_D | Preset-Übergangsdauer in Sekunden |
PRES_ACTIVE | 1, während eine Preset-Bewegung läuft, sonst 0 |
PRES_E | Preset-Übergangs-Easing, 0 – 100 (- wenn die Kamera keinen APC-R mit Firmware 2.0 oder neuer hat) |
REC_LIST[…] | Kamera-IDs, die aktuell aufnehmen |
CAM_CON_LIST[…] | Kamera-IDs, die aktuell verbunden sind |
APCR_CON_LIST[…] | Kamera-IDs mit verbundenem APC-R Gimbal |
Je nach Kameramarke und Verbindungsart können einige Token im Frame fehlen, und ein nicht verfügbarer Wert wird als - (Bindestrich) gesendet — stelle sicher, dass dein Parser beide Fälle behandelt, anstatt davon auszugehen, dass jedes Token immer vorhanden und numerisch ist.