argent-screen-recording

1. ツール

• screen-recording-start：起動済みデバイスの画面キャプチャを開始し、動画ファイルに記録します。フレームは、screenshot とインタラクションツールがすでに使用しているものと同じ simulator-server バックエンドから取得され、h264 mp4 にリアルタイムでエンコードされます（固定 30 fps、デバイス本来の解像度）。
• screen-recording-stop：キャプチャを停止してコンテナを確定し、ダウンロード可能な成果物として動画を取得します（同じ場所にあるクライアントでは video.hostPath）。

デバイスごとに同時に記録できる動画は 1 本です。異なるデバイスなら同時に記録できます。記録によって、デバイスを読み取るほかの処理が妨げられることはありません。同じ画面のプレビューウィンドウを開いたままにできます。

---

2. 重要：記録を実行したままにしないでください

記録は timeLimitSeconds の上限に達する前に自動停止しません。停止し忘れると、上限に達するまでキャプチャが続き、記録セッションを占有し、ディスクを無駄に消費し、待機中の動画の取得が遅れます（さらに trimStatic: false の場合は、無音部分が余分に付いた状態で返されます）。安全策は 2 つあります。両方を使ってください。

1. 記録開始と同時にリマインダーを設定してください。 これから実行するインタラクションの想定時間は把握できているはずです。screen-recording-start の応答が返ったらすぐに、利用可能な手段で想定終了時刻に起動するよう設定してください。利用できる場合は組み込みのリマインダー／起動ツールまたはスケジュール済みタスクツールを使い、なければ sleep <expected-seconds> を実行するバックグラウンドシェルを使い、完了通知によって作業に戻るようにしてください。通知が届いたら screen-recording-stop を呼び出してください。覚えておくことに頼らないでください。
2. ツール結果の注記を読んでください。 記録中は、すべての argent ツール結果に、まだ記録中であることと停止方法を知らせる NOTE: が含まれます。注記に記録がすでに終了した（時間上限に達した）と記載されていても、screen-recording-stop を呼び出してください。これによってファイルが取得できます。

---

3. ワークフロー

1. 対象デバイスが起動済みであり、動画を開いたときに表示したい状態にアプリがあることを確認します（list-devices、launch-app、argent-device-interact）。
2. udid と、想定されるインタラクションの長さを少し上回る timeLimitSeconds を指定して screen-recording-start を呼び出します（デフォルトは 180、最大は 600）。デフォルトではタップやスワイプが動画に描画されます（下記のタッチビジュアライザーに関する注記を参照）。生の画面をそのままキャプチャするには、showTouches: false を渡します。
3. §2 で説明した記録終了リマインダーを設定します。この手順は省略できません。
4. キャプチャするインタラクションを実行します。ジェスチャー、画面遷移、入力を行います（argent-device-interact）。ツール呼び出しの遅延によって動画に余分な時間が入らないよう、短い時間で複数の操作を行う場合は run-sequence を使ってください。
5. 同じ udid を指定して screen-recording-stop を呼び出します。{ video, durationMs, wallClockMs?, trimmedMs?, warning? } が返されます。video は成果物で、解決後のパスは永続的に保存されたファイルを指します（詳細は以下を参照）。停止が返る時点で動画はすでに確定しています（ウォーターマークは後処理ではなくキャプチャ中に付与されます）。そのため、停止処理は 1 秒もかかりません。
6. warning を確認してください。上限到達による停止、エンコーダーの早期終了、フレームストリームの欠落、コンテナの切り詰めの可能性が報告されます。ユーザーに提示する前に、ファイルが再生できること（または少なくとも妥当なサイズであること）を確認してください。 ファイルの保存先（耐久性のある保存先であり、一時領域ではありません）。 OS が再利用する使い捨ての一時キャッシュに保存されることが多い argent の成果物とは異なり、完成した録画はクライアント上の <project>/.argent/recordings/ に永続的に保存されます。<project> は、クライアントの作業ディレクトリから最も近い祖先にある .git／package.json／.argent のいずれかを含むディレクトリです。クライアントがプロジェクト内にない場合は、~/.argent/recordings/ に保存されます。リモートの argent link ツールサーバーを使用している場合も同様で、mp4 はサーバーではなくクライアントホストに書き込まれます。保存先は recordings.directory 設定（デフォルトではグローバル設定。リポジトリごとに設定するには --scope project を指定します。両方が設定されている場合はプロジェクト設定が優先されます）で変更できます。値には絶対パス、~ で始まるパス、またはプロジェクトルートからの相対パスを指定でき、常にクライアントホスト上で解決されます。保存ファイル名は screen-recording-<device>-<timestamp>.mp4 です。同名のファイルがすでにある場合は上書きせず、隣に … (2).mp4 として新しいファイルを保存します。これらのファイルは作業ツリーに残るため、ユーザーにパスを伝えてください（また、追跡対象外であることも伝え、コミットすべきでない場合は .gitignore に追加するか、削除してください）。

