IA nativa

Trabaja en un proyecto de Beam con tu agente

Beam CLI permite que un agente externo examine y edite proyectos reales de Screenshot y vídeo. Pídele que lea el documento, haga un cambio y revise el resultado. El mismo proyecto seguirá siendo editable en Beam.

• Edita contenido nativo: recorta o mueve clips, ajusta zooms y fondos, u organiza capas, grupos y efectos de Screenshot.
• Crea diseños en HTML y TypeScript, opcionalmente con Vue, GSAP o WebGL, y publícalos como una capa.
• Revisa el lienzo en directo, deshaz una edición y exporta con el renderizador de Beam.

Configura el iniciador de línea de comandos

Usa el iniciador beam-cli incluido con Beam. Desde una copia del código fuente, sustituye beam-cli por bun run beam y ejecútalo desde la raíz del repositorio. Empieza por enumerar las herramientas y leer sus esquemas; estos comandos de descubrimiento funcionan sin la aplicación de escritorio.

Las llamadas a herramientas aceptan JSON en línea, un archivo de argumentos precedido por una arroba o un guion para leer JSON de stdin. Los resultados se envían a stdout; los errores, a stderr con un código de salida distinto de cero. Los ejemplos en línea usan el entrecomillado POSIX. En Windows, los archivos de argumentos evitan las diferencias de entrecomillado del shell. Las rutas de un archivo se resuelven junto a él; las rutas en línea, desde el directorio de trabajo.

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

Instala las skills de Beam

Abre un terminal en el proyecto donde trabaja tu agente e instala las skills. El destino predeterminado es .agents/skills dentro de ese proyecto. No se instala nada globalmente salvo que pases --global de forma explícita. Después, vuelve a cargar las skills del agente o inicia una sesión nueva.

El paquete incluye diez skills especializadas. Instálalas todas con el comando siguiente o añade nombres para elegir algunas, como beam-cli beam-design beam-composition beam-animation. Para usar una carpeta específica del agente, indica --agent claude, --agent cursor o --agent gemini; esas carpetas también quedan dentro del proyecto actual. Si la CLI instalada aún no reconoce las skills, usa una compilación más reciente de Beam CLI o ejecuta bun run beam desde una copia actualizada del código fuente de Beam.

beam-cli skills install

Comprueba y actualiza las skills

Ejecuta estos comandos desde la misma carpeta del proyecto. check compara los archivos instalados con el paquete de BeamRecorder/Beam y no cambia nada. Su informe JSON identifica las skills actuales, ausentes, desactualizadas, modificadas o en conflicto; devuelve el código 1 si alguna skill seleccionada no está al día. update descarga el paquete actual, incluidas las skills ausentes, y protege tus cambios locales.

El paquete mantenido está en .skills/Beam-cli, en el repositorio de GitHub de Beam. Los archivos se verifican antes de instalarse. Las actualizaciones son explícitas; los comandos de edición habituales no buscan skills nuevas. Usa --ref con una etiqueta o un commit para fijar una versión y consulta las skills de documentación sobre carpetas personalizadas y protección de cambios locales.

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

Abre el proyecto y consulta su estado

Inicia Beam y enumera los proyectos. El ejemplo crea un lienzo Screenshot transparente. Sustituye PROJECT_UUID por el id devuelto, abre el proyecto y espera a que projects.list incluya ese id en open. Después, solicita documents.snapshot para obtener el documento y la revisión actuales.

Para Studio, usa kind: video tanto al crear como al abrir. projects.open normalmente abre un editor nuevo; disposition: reuse reemplaza el editor activo. Si hay más de una instancia de Beam en ejecución, añade --instance PID con un id de 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"}'

Edita una capa de Screenshot

Usa este ejemplo con un proyecto que incluya una imagen capturada, no con el lienzo vacío creado antes. Guárdalo como edit.json y sustituye SCREENSHOT_UUID y expectedRevision por valores de documents.snapshot. La capa de origen capturada tiene el id image; la transacción le cambia el nombre y añade un ángulo 3D.

Busca otros ids de capa en el snapshot. La interfaz de comandos admite colocación, recorte, agrupación, orden, color, efectos y ajustes de PNG/WebP. Lee el esquema del payload antes de editar. Un array effects reemplaza toda la pila, así que incluye los efectos existentes que quieras conservar.

{
  "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
          }
        }
      }
    }
  ]
}

Edita un clip de vídeo existente

Para un proyecto de vídeo que contenga un clip, usa esta transacción como edit.json. Sustituye VIDEO_UUID, expectedRevision y CLIP_ID a partir de un snapshot reciente. Aplica desenfoque al fondo y mueve el clip al segundo uno de la línea de tiempo.

Los comandos de vídeo también permiten recortar, dividir y ajustar la velocidad de reproducción, el volumen, los subtítulos, los elementos, los grupos de escena, la animación de propiedades y los zooms. assets.import copia medios al proyecto; después usa comandos de documento para colocarlos en la línea de tiempo.

{
  "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
      }
    }
  ]
}

Aplica una transacción

Aplica edit.json al proyecto que describe. Los comandos forman una edición atómica y un único paso de deshacer: si el lote no es válido, no se aplica ninguna parte. El contenido bloqueado sigue protegido.

Asigna un operationId nuevo a cada edición. Reutiliza un id solo al reintentar exactamente la misma operación. Puedes deshacer en Beam o llamar a documents.undo/documents.redo con el expectedRevision actual y un requestId único.

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

