Python API 与 IPC

Bernard Review 可以由 Python、Maya、Nuke、Houdini、生产 tracker，或任何能打开 TCP 连接的语言来操控。艺术家手动完成的每一件事都有对应的命令：打开片段、播放、对比、调色、导出、开始会话、发布备注。本页足以让您实现播放器的自动化；逐字段的完整参考是 API 参考（英文；也可通过 Help > API Documentation 打开）。

协议

• 地址：127.0.0.1，默认端口 5556。使用 --ipc-port N 启动的播放器监听 N：这样同一台机器上就可以运行两个播放器。
• 格式：JSON Lines。每个请求是单独一行的一个 JSON 对象，以 \n 结尾，带有 "cmd" 字段：{"cmd": "seek", "frame": 24}。
• 每个请求对应一个应答，按发送顺序返回，通常在几毫秒之内：{"status": "ok", "cmd": "seek", ...} 或 {"status": "error", "cmd": "seek", "reason": "..."}。错误总是附带一个用平实语言写成的原因，绝不会等到您的超时。没有请求 ID：应答通过其 "cmd" 与请求对应。
• 播放器发出的事件（{"event": ...}）在同一连接上到达，与应答混杂在一起（见下文）。
• 一次只能有一个客户端。 第二个连接要等第一个关闭后才能进行。
• 仅限本地。 该端口只在环回上监听。看起来像浏览器请求的连接（HTTP 行、Host: 头）会被直接关闭，不执行任何内容：网页无法操控播放器。一行最多 16 MiB。
• 通过这个端口不会传输任何机密信息用于 tracker：携带 tracker 密码、密钥或令牌的请求会被拒绝。

无需编写代码就能试用：Window > Console（Ctrl+Shift+C）可以在播放器内部发送同样的命令，并支持 Tab 补全：status、seek {"frame": 24}，或完整的 JSON 形式。在执行写文件、发布或关闭播放器的命令之前，它会先询问。

Python 客户端

bernard_api.py 用一个类 BernardClient 封装了该协议，每个命令对应一个方法。它安装在播放器旁边的 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。
• 多个同名请求同时在途时无法区分：请逐个发送。

按系列划分的命令

播放器的 115 个命令。括号中的字段是主要字段；track 为 "A"（默认）或 "B"。

播放与范围

片段与播放列表

对比与版本

色彩

查看器、界面和窗口

备注、截图与导出

内存与解码

审阅会话

Tracker（任何请求都不含机密信息）

诊断

事件

播放器会主动向其客户端广播这些行：

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（每个片段一项）。

示例

打开最新的渲染并播放（例如从 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 schema：playlist.schema.json（.bpl 播放列表，带有 tracker 标识符的 x_tracking 块）、notes_payload.schema.json（备注的 export.json）和 export_recipe.schema.json（导出方案），以及 export_examples/ 中的导出任务示例。

另请参见：命令行与无界面导出、集成。