openscreen-demo

OpenScreen でデモ動画を作成する

1つの機能を紹介し、操作を拡大して見せ、画面上のコールアウトでメッセージを伝える短い MP4 を作成します。作業はすべて OpenScreen の MCP ツールで行います。録画、編集、エクスポート、確認まで対応します。完成形は次のいずれかです。

• プルリクエスト動画： 10～30 秒で、プルリクエストによる変更を紹介します。レビュアーがその場で視聴できるよう、プルリクエストに添付します（ステップ 8）。
• ローンチデモ： 20～60 秒、1080p で、X への投稿文を下書きします（ステップ 9）。ユーザーが明示的に許可しない限り、投稿することはありません。

1. OpenScreen をセットアップする

startRecording、stopRecording、exportVideo、getFrames ツールが必要です。OpenScreen のどちらの MCP サーバーにもこれらのツールがあります。アプリが提供するもの（AI settings → MCP server）と、以下でセットアップする openscreen mcp です。これらのツールが使える場合は、ステップ 2 に進んでください。そうでない場合は、各マシンにつき一度だけ、足りないものだけをセットアップします。

アプリ。 実行ファイルが MCP サーバーです。

OS	実行ファイル
Windows	%LOCALAPPDATA%\Programs\Openscreen\Openscreen.exe、または C:\Program Files\Openscreen\Openscreen.exe。Microsoft Store 版では、リリースに実行エイリアスが含まれた後は PATH 上の openscreen（where openscreen）を使います。それまでは、PowerShell で (Get-AppxPackage EtienneLescot.OpenScreen).InstallLocation の下にある app\Openscreen.exe を使います。このパスにはバージョンが含まれるため、Store の更新後に再登録してください。powershell -Command ランチャーでラップしないでください。PowerShell は最初のメッセージの後、サーバーへの入力を飲み込んでしまいます
macOS	/Applications/Openscreen.app/Contents/MacOS/Openscreen
Linux	PATH 上の openscreen、または AppImage

OpenScreen がないと判断する前に、表にあるすべての場所を確認してください。Store 版は最も見落とされやすいものです。"<executable>" help を実行し、mcp が一覧に表示されることを確認してください。アプリが見つからない場合、または古すぎて一覧に表示されない場合は、最新リリースのインストールを提案し、ユーザーの同意を得てから実行してください。

1. getopenscreen/openscreen の最新リリースから、このマシン用のインストーラーを探します。gh release view --repo getopenscreen/openscreen --json assets または https://github.com/getopenscreen/openscreen/releases/latest を使います。
   • macOS： Openscreen-macOS-Apple-Silicon-<version>.dmg、または -Intel-（uname -m で確認します）。マウントして Openscreen.app を /Applications にコピーし、アンマウントします。
   • Windows： Openscreen.Setup.<version>.exe インストーラーを、現在のユーザー向けのサイレントインストールとして /S /currentuser を付けて実行します。
   • Linux： ディストリビューション用の .deb、.rpm、.pacman、または実行可能にした .AppImage を使います。
2. help をもう一度確認します。最新リリースでも mcp が一覧に表示されない場合、この OpenScreen の機能はまだリリースされていません。その旨を伝えて終了します。

MCP サーバー。 エージェントに追加すると、次のセッションでツールが読み込まれます。

• Claude Code： claude mcp add openscreen -- "<executable>" mcp
• Codex： codex mcp add openscreen -- "<executable>" mcp
• Cursor など： 実行ファイルを command、["mcp"] を args に指定した stdio サーバーを設定します。

権限。

• macOS： エージェントを実行するアプリには、システム設定 → プライバシーとセキュリティで、録画に必要な画面収録の許可と、OpenScreen がポインターのクリックや形状を記録するためのアクセシビリティの許可が必要です。アクセシビリティの許可がない場合、実際のマウスで操作したテイクではクリック箇所がズームされません。許可を付与するか、スクリプトによるテイクの場合と同様に setPointerTrack を使ってクリックを引き継いでください。
• Linux： 録画のたびにデスクトップのピッカーが開き、ユーザーがウィンドウを選択します。

次のセッションへの引き継ぎ。 ユーザーの依頼内容と、すでに決まっていることを作業ディレクトリの openscreen-demo-plan.md に書き込みます。その後、ユーザーに新しいセッションを開始して continue the OpenScreen demo と伝えるよう依頼します。そのセッションでファイルを読み、ステップ 2 から続けてください。

プラグインまたはサーバーを追加した直後は、ツールが使えません。エージェントはセッション開始時に MCP サーバーを読み込みます。わかりやすくその旨を伝え、上記の手順で引き継いでください。ストーリーボードを作成済みの場合は、ファイルに含めます。不足しているツールの代わりに、コンピューター操作やマウスツールで OpenScreen のウィンドウを操作してはいけません。ユーザーが作業中でも、その操作によってユーザーのマウスと画面が奪われてしまいます。

