Python-API und IPC

Bernard Review lässt sich aus Python, Maya, Nuke, Houdini, einem Produktions-Tracker oder jeder Sprache steuern, die eine TCP-Verbindung öffnen kann. Alles, was ein Artist von Hand tut, hat seinen Befehl: Clips öffnen, abspielen, vergleichen, graden, exportieren, eine Sitzung starten, Notizen veröffentlichen. Diese Seite genügt, um den Player zu automatisieren; die erschöpfende Referenz, Feld für Feld, ist die API-Referenz, auf Englisch (auch über Help > API Documentation zu öffnen).

Das Protokoll

• Adresse: 127.0.0.1, standardmäßig Port 5556. Ein mit --ipc-port N gestarteter Player lauscht auf N: So laufen zwei Player auf demselben Rechner.
• Format: JSON Lines. Jede Anfrage ist ein JSON-Objekt in einer Zeile, beendet mit \n, mit einem Feld "cmd": {"cmd": "seek", "frame": 24}.
• Eine Antwort pro Anfrage, in der gesendeten Reihenfolge, meist innerhalb weniger Millisekunden: {"status": "ok", "cmd": "seek", ...} oder {"status": "error", "cmd": "seek", "reason": "..."}. Ein Fehler trägt immer einen Grund in einfachen Worten und wartet nie auf Ihr Zeitlimit. Es gibt keine Anfrage-ID: Eine Antwort wird ihrer Anfrage über ihr "cmd" zugeordnet.
• Ereignisse des Players ({"event": ...}) kommen auf derselben Verbindung an, gemischt mit den Antworten (siehe unten).
• Immer nur ein Client. Eine zweite Verbindung wartet, bis die erste geschlossen wird.
• Nur lokal. Der Port lauscht auf dem Loopback. Eine Verbindung, die wie die Anfrage eines Browsers aussieht (eine HTTP-Zeile, ein Header Host:), wird geschlossen, ohne etwas auszuführen: Eine Webseite kann den Player nicht steuern. Eine Zeile umfasst höchstens 16 MiB.
• Kein Secret geht für Tracker über diesen Port: Eine Anfrage, die ein Passwort, einen Schlüssel oder ein Token eines Trackers enthält, wird abgelehnt.

Zum Ausprobieren ohne Code: Window > Console (Strg+Umschalt+C) sendet dieselben Befehle aus dem Player heraus, mit Vervollständigung per Tab: status, seek {"frame": 24} oder die vollständige JSON-Form. Sie fragt vor den Befehlen nach, die Dateien schreiben, veröffentlichen oder den Player schließen.

Der Python-Client

bernard_api.py verpackt das Protokoll in eine Klasse, BernardClient, mit einer Methode pro Befehl. Er wird neben dem Player im Ordner api installiert:

Er braucht nichts außer der Standardbibliothek von Python 3.

import sys
sys.path.append(r"C:\Program Files\Bernard Review\bin\api")
from bernard_api import BernardClient

client = BernardClient(host="127.0.0.1", port=5556)
if not client.connect():
    raise SystemExit("Bernard Review does not answer on port 5556")

reply = client.open_media("D:/shots/SQ010_SH010_ANIM_v002.mov")
if reply is None or reply.get("status") == "error":
    print("refused:", reply and reply.get("reason"))
else:
    client.play()

• request(dict) sendet einen Befehl und wartet auf seine Antwort (ein dict), Fehler eingeschlossen: Bei einer Ablehnung durch den Player löst es keine Exception aus und liefert bei einem Zeitlimit oder einer verlorenen Verbindung None.
• send_command(dict) sendet, ohne zu warten.
• Die benannten Methoden (play(), seek(), set_exposure(), export() ...) rufen die eine oder die andere auf; die, die Daten liefern, laufen über request().
• on("frame_changed", function) meldet eine Funktion für ein Ereignis an; ein Hintergrund-Thread liest die Verbindung.

Ohne den Client genügen ein paar Zeilen:

import json, socket

with socket.create_connection(("127.0.0.1", 5556)) as s:
    f = s.makefile("rw", encoding="utf-8", newline="\n")
    f.write(json.dumps({"cmd": "status"}) + "\n"); f.flush()
    for line in f:
        msg = json.loads(line)
        if msg.get("cmd") == "status":      # skip the events
            print(msg["playback"]["currentFrame"]); break

