API Python et IPC

Bernard Review se pilote depuis Python, Maya, Nuke, Houdini, un outil de suivi de production ou tout langage capable d'ouvrir une connexion TCP. Tout ce qu'un artiste fait à la main a sa commande : ouvrir des plans, lire, comparer, étalonner, exporter, lancer une séance, publier des notes. Cette page suffit pour automatiser le lecteur ; la référence exhaustive, champ par champ, est la référence de l'API, en anglais (aussi ouverte par Help > API Documentation).

Le protocole

• Adresse : 127.0.0.1, port 5556 par défaut. Un lecteur lancé avec --ipc-port N écoute sur N : c'est ainsi que deux lecteurs tournent sur la même machine.
• Format : JSON Lines. Chaque requête est un objet JSON sur une ligne, terminé par \n, avec un champ "cmd" : {"cmd": "seek", "frame": 24}.
• Une réponse par requête, dans l'ordre d'envoi, en général en quelques millisecondes : {"status": "ok", "cmd": "seek", ...} ou {"status": "error", "cmd": "seek", "reason": "..."}. Une erreur porte toujours une raison en clair et n'attend jamais l'expiration du délai. Il n'y a pas d'identifiant de requête : on associe une réponse à sa requête par son "cmd".
• Les événements du lecteur ({"event": ...}) arrivent sur la même connexion, mêlés aux réponses (voir plus bas).
• Un client à la fois. Une deuxième connexion attend que la première se ferme.
• Local seulement. Le port écoute sur la boucle locale. Une connexion qui ressemble à une requête de navigateur (une ligne HTTP, un en-tête Host:) est fermée sans rien exécuter : une page web ne peut pas piloter le lecteur. Une ligne fait au plus 16 Mio.
• Aucun secret ne passe par ce port pour les trackers : une requête qui contient un mot de passe, une clé ou un jeton de tracker est refusée.

Pour essayer sans écrire de code : Window > Console (Ctrl+Maj+C) envoie les mêmes commandes depuis le lecteur, avec complétion par Tab : status, seek {"frame": 24}, ou la forme JSON complète. Elle demande confirmation avant les commandes qui écrivent des fichiers, publient ou ferment le lecteur.

Le client Python

bernard_api.py emballe le protocole dans une classe, BernardClient, avec une méthode par commande. Il est installé à côté du lecteur, dans le dossier api :

Il n'a besoin que de la bibliothèque standard 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 ne répond pas sur le port 5556")

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

• request(dict) envoie une commande et attend sa réponse (un dict), erreurs comprises : elle ne lève pas d'exception pour un refus du lecteur, et renvoie None en cas d'expiration ou de connexion perdue.
• send_command(dict) envoie sans attendre.
• Les méthodes nommées (play(), seek(), set_exposure(), export()...) appellent l'une ou l'autre ; celles qui renvoient des données passent par request().
• on("frame_changed", fonction) abonne une fonction à un événement ; un fil de fond lit la connexion.

Sans le client, quelques lignes suffisent :

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":      # on saute les événements
            print(msg["playback"]["currentFrame"]); break

Ce qu'il faut savoir avant d'écrire un script

• Les numéros d'image. seek, set-in, set-out et l'option --frame prennent la position dans le plan comptée à partir de 0, pas le numéro affiché sur la règle. Sur un plan qui commence à 1001, l'image affichée 1010 est la position 9. status donne la position (playback.currentFrame) et le numéro de départ (playback.startOffset).
• Ce qui est asynchrone. open répond avant que le plan soit sondé : status.playback.transitioning reste true jusqu'à ce que le plan soit à l'écran. export met un travail en file : suivez-le avec export-status ou l'événement export-done. export-notes écrit ses fichiers en arrière-plan. Après set-proxy, attendez que status.viewport.retiering repasse à false.
• Un profil neuf pose la question du premier lancement dans une fenêtre modale : envoyez d'abord {"cmd": "set-ui-level", "value": "complete"}.
• quit répond, puis ferme le lecteur proprement, sans demander s'il faut enregistrer : envoyez save-playlist ou export-notes avant si la revue compte.
• Plusieurs requêtes du même nom en parallèle ne se distinguent pas : envoyez-les l'une après l'autre.

Les commandes, par famille

Les 115 commandes du lecteur. Les champs entre parenthèses sont les principaux ; track vaut "A" (par défaut) ou "B".

Lecture et plage

Plans et playlist

Comparaison et versions

Couleur

Viewer, interface et fenêtres

Notes, captures et export

Mémoire et décodage

Séances de revue

Trackers (sans aucun secret dans les requêtes)

Diagnostic

Les événements

Le lecteur diffuse ces lignes à son client, sans qu'il les demande :

status

{"cmd": "status"} renvoie l'état complet. Les blocs les plus utiles : playback (state, currentFrame, startOffset, fps, ab_mode, ab_view, transitioning, les compteurs late_frames et lost_frames), color (étalonnage de la piste A, canal), viewport (résolution décodée et d'origine, proxy_idx, retiering, zoom), decode (temps de décodage, too_slow), track_b, ram_fit et playlist (un élément par plan).

Exemples

Ouvrir le dernier rendu et le lire (par exemple depuis un bouton de Nuke) :

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

Suivre la tête de lecture (pour synchroniser une timeline Maya, par exemple) :

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

Exporter des dailies et attendre la fin :

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

Récupérer les notes d'une revue :

import json, os, time
out = "D:/review/SQ010_notes"
client.export_notes(out)
time.sleep(2)  # l'écriture se fait en arrière-plan
notes = json.load(open(os.path.join(out, "export.json"), encoding="utf-8"))

Lancer une séance de revue protégée :

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

Formats de fichiers

Le dossier api contient les schémas JSON des fichiers échangés : playlist.schema.json (la playlist .bpl, avec le bloc x_tracking des identifiants de tracker), notes_payload.schema.json (le export.json des notes) et export_recipe.schema.json (les recettes d'export), ainsi que des exemples de travaux d'export dans export_examples/.

Voir aussi : Ligne de commande et export sans fenêtre, Intégrations.