2. 録画前に計画する

ストーリーボードを書き、数行でユーザーに見せてから、異議がなければ続行します。

• 伝えることは1つ。 3秒後に視聴者に覚えていてほしいことは何ですか？ 最初の場面では、設定画面ではなく結果を見せます。
• ローンチデモ：3〜6場面、20〜60秒。 各場面は1つのアクションと、6語以内のコールアウトで構成します。Xではミュートで自動再生されるため、ストーリーを伝えるのは音声ではなくコールアウトです。
• プルリクエスト動画：1〜3場面、10〜30秒。 製品全体ではなく、変更によって何ができるようになるかを見せます。新しい動作、または発生しなくなったバグを見せましょう。残りはプルリクエストの本文で説明するため、各場面に短いコールアウトを1つ付ければ十分です。
• 現実的なデータ。 アプリには、実際にありそうなコンテンツを用意します。画面には、実際の顧客データ、シークレット、トークン、個人宛ての通知を表示しないでください。

3. 録画の準備をする

• アプリを起動し、最初の場面の開始状態を表示します。
• 約1600×1000の、すっきりしたウィンドウを1つ用意します。Webアプリの場合は、ブラウザーの表示領域を除いたアプリウィンドウで開きます：chrome --app=http://localhost:3000 --window-size=1600,1000 --user-data-dir=<temp folder>。タイトルにはページの<title>が使われます。
• listSourcesを呼び出し、ウィンドウのタイトルから他と重複しない部分を選びます。
• 画面にはアプリだけを表示します。 録画するウィンドウには、ブラウザーのツールバー、アドレスバー、ローカルファイルのパス、ユーザー名、ブックマークバー、翻訳プロンプト、通知を表示しないでください。ウィンドウを1つだけ録画すれば、デスクトップのほかの部分は映りません。

4. 録画する

1. windowを指定してstartRecordingを実行します。キャプチャが始まると、呼び出しは戻ります。アプリ内でサーバーに接続していれば、録画はOpenScreenの録画バーを通じて進みます。エディターが閉じ、バーでカウントダウンが始まり、stopRecordingを実行すると録画がエディターで開きます。ユーザーを画面に表示する場合に限りcameraを指定します。その場合、Webカメラ映像がピクチャーインピクチャーで表示されます。ユーザーがナレーションする場合はmicrophone: trueを指定します。指定しないと録画に音声は入りません。そのため、キャプションを付ける音声もありません。
2. ストーリーボードどおりに再生します。意図的に操作し、各結果が表示されたあとに約1秒間止めます。
3. titleを指定してstopRecordingを実行します。戻り値のprojectId、checkpointId、videoPath、recordingStartedAtを保持します。

アプリの操作方法によってカーソルが決まります。

• 実際のマウス（コンピューター操作ツールなど、実際のポインターを動かすツール）：OpenScreenはポインターを記録し、見やすいカーソルを描画して、クリック位置を自動的にズームします（下記の「操作箇所をズームする」を参照）。マウスツールでアプリのウィンドウをクリックできない場合（ブラウザーの読み取りしかできないツールなど）は、代わりにスクリプトで操作します。
• スクリプト（Playwright、CDP）：画面上のポインターは動かないため、録画にカーソルもズームも入りません。スクリプトでは、実行中に各アクションを記録します。atにはDate.now()、xとyにはウィンドウ内の位置を割合で指定し、クリックの場合はclickをtrueにします。stopRecordingのあとでログをsetPointerTrackに渡します。説明には、ページ上の座標から変換する式が記載されています。スクリプトを使うと、毎回同じタイミングで実行でき、ためらいもないため、最もきれいに録画できます。

すでにある動画は録画する必要はありません。絶対パスのvideoPathを指定してcreateProjectを実行すると、動画がプロジェクトとして配置され、stopRecordingと同様にprojectIdとcheckpointIdが返されます。手順5では、videoPathも含めて録画素材として確認し、その後、手順6に進みます。

5. 録画素材を確認する

videoPathを指定してgetFramesを実行し、約6フレームを確認します。正しいウィンドウが映っていますか？ 個人情報が表示されていませんか？ すべての場面が実行されていますか？ そうでなければ、もう一度録画します。編集で修正するよりも、新しい素材を録画するほうが時間がかかりません。

6. 編集する

ドキュメントツールは、必ずprojectIdを指定して使います。まずgetCurrentDocumentでプロジェクトを読み込みます。メモには、録画の秒数を使う箇所と、エディターのルーラーを使う箇所が記載されています。

