Python API と IPC

Bernard Review は、Python、Maya、Nuke、Houdini、制作トラッカー、あるいは TCP 接続を開ける任意の言語から操作できます。アーティストが手で行うことには、すべて対応するコマンドがあります。クリップを開く、再生する、比較する、グレーディングする、書き出す、セッションを開始する、ノートをパブリッシュする、などです。このページだけでプレーヤーの自動化ができます。フィールドごとの網羅的なリファレンスは、API リファレンス（英語。Help > API Documentation でも開きます）です。

プロトコル

• アドレス：127.0.0.1、既定のポートは 5556 です。--ipc-port N で起動したプレーヤーは N で待ち受けます。これにより、同じマシンで 2 つのプレーヤーを動かせます。
• 形式：JSON Lines です。各リクエストは、1 行の JSON オブジェクトで、\n で終わり、"cmd" フィールドを持ちます：{"cmd": "seek", "frame": 24}。
• リクエストごとに 1 つの応答が、送信順に、通常は数ミリ秒以内に返ります：{"status": "ok", "cmd": "seek", ...} または {"status": "error", "cmd": "seek", "reason": "..."}。エラーには必ず平易な言葉の理由が付き、こちらのタイムアウトまで待たされることはありません。リクエスト ID はなく、応答は "cmd" によってリクエストと対応付けられます。
• プレーヤーからのイベント（{"event": ...}）は、同じ接続で、応答と混ざって届きます（後述）。
• 同時に接続できるクライアントは 1 つです。2 つ目の接続は、最初の接続が閉じるまで待たされます。
• ローカルのみ。 ポートはループバックで待ち受けます。ブラウザーのリクエストに見える接続（HTTP の行、Host: ヘッダー）は、何も実行されずに閉じられます。Web ページからプレーヤーを操作することはできません。1 行は最大 16 MiB です。
• トラッカーのシークレットはこのポートを通りません。トラッカーのパスワード、キー、トークンを含むリクエストは拒否されます。

コードを書かずに試す方法：Window > Console（Ctrl+Shift+C）は、プレーヤー内から同じコマンドを送信でき、Tab による補完も使えます。status、seek {"frame": 24}、または完全な JSON 形式です。ファイルを書き込む、パブリッシュする、プレーヤーを閉じるといったコマンドの前には、確認が表示されます。

Python クライアント

bernard_api.py は、プロトコルを BernardClient という 1 つのクラスで包み、コマンドごとに 1 つのメソッドを用意しています。プレーヤーの隣の api フォルダーにインストールされます。

必要なのは 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) はコマンドを送り、そのコマンドの応答（dict）を待ちます。エラーも含みます。プレーヤーが拒否しても例外は発生せず、タイムアウトまたは接続が切れた場合は None を返します。
• send_command(dict) は、待たずに送信します。
• 名前付きのメソッド（play()、seek()、set_exposure()、export() など）は、そのどちらかを呼び出します。データを返すものは request() を経由します。
• on("frame_changed", function) は、関数をイベントに登録します。バックグラウンドのスレッドが接続を読み取ります。

クライアントを使わなくても、数行で足ります。

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

スクリプトを書く前に知っておくこと

• フレーム番号。 seek、set-in、set-out、および --frame オプションが受け取るのは、ルーラーに印字された番号ではなく、クリップ内の 0 から数えた位置です。1001 から始まるクリップでは、表示上のフレーム 1010 は位置 9 です。status は位置（playback.currentFrame）と最初のフレーム番号（playback.startOffset）を返します。
• 非同期のもの。 open は、クリップを解析する前に応答します。クリップが画面に出るまで、status.playback.transitioning は true のままです。export はジョブをキューに入れます。export-status または export-done イベントで追跡してください。export-notes はバックグラウンドでファイルを書き込みます。set-proxy のあとは、status.viewport.retiering が false に戻るのを待ってください。
• 新しいプロファイルでは、初回起動時の質問がモーダルウィンドウで表示されます。先に {"cmd": "set-ui-level", "value": "complete"} を送ってください。
• quit は応答したあと、保存するかどうかを尋ねずに、プレーヤーを正常に閉じます。レビューが重要な場合は、先に save-playlist または export-notes を送ってください。
• 同じ名前のリクエストを複数同時に送ると、区別できなくなります。1 つずつ順に送ってください。

ファミリー別のコマンド

プレーヤーの 115 のコマンドです。括弧内のフィールドは主なものです。track は "A"（既定）または "B" です。

再生と範囲

クリップとプレイリスト

比較とバージョン

カラー

ビューア、インターフェース、ウィンドウ

ノート、キャプチャ、書き出し

メモリとデコード

レビューセッション

トラッカー（どのリクエストにもシークレットは含めない）

診断

イベント

プレーヤーは、これらの行を、要求されなくてもクライアントにブロードキャストします。

status

{"cmd": "status"} は、状態全体を返します。特に有用なブロックは次のとおりです。playback（state、currentFrame、startOffset、fps、ab_mode、ab_view、transitioning、late_frames と lost_frames のカウンター）、color（トラック A のグレード、チャンネル）、viewport（デコード後とオリジナルの解像度、proxy_idx、retiering、zoom）、decode（デコード時間、too_slow）、track_b、ram_fit、playlist（クリップごとに 1 エントリ）。

例

最新のレンダリングを開いて再生する（たとえば Nuke のボタンから）：

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

再生ヘッドに追従する（たとえば Maya のタイムラインを同期させる場合）：

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

デイリーズを書き出して、終わるまで待つ：

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

レビューのノートを収集する：

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

パスワード付きのレビューセッションを開始する：

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

ファイルフォーマット

api フォルダーには、やり取りされるファイルの JSON スキーマが入っています。playlist.schema.json（.bpl プレイリスト。トラッカーの識別子を持つ x_tracking ブロックを含む）、notes_payload.schema.json（ノートの export.json）、export_recipe.schema.json（書き出しレシピ）、そして export_examples/ の書き出しジョブのサンプルです。

関連項目：コマンドラインとヘッドレス書き出し、連携。