スクリーン キャプチャ

macOS でのプログラマティック スクリーンショット キャプチャ：ウィンドウを検索し、ビューを制御し、画像をキャプチャします。

クイック スタート

# Excel ウィンドウ ID を検索
swift scripts/get_window_id.swift Excel

# そのウィンドウをキャプチャ (12345 を実際の WID に置き換え)
screencapture -x -l 12345 output.png

概要

3 ステップのワークフロー：

1. ウィンドウを検索  →  Swift CGWindowListCopyWindowInfo  →  数値ウィンドウ ID を取得
2. ビューを制御     →  AppleScript (osascript)           →  ズーム、スクロール、選択
3. キャプチャ       →  screencapture -l <WID>            →  PNG/JPEG 出力

ステップ 1: ウィンドウ ID を取得 (Swift)

CoreGraphics で Swift を使用してウィンドウを列挙します。これは macOS での唯一の信頼できる方法です。

インラインで実行

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          # すべてのウィンドウをリスト

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

WID 番号を解析して screencapture -l で使用します。

ステップ 2: ウィンドウを制御 (AppleScript)

キャプチャの前にアプリケーション ウィンドウを制御するための検証済みコマンド。

Microsoft Excel (完全 AppleScript サポート)

# アクティベート (前面に表示)
osascript -e 'tell application "Microsoft Excel" to activate'

# ズーム レベルを設定 (パーセンテージ)
osascript -e 'tell application "Microsoft Excel"
    set zoom of active window to 120
end tell'

# 特定の行にスクロール
osascript -e 'tell application "Microsoft Excel"
    set scroll row of active window to 45
end tell'

# 特定の列にスクロール
osascript -e 'tell application "Microsoft Excel"
    set scroll column of active window to 3
end tell'

# セル範囲を選択
osascript -e 'tell application "Microsoft Excel"
    select range "A1" of active sheet
end tell'

# 特定のシートを選択
osascript -e 'tell application "Microsoft Excel"
    activate object sheet "DCF" of active workbook
end tell'

# ファイルを開く
osascript -e 'tell application "Microsoft Excel"
    open POSIX file "/path/to/file.xlsx"
end tell'

任意のアプリケーション (基本制御)

# 任意のアプリをアクティベート
osascript -e 'tell application "Google Chrome" to activate'

# 特定のウィンドウを前面に表示 (インデックス別)
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)

# ID で特定のウィンドウをキャプチャ
screencapture -l <WID> output.png

# サイレント キャプチャ (カメラ シャッター音なし)
screencapture -x -l <WID> output.png

# JPEG としてキャプチャ
screencapture -l <WID> -t jpg output.jpg

# 遅延でキャプチャ (秒)
screencapture -l <WID> -T 2 output.png

# 画面領域をキャプチャ (対話的)
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

キャプチャを確認

# ファイルが作成されコンテンツがあることを確認
ls -la output.png
file output.png    # "PNG image data, ..." と表示されるはず

マルチ ショット ワークフロー

完全な例：Excel ワークブックの複数セクションをキャプチャします。

# 1. ファイルを開いて Excel をアクティベート
osascript -e 'tell application "Microsoft Excel"
    open POSIX file "/path/to/model.xlsx"
    activate
end tell'
sleep 2

# 2. ビューをセットアップ
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. ウィンドウ ID を取得
#    重要：キャプチャする前に常に再度フェッチしてください。CGWindowID は無効化されます
#    アプリが再起動されたり、ウィンドウがクローズして再度開かれた場合。
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. セクション A (シートの上部) をキャプチャ
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. セクション B (さらに下) をキャプチャ
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. シートを切り替えてキャプチャ
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	PyObjC がシステム Python にインストールされていません。インストールを試みないで、代わりに Swift を使用してください
osascript window id	不正な形式	screencapture -l で必要な CGWindowID ではなく、AppleScript ウィンドウ インデックスを返します

権限トラブルシューティング

swift scripts/get_window_id.swift は CoreGraphics 経由でオンスクリーン ウィンドウを読み取るため、macOS でスクリーン レコーディング権限が必要です。

この順序を使用します：

1. トリガーを確認
2. ターゲット ID を確認
3. 設定で正確なアプリを追加/有効化

コマンドが ERROR: Failed to enumerate windows で失敗した場合は、以下を実行します：

open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"

または、スクリプトから直接チェックリストを出力します：

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

その後：

1. プライバシーとセキュリティ → スクリーン レコーディングで、ターゲット アプリを有効にします。
2. アプリがリストにない場合：
   • 実際のアプリ バンドルに権限を付与したことを確認します (swift / ターミナル ヘルパーではなく)。
   • CLI ツールの場合、権限確認中にパッケージ化された .app として構築/実行します。
   • + をクリックし、/Applications から .app を手動で追加します。
3. アプリを再起動した後、コマンドを再実行します。
4. これが CLI ワークフローの場合は、ランチャーがヘルパー バイナリかどうかも確認します：
   • ほとんどの場合、TCC に表示されるエントリは、ビジネス アプリではなく、ヘルパー プロセス (swift、Terminal、iTerm など) です。
   • ヘルパー レベルの付与後も権限は機能しますが、最終的な UX には理想的ではありません。

マイク アクセス関連のプロンプトについては、マイク ペインで同じパターンを使用します：

open "x-apple.systempreferences:com.apple.preference.security?Privacy_Microphone"

同じルールが適用されます：システムは具体的な .app バンドルの権限のみを表示できます。リクエストがヘルパー バイナリによって行われた場合、設定リストはプロダクト アプリに対して誤解を招く可能性があるか、空の可能性があります。

クイック チェック テンプレート

1) エラー：権限が拒否されました
2) ターゲット ペインを開く
3) OS が表示するID = 付与した ID であることを確認
4) 一致しない場合、スクリプト報告の候補 ID を使用し、ランチャー プロセスに権限を付与
5) 再度開く/再起動して確認

プロダクション アプリの場合、swift/python エントリ ポイント経由での権限リクエストを避けます。常にパッケージ化されたアプリ プロセスで権限チェックをルーティングして、ユーザーは 1 つのターゲットのみを表示します。

別の macOS 権限関連フローを管理する場合は、この標準化されたトリアージ テンプレートを再利用します：

• permission-triage-template.md

サポートされているアプリケーション

アプリケーション	ウィンドウ ID	AppleScript 制御	注記
Microsoft Excel	Swift	完全 (ズーム、スクロール、選択、シートアクティベート)	最高の対応
Google Chrome	Swift	基本 (アクティベート、ウィンドウ管理)	AppleScript でのスクロール/ズーム不可
任意の macOS アプリ	Swift	基本 (tell application でアクティベート)	screencapture はユニバーサルに動作

AppleScript 制御の深度はアプリケーションによって異なります。Excel が最も豊富な AppleScript ディクショナリを持ちます。AppleScript が限定的なアプリの場合は、フォールバックとして System Events 経由のキーボード シミュレーション を使用します。