Communitygithub.com

BuilderIO/agent-native

Clipsにおける画面・カメラ録画の仕組み — MediaRecorderのライフサイクル、チャンクアップロード、権限処理、一時停止/再開、カメラバブルのオーバーレイ、エラー復旧、スクリーンショット(静止画録画)について説明します。レコーダーUI、アップロードエンドポイント、権限プロンプト、またはスクリーンショットを扱う際に参照してください。

agent-native とは?

このスキルは、Clipsアプリケーションにおける録画機能の完全な実装詳細を提供します。画面共有やカメラ入力を使用した録画の開始から、MediaRecorderによるチャンクベースのアップロード、最終化処理、そしてシーク可能な再生を保証するためのメディア再パッケージングまでをカバーします。また、モバイルアプリ(Agent-Native Mobile)のネイティブキャプチャパイプライン、Loomからの録画インポート、ブラウザ診断、Chrome拡張機能との統合、スクリーンショットのキャプチャと編集、一時停止/再開、カメラバブルのオーバーレイ、フォルダ管理などの高度なトピックについても説明します。データモデル(`recordings`テーブル、`application_state`)、アップロードAPIエンドポイント、権限処理、エラー復旧戦略、そしてスクリーンショットとビデオ録画の両方にわたる編集・共有機能も網羅されています。このスキルを使用する開発者は、Clipsの録画システム全体を理解し、新機能の追加や既存機能の修正を安全かつ効率的に行えるようになります。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/BuilderIO/agent-native/tree/HEAD/templates/clips/.agents/skills/recording

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

録画

使用するタイミング

レコーダーに触れるときはいつでもこのスキルを参照してください。録画ボタン、録画中のツールバー、権限プロンプト、チャンクアップロードフロー、カメラバブルなどが対象です。新しいソース(例:タブキャプチャ、iPhone連係カメラ)のサポートを追加する場合や、サーバー側でのチャンク最終化処理を変更する場合も、このマップが役立ちます。

関連するデータモデル

  • recordings — ユーザーが録画ボタンを押すか、ソースをインポートすると同時に行が作成されます。ネイティブ/ファイル録画は uploading → processing → ready(または failed)と遷移します。アップロードがストリーミングされるにつれて、videoUrl、durationMs、videoSizeBytes、width、height、hasAudio、hasCamera が設定されます。Loomインポートは import-loom-recording を使用し、ClipsがホストするMP4またはLoomの埋め込み(MP4エクスポートが利用できない場合)として ready 状態になります。
  • application_state.record-intent — エージェントが録画を開始したいときにこれを書き込みます。UIが読み取ってクリアし、その後権限を要求します。
  • application_state.navigation — レコーダーがアクティブな間は { view: "record" } に設定されます。

バイナリアップロードは、アクションではなくカスタムAPIルート(/api/uploads/:id/chunk および /api/uploads/:id/abort)を使用します。これは、アクションがバイナリストリーミングボディに適していないためです。最後のチャンクは finalize-recording を呼び出します。Loom URLインポートはメタデータのみであり、import-loom-recording アクションを経由する必要があります。

一部の録画はミーティングにリンクされています。録画行の meeting_id が非nullの場合、start-meeting-recording によって作成されたものであり、recording スキルと meetings スキルの両方が適用されます。双方向リンクについては meetings スキルを参照してください。

