API de Python e IPC

Bernard Review puede controlarse desde Python, Maya, Nuke, Houdini, un tracker de producción o cualquier lenguaje capaz de abrir una conexión TCP. Todo lo que un artista hace a mano tiene su comando: abrir clips, reproducir, comparar, corregir el color, exportar, iniciar una sesión, publicar notas. Esta página basta para automatizar el reproductor; la referencia exhaustiva, campo por campo, es la referencia de la API, en inglés (también abierta por Help > API Documentation).

El protocolo

• Dirección: 127.0.0.1, puerto 5556 por defecto. Un reproductor iniciado con --ipc-port N escucha en N: así es como dos reproductores funcionan en la misma máquina.
• Formato: JSON Lines. Cada petición es un objeto JSON en una línea, terminada con \n, con un campo "cmd": {"cmd": "seek", "frame": 24}.
• Una respuesta por petición, en el orden de envío, normalmente en unos pocos milisegundos: {"status": "ok", "cmd": "seek", ...} o {"status": "error", "cmd": "seek", "reason": "..."}. Un error siempre lleva un motivo en lenguaje llano y nunca espera a su tiempo de espera. No hay identificador de petición: una respuesta se asocia a su petición por su "cmd".
• Los eventos del reproductor ({"event": ...}) llegan por la misma conexión, mezclados con las respuestas (véase más abajo).
• Un solo cliente a la vez. Una segunda conexión espera a que se cierre la primera.
• Solo en local. El puerto escucha en el loopback. Una conexión que parece la petición de un navegador (una línea HTTP, una cabecera Host:) se cierra sin ejecutar nada: una página web no puede controlar el reproductor. Una línea contiene como máximo 16 MiB.
• Ningún secreto pasa por este puerto en lo que respecta a los trackers: una petición que lleve una contraseña, una clave o un token de tracker se rechaza.

Para probarlo sin escribir código: Window > Console (Ctrl+Mayús+C) envía los mismos comandos desde el propio reproductor, con autocompletado con Tab: status, seek {"frame": 24}, o la forma JSON completa. Pregunta antes de los comandos que escriben archivos, publican o cierran el reproductor.

El cliente de Python

bernard_api.py envuelve el protocolo en una clase, BernardClient, con un método por comando. Se instala junto al reproductor, en la carpeta api:

No necesita nada más que la biblioteca estándar de 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) envía un comando y espera su respuesta (un dict), errores incluidos: no lanza ninguna excepción por la negativa del reproductor, y devuelve None si se agota el tiempo de espera o se pierde la conexión.
• send_command(dict) envía sin esperar.
• Los métodos con nombre (play(), seek(), set_exposure(), export()...) llaman a uno u otro; los que devuelven datos pasan por request().
• on("frame_changed", function) suscribe una función a un evento; un hilo en segundo plano lee la conexión.

Sin el cliente, bastan unas pocas líneas:

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

Qué saber antes de escribir un script

• Números de fotograma. seek, set-in, set-out y la opción --frame toman la posición en el clip contada desde 0, no el número impreso en la regla. En un clip que empieza en 1001, el fotograma mostrado 1010 es la posición 9. status da la posición (playback.currentFrame) y el número del primer fotograma (playback.startOffset).
• Qué es asíncrono. open responde antes de que se sondee el clip: status.playback.transitioning permanece en true hasta que el clip está en pantalla. export pone un trabajo en cola: sígalo con export-status o con el evento export-done. export-notes escribe sus archivos en segundo plano. Tras set-proxy, espere a que status.viewport.retiering vuelva a false.
• Un perfil nuevo hace la pregunta del primer arranque en una ventana modal: envíe primero {"cmd": "set-ui-level", "value": "complete"}.
• quit responde y después cierra el reproductor de forma limpia, sin preguntar si se guarda: envíe antes save-playlist o export-notes si la revisión importa.
• Varias peticiones del mismo nombre en vuelo no se pueden distinguir: envíelas una tras otra.

Comandos, por familia

Los 115 comandos del reproductor. Los campos entre paréntesis son los principales; track es "A" (el valor por defecto) o "B".

Reproducción y rango

Clips y playlist

Comparación y versiones

Color

Visor, interfaz y ventanas

Notas, capturas y exportación

Memoria y decodificación

Sesiones de revisión

Trackers (ningún secreto en ninguna petición)

Diagnóstico

Eventos

El reproductor difunde estas líneas a su cliente, sin que se las pidan:

status

{"cmd": "status"} devuelve todo el estado. Los bloques más útiles: playback (state, currentFrame, startOffset, fps, ab_mode, ab_view, transitioning, los contadores late_frames y lost_frames), color (la corrección de la pista A, canal), viewport (resolución decodificada y original, proxy_idx, retiering, zoom), decode (tiempo de decodificación, too_slow), track_b, ram_fit y playlist (una entrada por clip).

Ejemplos

Abrir el último render y reproducirlo (desde un botón de Nuke, por ejemplo):

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

Seguir el cabezal de reproducción (para mantener sincronizada una timeline de Maya, por ejemplo):

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

Exportar dailies y esperar al final:

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

Recoger las notas de una revisión:

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

Iniciar una sesión de revisión protegida con contraseña:

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

Formatos de archivo

La carpeta api contiene los esquemas JSON de los archivos intercambiados: playlist.schema.json (la playlist .bpl, con el bloque x_tracking de identificadores del tracker), notes_payload.schema.json (el export.json de las notas) y export_recipe.schema.json (recetas de exportación), y trabajos de exportación de ejemplo en export_examples/.

Véanse también: Línea de comandos y exportación sin ventana, Integraciones.