getlarge/themoltnet

製品デモ録画

フレーミング、プライバシー、ナラティブ、デコードされた出力をそれぞれ独立したリリースゲートとして扱います。 製品が正常に動作したとしても、録画が安全で読みやすく、きれいに構成されているとは限りません。

ネイティブのmacOSまたはブラウザのキャプチャメカニズムについては、references/capture-macos.md を参照してください。 ポーリングやリトライループを含むブラウザワークフロービルダーについては、references/browser-workflows.md を参照してください。 タイトルカード、ローワーサード、図、コールアウト、エンドカードについては、references/infographic-style.md を参照してください。

最初に配信フレームを確立する

録画の前に:

1. ショットリストを書く前にナラティブのタイプを選択します:
   • 概要は製品の形状を説明します。最小の代表的なノードまたは画面シーケンスを示し、汎用的なコピーを使用し、シナリオ固有の説明は省略します。
   • シナリオデモは1つの具体的な質問に答えます。ケースを説明し、実際の実行段階を示し、検証された結果で終了します。
   • 両方が有用な場合は、個別の短い動画を優先します。ユーザーが明示的に統合ウォークスルーを希望しない限り、汎用的な製品説明とドメイン固有のケースを混在させないでください。
2. 視覚的なリファレンスを確立します:
   • 以前の録画が存在する場合は、最初から最後まで検査します。必要に応じてコンタクトシートを抽出し、そのペーシング、フレーミング、注釈、および最も説明的な瞬間を記録します。
   • 以前の録画がない場合は、@themoltnet/design-system ライブラリ、隣接するドキュメントのメディア、および統合製品のネイティブUIをこの順序で使用して、録画前にタイトルカード画像、最も密集した注釈付きUI画像、およびエンドカード画像を作成します。これらの承認された静止画は、シリーズの後続の動画のベースラインになります。
3. 動画が表示されるページを読みます。ユーザーの成果、必要なセットアップ、メインのインタラクション、待機またはリトライ動作、成功結果を指定した短いショットリストを書きます。
4. アプリを配置する前に、最終的なアスペクト比と解像度を選択します。1440x810や1920x1080などの従来の16:9フレームを優先します。
5. 意図したコンテンツ領域全体がそのフレームに収まるようにアプリケーションを配置します。必要に応じてアプリ内のオプションのサイドバーを非表示にします。ポストプロダクションで任意のクロップを使用してサイドバーやコントロールの半分を削除しないでください。
6. ブラウザのクローム（ウィンドウ装飾）を構成の一部とするかどうかを決定します。クリーンなブラウザビューポートキャプチャを優先します。それが利用できない場合は、ブラウザウィンドウ全体を保持するか、意図的なフレーム内に配置します。切り取られたタブ、エッジ、またはアプリケーションコンテンツよりも、完全なウィンドウの方がクリーンです。
7. 3つの代表的なスタイルフレームを実際の表示サイズで確認します。オーバーレイシステム、セーフエリア、情報階層がまだ開発中の状態で、完全なウォークスルーを録画しないでください。

安全なキャプチャ境界を使用する

• 1つのアプリケーションウィンドウまたは1つのブラウザビューポートをキャプチャします。他のアプリケーションが侵入できるデスクトップ矩形は決してキャプチャしないでください。
• 録画前に正確なウィンドウ識別子を解決してロックします。ナビゲーション、ポップアウト、またはアプリケーションの再起動後に再確認します。
• 通知を無効にし、専用のデモデータを使用しますが、これらの注意事項をプライバシー境界として依存しないでください。
• 認証情報、トークン、個人識別子、プライベートURL、および無関係なアカウントデータをキャプチャ面の外に保持します。パスワードマスキングは必要ですが、認証情報入力の映像を望ましいものにするわけではありません。
• ポインターを意図的に操作します。静的な結果が読まれている間は、ポインターをテキストから離して配置します。

理解できるように録画する

• 1ショットに1つのアイデアを使用します。重要な設定と結果は、通常の再生速度で読めるのに十分な時間保持します。
• セットアップは、視聴者が結果を再現するのに役立つ場合にのみ表示します。統合デモの場合、これは多くの場合、インストール、シークレットを明かさずに認証、ワークフローのインポート、実行、および端末結果の検査を意味します。
• 後でラスターを拡大してクロップするよりも、ネイティブアプリケーションのズームとレイアウト変更を優先します。
• 実際の成功した実行をキャプチャします。再構築されたタイトルカードと注釈はそれを説明する場合がありますが、観察されなかったアクションや結果を暗示してはなりません。
• 状態主導の編集では、動き自体が教育的でない場合、1回の実際の実行からキャプチャされたクリーンな静止画を使用できます。観察された順序で状態を維持し、目に見えるタスクの証拠を保持し、進行を伝えるためにのみトランジションを使用します。
• 認証情報の作成と接続テストは、録画するテイクの外で完了します。認証情報のセットアップ自体が文書化の対象でない限り、認証済みの安全な状態からナレーションを開始します。
• フローに安定したステージがある場合は、短く独立して使用できるテイクを録画します。これにより、再録画が制限され、プライバシーレビューがより正確になります。
• 長時間のポーリングまたはリトライループの場合、実際の順序付けられた状態を保持しますが、繰り返されるアイドル部分を加速またはトリミングします。初期アクション、ターミナルワークフロー状態、および受け入れられた結果を読み取り可能な速度で保持します。

製品を隠さずに編集する

