Python API and IPC

Bernard Review can be driven from Python, Maya, Nuke, Houdini, a production tracker or any language that can open a TCP connection. Everything an artist does by hand has its command: open clips, play, compare, grade, export, start a session, publish notes. This page is enough to automate the player; the exhaustive reference, field by field, is the API reference (also opened by Help > API Documentation).

The protocol

• Address: 127.0.0.1, port 5556 by default. A player started with --ipc-port N listens on N: that is how two players run on the same machine.
• Format: JSON Lines. Each request is one JSON object on one line, ended by \n, with a "cmd" field: {"cmd": "seek", "frame": 24}.
• One reply per request, in the order sent, usually within a few milliseconds: {"status": "ok", "cmd": "seek", ...} or {"status": "error", "cmd": "seek", "reason": "..."}. An error always carries a reason in plain words and never waits for your time-out. There is no request ID: a reply is matched to its request by its "cmd".
• Events from the player ({"event": ...}) arrive on the same connection, mixed with the replies (see below).
• One client at a time. A second connection waits until the first closes.
• Local only. The port listens on the loopback. A connection that looks like a browser's request (an HTTP line, a Host: header) is closed without running anything: a web page cannot drive the player. A line holds at most 16 MiB.
• No secret goes through this port for trackers: a request that carries a tracker password, key or token is refused.

To try it without writing code: Window > Console (Ctrl+Shift+C) sends the same commands from inside the player, with Tab completion: status, seek {"frame": 24}, or the full JSON form. It asks before the commands that write files, publish or close the player.

The Python client

bernard_api.py wraps the protocol in one class, BernardClient, with one method per command. It is installed next to the player, in the api folder:

It needs nothing but Python 3's standard library.

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) sends a command and waits for its reply (a dict), errors included: it raises no exception for the player's refusal, and returns None on a time-out or a lost connection.
• send_command(dict) sends without waiting.
• The named methods (play(), seek(), set_exposure(), export()...) call one or the other; the ones that return data go through request().
• on("frame_changed", function) subscribes a function to an event; a background thread reads the connection.

Without the client, a few lines are enough:

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

What to know before writing a script

• Frame numbers. seek, set-in, set-out and the --frame option take the position in the clip counted from 0, not the number printed on the ruler. On a clip that starts at 1001, the displayed frame 1010 is position 9. status gives the position (playback.currentFrame) and the first frame number (playback.startOffset).
• What is asynchronous. open replies before the clip is probed: status.playback.transitioning stays true until the clip is on screen. export queues a job: follow it with export-status or the export-done event. export-notes writes its files in the background. After set-proxy, wait for status.viewport.retiering to go back to false.
• A fresh profile asks the first-launch question in a modal window: send {"cmd": "set-ui-level", "value": "complete"} first.
• quit replies, then closes the player cleanly, without asking whether to save: send save-playlist or export-notes first if the review matters.
• Several requests of the same name in flight cannot be told apart: send them one after the other.

Commands, by family

The player's 115 commands. The fields in brackets are the main ones; track is "A" (the default) or "B".

Playback and range

Clips and playlist

Comparison and versions

Color

Viewer, interface and windows

Notes, captures and export

Memory and decoding

Review sessions

Trackers (no secret in any request)

Diagnostics

Events

The player broadcasts these lines to its client, unasked:

status

{"cmd": "status"} returns the whole state. The most useful blocks: playback (state, currentFrame, startOffset, fps, ab_mode, ab_view, transitioning, the late_frames and lost_frames counters), color (track A's grade, channel), viewport (decoded and original resolution, proxy_idx, retiering, zoom), decode (decode time, too_slow), track_b, ram_fit and playlist (one entry per clip).

Examples

Open the latest render and play it (from a Nuke button, for instance):

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

Follow the playhead (to keep a Maya timeline in step, for instance):

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

Export dailies and wait for the end:

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"))

Collect a review's notes:

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"))

Start a password-protected review session:

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

File formats

The api folder holds the JSON schemas of the files exchanged: playlist.schema.json (the .bpl playlist, with the x_tracking block of tracker identifiers), notes_payload.schema.json (the notes' export.json) and export_recipe.schema.json (export recipes), and sample export jobs in export_examples/.

See also: Command line and headless export, Integrations.