AI ネイティブ

エージェントと Beam プロジェクトを編集する

Beam CLI を使うと、外部エージェントが実際の Screenshot と動画のプロジェクトを確認・編集できます。ドキュメントを読み、変更を加え、結果を確認するよう指示できます。同じプロジェクトは Beam でも引き続き編集できます。

• ネイティブコンテンツを編集する：クリップをトリミングまたは移動し、ズームや背景を調整し、Screenshot のレイヤー、グループ、エフェクトを配置します。
• 必要に応じて Vue、GSAP、WebGL を使って HTML と TypeScript のアートワークを作成し、レイヤーとして公開します。
• ライブキャンバスを確認し、編集を取り消し、Beam のレンダラーで書き出します。

コマンドラインランチャーを設定する

Beam に同梱されている beam-cli ランチャーを使用します。ソースのチェックアウトから使う場合は、beam-cli を bun run beam に置き換え、リポジトリのルートで実行してください。まずツール一覧を表示してスキーマを読みます。これらの検出コマンドはデスクトップアプリなしで実行できます。

ツール呼び出しでは、JSON の直接指定、先頭に @ を付けた引数ファイル、または標準入力の JSON を示す - を使用できます。結果は stdout に、エラーはゼロ以外の終了コードとともに stderr に出力されます。直接指定の例では POSIX 形式の引用符を使います。Windows では引数ファイルを使うとシェルごとの引用符の違いを避けられます。ファイル内のパスはそのファイルの場所を基準に解決され、直接指定のパスは作業ディレクトリを基準に解決されます。

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

Beam スキルをインストールする

エージェントが作業するプロジェクトでターミナルを開き、スキルをインストールします。既定のインストール先はプロジェクト内の .agents/skills です。--global を明示的に指定しない限り、グローバルにはインストールされません。インストール後、エージェントのスキルを再読み込みするか、新しいセッションを開始してください。

このパックには用途別のスキルが 10 個含まれています。以下のコマンドですべてをインストールするか、beam-cli beam-design beam-composition beam-animation などの名前を追加して一部を選択します。エージェント固有のフォルダーを使うには --agent claude、--agent cursor、または --agent gemini を指定します。これらも現在のプロジェクト内にインストールされます。インストール済みの CLI がまだスキルを認識しない場合は、新しい Beam CLI ビルドを使うか、最新の Beam ソースチェックアウトから bun run beam を実行してください。

beam-cli skills install

スキルを確認して更新する

同じプロジェクトフォルダーでこれらのコマンドを実行します。check はインストール済みファイルと BeamRecorder/Beam 内のパックを比較し、変更は行いません。JSON レポートには最新、欠落、古い、変更済み、競合中のスキルが示されます。選択したスキルに最新でないものがあると、終了コード 1 で終了します。update は欠落分を含む最新パックをダウンロードし、ローカルの編集を保護します。

メンテナンス対象のパックは Beam の GitHub リポジトリ内の .skills/Beam-cli にあります。インストール前にファイルが検証されます。更新は明示的に行います。通常の編集コマンドは新しいスキルを確認しません。特定のバージョンに固定する場合は --ref とタグまたはコミットを指定し、カスタムフォルダーや保護されるローカル変更については docs のスキルを読んでください。

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

プロジェクトを開いて状態を読む

Beam を起動してプロジェクト一覧を表示します。この例では透明な Screenshot キャンバスを作成します。PROJECT_UUID を返された ID に置き換えて開き、projects.list の open にその ID が表示されるまで待ちます。次に、現在のドキュメントとリビジョンについて documents.snapshot を要求します。

Studio の作成とオープンには、どちらも kind: video を指定します。projects.open は通常、新しいエディターを開きます。disposition: reuse を指定すると現在のエディターを置き換えます。複数の Beam インスタンスが実行中の場合は、instances で取得した ID を使い --instance PID を追加します。

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"}'

Screenshot レイヤーを編集する

上で作成した空のキャンバスではなく、画像をキャプチャしたプロジェクトでこの例を使います。edit.json として保存し、SCREENSHOT_UUID と expectedRevision を documents.snapshot の値に置き換えます。キャプチャしたソースレイヤーの ID は image です。このトランザクションはレイヤー名を変更して 3D の角度を加えます。

スナップショットでほかのレイヤー ID を確認します。コマンドインターフェイスは配置、切り抜き、グループ化、順序、色、エフェクト、PNG/WebP 設定に対応しています。編集前にペイロードのスキーマを確認してください。effects 配列はスタック全体を置き換えるため、残したい既存のエフェクトも含めてください。

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

既存の動画クリップを編集する

クリップを含む動画プロジェクトでは、代わりにこのトランザクションを edit.json として使用します。最新のスナップショットにある VIDEO_UUID、expectedRevision、CLIP_ID に置き換えてください。背景のぼかしを設定し、クリップをタイムラインの 1 秒位置に移動します。

動画コマンドではトリミング、分割、再生速度、音量、キャプション、要素、シーングループ、プロパティアニメーション、ズームも操作できます。assets.import はメディアをプロジェクトにコピーします。その後、document コマンドでタイムラインに配置してください。

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

トランザクションを適用する

edit.json を記述されているプロジェクトに適用します。コマンドは 1 つのアトミックな編集と 1 回の取り消し操作になります。バッチが無効なら一部だけが適用されることはありません。ロックされたコンテンツは保護されます。

編集ごとに新しい operationId を指定します。同一内容を再試行する場合に限り ID を再利用できます。Beam で取り消すか、現在の expectedRevision と一意の requestId を指定して documents.undo/documents.redo を呼び出せます。

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

静的 HTML カードを作成する

