Scripts et API Python

Bernard peut être automatisé de deux façons :

• des scripts que Bernard lance lui-même, sur une tâche (tâche script), sur une sélection (action), à une date (événement) ou quand une valeur change (déclencheur) ;
• l'API Python (CallBernard) : une bibliothèque qu'un script, un plugin ou un outil externe utilise pour lire et modifier ce que contient Bernard.

Les scripts et l'API s'adressent aux TD et aux développeurs de pipeline. Un artiste n'en a pas besoin pour travailler.

Ce que les scripts peuvent faire

Via l'API, un script peut :

• chercher des objets (projets, éléments, tâches, fichiers, utilisateurs…) ;
• lire et écrire des propriétés, une par une ou plusieurs à la fois ;
• créer et supprimer des objets (une suppression faite par un script va dans la corbeille Garbage, restaurable comme une suppression faite dans l'interface) ;
• calculer des chemins selon la variation de chemin et le système du poste, créer des versions de fichiers, enregistrer ou regénérer des vignettes ;
• copier, déplacer, envoyer ou télécharger des fichiers entre variations de chemin ;
• lire les instructions d'une tâche et les cocher, lire et écrire le temps passé ;
• construire des workflows de modèle (tâches, compounds, liens) en un seul appel ;
• ouvrir un média dans le lecteur du studio, comme le ferait Bernard (voir Revue) ;
• afficher une fenêtre de message ou de choix de fichier dans le client.

Un script agit avec les droits de l'utilisateur connecté. Une écriture refusée par les règles (machine d'états, droits) ne lève pas d'erreur : l'appel rend False. Voir Workflows, états et modèles pour ces règles.

Les tâches script

Une tâche script est une tâche du workflow qui lance une commande. Le script devient ainsi une étape du workflow, avec ses sources, ses suites et ses états.

Ce qu'elle porte :

Comment elle s'exécute :

1. Quand la tâche devient Ready (ses sources sont terminées), le Bernard du poste désigné la lance. Il n'y a pas de bouton Run : pour relancer un script, remettez sa tâche en Ready.
2. Elle passe en WIP et sa sortie (normale et erreurs) s'écrit dans Log. Pendant l'exécution, le Log se met à jour toutes les 5 secondes.
3. Elle passe en Done si le script se termine avec le code 0, en Failed sinon.

Règles à connaître :