静止フレームのトリミング（デフォルトで有効）。 画面に変化がない区間は短縮されます。各静止区間の最初の1秒は自然な間として残し、その後は画面が再び動くまで変化のないフレームが削除されます（数ピクセルの変化でも動きとして判定されます）。そのため、手順の進行が遅い場合や、待ち時間、考え中の時間を含む録画をそのまま続けても、無音の映像でクリップが長くなることはありません。実際に動きがあった時間が5秒の40秒間のセッションなら、約5～7秒の動画になります。トリミングによって何かが削除された場合、停止時に wallClockMs（実際の経過時間）と trimmedMs（削除された時間）も返されます。durationMs は、実際に取得した動画の長さを常に示します。実時間どおりの録画が必要な場合（画面上で何かにかかった時間を計測する場合など）は、screen-recording-start に trimStatic: false を渡してください。

タッチビジュアライザー（デフォルトで有効）。 argent が実行するすべての操作は、動画に直接描画されます。タップにはパルス、スワイプやドラッグには徐々に消える軌跡が表示され、ピンチや回転では2つの接触点がマーカーで示されます。これにより録画だけで操作内容が分かり、画面の反応を、見えない指によるものとしてではなく、各ジェスチャーが行われた 場所 とともに確認できます。フレームストリームに simulator-server が描画するため（ホスト側で合成することはありません）、追加コストはかからず、screenshot に表示されることもありません。オーバーレイなしで画面をそのまま録画する場合（ユーザーに見える画面をそのままキャプチャする場合など）は、screen-recording-start に showTouches: false を渡してください。simulator-server が有効化できない場合でも録画は成功し、停止時にタッチが表示されていないことを示す warning が返されます。

---

4. プラットフォームに関する注意事項と制限

• 記録できるもの：simulator-server で操作できるものはすべて対象です。iOS シミュレーター、Android エミュレーター、物理 Android デバイスが含まれます。長さの制限は timeLimitSeconds（最大 600）のみです。
• タイムラインは安定した 30 fps に調整されます：デバイスは画面が変化したときにのみフレームを出力するため、キャプチャしたフレームは、まとまって出力されるのではなく、固定タイムラインに合わせて再調整されます。静止フレームのトリミングをオフ（trimStatic: false）にすると、タイムラインは実時間に正確に対応します。画面がまったく動かなくても、動画は記録した長さのまま出力され（圧縮によりサイズはほぼゼロになります）、durationMs は実際の記録時間と一致します。トリミングをオン（デフォルト。§3 を参照）にすると、猶予時間を超える静止区間は折りたたまれるため、durationMs はトリミング後の動画の長さとなり、実際の経過時間は wallClockMs に記録されます。
• 動画ごとにサイズは 1 つです：動画のサイズは、記録開始時の画面サイズが維持されます。画面サイズが変わると、argent は新しい画面の縦横比を維持し、黒帯を追加します。折りたたみ式シミュレーターでは、必要なパネルが全画面サイズになる状態で記録を開始してください。
• Android：デバイス本来の解像度で記録します。セキュア画面（DRM、一部のパスワード入力欄）は黒くなります。
• 未対応：tvOS シミュレーター、物理 iPhone、Chromium アプリ、Vega/Fire TV、リモート（remote: で始まる）シミュレーターは、読み取り可能なフレームストリームを公開しないため、いずれも未対応です。静止画を 1 枚だけ取得するには screenshot を、再生可能な操作スクリプトを作成するには動画ではなく argent-create-e2e を使用してください。
• ffmpeg が必要です：エンコーダーであるため、インストールされていない場合、screen-recording-start はインストール方法を示して起動前に失敗します（macOS では brew install ffmpeg）。PATH と一般的な Homebrew のプレフィックスから解決されます。
• ウォーターマーク：エンコード時に Argent のロゴと「By @swmansion」が左下に表示されます。薄く（不透明度 20%）、背景とのピクセル単位のコントラストに合わせています（暗い UI には明るいロゴ、明るい UI には暗いロゴ）。デフォルトで有効です。argent disable video-watermark で無効にし、argent enable video-watermark で再度有効にできます。このフラグは記録開始時に読み込まれます。