screencast-desktop

Claude Code プラグイン。エージェントが Windows アプリケーションを操作し、そのセッションを完成したデモ動画に変換します。カメラはクリックの 0.5 秒前 からクリック位置に向かってズームインし始めます。

• 視覚をループに組み込んだデスクトップ操作。 すべてのアクションは同じ応答内で新しいスクリーンショットを返すため、エージェントは「見る → 操作する → 見る」のサイクルで作業し、盲目的にスクリプトを書くことはありません。コントロールは Windows UI Automation を通じて名前で検索されます。コントロールツリーを公開しない Electron アプリは、スクリーンショットと座標（またはデバッグポートが開いている場合は CDP 経由で DOM）にフォールバックします。

• 画面ではなくウィンドウを録画。 キャプチャは Windows Graphics Capture を使用し、ウィンドウハンドルにバインドされるため、アプリの背後にあるデスクトップはフレームに入りません。また、ウィンドウがどのモニターや GPU にあるかは関係ありません。

• 動画は映像ではなくイベントログから構築。 すべてのクリック、入力された文字列、カーソルの完全なパスは、発生時にタイムスタンプが付けられます。カメラの動きはそのログから計算されます。

• Screen Studio 級の仕上がりを生成: イージング付きのカメラプッシュとパン、柔らかい影付きの描画カーソル、クリックリップル、モーションブラー、グラデーション背景に角丸、ビネットとグレイン、さらにエージェントの思考時間を除去する無音部分の削除。

• ビートに合わせたナレーション。 オプションの ElevenLabs 音声を 実行前 に生成し、クリックがそれを説明する文の中に収まるようにします。

• スクリプト1つで実現する、より充実したモンタージュ層。 タイトルとアウトロカード、キャプション、完全なサウンドデザインパス（クリックトラック、カメラのスウッシュ、着地インパクト、クロージングライザー、ダッキングされた音楽ベッド、ラウドネス正規化）は cinematic.py、sfx.py、sfx_bank.py にあります。これらは desktop_render ツールではなく server/make_showcase.py によって駆動されます。既知の制限 を参照してください。

• 無料で再レンダリング。 レンダリングはアプリケーションに一切触れません。ズーム上限、ナレーション、エフェクトを変更して、同じテイクを何度でも再構築できます。

なぜ違うのか

「自動ズーム」を行うすべての画面レコーダー（Screen Studio とその Windows クローン）は同じ方法で動作します。まず録画し、その後マウスフックや映像自体を遡って、興味深い瞬間がどこにあったかを推測します。この順序には誰も回避できない厳しい結果があります。クリックの瞬間にレコーダーはクリックが来ることを知ったばかりなので、ズームはクリック前に開始できません。 できる最善はクリック時に動き始め、少し遅れて到着することです。人間の編集者は逆のことをします。視聴者を先導し、ボタンが押される時には目がすでにそこにあるようにします。

ここではエージェントがアクションを 生成 するため、座標とタイミングは単一のフレームが合成される前にわかっています。カメラにはリードイン（server/camera.py の LEAD_IN = 0.55 s）を与えることができるため、ボタンが押される頃にはショットはすでに到着し、落ち着いています。同じ事前知識は、事後ツールにはない3つの追加の利点をもたらします。

• ポンピングなし。 同じ領域での連続クリックは、リスト項目ごとにカメラがズームイン・アウトする代わりに、1つの安定したショットに統合されます。

• フィットするナレーション。 音声は実行 前 に生成され（voice.plan()）、実際の長さは ffprobe で測定され、エージェントのポーズはそれらの数値から設定されます。そのため、クリックはそれを説明する文の中に収まり、手動での調整は不要です。最初に録画して後からナレーションを付けると、常に「Save をクリックします」という声が Save がクリックされた1秒後に流れることになります。

• 何が起こったかの機械可読な記録。 desktop_describe_take はテイクを番号付きの手順（「3. [12.4s] Multiply by をクリック」）として読み戻します。これはスクリーンショットの山よりも優れた成果物であり、再利用可能なスキルを書くのに十分です。

類似ツールとの位置づけ

このアイデアは目新しいものではありません。Windows で実現するのが難しいだけです。ブラウザ側の4つのプロジェクト（argo、testreel、pagecast、playwright-recast）が「アクションログからの編集」を実装して 2026年3月の2週間以内 に登場しました。Playwright がログを無料で提供するからです。Windows では、ログは入力ドライバと一緒に構築する必要があり、同じ5か月間で何も登場しませんでした。レコーダーにはエージェントがなく、エージェントはフレームを生成しません。

