IA native

Travailler avec votre agent sur un projet Beam

Beam CLI permet à un agent externe d’examiner et de modifier de véritables projets Capture d’écran et vidéo. Demandez-lui de lire le document, d’apporter une modification et d’examiner le résultat. Le projet reste modifiable dans Beam.

• Modifiez le contenu natif : coupez ou déplacez des clips, réglez les zooms et les arrière-plans, ou organisez les calques, groupes et effets de Capture d’écran.
• Créez des créations HTML et TypeScript, éventuellement avec Vue, GSAP ou WebGL, puis publiez-les sous forme de calque.
• Examinez le canevas en direct, annulez une modification et exportez avec le moteur de rendu de Beam.

Configurer le lanceur en ligne de commande

Utilisez le lanceur beam-cli fourni avec Beam. Depuis une copie du code source, remplacez beam-cli par bun run beam et exécutez la commande à la racine du dépôt. Commencez par lister les outils et lire leurs schémas ; ces commandes de découverte fonctionnent sans l’application de bureau.

Les appels d’outils acceptent du JSON en ligne, un fichier d’arguments précédé d’un arobase, ou un tiret pour lire le JSON depuis stdin. Les résultats sont envoyés vers stdout ; les erreurs vers stderr avec un code de sortie non nul. Les exemples en ligne utilisent les guillemets POSIX. Sous Windows, les fichiers d’arguments évitent les différences de guillemets entre shells. Les chemins d’un fichier sont résolus à côté de celui-ci ; les chemins en ligne sont résolus depuis le répertoire de travail.

beam-cli tools list
beam-cli tools describe html.publish
beam-cli docs agent
beam-cli docs html
beam-cli docs gradients
beam-cli docs commands
beam-cli commands

Installer les skills Beam

Ouvrez un terminal dans le projet utilisé par votre agent, puis installez les skills. La destination par défaut est .agents/skills dans ce projet. Aucune installation globale n’est effectuée sauf si vous indiquez explicitement --global. Rechargez ensuite les skills de l’agent ou démarrez une nouvelle session.

Le pack comprend dix skills spécialisées. Installez-les toutes avec la commande ci-dessous ou ajoutez des noms pour en choisir certaines, par exemple beam-cli beam-design beam-composition beam-animation. Pour utiliser un dossier propre à un agent, indiquez --agent claude, --agent cursor ou --agent gemini ; ces dossiers restent également dans le projet actuel. Si votre CLI installé ne reconnaît pas encore les skills, utilisez une version plus récente de Beam CLI ou bun run beam depuis une copie à jour du code source de Beam.

beam-cli skills install

Vérifier et mettre à jour les skills

Exécutez ces commandes depuis le même dossier de projet. check compare les fichiers installés au pack de BeamRecorder/Beam sans rien modifier. Son rapport JSON indique les skills à jour, manquantes, obsolètes, modifiées ou en conflit ; la commande renvoie le code de sortie 1 si une skill sélectionnée n’est pas à jour. update télécharge le pack actuel, y compris les skills manquantes, et préserve vos modifications locales.

Le pack maintenu se trouve dans .skills/Beam-cli sur le dépôt GitHub de Beam. Les fichiers sont vérifiés avant installation. Les mises à jour sont explicites ; les commandes de montage courantes ne recherchent pas de nouvelles skills. Utilisez --ref avec un tag ou un commit pour fixer une version, et consultez les skills docs pour les dossiers personnalisés et la protection des modifications locales.

beam-cli skills check
beam-cli skills update
beam-cli docs skills

Ouvrir le projet et lire son état

Démarrez Beam, puis listez les projets. L’exemple crée un canevas Capture d’écran transparent. Remplacez PROJECT_UUID par l’identifiant renvoyé, ouvrez le projet et attendez que projects.list inclue cet identifiant dans open. Demandez ensuite documents.snapshot pour obtenir le document et la révision actuels.

Pour Studio, utilisez kind: video à la création comme à l’ouverture. projects.open ouvre normalement un nouvel éditeur ; disposition: reuse remplace l’éditeur actif. Si plusieurs instances de Beam sont ouvertes, ajoutez --instance PID avec un identifiant obtenu via instances.

beam-cli instances
beam-cli tools call projects.list
beam-cli tools call projects.create '{"kind":"image","name":"Feature card","width":1920,"height":1080}'
beam-cli tools call projects.open '{"projectId":"PROJECT_UUID","kind":"image"}'
beam-cli tools call documents.snapshot '{"projectId":"PROJECT_UUID"}'

Modifier un calque Capture d’écran

Utilisez cet exemple avec un projet contenant une image capturée, et non avec le canevas vide créé ci-dessus. Enregistrez-le sous edit.json et remplacez SCREENSHOT_UUID et expectedRevision par les valeurs de documents.snapshot. Le calque source capturé a l’identifiant image ; la transaction le renomme et lui ajoute un angle 3D.