Was Sie wissen sollten, bevor Sie ein Skript schreiben

• Bildnummern. seek, set-in, set-out und die Option --frame nehmen die Position im Clip ab 0 gezählt, nicht die auf dem Lineal gedruckte Nummer. Bei einem Clip, der bei 1001 beginnt, ist das angezeigte Bild 1010 die Position 9. status liefert die Position (playback.currentFrame) und die erste Bildnummer (playback.startOffset).
• Was asynchron ist. open antwortet, bevor der Clip untersucht ist: status.playback.transitioning bleibt true, bis der Clip auf dem Bildschirm ist. export stellt einen Auftrag in die Warteschlange: Verfolgen Sie ihn mit export-status oder dem Ereignis export-done. export-notes schreibt seine Dateien im Hintergrund. Warten Sie nach set-proxy, bis status.viewport.retiering wieder auf false steht.
• Ein frisches Profil stellt die Frage des ersten Starts in einem modalen Fenster: Senden Sie zuerst {"cmd": "set-ui-level", "value": "complete"}.
• quit antwortet und schließt dann den Player sauber, ohne zu fragen, ob gespeichert werden soll: Senden Sie zuerst save-playlist oder export-notes, wenn das Review wichtig ist.
• Mehrere gleichnamige Anfragen gleichzeitig lassen sich nicht unterscheiden: Senden Sie sie nacheinander.

Befehle nach Familie

Die 115 Befehle des Players. Die Felder in Klammern sind die wichtigsten; track ist "A" (Standard) oder "B".

Wiedergabe und Bereich

Clips und Playlist

Vergleich und Versionen

Farbe

Viewer, Oberfläche und Fenster

Notizen, Aufnahmen und Export

Speicher und Decodierung

Review-Sitzungen

Tracker (kein Secret in irgendeiner Anfrage)

Diagnose

Ereignisse

Der Player sendet diese Zeilen ungefragt an seinen Client:

status

{"cmd": "status"} liefert den gesamten Zustand. Die nützlichsten Blöcke: playback (state, currentFrame, startOffset, fps, ab_mode, ab_view, transitioning, die Zähler late_frames und lost_frames), color (Grading von Spur A, Kanal), viewport (decodierte und originale Auflösung, proxy_idx, retiering, zoom), decode (Decodierzeit, too_slow), track_b, ram_fit und playlist (ein Eintrag pro Clip).

Beispiele

Den neuesten Render öffnen und abspielen (zum Beispiel aus einer Nuke-Schaltfläche):

client.open_media("D:/renders/SQ010_SH010_COMP_v003/SQ010_SH010_COMP_v003.1001.exr")
client.set_colorspace("ACEScg")
client.play()

Dem Playhead folgen (zum Beispiel, um eine Maya-Timeline im Gleichschritt zu halten):

client.on("frame_changed", lambda e: print("position", e["frame"]))
client.on("play", lambda e: print("playing"))

Dailies exportieren und auf das Ende warten:

client.export("D:/dailies/<clip>.mov", preset="dailies_prores_lt",
              playlist=True, burn_in=True)
result = client.wait_for_export()
print(result["state"], result.get("error"))

Die Notizen eines Reviews einsammeln:

import json, os, time
out = "D:/review/SQ010_notes"
client.export_notes(out)
time.sleep(2)  # the files are written in the background
notes = json.load(open(os.path.join(out, "export.json"), encoding="utf-8"))

Eine passwortgeschützte Review-Sitzung starten:

r = client.session_create(name="SQ010 dailies", password="...")
for link in r["links"]:
    print(link["kind"], link["link"])   # lan, vpn...

Dateiformate

Der Ordner api enthält die JSON-Schemas der ausgetauschten Dateien: playlist.schema.json (die .bpl-Playlist, mit dem Block x_tracking der Tracker-Kennungen), notes_payload.schema.json (das export.json der Notizen) und export_recipe.schema.json (Export-Rezepte) sowie Beispiel-Exportaufträge in export_examples/.

Siehe auch: Kommandozeile und Export ohne Fenster, Integrationen.