Related MCP server: windows-gui-mcp

要件

Python パッケージ

server/ 内のすべてのモジュールのインポートから取得:

pip install mcp pillow opencv-python numpy windows-capture uiautomation

プライバシースキャンにはパッケージは不要です。Windows に同梱されている OCR を使用して画面を読み取り、PowerShell 経由で駆動します。

インストール

1. プラグインを取得

git clone https://github.com/JHamidun/screencast-desktop.git

2. Claude Code に登録

リポジトリは独自のマーケットプレイス（.claude-plugin/marketplace.json）であるため、Claude Code をクローンにポイントして、そこからインストールします:

/plugin marketplace add <path-to-clone>
/plugin install screencast-desktop

.mcp.json は両方のサーバーを ${CLAUDE_PLUGIN_ROOT} 相対パスで登録するため、グローバルインストールは不要で、クローンはどこにでも置けます。

3. セットアップを実行

/screencast-desktop:setup

これにより server/doctor.py が実行され、静かに 壊れるものをチェックします:

• DPI 認識 — DPI 認識を宣言していないプロセスは、実際には 3840×2160 であるのに画面が 2560×1440 であると通知され、すべてのクリックがスケーリング係数だけずれます。

• モニターレイアウト — 座標はすべての画面で共有され、セカンダリモニターでは負の値になります。

• ffmpeg と利用可能なエンコーダー。

• ウィンドウキャプチャ（実際に） — 約25フレームをキャプチャし、すべてが同一でないことを確認します。

• ナレーション — キーが存在するか、設定された音声 ID がアカウントにまだ存在するか（削除された音声は、そうでなければ素の 404 で失敗します）。

見つかった内容を machine.json に書き込みます。

4. UI Automation バイナリを取得

windows-ui サーバーは外部バイナリです — sbroenne/mcp-windows（MIT）。これは意図的にこのリポジトリに ベンダリングされていません。約60 MB あり、他人のプロジェクトであり、ここにコピーを固定すると古いものを配布することになります。オンデマンドでダウンロードします:

python server/fetch_ui_binary.py          # --force to re-download

スクリプトは最新の GitHub リリースを解決し、アーカイブを公開された SHA256SUMS.txt と照合し、不一致の場合は何もインストールしません。bin/ に配置されます。これは .mcp.json が期待する場所です。

5. 両方のサーバーが起動していることを確認

claude mcp list      # expect: screencast, windows-ui

クイックスタート

Windows 電卓のデモを録画します。/screencast-desktop:record コマンドはエージェントをこの手順に導きますが、実際のツール名を使用して、実際に何を行うかを次に示します。

1 — ウィンドウをステージング。 可能であればセカンダリモニターに配置し、作業の上に重ならないようにします:

desktop_monitors()
desktop_place_window(window="Calculator", monitor=1, fit=0.7)

応答を読んでください。アプリケーションは指示されたサイズになる義務はありません。ここで 2380×1490 を要求した UWP ウィンドウは 3967×2426 で返され、画面からはみ出しました。desktop_place_window は結果を測定し、修正し、ウィンドウが収まるかどうかを明確に示します。

2 — フレームにプライベートなものがないか確認。

desktop_screenshot(window="Calculator")
desktop_privacy_check(window="Calculator")

チェックは報告するだけで、ブロックしません。フレームを OCR し、カード番号、API キー、メールアドレス、電話番号、個人名をフラグします。録画前に「おやすみモード」をオンにしてください。

3 — リハーサル。 実際のツールでルートを歩き、返されたスクリーンショットから、意図したものをクリックしていることを確認します。まだ何も録画されていません:

ui_snapshot(windowHandle=…)          # windows-ui: controls by name — try this first
desktop_snapshot(window="Calculator")# or the built-in UIA walk, which returns e1, e2, … refs
desktop_click(ref="e7")

4 — アプリをリセット。 リハーサルで開いたままの検索ボックスがテイクに入ってしまいます。

5 — 本番を録画。

desktop_record_start(window="Calculator")
desktop_click(ref="e12")                 # every click from here is logged for the camera
desktop_type("128")
desktop_click(ref="e19")
desktop_record_stop()

desktop_record_stop は、期間、フレーム数、ログに入ったクリック数を報告し、レンダリングする out_dir を指示します。

6 — レンダリングして、確認。

desktop_render(out_dir="%USERPROFILE%/screencasts/take-143502", max_zoom=2.0)
desktop_render_status(out_dir="…")       # rendering runs in a child process