ライフサイクル

  1. 意図 (Intent)。ユーザーが録画ボタンをクリックする(グローバル Cmd+Shift+L)か、エージェントが pnpm action start-recording --mode=screen を呼び出します。エージェントバージョンは record-intent をアプリケーション状態に書き込みます。UIがそれを読み取り、ユーザークリックと同じフローを開始します。
  2. 権限 (Permission)。画面の場合は navigator.mediaDevices.getDisplayMedia({ video, audio })、カメラの場合は getUserMedia({ video, audio }) を呼び出します。ユーザーのジェスチャーなしにプロンプトを表示してはいけません。エージェントパスはUIのボタンに依存します。ブラウザの権限モデルをバイパスすることは決してありません。
  3. 行の作成 (Create row)。ストリームが許可されるとすぐに、create-recording を呼び出して、status: "uploading" と事前生成されたIDを持つ行を挿入します。このIDは後続のすべてのチャンクアップロードに使用されます。
  4. 録画 (Record)。mimeType: "video/webm;codecs=vp9,opus" を使用して MediaRecorder を開始します(フォールバック:vp8、次にブラウザデフォルト)。timeslice: 2000 を使用して、チャンクが2秒ごとに到着するようにします。
  5. 各チャンクのアップロード (Upload each chunk)。ondataavailable は、ヘッダー X-Recording-Id と X-Chunk-Index を使用して /api/uploads/chunk にバイトをストリーミングし、同時に独立して生のチャンクをベストエフォートのバックアップとして IndexedDB にミラーリングします。一時的な配信失敗はアップロードを一時停止し、現在のブラウザタブが開いている間のみメモリ内ソースを再開します。バックグラウンド再送ワーカーやタブクローズ後の復旧保証はありません。IndexedDB への書き込み失敗はキャプチャやアップロードをブロックしません。
  6. ライブ文字起こし (Live transcription)。MediaRecorderと並行して、useLiveTranscription がWeb Speech APIを実行し、リアルタイムで文字起こしテキストを蓄積します。停止時に、クライアントは save-browser-transcript を呼び出して結果を即座に永続化します。APIキーは不要です。デスクトップ録画は、利用可能な場合はローカルのWhisper/macOS音声認識を最初に使用し、非macのWebViewではWeb Speechにフォールバックし、最終手段としてアップロード後の文字起こしに依存します。
  7. 最終化 (Finalize)。停止時に、最後のチャンクを /api/uploads/:id/chunk?isFinal=1 に送信します。ルートは finalize-recording を呼び出し、チャンクを結合し、メディアをシーク可能にし(下記参照)、ストレージが設定されている場合は完成したメディアをアップロードし、status を ready に遷移させ、その後 request-transcript を開始して高品質な出力を生成します(ai-video-tools 参照)。
  8. 即座にナビゲート (Navigate immediately)。デスクトップレコーダーは、停止が最終化を開始するとすぐに /r/:id を開きます。録画行は既に存在するため、ページは uploading または processing から ready へのポーリング中に、タイトル、共有リンク、アップロード進捗を表示できます。ページを開くためにアップロード/最終化の応答を待ってはいけません。

モバイルコンパニオンアプリのライフサイクル

Agent-Nativeモバイルアプリは、同じ録画行とバイナリアップロードルートを、ネイティブキャプチャプリミティブとともに使用します。

  1. カメラビデオ/インポートは expo-camera / システムのフォトピッカーを使用します。ミーティング音声は、バックグラウンド録音を有効にした expo-audio を使用します。
  2. ネイティブファイルはドキュメントディレクトリにコピーされ、アップロード開始前に型指定されたAsyncStorageキャプチャジョブが書き込まれます。
  3. create-recording は、安定したクライアント生成ID、sourceAppName: "Agent-Native Mobile"、およびコンテナMIMEタイプを受け取ります。
  4. アップロードはExpo FileHandleを使用して最大3 MiBを読み取り、確認応答後のPOSTごとに次のチャンクインデックスを永続化します。サーバー側の4 MiBキャップは引き続き適用されます。
  5. フォアグラウンド/再開時の調整は /api/uploads/:id/status をポーリングします。再試行可能な失敗はバックオフし、ローカルファイルを決して破棄しません。完了時にローカル通知を送信でき、録画はClipsのすべての場所に表示されます。

モバイル音声M4AはMP4コンテナであり、録画ルートのMP4 MIMEエイリアスを使用します。バイトは変換されたり、JavaScriptメモリに全体が読み込まれたりすることはありません。

電話機はネットワーク処理の前に各音声/ビデオファイルを永続化し、耐久性のあるキューからバインドされたチャンクアップロードを再開するため、一時的なアップロード失敗によってキャプチャが失われることはありません。ユーザーにキャプチャ画面を開いたままにするように頼んだり、アップロード失敗後に再録画を依頼したりしないでください。代わりに、Clipsに再接続し、モバイルホームから保存されたジョブを再試行するように指示してください。

モバイルミーティングキャプチャはマイクのみです。デスクトップのマイク+システム音声の忠実度があると主張してはいけません。参加者の属性への影響については meetings スキルを参照してください。

シーク可能な再生(生のMediaRecorder出力を出荷しないでください)

生の MediaRecorder ファイルはプログレッシブHTTP再生に適していません。これにより、「クリップの読み込みに数分かかる」、「シークするたびに再バッファリングが発生する」といった問題が発生します。ファイルのダウンロードは正常でも同様です。

  • MP4 は moov メタデータアトムが mdat の_後_に書き込まれるため、プレーヤーは開始またはシークする前にファイル全体をフェッチする必要があります。
  • WebM はCues(シークインデックス)がなく、Segmentの長さが不明なライブストリームであるため、Chromeは currentTime = X を尊重せず、スキャン/ダウンロードする必要があります。

