IA nativa

Trabalhe em um projeto do Beam com seu agente

A Beam CLI permite que um agente externo inspecione e edite projetos reais de Screenshot e vídeo. Peça que ele leia o documento, faça uma alteração e confira o resultado. O mesmo projeto continua editável no Beam.

• Edite conteúdo nativo: corte ou mova clipes, ajuste zooms e planos de fundo ou organize camadas, grupos e efeitos de Screenshot.
• Crie artes em HTML e TypeScript, opcionalmente com Vue, GSAP ou WebGL, e publique-as como uma camada.
• Confira a tela ao vivo, desfaça uma edição e exporte usando o renderizador do Beam.

Configure o iniciador da linha de comando

Use o iniciador beam-cli incluído no Beam. Em um checkout do código-fonte, substitua beam-cli por bun run beam e execute o comando na raiz do repositório. Comece listando as ferramentas e lendo seus esquemas; esses comandos de descoberta funcionam sem o aplicativo para desktop.

As chamadas de ferramentas aceitam JSON em linha, um arquivo de argumentos prefixado com o símbolo de arroba ou um hífen para receber JSON pela entrada padrão. Os resultados vão para stdout; os erros, para stderr, com código de saída diferente de zero. Os exemplos em linha usam aspas no formato POSIX. No Windows, arquivos de argumentos evitam diferenças de escape no shell. Os caminhos em um arquivo são resolvidos a partir da pasta dele; os caminhos em linha são resolvidos a partir do diretório de trabalho.

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

Instale as skills do Beam

Abra um terminal no projeto em que seu agente trabalha e instale as skills. O destino padrão é .agents/skills dentro desse projeto. Nada é instalado globalmente, a menos que você passe --global explicitamente. Depois, recarregue as skills do agente ou inicie uma nova sessão.

O pacote inclui dez skills especializadas. Instale todas com o comando abaixo ou acrescente nomes para selecionar um subconjunto, como beam-cli beam-design beam-composition beam-animation. Para usar uma pasta específica do agente, passe --agent claude, --agent cursor ou --agent gemini; os arquivos também ficam dentro do projeto atual. Se a CLI instalada ainda não reconhecer skills, use uma versão mais recente da Beam CLI ou bun run beam em um checkout atualizado do código-fonte do Beam.

beam-cli skills install

Confira e atualize as skills

Execute estes comandos na mesma pasta do projeto. check compara os arquivos instalados com o pacote em BeamRecorder/Beam sem fazer alterações. O relatório JSON identifica skills atualizadas, ausentes, desatualizadas, modificadas ou em conflito; o comando termina com código 1 quando alguma skill selecionada não está atualizada. update baixa o pacote atual, incluindo as skills ausentes, e protege suas edições locais.

O pacote mantido fica em .skills/Beam-cli no repositório do Beam no GitHub. Os arquivos são verificados antes da instalação. As atualizações são explícitas; os comandos normais de edição não procuram novas skills. Use --ref com uma tag ou um commit quando precisar fixar uma versão e consulte as skills de documentação para saber mais sobre pastas personalizadas e alterações locais protegidas.

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

Abra o projeto e leia o estado dele

Inicie o Beam e liste os projetos. O exemplo cria uma tela Screenshot transparente. Substitua PROJECT_UUID pelo id retornado, abra o projeto e aguarde até que projects.list o inclua em open. Em seguida, solicite documents.snapshot para obter o documento e a revisão atuais.

Para o Studio, use kind: video tanto na criação quanto na abertura. Em geral, projects.open abre um novo editor; disposition: reuse substitui o editor ativo. Se houver mais de uma instância do Beam em execução, acrescente --instance PID usando um 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"}'

Edite uma camada Screenshot

Use este exemplo com um projeto que contenha uma imagem capturada, e não com a tela vazia criada acima. Salve-o como edit.json e substitua SCREENSHOT_UUID e expectedRevision pelos valores de documents.snapshot. A camada de origem capturada tem o id image; a transação a renomeia e adiciona um ângulo 3D.

Encontre os ids de outras camadas no snapshot. A interface de comandos oferece posicionamento, recorte, agrupamento, ordenação, cor, efeitos e configurações de PNG/WebP. Leia o esquema do payload antes de editar. Um array effects substitui toda a pilha; por isso, inclua os efeitos existentes que quiser manter.

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

Edite um clipe de vídeo existente

Para um projeto de vídeo que contenha um clipe, use esta transação no lugar do exemplo anterior e salve-a como edit.json. Substitua VIDEO_UUID, expectedRevision e CLIP_ID usando um snapshot recente. Ela aplica desfoque ao plano de fundo e move o clipe para a marca de um segundo na linha do tempo.

Os comandos de vídeo também incluem corte, divisão, velocidade de reprodução, volume, legendas, elementos, grupos de cenas, animação de propriedades e zooms. assets.import copia a mídia para o projeto; depois, use os comandos de documento para colocá-la na linha do tempo.

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

Aplique uma transação

Aplique edit.json ao projeto descrito nele. Os comandos formam uma única edição atômica e uma etapa de desfazer: se o lote for inválido, nenhuma alteração parcial será confirmada. O conteúdo bloqueado continua protegido.

Use um operationId novo para cada edição nova. Reutilize um id somente ao repetir uma solicitação idêntica. Você pode desfazer no Beam ou chamar documents.undo/documents.redo com o expectedRevision atual e um requestId exclusivo.

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