ファイルを開いて目で確認する。カメラが本来あるべき場所に来ているか、どの端にも黒いバーがないか、カーソルが見えているか。座標が間違っていると、カメラが何も見ていない技術的には有効なファイルが生成される。ずれている場合は、desktop_render を別の設定で再実行する。アプリケーションは再起動されず、画面も再録画されない。

ツールリファレンス

screencast サーバー — desktop_monitors, desktop_windows, desktop_screenshot, desktop_snapshot, desktop_dom, desktop_dom_launch, desktop_click, desktop_type, desktop_key, desktop_move_mouse, desktop_scroll, desktop_focus, desktop_launch, desktop_place_window, desktop_privacy_check, desktop_record_start, desktop_record_stop, desktop_render, desktop_render_status, desktop_describe_take。

desktop_click, desktop_type, desktop_key, desktop_scroll, desktop_focus と desktop_launch はすべて see="shot"（デフォルト）または see="none" を受け取る。2番目は、画面の見た目をすでに把握している場合にコンテキストを節約する。

windows-ui サーバー（公開サブセット）— ui_snapshot, ui_find, ui_click, ui_type, ui_select, ui_read, ui_wait, window_management, app。

仕組み

ターミナルで読む人のために、同じことをテキストで説明する:

  AGENT                                                   server/
  ─────                                                   ───────
  desktop_click / desktop_type / …                        desktop_server.py
        │                                                 (MCP, FastMCP)
        ├──► real SendInput: cursor eased to the target,  driver.py
        │    clicked, keys sent                           ── moves + clicks
        │                                                    the real desktop
        │
        ├──► EVENT LOG  t, kind, x, y, label, dur         driver.py → events.json
        │    + the sampled cursor path (track)               ◄── the ground truth
        │
        └──► screenshot back to the agent in the same reply

  desktop_record_start                                    recorder_proc.py (child process)
        └──► Windows Graphics Capture, bound to the HWND  wgc.py
             ├─ frames arrive only when the picture       ── writer thread re-sends
             │  changes …                                    the last frame on a
             └─ … so a writer thread feeds ffmpeg at a       fixed clock
                constant rate, logging the true
                wall-clock time of every frame
                                                          → raw.mp4 + frame_times.json

  desktop_render                                          render_proc.py (child process)
        │
        ├─ 1. TIMELINE   collapse the dead air            timeline.py
        │      keep 1.1 s before and 1.5 s after every
        │      action, squeeze the gaps to 0.55 s
        │
        ├─ 2. CAMERA     event log → keyframes            camera.py
        │      lead-in 0.55 s BEFORE each click,
        │      nearby clicks merged into one shot,
        │      pan instead of pumping in and out
        │
        ├─ 3. COMPOSITOR one affine matrix per frame      composer.py
        │      recording on a gradient backdrop, rounded     + cinematic.py
        │      corners, drop shadow, drawn cursor, click     (vignette, grain;
        │      ripples, motion blur, breathing idle,          title cards and
        │      vignette, grain                                captions available)
        │                                                 → silent.mp4
        │
        └─ 4. SOUND      optional narration               voice.py
               ElevenLabs TTS mixed onto the cut          → demo.mp4

  make_showcase.py — the fuller montage, run as a script rather than a tool:
        the same four stages plus title/outro cards, captions, and the whole
        sound design pass (clicks, whooshes, impacts, riser, ducked music bed,
        loudness normalisation)                           sfx.py + sfx_bank.py

ファイルレイアウトの大部分を説明する2つの設計上の決定:

キャプチャとレンダリングは子プロセスで実行される。 MCPサーバープロセス内でキャプチャライブラリやOpenCVをインポートするとプロセスが詰まり、レンダリングには数分かかるため、ツール呼び出しが長時間保持されるべきではない。recorder_proc.py と render_proc.py はそのためだけに存在する。これらはファイル（started.json, stop, render.log）を介して通信し、両方とも stdin=DEVNULL で起動される。サーバーのstdinを継承した子プロセスは、サーバー宛てのJSON-RPCリクエストを消費し始めるからだ。

フレームはインデックスではなくタイムスタンプで照合される。 マシンが遅れている場合、ソースフレーム N は N/fps の位置にはない。frame_times.json は各フレームの実際のキャプチャ時刻を保持し、コンポジターはそれを介してフレームを検索する。これにより、マシンが途切れてもカメラがクリック位置に留まる。

設定

レンダリング