finalize-recording はアップロード前にこれを修正します。MP4はpure-TS faststart(server/lib/faststart.ts)、WebMはSeekHead + Cues + 実際の長さを書き込むロスレス ffmpeg -c copy リマックス(server/lib/video-remux.ts)を受けます。どちらもベストエフォートです。失敗した場合はオリジナルをアップロードし、最終化をブロックしません。CLIPS_INLINE_REMUX_MAX_BYTES(デフォルト200 MB)を超える録画はインラインパスをスキップし、バックグラウンドで修復されます。

ストリーミング/再開可能 アップロードパスは生のバイトをプロバイダーに直接転送し、インラインで書き換えることができないため、finalize-recording はそれらのためにバックグラウンドの ensureRecordingSeekable パスをスケジュールします。

これが存在する前(またはストリーミング経由)にアップロードされたクリップを修復するには、reprocess-recording アクションを呼び出します。--id、--ids='[...]'、または --all --limit=N を指定します。プロバイダーのメディアを再フェッチし、書き換え、再アップロードし、行を更新します。これは冪等です(既にシーク可能なクリップは --force がない限りスキップされます)。呼び出し元が所有するプロバイダーホストのクリップのみに影響します。これは、ユーザーが特定の遅い/バッファリングするクリップを報告した場合に適切なツールです。

シーク可能性のリマックスは、ビデオトラックに大きなタイムスタンプギャップがある場合(モバイルブラウザがユーザーのアプリ切り替え後にカメラをサスペンドする場合によく発生します)、音声が続いている録画を修復できません。宣言された長さの前にフリーズしたり停止したりするように見えるクリップについては、--normalizeTimeline=true を指定して reprocess-recording を呼び出してください。この明示的なモードは、同じ所有者スコープのフェッチとアップロードフローを使用しますが、完全にトランスコードして、一定の30fps faststart MP4(H.264 + AAC)にします。オーディオを保持し、欠落フレームのギャップに最後のデコード済みビデオフレームを複製します。このアクションは新しいメディアオブジェクトにアップロードし、確認済みの出力が保存された後にのみ、アトミックに行を再ポイントします。トランスコード、オーディオ検証、アップロード、または同時更新の失敗は、元のURLとフォーマットをそのまま残します。

Loomインポート

Loom共有URLまたは埋め込みURLには import-loom-recording を使用します。このアクションはLoom URLを検証し、LoomのパブリックエンドポイントからLoom oEmbedメタデータを読み取り、Loomの埋め込みURL、サムネイル、タイトル、長さ、寸法を持つ ready 録画を作成します。Loomが共有ページで署名付きパブリック文字起こしJSON URLを公開している場合、アクションはその文字起こしをClipsにインポートし、正規化されたセグメントを保存します。Loomの署名付きCDN URLを保存してはいけません。

Loomがダウンロード可能なパブリックMP4を公開している場合、import-loom-recording はそれをダウンロードし、バイトをClipsストレージに再アップロードし、再生可能なClipsホスト録画を作成し、共有ページが公開している場合はLoomのパブリック文字起こしをインポートします。Loomがパブリック再生を許可しているがMP4を公開していない場合、アクションは埋め込みベースの ready 録画を保持し、利用可能な場合は文字起こしをインポートします。

埋め込みベースのLoomインポートはLoom iframeをレンダリングし、ネイティブのClipsエディターを非表示にします。再アップロードされたLoomインポートは、Clipsネイティブのトリミング、エクスポート、フレーム抽出、アップロードベースの文字起こしをサポートします。埋め込みベースのインポートでこれらの機能が必要な場合は、ユーザーに元のビデオファイルをアップロードするように依頼してください。

ブラウザ診断とレコーダーインストールオプション

ブラウザ録画は、createBrowserDiagnosticsCapture を通じて、制限付きで編集された診断情報を保存できます。コンソールメッセージと、fetch/XHRのメソッド、URL、ステータス、期間、エラーなどです。ブラウザレコーダーは、レコーダーページ自体からのアクティビティのみをキャプチャします。Clips Chrome拡張機能は、ブラウザログのアクティブタブパスです。拡張機能のキャプチャセッションで /record を起動し、developerLogs=1/0 を渡し、ソース extension で診断情報を保存します。

Web Storeのリストは公開されているため、パブリックChrome拡張機能オプションがデフォルトで表示されます。それ以外の場合は「デスクトップアプリをダウンロード」と表示するUIプロンプトは、共有のインストール選択コンポーネント(CaptureInstallButton / CaptureInstallInlineLink)を使用して、Chrome拡張機能(ブラウザログ用)とデスクトップアプリ(最もシームレスなネイティブキャプチャ用)の2つのオプションを提供します。VITE_CLIPS_CHROME_EXTENSION_ENABLED=0 を設定すると、Chromeオプションを再度非表示にできます。VITE_CLIPS_CHROME_EXTENSION_URL を設定すると、別のリストを指すことができます。

