Piloter un enregistrement NDI® avec Companion et l’API HTTP | Apex

Pour piloter l’enregistrement d’une source NDI® avec Bitfocus Companion, utilisez le module Generic HTTP Requests et l’API de Timecode Recorder : POST /start_record démarre, POST /stop_record arrête et GET /status lit l’état. Configurez des boutons séparés pour garder une commande explicite et contrôler le résultat.

Préparer le Recorder et le réseau

Ouvrez Timecode Recorder, sélectionnez une source puis cliquez sur Connect. Attendez au moins une image reçue ; une connexion seule ne suffit pas au départ API. Contrôlez aussi le son avant la prise. Le port par défaut est 8088. Dans le panneau API, relevez l’URL de base réellement affichée. Après changement de port, utilisez Apply puis actualisez votre configuration Companion.

Si Companion tourne sur le même Mac, http://127.0.0.1:8088 convient avec le port par défaut. Sur une autre machine, remplacez cette adresse par celle du Mac Recorder sur votre LAN. 127.0.0.1 désigne toujours la machine qui envoie la requête.

Réservez cette API à un réseau de confiance, sans exposition Internet. Automatic répond sur les interfaces réseau du Mac. Le choix d’une carte peut refuser une requête par HTTP 403 si son adresse ne correspond pas, mais ce filtre ne constitue pas une authentification ni une isolation forte. Maîtrisez l’accès réseau aux machines autorisées.

Créer la connexion Generic HTTP Requests

1. Dans Companion, ajoutez une connexion utilisant Generic HTTP Requests. Consultez la documentation officielle du module Bitfocus pour les champs de votre version.
2. Renseignez Base URL avec l’URL du Recorder, sans chemin de commande, par exemple http://127.0.0.1:8088. Vous pouvez aussi laisser ce champ vide et saisir des URL complètes dans chaque action.
3. Créez un bouton START REC. À l’appui, ajoutez une action de requête POST, avec l’URL complète http://127.0.0.1:8088/start_record adaptée à votre hôte. Laissez le corps vide ; aucun JSON n’est requis.
4. Créez STOP REC de la même manière, en POST vers http://127.0.0.1:8088/stop_record.
5. Créez un troisième bouton de lecture STATUS, en GET vers http://127.0.0.1:8088/status. Une URL complète ignore la Base URL : mettez les trois actions à jour si l’adresse change.

Comprendre ce que chaque requête confirme

Pour isoler un problème avant Companion, exécutez ces commandes séparément dans un terminal sur le Mac Recorder, en laissant une courte prise entre Start et Stop :

curl --fail-with-body http://127.0.0.1:8088/status
curl --fail-with-body -X POST http://127.0.0.1:8088/start_record
curl --fail-with-body -X POST http://127.0.0.1:8088/stop_record

Une commande d’enregistrement envoyée en GET renvoie 405. Un paramètre invalide ou une source absente peut produire 400 ; un refus d’adresse, 403. Lisez la réponse plutôt que de considérer tout échange HTTP comme une réussite.

Erreur fréquente : relancer Start après un silence

Évitez les réessais automatiques : Start répété peut remplacer un enregistrement actif. Si la réponse manque, consultez d’abord l’application et Status. Un bouton coloré au clic indique une action demandée ; pour afficher l’état réel, configurez séparément la lecture et l’interprétation de la réponse. Gardez les commandes manuelles accessibles.

Retrouver et contrôler le fichier

Un départ API écrit dans ~/Movies/NDI_AAAAMMJJ-HHMMSS.mov, indépendamment du dossier et du nom saisis dans Recording. Après Stop, ouvrez ce fichier et vérifiez image, audio et durée. Faites d’abord un essai court, puis un contrôle de perte réseau sans prise utile en cours. Le retour WebRTC aide à observer l’image, mais ne confirme pas l’écriture complète du MOV.

NDI® est une marque déposée de Vizrt NDI AB.