desktop_render(out_dir, name="demo.mp4", max_zoom=2.0, narration="") — narration はJSONリストの {"text": …, "at": seconds} を受け取る。

それ以外はすべてモジュール定数で、その場で編集する:

desktop_record_start(window, out_dir="", fps=30) はデフォルトで ~/screencasts/take-HHMMSS になる。

max_zoom が指定されない場合、camera.build() はウィンドウの高さの少なくとも70%がフレーム内に収まるように上限を自動選択する。背の高い細いウィンドウを16:9フレームに収めるとすでに小さく、そこで2倍を強制するとアクションの意味を与える部分が切り取られる。（電卓では結果を表示するディスプレイが切り取られた。）

ナレーション

環境変数またはプラグインルートの .env ファイルに ELEVENLABS_API_KEY を設定する（KEY=value、1行に1つ。ファイルはgit-ignoreされる）。オプションで ELEVENLABS_VOICE_ID で音声を固定できる。設定がない場合はアカウントの最初の音声が使われる。モデル: eleven_multilingual_v2。キーを別の場所に置く場合は SCREENCAST_ENV_FILE を別の場所に指定する。

voice.resolve_voice() は、設定されたIDを使用する前にアカウントの実際の音声リストと照合する。削除された音声は、そうしないと説明のつかない404で失敗するためだ。

キーがなくても何も壊れない。 doctor.py はそれを失敗ではなく警告として報告し、desktop_render は無音のビデオを生成する。これは narration 引数が渡されない場合にキーがあっても生成されるものと同じである。

サウンドデザイン層はキーがなくても死ぬのではなく劣化する。sfx_bank.build() はパレットを生成するためにElevenLabsを必要とするが、sfx_bank.build_synthetic() はnumpyでオフラインで同じファミリーを合成する（*_syn1.wav / *_syn2.wav ファイル）。sfx.click_samples() はサンプルアセットが見つからない場合に synth_click() にフォールバックする。つまり、オフラインマシンでもクリック、スウッシュ、インパクトは得られる。失われるのは音声だけだ。

既知の制限

正直なリスト。これらは実際に存在し、現在も真実であり、ほとんどは開発中に遭遇したものだ。それらについて計画されていること（優先順位と各項目の測定値）は ROADMAP.md にある。

• desktop_render ツールはコードベースができることより少ないものをレンダリングする。 composer.compose() を intro, outro, captions なしで呼び出し、ナレーションのみをミックスする。クリックトラック、スウッシュ、ミュージックベッドはない。それ以外はすべて実装され動作しているが、現在は server/make_showcase.py を通してのみ到達可能であり、これは独自のハードコードされたテイクパスとビートリストを持つスクリプトである。それらのパラメータをツールに配線することが、このリポジトリで最も明白な未完了タスクである。

• ドラッグがない。 ドラッグやドラッグアンドドロップのツールはない。マウスダウンとマウスアップは常に同じ位置で発行されるため、押して動かして離すジェスチャー（スライダー、並べ替え、キャンバス描画、グリップでのサイズ変更）を必要とするものはすべて手の届かないところにある。

• キー押下はイベントログに書き込まれない。 desktop_key はキーストロークを送信するがログに記録しないため、カメラはキーボードのみのステップに反応せず、desktop_describe_take にも表示されない。クリックと入力テキスト（desktop_type）はログに記録される。個々のキー押下は記録されない。

• UWPウィンドウはフレームウィンドウでアドレス指定する必要がある。 Windows Graphics Capture はトップレベルウィンドウハンドルを受け取る。UWP/ストアアプリの場合、それは表示されている ApplicationFrameWindow である。内側の CoreWindow はキャプチャターゲットとして使用できない。実際には、アプリを表示ウィンドウタイトルで解決し（ツールが行うこと）、それを越えて到達しようとしないこと。

• desktop_screenshot はウィンドウキャプチャではなく画面のクロップである。 ウィンドウが占める画面領域を取得する。ウィンドウに重なるもの（別のウィンドウ、通知トースト、ツールチップ）はスクリーンショットに表示される。（録画にはこの問題はない。WGCはウィンドウ自体をキャプチャする。）スクリーンショットを信頼する前に、ターゲットウィンドウが最前面にあることを確認すること。

• ElectronアプリはUI Automationにほとんど何も公開しない。 Windows 11で測定: 典型的なElectronアプリは2〜6個の名前付き要素を返す。ウィンドウラッパーであり、インターフェースではない。スクリーンショットと座標にフォールバックするか、デバッグポートが利用可能な場合は desktop_dom を使用する。desktop_dom_launch は別のプロファイルを持つアプリの2番目のコピーを開くが、サインインしていない。