• 意図されたすべてのアプリケーションのエッジを保持します。コンテンツをクロップしてアスペクト比を強制するのではなく、スケールダウンして配信フレームにパディングします。
• タイトルカードとエンドカードは、方向性や次のステップを向上させる場合にのみ使用します。
• ローワーサードは、事前に計画されたセーフエリア内に保持します。フローの理解に必要なコントロール、ステータス、出力、エラー、または識別子を覆ってはなりません。
• シナリオデモの場合、注釈を実行とともに進めます。現在のステージを命名し、その結果を1つの短い行で説明します。例: INTENT — 場所と時間枠を抽出 の後に INTENT COMPLETE — 予報を取得。製品の実際のステージ名と観察可能な状態を使用します。隠れた推論を説明しないでください。
• 概要動画は、関連するシナリオデモよりも視覚的に静かにします。ノードラベルとネイティブステータスインジケーターがすでに十分な場合は、それらが説明を担うようにします。
• 既存の動画を置き換える場合は、確立されたドキュメントの視覚言語に合わせます。置き換えが、それが取って代わるアセットよりも意図的でないと感じさせないでください。
• 広範なブラウザ互換性のために、デフォルトでH.264 High、yuv420p、定数30 fps、ナレーションが意図的でない限りオーディオなし、MP4 fast-startを使用します。
• このmacOSツールチェーンでは、可能な場合は最終レンダリングにシングルスレッドのlibx264を優先します。正確なタイムスタンプのQAフレームを抽出する場合は、高速入力シークの代わりにバンドルされたヘルパーを使用します。
• アーティファクトプレビューでフレームが破損しているように見える場合は、チェックサムが安定しているアーティファクトを再度開き、ネイティブプレーヤーで動画を検査します。プレビューパスは、同じ画像バイトを異なる方法でレンダリングすることがあります。欠陥が独立して再現可能でない限り、動画を変更しないでください。
• 通常の再生と繰り返しの抽出でフレームが破損したままの場合は、クリーンなソースから影響を受けるセグメントを置き換え、-threads 1 を使用して最終マスターを再エンコードします。

オーディオは、その価値が認められる場合のみ追加する

• 埋め込みドキュメント動画のデフォルトは無音再生とします。簡潔な視覚的注釈では説明できないタイミング、因果関係、またはコンテキストを実質的に説明する場合にのみ、ナレーションを追加します。
• ロックされた画像に対してナレーションを書き、タイミングを合わせます。キャプションまたはテキストトランスクリプトは同じ情報を保持する必要があり、動画はミュートされた状態でも理解可能である必要があります。
• 特定可能な人物をモデルにしたクローンまたは合成音声は、その人物の明示的な許可がある場合にのみ使用します。周囲のページまたはクレジットで音声が合成であることを開示します。本物のライブ録音として提示しないでください。
• 音声サンプル、モデルファイル、および生成された中間ファイルは、ユーザーが明示的に公開することを選択しない限り、リポジトリの外に保持します。1つのナレーションデモを作成する許可は、その成果物に限定され、将来の音声生成に対する継続的な同意とは見なされません。
• オーディオをミックスした後、配信QAを再実行します。了解度、レベル、同期、キャプション、チャンネルレイアウト、および最終コンテナが依然として動画配信仕様を満たしていることを確認します。

デコードされた成果物をレビューする

バンドルされたヘルパーを中間ファイルではなく最終ファイルに対して実行します:

.agents/skills/product-demo-recording/scripts/qa-video.sh \
  path/to/final.mp4 /private/tmp/demo-video-qa --interval 2 4 5 6

ヘルパーは、ストリームメタデータ、順次デコードされたコンタクトシート、および開始/中間/終了と要求されたタイムスタンプフレームをJPEGとして書き込みます。新しい出力ディレクトリを使用します。

次に、以下のすべてのチェックを実行します:

1. 最終的な動画全体を通常速度で視聴します。
2. アプリケーション、モーダル、ショット、注釈、結果状態のすべての変更についてコンタクトシートを検査します。
3. すべての編集境界の直前、境界上、直後の正確なフレームを検査します。レビューフィードバックで名前が付けられたタイムスタンプを常に追加します。隣接するフレームが代表的であると推測しないでください。
4. 他のアプリ、デスクトップ領域、通知、認証情報、プライベートデータ、クリップされたエッジ、部分的なブラウザクローム、奇妙な黒い境界線、または妨害されたコントロールがないことを確認します。
5. テキストが読みやすく、ポインターの配置が落ち着いており、トランジションがクリーンで、表示される結果が周囲のドキュメントと一致していることを確認します。
6. コーデック、ピクセル形式、寸法、フレームレート、再生時間、オーディオの選択、およびfast-start要件を配信仕様に対して確認します。

これらのチェックがコミットされる正確なファイルに対して実行されるまでは、録画がレビューされたと説明しないでください。

意図的に出荷して保持する

• 最終アセットと意図的なドキュメント変更のみをステージングします。生のテイク、認証情報、ブラウザプロファイル、またはQAエクスポートは追加しないでください。
• 最終ファイルがレビューされ、安全にコミットまたはアップロードされるまで、生のテイクを保持します。その後、オペレーターの保持ポリシーに従います。広範な削除パターンではなく、機密性の一時キャプチャを明示的に削除します。
• ハンドオフでは、何が表示されたか、最終的な技術的特性、どのタイムスタンプが検査されたか、および最終アセットがどこにあるかを明記します。