Crea una tarjeta HTML estática

Crea composition/index.html con el ejemplo siguiente. Mantén las fuentes, los estilos y los medios en local. HTML y TypeScript funcionan sin Vue; instala las bibliotecas importadas en este proyecto de origen.

Una tarjeta estática no necesita un reloj de animación. Beam espera a que se carguen las fuentes locales y se decodifiquen las imágenes. Para una inicialización asíncrona, expón una promesa ready en 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>

Prepara la solicitud de publicación

Guarda publish.json junto a la carpeta de composición. Usa el id y la revisión actual del proyecto Screenshot abierto. Width y height son las dimensiones en píxeles del lienzo HTML. Las publicaciones de Screenshot requieren durationMs: 0. Usa framework: html o vue para una fuente Vue.

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

Añade la tarjeta a Beam

html.publish compila el código, guarda el origen y el paquete en el proyecto e inserta una capa HTML. Devuelve layerId y la nueva revisión. Un proyecto Screenshot también guarda un PNG renderizado de esa capa.

Para crear otra versión de la misma tarjeta, conserva el layerId devuelto en publish.json y actualiza expectedRevision. La actualización conserva la posición, el orden de las capas, la visibilidad y los efectos. Las versiones publicadas del código siguen disponibles en el proyecto reabierto y el historial de deshacer.

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

Anima una capa de vídeo con un reloj navegable

Para animar la tarjeta durante cinco segundos, instala GSAP en su proyecto de origen y guarda el código siguiente como composition/main.ts. Añade a index.html un script de módulo para ./main.ts. En publish.json, usa el id de un proyecto de vídeo abierto, durationMs: 5000 y fps: 30. Elimina el layerId de Screenshot antes de la primera publicación en este vídeo.

Expón window.beamComposition.seek(timeMs). Beam solicita tiempos exactos en milisegundos y puede retroceder. Mantén GSAP en pausa y define de forma explícita el tiempo de su línea de tiempo. Con Vue, espera a las actualizaciones reactivas; con WebGL, dibuja el fotograma terminado. seek puede devolver una promesa para preparar operaciones asíncronas.

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);
    },
  },
});

Previsualiza los guardados del código en Beam

Conserva un layerId existente en publish.json e inicia html watch. Publica una vez, lee la revisión actual antes de las actualizaciones posteriores y vuelve a publicar al guardar el código. Ctrl+C detiene la supervisión. Si ocurre un error de compilación o de revisión, la capa publicada anteriormente sigue disponible.

Para recuperar el código de una capa guardada, llama a html.source con el descriptor HTML de documents.snapshot. Copia el código guardado a una carpeta de trabajo antes de editarlo; las versiones publicadas son inmutables. La vista previa puede agrupar solicitudes, mientras que la exportación renderiza cada fotograma solicitado de la línea de tiempo.

beam-cli html watch @publish.json

Añade imágenes y fuentes

• Guarda las imágenes y fuentes locales en la carpeta de origen o proporciona entradas references con campos name y source. Beam copia estos archivos en references junto al HTML.
• Para hacer referencia a medios de otro proyecto guardado, incluye su projectId. assets.resolve localiza un archivo del proyecto para examinarlo; html.publish puede copiarlo al paquete.
• Usa texto nativo si quieres editar las palabras en Beam: still.layer.add para Screenshot o clip.insert para elementos de vídeo. El texto de HTML se edita en su código de origen.
• fonts.import acepta TTF, OTF, WOFF y WOFF2. Asigna text.style.fontFamily y text.style.fontAssetId a la familia y el id devueltos para que el texto editable use esa fuente en la vista previa y la exportación.

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

Examina y exporta el resultado

Instala una vez el backend Chromium de la CLI o configura BEAM_CHROMIUM_EXECUTABLE para que apunte a un navegador compatible. Mantén Beam en ejecución mientras exportas un proyecto abierto con capas HTML: proporciona sus fotogramas renderizados. Sustituye los ids siguientes y elige un tiempo dentro de la duración del vídeo.

Screenshot usa los ajustes PNG/WebP de su documento; utiliza la extensión de salida correspondiente. Video admite MP4 y WebM con las capas, los subtítulos y los zooms de la composición. Para reemplazar intencionadamente un destino existente, pasa 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"}'

Edita un archivo de imagen sin la aplicación de escritorio

Empieza con un PNG existente y sus dimensiones reales. Guarda solo el array commands de la transacción Screenshot como edits.json y luego crea, edita y exporta el documento independiente siguiente. Este flujo modifica un documento de archivo, no un editor abierto de Beam.

Standalone edit y serve no requieren la aplicación de escritorio. Para exportar se necesita el backend Chromium de la CLI. Para crear un vídeo HTML sin editor, usa motion con un archivo de tarea; beam-cli docs html describe la entrada, las dimensiones, la duración en segundos, los fps y el formato.

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

Comprende qué se ejecuta localmente

La CLI se conecta al escritorio mediante un endpoint local autenticado. Beam renderiza localmente. El HTML publicado se ejecuta en ventanas aisladas sin acceso a Node ni a un preload de Beam; las solicitudes de red externas están bloqueadas, así que incluye sus recursos en el paquete local.

Tú proporcionas el agente y el modelo. El tratamiento de datos depende del proveedor que elijas. Beam ofrece las herramientas de documentos y la interfaz de renderizado; no incluye una suscripción de chat con IA, un servidor MCP stdio ni edición compartida en red.