save-browser-diagnostics はUI/内部用です。制限付きのコンソールログと、fetch/XHRのメソッド、URLパス/クエリキー、ステータス、期間を保存します。ヘッダー、ボディ、Cookie、ネットワークURLクエリ値は決してキャプチャしません。コンソールテキストは、認証情報のように見えるキーとヘッダーを編集しながら、有用な非秘密の値を保持します。エディターアクセスがある場合は、完全な診断ペイロードに get-recording-player-data を使用してください。パブリックエージェントコンテキストが公開する、より狭い編集済みストリームについては video-sharing スキルを参照してください。

Chrome拡張機能

拡張機能は chrome-extension/ にあります。clipsExtensionId と clipsCaptureSessionId を指定して /record を起動し、レコーダーは CLIPS_CAPTURE_START / CLIPS_CAPTURE_STOP / CLIPS_CAPTURE_CANCEL を拡張機能に送り返します。ユーザーが起動したタブでのみ、録画がアクティブな間のみChromeデバッガーAPIを使用し、save-browser-diagnostics によって保存されるのと同じ編集済み診断形状を返します。

拡張機能はGitHubのIssueやPRのマークダウンも強化します。狭い github.com コンテンツスクリプトがClipsの /r/、/share/、/embed/ リンクを検出し、拡張機能所有のプレビューiframe内に既存の /embed/:id プレーヤーをレンダリングして、GitHubから離れることなくビデオを再生できるようにします。これは、意図的な権限レビューがない限り、GitHubにスコープを限定してください。

フォルダ、スペース、一括移動

単一および一括フォルダ移動の両方に move-recording を使用します。1つのクリップには id、選択したクリップには ids を渡し、ライブラリまたはスペースルートに移動するには folderId: null を渡します。

スクリーンショット

スクリーンショットは kind = "image" の recordings 行です(shared/recording-kind.ts の isImageRecording)。クリップとフォルダ、スペース、共有、コメント、検索を共有しますが、ビデオ部分(文字起こし、チャプター、フィルムストリップ、タイムライン、オーディオ)はありません。list-recordings --kind=image でリストできます。

  • キャプチャ、注釈、編集はブラウザ側の作業です(create-screenshot、save-screenshot-edits、どちらもUIのみ)。エージェントは get-recording-player-data または /api/agent-frame.jpg を通じてスクリーンショットを読み取ります。これらは任意の atMs に対して画像自体を返します。
  • imageUrl は配信される画像です。baseImageUrl はエディターが描画するマークのないベース画像です。どちらも /api/thumbnail/:id を通じて配信され、パスワード、有効期限、編集保留が適用されます。ストレージURLを決して配布してはいけません。
  • 編集はビデオと同様に2段階です。ボックスは保留中のオーバーレイとして保存され(閲覧者からは保留)、その後焼き付けられます。焼き付けは、元の画像を削除する前に editsJson.burnInProgress を書き込み、その後クリアします。unreclaimedUrls はまだ削除されていない古いコピーをリストします。どちらもサーバー側のみ(server/lib/screenshot-edits.ts)であり、閲覧者に決して到達してはいけません。
  • ビデオ編集アクションは assertNativeRecordingMedia でスクリーンショットを拒否します。save-screenshot-edits のみがスクリーンショットの editsJson を書き込みます。

一時停止 / 再開

MediaRecorder.pause() / .resume() はすべてのモダンブラウザでサポートされています。一時停止中は単一の MediaRecorder インスタンスを維持してください。ストリームを破棄しないでください。そうしないと、権限プロンプトが再度表示されます。一時停止中、アップロードワーカーはバッファを排出し続け、ユーザーが停止する前に追いつくようにします。

カメラバブル

モードが screen+camera の場合、「バブル」は2つの異なるものを指します。

  • オンスクリーンのセルフビュー。 CameraBubble は、ユーザーがカウントダウン/録画中に自分自身をフレーミングするためにドラッグできる、記録されていないプレーンな <video> 要素をレンダリングします。これは決してキャプチャされません。単なるローカルフレーミングUIです。
  • 録画された合成。 ユーザーが別のウィンドウ/アプリを録画すると、ディスプレイキャプチャはそのDOM要素を含めることができないため、保存されたビデオは MediaRecorder に送られる前にカメラサークルを焼き付ける必要があります。...

関連スキル