時間軸は1つです。 すべてのエフェクトをルーラー上の秒数で配置し、projectIdを指定してgetFramesで結果を確認します。こちらも同じ秒数を使います。書き出したファイルから時刻を読み取らないでください。カットや速度変更を行うと、時間軸がルーラーからずれてしまいます。

• まずフォーマットを設定します： 動画の表示先に合わせて setAspectRatio を指定します。X の場合は 16:9 です。テキストを配置する前に設定してください。
• 不要な時間をカットします： 冒頭のセットアップ、最後の停止部分、待ち時間をカットします。addTrims を使うか、待ち時間をカットする代わりに addSpeed で早送りにします。
• 操作にズームします： 画面共有で時間的にも画面上でも近いクリックは、1つのズームにまとめます。最初の 2.5 s は広い画角のままにします。確認してから、ズームを追加または移動するには addZooms と setZoom を使い、結果を個別に見せたい箇所にズームを設定します。ズームは少なくとも 1.5 s 保持します。一部を削除するカットの後は、addAutoZooms で残ったクリックを対象に、既存のズームと重ならないようにズームを再計画します。
• アプリをフレームに収めます： テイクにアプリ以外も映っている場合は、cropRegion を指定した setClipRange でクリップを切り抜きます。
• コールアウト： 1つの場面につき addAnnotation を1つ使い、短い文を操作の邪魔にならない位置に配置します。テキストは出力フレーム上に表示され、映像がズームしても位置は変わりません。見た目で階層を表現します。大きなタイトルには animation: "typewriter" を、手順のコールアウトには animation: "pop" を使います。矢印の type: "figure" は、テキストで示したコントロールを指します。setAnnotation で移動またはスタイルを変更できます。
• プライベートな情報を隠します： 画面に表示されるメールアドレス、トークン、名前には、表示されている範囲に重ねて type: "blur" を指定した addAnnotation を使います。x、y、width、height はフレームではなく録画映像に対するパーセント指定なので、ズームで映像が動いても隠す対象に追従します。getFrames で確認してください。
• 設定では用意されていないエフェクト（クリックごとの波紋、カット時のグリッチ、カラーグレーディングなど）：リソース openscreen://effects/contract を読み、WGSL で記述して addEffect を使います。エフェクトは、すでにフレーム上に配置されたクリックとポインターを読み取ります。コードがコンパイルできない場合は、該当行のコンパイラーエラーが返されます。修正して再度呼び出してください。結果にはコスト階層が表示されます。負荷の高いエフェクトは短い範囲にとどめてください。エフェクトが動作するタイミングで getFrames を使って確認します。
• 音楽やナレーション： ファイルの絶対パスを指定して importMedia を呼び出すと、ファイルがプロジェクトのメディアに追加されます。その後、addAudio で指定した範囲に再生します。タイムラインで使わなくなったファイルは removeMedia で削除します。
• 名前： stopRecording に指定した title が適切でなくなった場合は、setProjectInfo でプロジェクト名を変更します。
• ナレーション付きテイクの字幕（microphone: true を指定した startRecording）：
  1. projectId を指定して transcribe を呼び出します。Whisper はこのマシン上で実行され、1分ほどかかる場合があります。それまではテイクに文字起こしはありません。
  2. enabled: true と style を指定して setCaptionSettings を呼び出します。コールアウト用のスペースが必要な場合は、anchorV、insetY、または maxWordsPerLine も指定します。
  3. 別の言語で字幕を付けるには、language を指定して getCaptionTranslationUnits を呼び出し、各ユニット全体をフレーズとして翻訳して putCaptionTranslation で保存し、その language を指定して setCaptionSettings を呼び出します。
  4. getCaptions ですべてを確認できます。エクスポート時に字幕が映像に焼き込まれます。 名前の聞き間違いは setWordText で修正します（または setVocabulary を使い、language を指定して再度 transcribe を実行します）。言い間違えたフレーズは getTranscriptWords と removeWords でカットします。
• 取り消し： checkpointId を指定して restoreCheckpoint を呼び出すと、プロジェクトを1ステップで未編集のテイクに戻せます。また、テイク本来のポインタートラックも復元され、それ以降に行った setPointerTrack も取り消されます。
• アプリで開く： OpenScreen の実行中は、編集内容は OpenScreen を通じて反映されます。そのため、ユーザーがエディターで開いているプロジェクトはリアルタイムで変更され、編集を1つずつ取り消すこともできます。編集が「OpenScreen エディターで開いています」と拒否された場合、アプリから応答がありませんでした。1度再試行してから、そのプロジェクトを閉じるか OpenScreen を再起動するようユーザーに依頼してください。

その他の設定はそのままにします。背景、余白、影、カーソルのスタイルは見栄えがよくなるよう選ばれています。ユーザーが別の見た目を求めた場合は、setEditorSettings で設定します（背景、フレーム、カメラレイアウト、カーソル、音量）。getCurrentDocument では settings の下に現在の値が表示され、settingsContext.inactive では、現時点で変更しても何も変わらない設定が示されます。