• NVENCが事実上必須である。 wgc.WindowRecorder と composer.compose() の両方がデフォルトで h264_nvenc を使用する。libx264 パスは実装されており、doctor.py は正しいエンコーダを machine.json に検出するが、その選択を自動的に配線するものはまだない。NVENCのないマシンでは、自分でエンコーダを渡す必要がある。

• 大きなファイル。 フィルムグレインはフレームごとに適用され、フレーム間圧縮を無効にする。短いデモは、グレインなしの同じ映像よりも重い。サイズが外観よりも重要な場合は grain_amount=0 を設定する。

• テイクは15分に制限されている。 recorder_proc.py は自分自身を停止するため、忘れられた録画が永遠に続くことはない。

• Windowsのみ、しかもインタラクティブデスクトップのみ。 SendInput、UI Automation、WGC、WinRT OCRはすべてWindows APIである。これらは無人セッション、サービス、ロック画面では動作しない。

• ウィンドウはライブアプリケーションである。 テイク間で状態が残る。リハーサルで開いたままの検索ボックスが、入力した単語を「githubgithub」に変えた。クリーンテイクの前にアプリをリセットすること。

• プライバシーチェックは報告するだけで、ブロックしない。 マッチングは文字通りである。メニュー内の名前はリークではなく、OCRは見逃すことがある。公開する前に自分でフレームを確認すること。

クレジットとライセンス

• sbroenne/mcp-windows (MIT) — UI Automationを行う windows-ui MCPサーバー。ここにベンダリングされておらず、server/fetch_ui_binary.py によってオンデマンドでダウンロードされ、リリース自身の SHA256SUMS.txt に対してチェックサム検証される。

• ffmpeg — キャプチャエンコーディング、オーディオミックス、ffprobe による時間測定。外部バイナリとして呼び出される。バンドルされていない。ライセンスはインストールするビルドに依存する（LGPLまたはGPL）。

• サウンドバンク。 server/sfx_bank/ の .wav ファイルはサンプリングではなく生成されている。server/sfx_bank.py はElevenLabsのサウンド生成APIを介してプロンプトレシピから一度だけビルドしてキャッシュし、すべての候補は測定によってスクリーニングされる（ピークが200ms遅れている「クリック」は、どんなに良く聞こえても拒否される）。2番目のファミリーのファイル — *_syn1.wav, *_syn2.wav — は sfx_bank.build_synthetic() でnumpyを使って完全にオフラインで合成されるため、APIキーのないマシンでもサウンドデザインが得られる。サードパーティのサンプルライブラリはここで再配布されない。SCREENCAST_SFX_DIR を自分のサンプルフォルダに指定すると、sfx.py は出荷されたバンクよりもそれらのクリックとミュージックベッドを優先する。何も設定されていない場合は server/sfx_bank/ を使用し、何も見つからない場合は合成する。どちらにしてもハードな依存関係はない。

• ElevenLabs — オプション。ナレーションとサウンドバンクの構築用。自分のキーを持参すること。プラグインは誰かの声から生成されたオーディオを同梱しない。

• フォント — タイトルとキャプションはWindowsに同梱されているSegoe UIを使用し、フォールバックとしてArialを使用する。フォントファイルは再配布されない。

• Model Context Protocol Python SDK (MIT) — サーバーフレームワーク。

プラグイン自身のコードはMITライセンスでリリースされている。LICENSE を参照。

貢献

Issue とプルリクエストは歓迎します。レビューを迅速にするためのいくつかのポイント:

• Windows のみ。 実際のデスクトップでテストしてください。ボタンをクリックしてくれる CI はありません。

• 最初に doctor を実行 (python server/doctor.py) し、その出力をバグレポートに貼り付けてください — ここでの問題のほとんどは環境によるものです (DPI スケーリング、モニターレイアウト、エンコーダーの欠落)。doctor が直接その名前を挙げます。

• 静かに壊れた場合は、コメントでその旨を伝えてください。 このコードベースには、行がそのようになっている 理由 を説明するメモが溢れています。なぜなら、それらのほぼすべてが成功に見えた失敗だからです: 録画として通る同一フレーム、端からずれていくカメラ、ズームがまったくないビデオを生成する空のイベントログ。これらのメモを残すことは意図的です。

• カメラまたはタイムラインの定数の変更には、変更前/変更後のクリップが必要です。 それらは結果がどのように 見える かに関する判断であり、テストでは決着をつけられません。