• Quel poste ? Avec Launch On renseigné, c'est ce poste, quel que soit l'utilisateur connecté. Avec Launch On vide, c'est le poste courant de l'utilisateur assigné. Dans les deux cas la tâche doit avoir exactement un assigné ; un poste éteint ou plusieurs assignés empêchent le lancement automatique (un avertissement l'explique dans le Log). Le cas typique est un utilisateur « robot » seul dans son couple département × rôle.
• File d'attente. Au plus 3 scripts tournent en même temps sur un poste (Local Settings › Max Simultaneous Script). Les autres attendent, par priorité ; à priorité égale, dans l'ordre où ils sont devenus Ready.
• Chaînes de scripts. Avec le réglage de studio Subsequent scripts are executed first, la chaîne de scripts d'un plan se termine avant que ceux d'un autre plan continuent.
• Arrêt. Passer une tâche en Aborted arrête le script en cours (et les processus qu'il a lancés). Si une tâche est réassignée pendant l'exécution (autre utilisateur, département ou poste), le script s'arrête et la tâche passe en Failed. Fermer Bernard pendant qu'un script tourne demande une confirmation.
• Journal. Le Log garde la fin de la sortie si elle est trop longue (réglages du studio Max number of lines for the logs of a task script et Max size in kiloBytes for the logs of a task script).
• Un seul Bernard par poste exécute les scripts : l'instance principale.

Actions, déclencheurs et événements

• Une action est une commande enregistrée dans les réglages, que l'on lance à la main sur une sélection (clic droit, sous-menus par département), qui peut démarrer avec Bernard, ou que déclenche un événement. Trois actions tournent au plus en même temps (Max Simultaneous Action). Une action est réussie si elle n'écrit rien sur sa sortie d'erreur. La vue Action Log montre « Waiting », « Running », « Success » ou « Failed ».
• Un déclencheur surveille une propriété (état, version, valeur) et lance une action quand une condition est remplie. Un déclencheur Changed ne se lance pas si la valeur ne change pas.
• Un événement lance une action à une date, pour des utilisateurs ou des rôles, avec une répétition (Never, Every Day, Every Week, Every Hour). Un événement qui ne vous est plus assigné ne lance plus son action.

L'API Python

Référence

La référence complète, générée à partir du code et tenue à jour à chaque version, est en ligne :

bernardengineapi.readthedocs.io

On y trouve la classe CallBernard (communiquer avec Bernard), des outils pour les chemins et les logiciels tiers (3DEqualizer, Nuke…) et les constantes à utiliser avec l'API. Pour chaque méthode : ce qu'elle fait, ce qu'elle accepte, ce qu'elle renvoie et les erreurs qu'elle signale. L'application ouvre cette référence depuis Help › API Documentation.

Se connecter

L'API parle au client Bernard ouvert sur le même poste, comme un plugin de logiciel de création (voir Intégrations DCC).

• Le client Bernard doit être lancé et connecté.
• Une connexion par fil d'exécution : rappeler CallBernard() rend la même.
• Les objets sont désignés par leur identifiant (24 caractères hexadécimaux), les propriétés par leur nom (State, Start Frame…).
• Si aucun client n'écoute, la connexion est refusée (ConnectionRefusedError). Une erreur côté Bernard lève une exception avec la trace du client.

from Bernard import CallBernard
from Bernard.Static import State, ClassName

bernard = CallBernard()
print(bernard.GetCurrentUserID())

Exemples

Les exemples utilisent des identifiants fictifs.

# Mes tâches à faire, et passer la première en WIP
for task_id in bernard.GetMyTasks():
    print(bernard.GetPropertyValue(task_id, "Name"))

task_id = bernard.GetMyTasks()[0]
if not bernard.SetPropertyValue(task_id, "State", State.wip):
    print("refusé : assignation, checklist, correction active…")

# Publier une nouvelle version d'un fichier et obtenir son chemin sur ce poste
bernard.IncrementVersion(file_id)
print(bernard.GetPathValue(nodeID=file_id))

# Les plans d'une séquence dont une tâche est en cours
shots = bernard.FindNodeIDs(parentIDs=[sequence_id], classNames=[ClassName.projectItem],
                            projectItemModelName="Shot")
wip = bernard.FindNodeIDs(parentIDs=[sequence_id], classNames=[ClassName.task],
                          propertyFilter={"State": [State.wip, State.pause]})

# Ouvrir un fichier dans le lecteur du studio
bernard.OpenInPlayer(nodeID=file_id)

Familles de méthodes

La liste complète et les paramètres sont dans la référence en ligne.

Nouveautés de l'API dans la 2.1.48

• Créer et configurer des tâches et des compounds dans le workflow d'un modèle en un appel (propriétés, modes global / local, liens), les exporter, changer le mode d'une propriété ; tout est vérifié avant la moindre écriture.
• Créer un modèle d'élément de projet avec son workflow vide.
• Chercher par propriété avec une liste de valeurs (par exemple plusieurs états pour State) : un élément correspond s'il a l'une d'elles.
• Lister toutes les applications capables d'ouvrir une extension, par priorité, pour prendre la première installée sur le poste.
• Une API qui refuse de créer un fichier sous une tâche de validation, où il ne serait visible nulle part.
• Chercher les enfants d'un dossier ne lit plus toute la base et n'est plus interrompu après 60 secondes (correction du 2026-11-09, voir Notes de version).

Exemples d'automatisation en studio

Ces exemples montrent ce que des studios ont automatisé avec l'API. Ce sont des scripts propres à des studios, pas des fonctions du produit. Ils sont décrits ici sans nom de studio ni de projet, pour illustrer les possibilités.

Principes que ces exemples illustrent :

• demander les chemins à Bernard (GetPathValue), selon la variation de chemin du poste, au lieu de les écrire en dur ;
• trouver les applications et FFmpeg par l'installation de Bernard, pas par un chemin figé ;
• passer par l'API publique CallBernard, dans un processus séparé, plutôt que par des interfaces internes du client.

Aller plus loin

• Workflows, états et modèles : les états des tâches, les tâches script dans le workflow.
• Intégrations DCC : les plugins des logiciels de création, qui utilisent la même API.
• Revue : ouvrir un média dans Bernard Review.
• Référence de l'API : bernardengineapi.readthedocs.io.