Crie um cartão HTML estático

Crie composition/index.html usando o exemplo abaixo. Mantenha fontes, estilos e mídias localmente. HTML e TypeScript funcionam sem Vue; instale as bibliotecas importadas neste projeto de origem.

Um cartão estático não precisa de relógio de animação. O Beam aguarda o carregamento das fontes locais e a decodificação das imagens. Para inicialização assíncrona, exponha uma promessa ready em 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>

Prepare a solicitação de publicação

Salve publish.json ao lado da pasta da composição. Use o id e a revisão atual do seu projeto Screenshot aberto. Largura e altura são as dimensões, em pixels, da tela HTML. Publicações Screenshot exigem durationMs: 0. Use framework: html ou vue para uma origem em Vue.

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

Adicione o cartão ao Beam

html.publish compila a origem, armazena o código-fonte e o bundle no projeto e insere uma camada HTML. O comando retorna layerId e a nova revisão. Um projeto Screenshot também armazena um PNG renderizado dessa camada.

Para criar outra versão do mesmo cartão, mantenha o layerId retornado em publish.json e atualize expectedRevision. A atualização preserva o posicionamento, a ordem das camadas, a visibilidade e os efeitos. As versões publicadas do código-fonte continuam disponíveis ao reabrir o projeto e no histórico de desfazer.

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

Anime uma camada de vídeo com um relógio navegável

Para animar o cartão por cinco segundos, instale o GSAP no projeto de origem e salve o código abaixo como composition/main.ts. Adicione a index.html um script de módulo para ./main.ts. Em publish.json, use o id de um projeto de vídeo aberto, durationMs: 5000 e fps: 30. Remova o layerId de Screenshot antes da primeira publicação neste vídeo.

Exponha window.beamComposition.seek(timeMs). O Beam solicita tempos exatos em milissegundos e pode retroceder. Mantenha o GSAP pausado e defina explicitamente o tempo da linha do tempo. Com Vue, aguarde as atualizações reativas; com WebGL, desenhe o quadro concluído. seek pode retornar uma promessa para preparação assíncrona.

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é-visualize salvamentos do código-fonte no Beam

Mantenha um layerId existente em publish.json e inicie html watch. O comando publica uma vez, lê a revisão atual antes das atualizações seguintes e republica após cada salvamento do código-fonte. Ctrl+C interrompe a monitoração. Um erro de compilação ou revisão mantém disponível a camada publicada anteriormente.

Para recuperar o código de uma camada salva, chame html.source com o descritor HTML de documents.snapshot. Copie o código-fonte armazenado para uma pasta de trabalho antes de editá-lo; as versões publicadas são imutáveis. A pré-visualização pode agrupar solicitações, enquanto a exportação renderiza cada quadro solicitado da linha do tempo.

beam-cli html watch @publish.json

Adicione imagens e fontes

• Mantenha imagens e fontes locais na pasta de origem ou forneça entradas references com os campos name e source. O Beam copia esses arquivos para references, ao lado do HTML.
• Para referenciar mídia de outro projeto salvo, inclua projectId. assets.resolve localiza um arquivo pertencente ao projeto para inspeção; html.publish pode copiá-lo para o bundle.
• Use texto nativo quando quiser editar a redação no Beam: still.layer.add para Screenshot ou clip.insert para elementos de vídeo. O texto dentro do HTML é editado no código-fonte.
• fonts.import aceita TTF, OTF, WOFF e WOFF2. Defina text.style.fontFamily e text.style.fontAssetId com a família e o id retornados para que o texto editável use essa fonte na pré-visualização e na exportação.

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

Inspecione e exporte o resultado

Instale uma vez o backend Chromium da CLI ou aponte BEAM_CHROMIUM_EXECUTABLE para um navegador compatível. Mantenha o Beam em execução ao exportar um projeto aberto com camadas HTML: ele fornece os quadros renderizados dessas camadas. Substitua os ids abaixo e escolha um tempo de quadro dentro da duração do vídeo.

Screenshot usa as configurações PNG/WebP do documento; escolha uma extensão de saída correspondente a esse formato. Vídeo aceita MP4 e WebM com as camadas, legendas e zooms da composição. Para substituir intencionalmente um destino existente, passe 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"}'

Edite um arquivo de imagem sem o aplicativo para desktop

Comece com um PNG existente e suas dimensões reais. Salve somente o array commands da transação Screenshot em edits.json; depois, crie, edite e exporte o documento independente abaixo. Esse fluxo altera um documento de arquivo, não um editor aberto no Beam.

Os comandos standalone edit e serve não exigem o aplicativo para desktop. A exportação precisa do backend Chromium da CLI. Para gerar um vídeo HTML sem um editor, use motion com um arquivo de tarefa; beam-cli docs html descreve a entrada, as dimensões, a duração em segundos, o fps e o 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

Entenda o que é executado localmente

A CLI se conecta ao aplicativo para desktop por um endpoint local autenticado. O Beam renderiza localmente. O HTML publicado é executado em janelas isoladas, sem acesso ao Node nem ao preload do Beam; solicitações à rede externa são bloqueadas, então inclua os recursos no bundle local.

Você fornece o agente e o modelo. O tratamento dos dados depende do provedor escolhido. O Beam fornece as ferramentas de documento e a interface de renderização; não inclui uma assinatura de chat com IA, um servidor MCP stdio nem edição compartilhada pela rede.