以下の例を使って composition/index.html を作成します。フォント、スタイル、メディアはローカルに置いてください。HTML と TypeScript は Vue なしで動作します。インポートするライブラリはこのソースプロジェクトにインストールしてください。

静的カードにアニメーションクロックは不要です。Beam はローカルフォントと画像のデコードを待ちます。非同期で初期化する場合は window.beamComposition に ready promise を公開してください。

<!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>

公開リクエストを準備する

publish.json を composition フォルダーの隣に保存します。開いている Screenshot プロジェクトの ID と現在のリビジョンを使用してください。width と height は HTML キャンバスのピクセル寸法です。Screenshot への公開では durationMs: 0 が必要です。framework: html を指定し、Vue ソースの場合は vue を指定します。

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

カードを Beam に追加する

html.publish はソースをコンパイルし、ソースとバンドルをプロジェクトに保存して HTML レイヤーを挿入します。layerId と新しいリビジョンを返します。Screenshot プロジェクトにはそのレイヤーをレンダリングした PNG も保存されます。

同じカードの別バージョンを公開するには、返された layerId を publish.json に残し、expectedRevision を更新します。更新後も配置、レイヤー順、表示状態、エフェクトは保持されます。公開済みソースバージョンはプロジェクトを開き直した後も、取り消し履歴からも利用できます。

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

シーク可能なクロックで動画レイヤーをアニメーション化する

カードを 5 秒間アニメーション化するには、ソースプロジェクトに GSAP をインストールし、以下のコードを composition/main.ts として保存します。index.html に ./main.ts の module script を追加してください。publish.json では開いている動画プロジェクトの ID、durationMs: 5000、fps: 30 を指定します。この動画への初回公開前に Screenshot の layerId を削除してください。

window.beamComposition.seek(timeMs) を公開してください。Beam はミリ秒単位の正確な時刻を要求し、逆方向にもシークできます。GSAP は一時停止したままにして、タイムライン時刻を明示的に設定してください。Vue ではリアクティブ更新を待ち、WebGL では完成したフレームを描画します。非同期準備では seek が promise を返す場合があります。

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

ソースの保存内容を Beam でプレビューする

publish.json に既存の layerId を残して html watch を開始します。最初に 1 回公開し、その後の更新前に最新リビジョンを読み取り、ソースの保存後に再公開します。Ctrl+C で監視を停止します。コンパイルまたはリビジョンエラーが起きても前回公開したレイヤーは利用できます。

保存済みレイヤーのコードを取得するには、documents.snapshot の HTML 記述子を使って html.source を呼び出します。編集前に保存済みソースを作業フォルダーへコピーしてください。公開済みソースバージョンは変更できません。プレビューでは要求がまとめられる場合がありますが、書き出しでは要求された各タイムラインフレームがレンダリングされます。

beam-cli html watch @publish.json

画像とフォントを取り込む

• ローカル画像とフォントをソースフォルダーに置くか、name と source フィールドを含む references エントリーを指定します。Beam はこれらのファイルを HTML の隣にある references フォルダーへコピーします。
• 別の保存済みプロジェクトのメディアを参照するには、その projectId を含めます。assets.resolve は確認用にプロジェクト所有のファイルを探し、html.publish はバンドルにコピーできます。
• Beam で文言を編集したい場合はネイティブテキストを使います。Screenshot では still.layer.add、動画要素では clip.insert を使用します。HTML 内のテキストはソースコードで編集します。
• fonts.import は TTF、OTF、WOFF、WOFF2 を受け付けます。返されたファミリー名と ID を text.style.fontFamily と text.style.fontAssetId に設定すると、編集可能なテキストがプレビューと書き出しでそのフォントを使います。

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

結果を確認して書き出す

CLI の Chromium バックエンドを一度インストールするか、BEAM_CHROMIUM_EXECUTABLE に対応ブラウザーのパスを指定します。HTML レイヤーを含む開いたプロジェクトを書き出す間は Beam を起動したままにしてください。Beam がレイヤーのレンダリング済みフレームを提供します。以下の ID を置き換え、動画の長さの範囲内でフレーム時刻を選択してください。

Screenshot はドキュメントの PNG/WebP 設定を使うため、出力ファイルの拡張子を形式に合わせてください。動画ではコンポジションのレイヤー、キャプション、ズームを含めて MP4 と WebM に対応します。既存の保存先を意図的に置き換えるには 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"}'

デスクトップアプリを使わず画像ファイルを編集する

既存の PNG とその実際の寸法を用意します。Screenshot トランザクションから commands 配列だけを edits.json として保存し、以下の手順で単独ドキュメントを作成、編集、書き出します。この方法で変更するのはファイルドキュメントであり、Beam で開いているエディターではありません。

単独ドキュメントの編集や配信にデスクトップアプリは不要です。書き出しには CLI Chromium バックエンドが必要です。エディターを使わず HTML 動画を作成するには、ジョブファイルを指定して motion を使います。beam-cli docs html ではエントリーポイント、寸法、秒単位の長さ、fps、形式について説明しています。

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

ローカルで実行される内容を確認する

CLI は認証済みのローカルエンドポイントを通じてデスクトップに接続します。Beam はローカルでレンダリングします。公開した HTML は Node アクセスや Beam preload のないサンドボックスウィンドウで実行されます。外部ネットワークリクエストはブロックされるため、リソースはローカルにまとめてください。

エージェントとモデルは利用者が用意します。データの取り扱いは選択したプロバイダーによって異なります。Beam はドキュメント操作ツールとレンダリングインターフェイスを提供しますが、AI チャットのサブスクリプション、MCP stdio サーバー、共有ネットワーク編集機能は含みません。