Trouvez les autres identifiants de calque dans l’instantané. L’interface de commande prend en charge le placement, le recadrage, le groupement, l’ordre, la couleur, les effets et les réglages PNG/WebP. Lisez le schéma de données avant de modifier le document. Un tableau effects remplace toute la pile : incluez donc les effets existants à conserver.

{
  "projectId": "SCREENSHOT_UUID",
  "expectedRevision": 0,
  "operationId": "screenshot-perspective-1",
  "commands": [
    {
      "type": "still.layer.rename",
      "payload": {
        "layerId": "image",
        "name": "Product capture"
      }
    },
    {
      "type": "still.layer.compositing",
      "payload": {
        "layerId": "image",
        "patch": {
          "rotation3d": {
            "x": 6,
            "y": -12,
            "perspective": 1200
          }
        }
      }
    }
  ]
}

Modifier un clip vidéo existant

Pour un projet vidéo contenant un clip, utilisez plutôt cette transaction dans edit.json. Remplacez VIDEO_UUID, expectedRevision et CLIP_ID à partir d’un nouvel instantané. Elle applique un flou d’arrière-plan et déplace le clip à une seconde sur la chronologie.

Les commandes vidéo couvrent aussi le découpage, la scission, la vitesse de lecture, le volume, les sous-titres, les éléments, les groupes de scène, l’animation de propriétés et les zooms. assets.import copie les médias dans le projet ; utilisez ensuite les commandes de document pour les placer sur la chronologie.

{
  "projectId": "VIDEO_UUID",
  "expectedRevision": 0,
  "operationId": "video-layout-1",
  "commands": [
    {
      "type": "render.patch",
      "payload": {
        "blurPercent": 12
      }
    },
    {
      "type": "clip.move",
      "payload": {
        "clipId": "CLIP_ID",
        "startMs": 1000
      }
    }
  ]
}

Appliquer une transaction

Appliquez edit.json au projet qu’il décrit. Les commandes forment une modification atomique et une seule étape d’annulation : si le lot est invalide, aucune partie n’est appliquée. Le contenu verrouillé reste protégé.

Attribuez un nouvel operationId à chaque modification. Réutilisez un identifiant uniquement pour réessayer une requête identique. Vous pouvez annuler dans Beam ou appeler documents.undo/documents.redo avec expectedRevision actuel et un requestId unique.

beam-cli tools call documents.transact @edit.json

Créer une carte HTML statique

Créez composition/index.html à partir de l’exemple ci-dessous. Gardez les polices, styles et médias en local. HTML et TypeScript fonctionnent sans Vue ; installez les bibliothèques importées dans ce projet source.

Une carte statique n’a pas besoin d’une horloge d’animation. Beam attend le chargement des polices locales et le décodage des images. Pour une initialisation asynchrone, exposez une promesse ready sur window.beamComposition.

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <style>
      html, body { margin: 0; width: 100%; height: 100%;
        overflow: hidden; background: transparent; }
      .card { position: absolute; inset: 100px; padding: 80px;
        border-radius: 40px; background: #151517; color: white;
        font: 64px sans-serif; }
    </style>
  </head>
  <body><div class="card">Beam feature</div></body>
</html>

Préparer la demande de publication

Enregistrez publish.json à côté du dossier de composition. Utilisez l’identifiant et la révision actuelle de votre projet Capture d’écran ouvert. Width et height indiquent les dimensions du canevas HTML en pixels. Les publications Capture d’écran nécessitent durationMs: 0. Utilisez framework: html, ou vue pour une source Vue.

{
  "projectId": "SCREENSHOT_UUID",
  "expectedRevision": 0,
  "entry": "./composition/index.html",
  "width": 1920,
  "height": 1080,
  "durationMs": 0,
  "framework": "html",
  "name": "Feature card"
}

Ajouter la carte à Beam

html.publish compile la source, enregistre son code source et son bundle dans le projet et insère un calque HTML. La commande renvoie layerId et la nouvelle révision. Un projet Capture d’écran conserve également un PNG rendu de ce calque.

Pour créer une autre version de la même carte, conservez le layerId renvoyé dans publish.json et actualisez expectedRevision. La mise à jour préserve le placement, l’ordre des calques, la visibilité et les effets. Les versions source publiées restent accessibles dans le projet rouvert et l’historique d’annulation.

beam-cli tools call html.publish @publish.json

Animer un calque vidéo avec une horloge navigable

Pour animer la carte pendant cinq secondes, installez GSAP dans son projet source et enregistrez le code ci-dessous sous composition/main.ts. Ajoutez à index.html un script module pour ./main.ts. Dans publish.json, utilisez l’identifiant d’un projet vidéo ouvert, durationMs: 5000 et fps: 30. Supprimez layerId de Capture d’écran avant la première publication dans cette vidéo.

