capture-screen

画面キャプチャ

macOS でプログラムからスクリーンショットをキャプチャします。ウィンドウの検索、表示の操作、画像のキャプチャを行います。

観察とフォアグラウンド操作の選択

既存の表示を確認する場合は、ウィンドウをアクティブにせず、正確なウィンドウを列挙してキャプチャします。 表示を変更する必要がない場合は、ステップ 2 を省略してください。ウィンドウ画像で確認できるのは、そのキャプチャ時点での表示内容です。キーボードフォーカス、入力の送信、または業務上の操作が成功したことは証明できません。

ウィンドウを開いたり前面に表示したり、スクロール、選択、ズームの変更、キー送信を行う前に、実行するエージェントはユーザーのアクティビティと他のエージェントの占有状況を確認します。具体的なタスクの引き継ぎ、または既存の明示的なデスクトップ待機中の操作許可に従ってください。後者の場合は排他的なアクセスを調整し、再確認せずに作業を進めます。入力がないことだけでは、操作権限があるとは限りません。使用中、または占有状況が不明な場合、あるいは予期しない入力があった場合は、フォアグラウンド操作を中止してください。独立して行える読み取りは続けてもかまいませんが、人が操作を引き継いだ後に以前のフォーカスへ戻してはいけません。

選択したツールのアクティブ化の動作を確認してください。アプリを指定した呼び出しや、バックグラウンドで実行されるシェルジョブであっても、フォーカスが維持されるとは限りません。キャプチャに失敗しても、ウィンドウを前面に表示したり、権限を変更したり、ホストによる拒否や GUI ロックを回避するために別のツールへ切り替えたりすることは許可されません。既存の許可がない場合に限り、引き継ぎを依頼してください。

クイックスタート

未特定のダイアログ、またはデスクトップ全体を観察する

ユーザーが画面全体の表示を求めている場合、または許可されたウィンドウの観察では報告された妨げを特定できない場合に、この手順を使用します。まず、ホストがこのキャプチャとその対象範囲を許可していることを確認してください。アプリ固有の操作が拒否されたからといって、画面キャプチャが利用できないとは限りません。また、ホストが保護している内容を別のツールで読み取ることも許可されません。拒否が予定しているキャプチャにも及ぶ場合、または GUI ロックにより実行できない場合は中止してください。

アクティブ化、スクロール、入力を行わずにキャプチャします。

capture_dir="$(mktemp -d)"
screencapture -x "$capture_dir/desktop.png"

ホストで許可されている画像ビューアーを使って、生成された画像を確認します。複数のディスプレイがあるデスクトップでは、デスクトップ全体を確認したと判断する前に、生成されたディスプレイ画像をすべて確認してください。ファイルが作成されただけでは、要求されたダイアログがキャプチャされた証明にはなりません。特定できたら、その後の観察では正確なウィンドウを優先し、ユーザーが報告した操作上の問題を引き続き考慮してください。

権限の分類と復旧については、macOS の権限管理者の macos-permissions エントリに従ってください。

既知のウィンドウをキャプチャする

# Find Excel window ID
swift scripts/get_window_id.swift Excel

# Capture that window (replace 12345 with actual WID)
screencapture -x -l 12345 output.png

ステップ 1：ウィンドウ ID を取得する（Swift）

ホストがウィンドウの列挙を許可している場合は、同梱の Swift/CoreGraphics 経由の方法を使用します。必要な ID が得られる場合は、ホストのネイティブなウィンドウ一覧を優先してください。

クイックなインライン実行

swift -e '
import CoreGraphics
let keyword = "Excel"
let list = CGWindowListCopyWindowInfo(.optionOnScreenOnly, kCGNullWindowID) as? [[String: Any]] ?? []
for w in list {
    let owner = w[kCGWindowOwnerName as String] as? String ?? ""
    let name = w[kCGWindowName as String] as? String ?? ""
    let wid = w[kCGWindowNumber as String] as? Int ?? 0
    if owner.localizedCaseInsensitiveContains(keyword) || name.localizedCaseInsensitiveContains(keyword) {
        print("WID=\(wid) | App=\(owner) | Title=\(name)")
    }
}
'

同梱スクリプトを使用する

swift scripts/get_window_id.swift Excel
swift scripts/get_window_id.swift Chrome
swift scripts/get_window_id.swift          # List all windows

出力形式：WID=12345 | App=Microsoft Excel | Title=workbook.xlsx

WID の数値を解析し、screencapture -l で使用します。

ステップ 2：ウィンドウを操作する（AppleScript、任意のフォアグラウンド作業）

以下のコマンドは、前述の許可されたフォアグラウンド操作時間内でのみ使用してください。active window や active workbook の例を使う前に、対象のアプリ／ウィンドウ／書類を正確に指定してください。たまたまアクティブになっているウィンドウから対象を推測してはいけません。

Microsoft Excel（AppleScript の完全サポート）

# Activate (bring to front)
osascript -e 'tell application "Microsoft Excel" to activate'

# Set zoom level (percentage)
osascript -e 'tell application "Microsoft Excel"
    set zoom of active window to 120
end tell'

# Scroll to specific row
osascript -e 'tell application "Microsoft Excel"
    set scroll row of active window to 45
end tell'

# Scroll to specific column
osascript -e 'tell application "Microsoft Excel"
    set scroll column of active window to 3
end tell'

# Select a cell range
osascript -e 'tell application "Microsoft Excel"
    select range "A1" of active sheet
end tell'

# Select a specific sheet
osascript -e 'tell application "Microsoft Excel"
    activate object sheet "DCF" of active workbook
end tell'

# Open a file
osascript -e 'tell application "Microsoft Excel"
    open POSIX file "/path/to/file.xlsx"
end tell'

