annotate-video-events

name	annotate-video-events
description	人手動画アノテーションを映像証拠から作成・監査し、既存データでは高品質例を校正に使って低tIoU項目を診断・改善し、十分な品質になったら新規動画の取得と注釈へ展開する。Temporal Grounding用GT、イベント定義、時間区間、低精度データの改善、未注釈動画の追加、動画アノテーションの一括処理を依頼されたときに使う。既定は1動画・1イベント・1区間だが、ユーザー指定の契約へ切り替えられ、特定のリポジトリ、モデル、動画形式、schemaには依存しない。

動画イベントGTを改善・拡張する

映像上の事実を正解とし、tIoUを改善サイクルの明確な品質ゲートとして使う。高tIoUを目的にGTをpredictionへ寄せてはいけないが、GTを永久固定する必要もない。映像の再監査で誤りが見つかればイベント定義と区間を新revisionへ直し、必ず再推論して確かめる。既存データの改善、新規アノテーション、両方を扱う。

1. 作業契約を固定する

開始前に次を確認し、短い作業メモへ固定する。

• 対象動画、既存GT、prediction run、評価結果、出力先
• fps、PTSまたは時刻表、動画hash、時間区間の規約
• 1動画あたりのイベント数と、1イベントあたりの区間数
• 対象モデル、評価指標、達成すべき品質ゲート
• 新規動画を扱う場合の取得元、利用条件、保存先

指定がなければ 1動画・1イベント・1区間、half-open interval [start_s, end_s)を使い、評価可能な全対象でtIoU 0.5以上を必須ゲートとする。平均値だけが0.5以上でも、個別対象が0.5未満なら未完了とする。ユーザーが別の閾値、複数イベント、複数区間を求めた場合だけ契約を明示的に変更する。

媒体を読めない、時刻へ変換できない、利用条件を確認できない、または保存先が不明なまま破壊的な上書きが必要な場合だけ停止する。

2. データ全体を棚卸しする

既存データがある場合、最新のGT revisionと互換性のあるpredictionだけで評価を再計算する。動画ごとに次を一覧化する。

video_id | GT revision | event count | mean tIoU | review status | prediction compatibility

次の順で処理対象を作る。

1. schema不正、動画hash不一致、古いGT向けpredictionを分離する
2. tIoUの低い動画を優先する
3. 同点なら、イベント文が曖昧、境界根拠が弱い、未レビューの順にする
4. 0.5未満の対象がなくなるまで、下位から改善キューを作り直す
5. 新規動画の指示がある場合だけ、新規対象を同じキューへ追加する

tIoUは優先順位であり、GT品質の証明ではない。高tIoUでも映像と不一致なら校正例に使わず、低tIoUでも映像上正しいGTをモデルへ合わせて変更しない。

3. 校正例を選ぶ

上位から代表的な5〜10件を候補にし、映像を再確認して次を満たすものだけを校正例にする。

• イベント文が区間内の大半を正確に説明する
• 開始と終了を画面上の状態変化で説明できる
• 対象物、道具、手段、方向、置き場所の必要な情報がある
• 指定されたイベント数・区間数の契約を満たす
• 高スコアの理由が時刻リーク、入力重複、prediction由来GTではない

校正例から、イベントの粒度、開始条件、終了条件、文の具体性を短いルールにする。時刻そのものや対象動画固有の文言はコピーしない。

4. 低tIoU動画を1本ずつ改善する

各動画を直列に処理する。対象ごとに実推論と評価を行い、tIoUが0.5以上になってから次へ進む。0.5未満のまま「改善完了」として扱わない。

4.1 証拠を固定する

元動画hash、GT revision、使用query、raw prediction、モデルrevision、評価値を保存する。完了済みrunは上書きせず、新しいrun IDを使う。GTとpredictionを同じファイルへ保存しない。

4.2 predictionを隠してGTを監査する

最初はprediction区間とtIoUを見ずに、動画全体を疎に走査する。候補区間とその前後は全annotation frameまたは利用可能な細粒度フレームを時系列に見る。

既定の単一イベント契約では、次をすべて満たす候補を選ぶ。

1. 動画内で一度だけ起きる
2. 一つの連続区間で表せる
3. 開始・継続・終了を複数フレームで確認できる
4. 動画長の10%以上、かつ6 annotation frames以上ある
5. 瞬間操作へ分割しすぎず、動画全体の曖昧な要約でもない
6. 対象物や手段によって他の動作と区別できる

適格なイベントがなければ捏造せず skip: no_eligible_event とする。複数イベント契約では、各イベントに同じ映像証拠の基準を適用する。

4.3 イベント定義と境界を確定する

イベント文は「誰が・何を・どうする」を基本に、識別に必要な対象物、道具、手段、方向、置き場所を加える。意図、成功、品質、危険性など画面から確認できない状態は書かない。

• start_s: 定義した動作が最初に視認できる時刻
• end_s: 定義した動作が終了した後の最初の時刻
• 準備や後片付けは、イベント文に含む場合だけ区間へ含める
• クリップ端で開始または終了を観測できない候補は原則として避ける

元GTが映像証拠と一致するなら、そのrevisionを次の推論中だけ固定する。一致しない場合は、根拠フレームと変更理由を残してイベント定義、開始、終了を新しいrevisionへ修正する。schemaがcurrent pointer方式なら最新版を更新してよいが、旧revisionと旧評価の追跡可能性は失わない。