Exposez window.beamComposition.seek(timeMs). Beam demande des instants exacts en millisecondes et peut revenir en arrière. Gardez GSAP en pause et définissez explicitement le temps de sa chronologie. Avec Vue, attendez les mises à jour réactives ; avec WebGL, dessinez l’image terminée. seek peut renvoyer une promesse pour une préparation asynchrone.

import { gsap } from 'gsap';

const timeline = gsap.timeline({ paused: true });
timeline.fromTo('.card',
  { opacity: 0, y: 80 },
  { opacity: 1, y: 0, duration: 1 }, 0);
timeline.to('.card', { scale: 1.05, duration: 3 }, 1);
timeline.to('.card', { opacity: 0, duration: 1 }, 4);

Object.assign(window, {
  beamComposition: {
    seek(timeMs: number) {
      timeline.time(timeMs / 1000, false);
    },
  },
});

Prévisualiser les sauvegardes de source dans Beam

Conservez un layerId existant dans publish.json et lancez html watch. La commande publie une première fois, lit la révision en cours avant les mises à jour suivantes et republie après chaque sauvegarde de la source. Ctrl+C arrête la surveillance. Une erreur de compilation ou de révision laisse le calque publié précédent disponible.

Pour retrouver le code d’un calque sauvegardé, appelez html.source avec le descripteur HTML de documents.snapshot. Copiez la source enregistrée dans un dossier de travail avant de la modifier ; les versions source publiées sont immuables. L’aperçu peut regrouper des demandes, tandis que l’exportation effectue le rendu de chaque image demandée dans la chronologie.

beam-cli html watch @publish.json

Importer des images et des polices

• Conservez les images et polices locales dans le dossier source, ou fournissez des entrées references avec les champs name et source. Beam copie ces fichiers dans le dossier references à côté du HTML.
• Pour référencer un média d’un autre projet sauvegardé, incluez son projectId. assets.resolve localise un fichier appartenant à un projet pour inspection ; html.publish peut le copier dans le bundle.
• Utilisez du texte natif pour modifier le texte dans Beam : still.layer.add pour Capture d’écran, ou clip.insert pour les éléments vidéo. Le texte HTML se modifie dans son code source.
• fonts.import accepte TTF, OTF, WOFF et WOFF2. Définissez text.style.fontFamily et text.style.fontAssetId avec la famille et l’identifiant renvoyés pour que le texte modifiable utilise cette police dans l’aperçu et l’exportation.

beam-cli tools call fonts.list
beam-cli tools call fonts.import '{"source":"./fonts/HankenGrotesk.ttf"}'

Examiner et exporter le résultat

Installez une fois le moteur Chromium de la CLI, ou définissez BEAM_CHROMIUM_EXECUTABLE vers un navigateur compatible. Laissez Beam ouvert pendant l’exportation d’un projet ouvert contenant des calques HTML : il fournit leurs images rendues. Remplacez les identifiants ci-dessous et choisissez un instant situé dans la durée de la vidéo.

Capture d’écran utilise les réglages PNG/WebP de son document ; faites correspondre l’extension de sortie au format choisi. La vidéo prend en charge MP4 et WebM avec les calques, sous-titres et zooms de la composition. Pour remplacer volontairement une destination existante, indiquez overwrite: true.

beam-cli browser install
beam-cli tools call render.export '{"projectId":"SCREENSHOT_UUID","output":"feature.png"}'
beam-cli tools call render.export '{"projectId":"VIDEO_UUID","output":"demo.mp4","format":"mp4"}'
beam-cli tools call render.frame '{"projectId":"VIDEO_UUID","timeMs":2000,"output":"frame.png"}'

Modifier un fichier image sans l’application de bureau

Partez d’un fichier PNG existant et de ses dimensions réelles. Enregistrez uniquement le tableau commands de la transaction Capture d’écran dans edits.json, puis créez, modifiez et exportez le document autonome ci-dessous. Ce flux modifie un document fichier, pas un éditeur Beam ouvert.

Les commandes standalone edit et serve ne nécessitent pas l’application de bureau. L’exportation requiert le moteur Chromium de la CLI. Pour une vidéo HTML sans éditeur, utilisez motion avec un fichier de tâche ; beam-cli docs html décrit l’entrée, les dimensions, la durée en secondes, les fps et le format.

beam-cli create image capture.png 1920 1080 screenshot.json
beam-cli edit screenshot.json edits.json edited-screenshot.json
beam-cli export edited-screenshot.json finished.png

Comprendre ce qui s’exécute en local

La CLI se connecte au bureau via un point de terminaison local authentifié. Beam effectue le rendu en local. Le HTML publié s’exécute dans des fenêtres isolées sans accès à Node ni préchargement Beam ; les requêtes réseau externes sont bloquées, donc regroupez ses ressources en local.

Vous fournissez l’agent et le modèle. Le traitement de leurs données dépend du fournisseur choisi. Beam fournit les outils de document et l’interface de rendu ; il n’inclut ni abonnement de chat IA, ni serveur MCP stdio, ni montage partagé par réseau.