任意のアプリケーション（基本操作）

# Activate any app
osascript -e 'tell application "Google Chrome" to activate'

# Bring specific window to front (by index)
osascript -e 'tell application "System Events"
    tell process "Google Chrome"
        perform action "AXRaise" of window 1
    end tell
end tell'

タイミングとタイムアウト

UI の描画が完了するまで待つため、AppleScript コマンドの実行後は必ず sleep 1 を追加してください。

重要：対象のアプリケーションが起動していない、または応答していない場合、osascript は無期限にハングします。必ず timeout で囲んでください。

timeout 5 osascript -e 'tell application "Microsoft Excel" to activate'

ステップ 3：キャプチャする（screencapture）

# Capture specific window by ID
screencapture -l <WID> output.png

# Silent capture (no camera shutter sound)
screencapture -x -l <WID> output.png

# Capture as JPEG
screencapture -l <WID> -t jpg output.jpg

# Capture with delay (seconds)
screencapture -l <WID> -T 2 output.png

# Capture a screen region (interactive)
screencapture -R x,y,width,height output.png

Retina ディスプレイ

Retina 搭載の Mac では、screencapture はデフォルトで 2 倍の解像度で出力します（例：2032x1238 のウィンドウから 4064x2476 の PNG が生成されます）。これは正常な動作です。1 倍の解像度にするには、キャプチャ後にサイズを変更します。

sips --resampleWidth 2032 output.png --out output_1x.png

キャプチャを確認する

# Check file was created and has content
ls -la output.png
file output.png    # Should show "PNG image data, ..."

複数回キャプチャするワークフロー

フォアグラウンド操作の例：Excel ワークブックの複数のセクションをキャプチャします。最初に、前述の許可を得て、排他的な操作権限を確保してください。ユーザーが操作を引き継いだ場合は、残りの手順を中止し、再実行したり以前のフォーカスに戻したりしないでください。

# 1. Open file and activate Excel
osascript -e 'tell application "Microsoft Excel"
    open POSIX file "/path/to/model.xlsx"
    activate
end tell'
sleep 2

# 2. Set up view
osascript -e 'tell application "Microsoft Excel"
    set zoom of active window to 130
    activate object sheet "Summary" of active workbook
end tell'
sleep 1

# 3. Get window ID
#    IMPORTANT: Always re-fetch before capturing. CGWindowID is invalidated
#    when an app restarts or a window is closed and reopened.
WID=$(swift -e '
import CoreGraphics
let list = CGWindowListCopyWindowInfo(.optionOnScreenOnly, kCGNullWindowID) as? [[String: Any]] ?? []
for w in list {
    let owner = w[kCGWindowOwnerName as String] as? String ?? ""
    let wid = w[kCGWindowNumber as String] as? Int ?? 0
    if owner == "Microsoft Excel" { print(wid); break }
}
')
echo "Window ID: $WID"

# 4. Capture Section A (top of sheet)
osascript -e 'tell application "Microsoft Excel"
    set scroll row of active window to 1
end tell'
sleep 1
screencapture -x -l $WID section_a.png

# 5. Capture Section B (further down)
osascript -e 'tell application "Microsoft Excel"
    set scroll row of active window to 45
end tell'
sleep 1
screencapture -x -l $WID section_b.png

# 6. Switch sheet and capture
osascript -e 'tell application "Microsoft Excel"
    activate object sheet "DCF" of active workbook
    set scroll row of active window to 1
end tell'
sleep 1
screencapture -x -l $WID dcf_overview.png

失敗した方法（使用しないでください）

以下の方法は macOS でテストされ、失敗することが確認されています。

方法	エラー	失敗する理由
System Events → id of window	Error -1728	System Events は、screencapture が必要とする形式のウィンドウ ID にアクセスできません
Python import Quartz (PyObjC)	ModuleNotFoundError	システムの Python に PyObjC がインストールされていません。インストールしようとせず、代わりに Swift を使用してください
osascript のウィンドウ ID	形式が不正	screencapture -l が必要とする CGWindowID ではなく、AppleScript のウィンドウインデックスを返します

権限に関するトラブルシューティング

get_window_id.swift でウィンドウを列挙できない場合や、必須のフィールドが利用できない場合は、 Screen Recording が原因だと判断する前に、実際の結果を確認してください。ウィンドウを列挙せずに ヘルパーの診断ガイダンスを取得するには、次を実行します。

swift scripts/get_window_id.swift --permission-hint screen
swift scripts/get_window_id.swift --permission-hint microphone

この出力は、ヘルパーの診断手順に沿って解釈してください。 ヒントにはガイダンスと実行コンテキストが表示されますが、許可の状態を確認したり、 許可を付与すべきプロセスを特定したりするものではありません。TCC に関する一般的な原因の特定、 権限の変更、リクエストの復旧には、引き続き macos-permissions を使用してください。

対応アプリケーション

アプリケーション	ウィンドウ ID	AppleScript による操作	備考
Microsoft Excel	Swift	全機能（ズーム、スクロール、選択、シートのアクティブ化）	最も充実した対応
Google Chrome	Swift	基本機能（アクティブ化、ウィンドウ管理）	AppleScript ではスクロール／ズーム不可
その他の macOS アプリ	Swift または許可されたホストのインベントリ	アプリによって異なります	キャプチャにはホストの許可とキャプチャ可能なサーフェスが必要です

AppleScript による操作の範囲はアプリケーションによって異なります。Excel は最も充実した AppleScript ディクショナリを備えています。AppleScript の機能が限られるアプリでは、System Events によるキーボードシミュレーションは、エントリーゲートを通過した後に限りフォアグラウンドでの代替手段として使用できます。バックグラウンド操作が失敗した場合の自動的な復旧手段ではありません。