Emir Chouchane - Carnet de notes

API REST pour caméras Blackmagic et Companion

Les caméras Blackmagic peuvent être contrôlées soit à travers un mélangeur ATEM, soit directement via leur API REST. Dans ce dernier cas, il suffit d’envoyer des requêtes HTTP de type GET ou PUT à l’adresse IP de la caméra, en veillant à ce qu’elle soit connectée au même réseau local que votre ordinateur.

Configuration de la caméra

Pour une première configuration de la caméra, installer le logiciel Blackmagic Camera Setup sur votre ordinateur, connecter la caméra à votre ordinateur via USB-C et ouvrir le logiciel. Profitez-en pour mettre à jour le firmware. Configurer ensuite l'adresse IP, le nom de la caméra (optionnel), le masque sous-réseau et la passerelle. Ne pas oublier d'activer le web media manager (HTTP) et Allow utility administration.

Blackmagic Camera Setup

S'assurer d'être sur le même réseau que la caméra envoyant un ping à l'adresse IP depuis votre ordinateur. Plusieurs caméras peuvent être connectées au même réseau, il faut s'assurer qu'elles ont des noms ou des adresses IP différentes.

Utilisation de l'API

Pour utiliser l'API, il faut envoyer des requêtes HTTP à l'adresse IP de la caméra. Voici quelques exemples de requêtes :

# Obtenir la configuration de la vidéo : format, codec, etc.
GET http://<camera_ip>/control/api/v1/system
# Avoir la valeur du shutter
GET http://<camera_ip>/control/api/v1/video/shutter

Pour les GET, les réponses sont au format JSON.

La documentation de l'API REST est disponible sur le site de Blackmagic Design. Il est possible d'utiliser des outils comme Postman pour tester les requêtes avant de les intégrer dans un script ou une application.

L'API ne permet malheureusement pas de contrôler l'alimentation de la caméra, ni l'enregistrement ou son arrêt à distance.

Utilisation avec Companion

Companion est un logiciel qui permet de contrôler des appareils via une interface web ou un StreamDeck. Il est possible d'utiliser Companion pour contrôler les caméras Blackmagic en utilisant l'API de la caméra.

Pour cela, il faut ajouter le module HTTP dans Companion et configurer les requêtes pour contrôler la caméra. Voici comment faire :

  1. Ouvrir Companion et se rendre dans l'onglet Modules.
  2. Ajouter le module HTTP Generic.
  3. Vu que j'ai plusieurs caméras, je ne vais pas indiquer l'adresse IP dans la configuration du module, mais dans chaque bouton que je vais créer.
  4. Changer Unauthorized Certificates à Accept.
  5. Dans l'onglet Boutons, ajouter un bouton en cliquant sur le bouton Ajouter un bouton.
  6. Dans Actions, sélectionnez le module HTTP, puis choisissez la méthode PUT.
  7. Dans le champ URL, indiquer l'URL de la requête HTTP que vous souhaitez envoyer à la caméra. Par exemple, pour avoir l'état du système, vous pouvez utiliser l'URL suivante :
    http://<camera_ip>/control/api/v1/system
  8. Garder le reste tel quel.
  9. Vérifiez dans le journal (log) de Companion que la requête a bien été envoyée et que la caméra a répondu.

Contrôle de l'optique

Ce qui m'intéresse avant tout avec cette méthode, c'est de pouvoir contrôler l'optique, aussi bien le zoom que le focus. Dans mes tests, j'ai utilisé la caméra Blackmagic Micro Studio 4K G2 et une optique compatible Olympus M.Zuiko ED 14-42mm f/3.5-5.6 EZ.

Petite note : Le capteur est un CMOS Four Thirds, donc l’objectif 14mm devient un équivalent 28mm (facteur x2). À prendre en considération lors du choix de l'optique.

Voici un exemple de requête pour contrôler le zoom avant dans Companion:

Le normalised fait référence à une valeur de zoom représentée en float entre 0.0 et 1.0, indépendamment de la plage optique réelle de la caméra. À 0.0, le zoom est au minimum, et à 1.0, il est au maximum. À vous de faire la conversion par rapport à l'optique que vous utilisez.

Je cherche encore une méthode fiable pour incrémenter le zoom avec de ±0.1 via une variable custom, ce qui éviterait d’avoir un bouton pour chaque niveau de zoom. Si vous avez une idée, n’hésitez pas à me la transmettre!

Pour le focus, vous pouvez soit envoyer une commande AutoFocus, soit définir une valeur de focus normalisée. Consultez la documentation de l'API REST de Blackmagic pour plus de détails (Section Lens Control API, page 22).

Voici un exemple de requête pour l'AutoFocus, directement depuis Companion :

Companion Blackmagic AutoFocus

Vous remarquerez que j’utilise le nom de la caméra au lieu de son adresse IP. J’ai cependant constaté une certaine lenteur avec les noms en .local, probablement liée à la résolution du nom d’hôte. Je vous recommande donc d’utiliser directement l’adresse IP pour une communication plus rapide et fiable.

En quelques boutons, vous pouvez créer une interface simple pour vos besoins : Companion Blackmagic

Note : J’utilise un switch PDU pour gérer l’alimentation des caméras, d’où la présence des boutons Allumer et Éteindre (qui devraient d’ailleurs être regroupés en un seul bouton avec changement d’état!)

Aller plus loin avec Companion

La prochaine étape, cela serait d'avoir du feedback sur les valeurs du zoom, focus, etc. directement dans Companion. Il est possible de le faire en utilisant des requêtes GET, cela permet d'avoir une interface un peu plus interactive.

N'hésitez pas à me faire part de vos retours ou de vos questions sur ce sujet!