4.4 独立レビューする

利用可能なら、粗い走査、境界精査、最終レビューをサブエージェントへ分担する。サブエージェントにはprediction、tIoU、期待する修正方向を渡さず、ファイルも編集させない。コーディネータだけが最終案を保存する。

サブエージェントを使えない場合は、predictionを見ない独立した2パスで再確認する。境界案が1 annotation frameを超えて食い違う場合は該当フレームを再確認し、解消しなければ needs_review とする。

4.5 実推論を含む改善ループを回す

各ラウンドで使用するGTをrevisionまたはhashで特定し、必ず対象モデルで実推論する。推論せずにイベント文や区間だけを更新して完了してはいけない。

1. GT時刻を見せず、人手イベント文からqueryを作る
2. 新しいrun IDで実推論し、raw出力と入力条件を保存する
3. event別・動画別tIoUと集計値を計算する
4. 0.5以上なら通過として次の対象へ進む
5. 0.5未満なら、query、モデル能力、時間解像度、イベント選択、GTの意味・境界を原因候補として分解する
6. queryが原因なら、同じGT revisionのままqueryを改善して再推論する
7. GTが疑わしければ、predictionと時刻を隠して動画を再監査し、映像証拠がある場合だけ新revisionへ直してbaselineから再推論する
8. 一つの変更軸だけを変えて新しいrunを作り、0.5以上になるまで繰り返す

高品質例は、queryの構造や具体性の校正に使う。対象物、道具、手段が曖昧なら具体化し、動作の中心しか検出しないなら開始から終了までを表す。ただし、正解時刻、秒数、prediction区間をqueryへ入れない。

任意の反復回数で打ち切らない。0.5未満なら次のラウンドを計画し、query、イベント定義、GT境界、フレームサンプリング、推論設定のうち未検証の原因へ移る。同じ変更を繰り返さず、各ラウンドの仮説と結果を記録する。映像上正しいGTを保ったままモデル上限で改善できない、適格なイベントが存在しない、媒体や計算資源を利用できないなど、正解を捏造せずには進めない場合だけ blocked または needs_review とし、0.5未満の値、試した変更、必要な次の条件を明示する。

全runと変更理由を残し、同じ動画で調整した値はdevelopment値として報告する。高いtIoUを持つ動画のイベント粒度、境界条件、query構造を参考にしてよいが、時刻や固有文言をコピーしない。

5. 新規動画を取得して追加する

ユーザーが新規追加を指定した場合に進む。指示がなければ既存の0.5未満対象の改善を続け、勝手に動画をダウンロードしない。新規動画も既存動画と同じGT監査、実推論、tIoU 0.5ゲートへ入れる。

1. 取得元、動画ID、URLまたはdataset revision、ライセンス、checksumをmanifestへ記録する
2. リポジトリ既存のdownloaderがあれば再利用し、なければ再実行可能な取得コマンドまたは小さなdownloaderを用意する
3. 動画本体はGit管理外のデータ領域へ保存し、リポジトリへpushしない
4. duration、fps、decode可否、重複hash、破損を検証する
5. 既存のsplit、命名規則、annotation schemaへ合わせる
6. 校正例を使って、predictionを見ずに新規GTを作る
7. 独立レビュー後にbaseline実推論を行い、tIoUが0.5未満なら同じ改善ループへ入れる

利用条件が不明な動画、個人情報や機密情報を含む動画、重複動画は追加しない。ログやmanifestへローカル絶対パス、token、cookieを残さない。

6. 保存・検証・報告する

指定schemaがなければ次の最小形式を使う。

{
  "video_id": "clip_001",
  "interval_convention": "half-open_seconds",
  "event_labels": {"event_001": "観測可能な動作"},
  "events": {"event_001": [{"start_s": 2.0, "end_s": 7.0}]}
}

保存後に次を機械的に検証する。

• event IDの対応、指定されたイベント数と区間数
• 0 <= start_s < end_s <= duration
• 区間規約、schema外field、重複区間
• 動画hash、GT revision、prediction互換性
• データ本体、秘密情報、ローカル絶対パスがGit差分にないこと

処理後は最低限、次を数字で報告する。

対象数 / 0.5以上 / 0.5未満 / GT変更 / queryのみ変更 / skip / needs_review
変更前mean tIoU / 変更後mean tIoU / 最小tIoU / 反復回数
新規取得数 / 新規注釈数 / 検証失敗数

完了条件

• 低tIoU対象を優先して1本ずつ監査した
• 高tIoUかつ映像上正しい例だけを校正に使った
• 各ラウンドで実推論し、GT修正とquery改善を別revision・別runで追跡できる
• モデル出力をGTへコピーせず、境界をpredictionへ寄せていない
• 新規動画は出所と利用条件を記録し、データ本体をGitへ追加していない
• 全対象がschema、時刻範囲、媒体、公開情報の検証を通った
• 評価可能な全対象がtIoU 0.5以上、または正解を捏造せずには解消できない明確なblockerがある
• 改善前後の数値、反復回数、未解決理由を報告した

英訳は各GT revisionを確定した後に推論queryとして作成し、元の人手イベント文を置き換えない。