7. エクスポートとレビュー

1. exportVideo に projectId と絶対パスを指定します。たとえば demo/demo.mp4 は、まず作業ディレクトリを基準に解決してください。アプリ内のサーバーは相対パスを受け付けないためです。プルリクエスト用の動画では、ファイルサイズを小さくするために quality: "medium"（720p）を指定します。GIF（README用など）の場合は、パスの末尾を .gif にして、gifSize: "small"（480p）を指定します。
2. projectId と、ビートのルーラー上の秒数を指定して getFrames を呼び出します。編集中にエクスポート前の確認として呼び出すこともできます。最新のエクスポートがなくても、エクスポート時に表示されるフレームをレンダリングします。
3. すべてのフレームを確認します。
   • 各コールアウトは読みやすく、動作を遮っていませんか？
   • 各ズームは、変化する対象に合っていますか？
   • 黒いフレーム、途中で切れたテキスト、不要になったセットアップ画面はありませんか？
4. プロジェクトを修正し、納得できるまで再度エクスポートします。

動画をリポジトリにコミットしてはいけません。プルリクエストや投稿に添付し、コードには含めないでください。

8. プルリクエストに添付する

このタスクでユーザーが動画を依頼したプルリクエスト、またはユーザーに代わって作成するプルリクエストにのみ添付します。

1. ファイルサイズを確認します。 GitHubでは、無料プランのリポジトリで最大10 MB、有料プランでは最大100 MBの動画を受け付けます。上限を超える場合は、ビートを短くするか速度を上げて、もう一度エクスポートします。

2. 動画の前後に添えるテキストを作成します。 たとえば demo/pr-video.md に、動画の内容を説明する1行を書き、その後に動画だけを独立した段落として記載します。GitHubにリンクではなくプレーヤーを表示させるためです。

   **Demo:** the export dialog now remembers the last format.
   
   ![](demo/pr-video.mp4)
   

3. gh を使って添付します。 バージョンは2.99.0以降である必要があります（gh --version）。gh がファイルをアップロードし、そのURLをパスの代わりに挿入します。リポジトリへのプッシュ権限が必要です。

   • 既存のプルリクエストの場合は、コメントとして投稿します。gh pr comment <number> --body-file demo/pr-video.md --attach demo/pr-video.mp4
   • 作成するプルリクエストの場合は、同じ2行を本文に記載し、gh pr create に --attach demo/pr-video.mp4 を渡します。

4. **古いバージョンの gh を使っている場合は、**ユーザーに更新を依頼します。GitHub Enterprise Serverでは、gh でファイルを添付できないため、--attach を省略します。どちらの場合も、プルリクエストのページでコメント欄にファイルを添付できるブラウザツールを使います。それができない場合は、ファイルと、ユーザーが自分で貼り付けるテキストを渡します。

5. コメントまたはプルリクエストのURLを報告します。

9. X に投稿する

1. 投稿文を作成します。 最大280文字です。まず注目を引く内容を書き、次に機能を説明し、リンクがあれば最後に記載します。ハッシュタグは1つか2つまでにします。
2. X の制限を確認します。 Premium ではないアカウントの場合、動画はMP4形式で、長さは最大2分20秒、サイズは最大512 MBである必要があります。エクスポートした動画はこの条件を満たします。
3. ユーザーに確認します。 投稿文、動画のパス、フレームを1つ提示し、明示的な承認を求めます。前の手順で「よさそうです」と言われていても、承認とはみなしません。
4. 承認後にのみ投稿します。 https://x.com/compose/post で投稿画面にファイルを添付できるブラウザツールを使うか、ユーザーが設定している場合は X API を使います。ファイルを添付できない場合は、投稿文とファイルをユーザーに渡します。
5. 投稿のURLを報告します。

問題が起きた場合

• The recording did not start： ウィンドウタイトルが一致しなかったか、キャプチャが許可されていません。listSources と手順1の権限設定を確認します。
• 録画、エクスポート、編集が拒否され、MCP edits と表示される： 録画、エクスポート、編集がユーザーの許可後にのみ行われる、アプリ内のサーバーに接続しています。AI settings → MCP server で MCP edits を有効にするようユーザーに依頼します。
• 動画にカーソルが表示されない： アプリはスクリプトで操作されています。手順4を参照してください。
• transcribe が no-audio で失敗する： microphone も systemAudio も使わずに録画されています。どちらかを使って録画し直します。
• 最初のクリックにズームがない： 最初の2.5秒間は意図的に広い範囲を表示します。その後に最初の操作を開始してください。
• unknown flag: --attach： gh が2.99.0より古いです。手順8を参照してください。