akari-video 0.1.19 → 0.1.21

package/vendor/skills/analyze-footage/bin/person-matte/person-matte.mjs

@@ -13,7 +13,8 @@
 // 使い方:
 //   node person-matte.mjs --check
 //   node person-matte.mjs --input <video> --out <matte.webm>
-//                         [--quality fast|balanced|accurate] [--fps 24] [--decode-width 1280]
+//                         [--quality fast|balanced|accurate|best]
+//                         [--model mobilenetv3|resnet50] [--fps 24] [--decode-width 1280]
 //
 // 出力は stdout の 1 行 JSON。成功時 `ok: true` と実測値、失敗時 `ok: false` と `reason`。
 // 外部 npm 依存ゼロ・ネットワーク禁止（edit-lint と同じ規律）。
@@ -25,18 +26,25 @@ import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
 import { findAlphaModeTag } from "./alpha-tag.mjs";
+import { DEFAULT_RVM_MODEL, resolveRvmModel } from "../../../../packages/matte-rvm/src/index.mjs";
+import { resolveFfmpeg, resolveFfprobe } from "../../../../packages/media-bin/src/index.mjs";
 
 const scriptDir = path.dirname(fileURLToPath(import.meta.url));
 const helperSource = path.join(scriptDir, "person-matte-helper.swift");
 const defaultHelperBin = path.join(scriptDir, "person-matte-helper");
+const rvmHelper = fileURLToPath(
+  new URL("../../../../packages/matte-rvm/bin/rvm-helper.mjs", import.meta.url),
+);
 
 // スパイク実測（2026-07-23）で確定した既定値。入力解像度は Vision の速度にほぼ無関係
 // （quality ごとに内部で固定リサイズされる）ため、デコード幅は 1280 で統一する。
 const DEFAULT_DECODE_WIDTH = 1280;
 const DEFAULT_FPS = 24;
 const DEFAULT_QUALITY = "balanced";
-const QUALITIES = ["fast", "balanced", "accurate"];
+const QUALITIES = ["fast", "balanced", "accurate", "best"];
+const RVM_MODELS = ["mobilenetv3", "resnet50"];
 const TOOL_ID = "vision-person-segmentation";
+const RVM_TOOL_ID = "rvm-person-matting";
 
 function printJson(value) {
   process.stdout.write(`${JSON.stringify(value)}\n`);
@@ -55,31 +63,52 @@ function spawnSyncSafe(command, args) {
   }
 }
 
-function checkAvailability() {
-  if (os.platform() !== "darwin") {
-    return { available: false, reason: `macOS ではありません（${os.platform()}）` };
+function checkAvailability({
+  platform = os.platform(),
+  runSync = spawnSyncSafe,
+  resolveFfmpegBin = resolveFfmpeg,
+  resolveFfprobeBin = resolveFfprobe,
+  resolveModel = resolveRvmModel,
+} = {}) {
+  if (platform !== "darwin" && platform !== "win32") {
+    return { available: false, reason: `未対応のプラットフォームです（${platform}）` };
   }
 
-  const swift = spawnSyncSafe("swiftc", ["-version"]);
-  if (swift.error?.code === "ENOENT") {
-    return { available: false, reason: "swiftc が PATH 上にありません" };
+  if (platform === "darwin") {
+    const swift = runSync("swiftc", ["-version"]);
+    if (swift.error?.code === "ENOENT") {
+      return { available: false, reason: "swiftc が PATH 上にありません" };
+    }
+    if (swift.error || swift.status !== 0) {
+      return { available: false, reason: "swiftc を起動できません" };
+    }
+  }
+
+  let ffmpegBin;
+  let ffprobeBin;
+  try {
+    ffmpegBin = resolveFfmpegBin();
+  } catch (error) {
+    return { available: false, reason: summarize(error?.message, "ffmpeg が見つかりません") };
   }
-  if (swift.error || swift.status !== 0) {
-    return { available: false, reason: "swiftc を起動できません" };
+  try {
+    ffprobeBin = resolveFfprobeBin();
+  } catch (error) {
+    return { available: false, reason: summarize(error?.message, "ffprobe が見つかりません") };
   }
 
-  for (const command of ["ffmpeg", "ffprobe"]) {
-    const probe = spawnSyncSafe(command, ["-version"]);
+  for (const [label, command] of [["ffmpeg", ffmpegBin], ["ffprobe", ffprobeBin]]) {
+    const probe = runSync(command, ["-version"]);
     if (probe.error?.code === "ENOENT") {
-      return { available: false, reason: `${command} が PATH 上にありません` };
+      return { available: false, reason: `${label} が見つかりません` };
     }
     if (probe.error || probe.status !== 0) {
-      return { available: false, reason: `${command} を起動できません` };
+      return { available: false, reason: `${label} を起動できません` };
     }
   }
 
   // VP9 alpha WebM を書けるかは libvpx-vp9 の有無で決まる（ffmpeg 内蔵の vp9 エンコーダは別物）。
-  const encoders = spawnSyncSafe("ffmpeg", ["-hide_banner", "-encoders"]);
+  const encoders = runSync(ffmpegBin, ["-hide_banner", "-encoders"]);
   if (encoders.error || encoders.status !== 0) {
     return { available: false, reason: "ffmpeg -encoders を取得できません" };
   }
@@ -87,6 +116,16 @@ function checkAvailability() {
     return { available: false, reason: "ffmpeg に libvpx-vp9 エンコーダがありません" };
   }
 
+  if (platform === "win32") {
+    const model = resolveModel(DEFAULT_RVM_MODEL);
+    if (model.missing) {
+      return {
+        available: false,
+        reason: `RVM model is not installed: ${model.path}. ${model.fetchHint}`,
+      };
+    }
+  }
+
   return { available: true };
 }
 
@@ -99,6 +138,8 @@ function parseArguments(argv) {
     fps: DEFAULT_FPS,
     decodeWidth: DEFAULT_DECODE_WIDTH,
     helperBin: defaultHelperBin,
+    model: DEFAULT_RVM_MODEL,
+    modelExplicit: false,
   };
   for (let index = 0; index < argv.length; index += 1) {
     const argument = argv[index];
@@ -122,6 +163,10 @@ function parseArguments(argv) {
       case "--quality":
         result.quality = value;
         break;
+      case "--model":
+        result.model = value;
+        result.modelExplicit = true;
+        break;
       case "--fps":
         result.fps = Number(value);
         break;
@@ -135,6 +180,12 @@ function parseArguments(argv) {
   if (!QUALITIES.includes(result.quality)) {
     throw new Error(`--quality は ${QUALITIES.join(" / ")} のいずれかです`);
   }
+  if (!RVM_MODELS.includes(result.model)) {
+    throw new Error(`--model は ${RVM_MODELS.join(" / ")} のいずれかです`);
+  }
+  if (result.modelExplicit && result.quality !== "best") {
+    throw new Error("--model は --quality best のときだけ指定できます");
+  }
   if (!Number.isFinite(result.fps) || result.fps <= 0 || result.fps > 240) {
     throw new Error("--fps は 0 より大きく 240 以下の数値です");
   }
@@ -166,8 +217,31 @@ function buildHelper(helperBin) {
   return null;
 }
 
-function ffprobeJson(args) {
-  const result = spawnSyncSafe("ffprobe", ["-v", "error", ...args, "-of", "json"]);
+function engineForPlatform(quality, platform = os.platform()) {
+  return platform === "win32" || quality === "best" ? "rvm" : "vision";
+}
+
+function prepareExecution(options, {
+  platform = os.platform(),
+  resolveModel = resolveRvmModel,
+  buildVisionHelper = buildHelper,
+} = {}) {
+  const engine = engineForPlatform(options.quality, platform);
+  if (engine === "rvm") {
+    const resolved = resolveModel(options.model);
+    if (resolved.missing) {
+      throw new Error(`RVM model is not installed: ${resolved.path}. ${resolved.fetchHint}`);
+    }
+    return { ...options, engine, modelPath: resolved.path };
+  }
+
+  const buildError = buildVisionHelper(options.helperBin);
+  if (buildError) throw new Error(`swiftc build failed: ${buildError}`);
+  return { ...options, engine };
+}
+
+function ffprobeJson(args, ffprobeBin = resolveFfprobe()) {
+  const result = spawnSyncSafe(ffprobeBin, ["-v", "error", ...args, "-of", "json"]);
   if (result.error || result.status !== 0) {
     throw new Error(summarize(result.stderr, "ffprobe に失敗しました"));
   }
@@ -179,14 +253,14 @@ function ffprobeJson(args) {
 }
 
 /// 素材の表示上の寸法（回転を反映した幅・高さ）と尺を得る。
-function probeSource(input) {
+function probeSource(input, ffprobeBin) {
   const probed = ffprobeJson([
     "-select_streams",
     "v:0",
     "-show_entries",
     "stream=width,height,r_frame_rate,duration:stream_side_data=rotation:format=duration",
     input,
-  ]);
+  ], ffprobeBin);
   const stream = probed?.streams?.[0];
   if (!stream) throw new Error("映像ストリームが見つかりません");
   const width = Number(stream.width);
@@ -230,7 +304,9 @@ function stage(name, command, args, stdio) {
 }
 
 async function generate(options) {
-  const source = probeSource(options.input);
+  const ffmpegBin = resolveFfmpeg();
+  const ffprobeBin = resolveFfprobe();
+  const source = probeSource(options.input, ffprobeBin);
   const size = outputSize(source, options.decodeWidth);
   const metricsPath = path.join(
     os.tmpdir(),
@@ -240,7 +316,7 @@ async function generate(options) {
 
   const decoder = stage(
     "decode",
-    "ffmpeg",
+    ffmpegBin,
     [
       "-hide_banner", "-nostdin", "-loglevel", "error",
       "-i", options.input,
@@ -251,20 +327,34 @@ async function generate(options) {
     ],
     ["ignore", "pipe", "pipe"],
   );
-  const helper = stage(
-    "segment",
-    options.helperBin,
-    [
-      "--width", String(size.width),
-      "--height", String(size.height),
-      "--quality", options.quality,
-      "--metrics", metricsPath,
-    ],
-    ["pipe", "pipe", "pipe"],
-  );
+  const helper = options.engine === "rvm"
+    ? stage(
+      "segment",
+      process.execPath,
+      [
+        rvmHelper,
+        "--width", String(size.width),
+        "--height", String(size.height),
+        "--model", options.modelPath,
+        "--metrics", metricsPath,
+        "--total-frames", String(source.duration ? Math.round(source.duration * options.fps) : 0),
+      ],
+      ["pipe", "pipe", "pipe"],
+    )
+    : stage(
+      "segment",
+      options.helperBin,
+      [
+        "--width", String(size.width),
+        "--height", String(size.height),
+        "--quality", options.quality,
+        "--metrics", metricsPath,
+      ],
+      ["pipe", "pipe", "pipe"],
+    );
   const encoder = stage(
     "encode",
-    "ffmpeg",
+    ffmpegBin,
     [
       "-hide_banner", "-loglevel", "error",
       "-f", "rawvideo", "-pix_fmt", "bgra",
@@ -289,6 +379,9 @@ async function generate(options) {
   }
   decoder.child.stdout?.pipe(helper.child.stdin);
   helper.child.stdout?.pipe(encoder.child.stdin);
+  if (options.engine === "rvm") {
+    helper.child.stderr?.on("data", (chunk) => process.stderr.write(chunk));
+  }
 
   const startedAt = Date.now();
   const results = await Promise.all([decoder.exited, helper.exited, encoder.exited]);
@@ -317,17 +410,20 @@ async function generate(options) {
     throw new Error("フレームを 1 枚も処理していません");
   }
 
-  const verified = verifyOutput(options.out);
+  const verified = verifyOutput(options.out, ffprobeBin);
+  const engine = options.engine;
   return {
     ok: true,
     path: options.out,
+    engine,
+    ...(engine === "rvm" ? { model: options.model } : {}),
     // analysis.json へ貼る形。path は analysis.json のディレクトリ基準へ書き換えること。
     person_matte: {
       path: options.out,
       fps: options.fps,
       quality: options.quality,
       generated_at: new Date().toISOString(),
-      tool: TOOL_ID,
+      tool: engine === "rvm" ? RVM_TOOL_ID : TOOL_ID,
     },
     source: { path: options.input, ...source },
     width: size.width,
@@ -336,7 +432,9 @@ async function generate(options) {
     bytes: fs.statSync(options.out).size,
     elapsed_seconds: elapsedSeconds,
     realtime_ratio: source.duration ? elapsedSeconds / source.duration : null,
-    vision_ms_per_frame: metrics.vision_ms_per_frame,
+    ...(engine === "rvm"
+      ? { rvm_ms_per_frame: metrics.ms_per_frame }
+      : { vision_ms_per_frame: metrics.vision_ms_per_frame }),
     mask_size: { width: metrics.mask_width, height: metrics.mask_height },
     alpha_transparent_ratio: metrics.alpha_transparent_ratio,
     alpha_partial_ratio: metrics.alpha_partial_ratio,
@@ -347,14 +445,14 @@ async function generate(options) {
 /// 書き出した WebM が本当に VP9 かつアルファ付きかを ffprobe で確かめる。
 /// ffmpeg 自身は VP9 の alpha レイヤをデコードできない（pix_fmt は yuv420p と報告される）ので、
 /// アルファの有無はコンテナの alpha_mode タグで判定する。
-function verifyOutput(out) {
+function verifyOutput(out, ffprobeBin) {
   const probed = ffprobeJson([
     "-select_streams",
     "v:0",
     "-show_entries",
     "stream=codec_name,width,height,r_frame_rate,nb_frames:stream_tags=alpha_mode:format=duration",
     out,
-  ]);
+  ], ffprobeBin);
   const stream = probed?.streams?.[0];
   if (!stream) throw new Error("書き出した WebM に映像ストリームがありません");
   if (stream.codec_name !== "vp9") {
@@ -385,9 +483,10 @@ async function main() {
     return;
   }
 
-  const availability = checkAvailability();
+  const platform = os.platform();
+  const availability = checkAvailability({ platform });
   if (options.check) {
-    printJson(availability);
+    printJson({ ...availability, rvm_model: resolveRvmModel(DEFAULT_RVM_MODEL) });
     return;
   }
   if (!options.input || !options.out) {
@@ -402,17 +501,33 @@ async function main() {
   }
 
   try {
-    const buildError = buildHelper(options.helperBin);
-    if (buildError) {
-      printJson({ ok: false, reason: `swiftc build failed: ${buildError}` });
-      process.exitCode = 1;
-      return;
-    }
-    printJson(await generate(options));
+    const prepared = prepareExecution(options, { platform });
+    printJson(await generate(prepared));
   } catch (error) {
     printJson({ ok: false, reason: summarize(error?.message, "人物マットの生成に失敗しました") });
     process.exitCode = 1;
   }
 }
 
-await main();
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule()) await main();
+
+export {
+  DEFAULT_DECODE_WIDTH,
+  DEFAULT_FPS,
+  DEFAULT_QUALITY,
+  QUALITIES,
+  RVM_MODELS,
+  checkAvailability,
+  engineForPlatform,
+  parseArguments,
+  prepareExecution,
+};

package/vendor/skills/analyze-footage/person-matte.md

@@ -5,7 +5,9 @@
 - [実行するかを先に決める](#実行するかを先に決める)
 - [道具を確認する](#道具を確認する)
 - [生成する](#生成する)
+- [カットへ自動配線する](#カットへ自動配線する)
 - [analysis.json へ書く](#analysisjson-へ書く)
+- [Windows 実機検証手順](#windows-実機検証手順)
 - [劣化](#劣化)
 
 ## 原則
@@ -37,6 +39,10 @@
 | `fast` | 当たり付け・「この素材で切り抜けるか」の事前判定のみ | マット 256x192。輪郭が階段状で**本番不可** |
 | `balanced`（既定） | **本番**（text-behind-person / 切り抜き） | マット 512x384・58 ms/frame・実用輪郭 |
 | `accurate` | 寄りカット・最終仕上げ | マット 2016x1512・135 ms/frame・peak 638 MB |
+| `best` | **髪の毛をくっきり残す必要があるときだけ** | RVM mobilenetv3。10 秒素材で約 1〜1.5 分待つ目安 |
+| `best --model resnet50` | 処理時間をさらに許容できる場合のこだわり指定 | RVM resnet50。既定の mobilenetv3 より大幅に遅い |
+
+Windows では全品質段が RVM mobilenetv3 になる。手順は [Windows 実機検証手順](#windows-実機検証手順) を参照する。
 
 `fast` の出力を本番の成果物として `analysis.json` に載せない。
 
@@ -46,9 +52,11 @@
 node bin/person-matte/person-matte.mjs --check
 ```
 
-`{"available":true}` 以外なら `reason` を報告し、マットを作らずに `null` のまま進む。macOS、
-`swiftc`、`ffmpeg`／`ffprobe`、ffmpeg の `libvpx-vp9` エンコーダのいずれかが欠けていれば作れない。
-ネットワークからツールを導入しない。Swift ヘルパーは初回実行時に `swiftc -O` で自動ビルドされ、
+`available:true` 以外なら `reason` を報告し、マットを作らずに `null` のまま進む。結果には既定の
+RVM モデルの配備状況を示す `rvm_model` も含まれる。Mac は `swiftc`、ffmpeg / ffprobe、ffmpeg の
+`libvpx-vp9` エンコーダを要求する。Windows は swiftc を要求せず、同じメディア道具に加えて RVM の
+mobilenetv3 モデルを要求する。ffmpeg / ffprobe は `packages/media-bin` の解決規則を使う。
+ネットワークからツールを導入しない。Mac の Swift ヘルパーは初回実行時に `swiftc -O` で自動ビルドされ、
 バイナリはコミットしない（[.gitignore](.gitignore) 参照）。
 
 ## 生成する
@@ -63,7 +71,9 @@ node bin/person-matte/person-matte.mjs \
 
 オプション（既定のままで良ければ渡さない）:
 
-- `--quality fast|balanced|accurate`（既定 `balanced`）
+- `--quality fast|balanced|accurate|best`（既定 `balanced`）
+- `--model mobilenetv3|resnet50`（`--quality best` のときだけ指定可、既定 `mobilenetv3`）。
+  `resnet50` は `cd packages/matte-rvm && node scripts/fetch-models.mjs --model resnet50` で明示取得する
 - `--fps <n>`（既定 24）。マット動画の fps。元素材と一致しなくてよい
 - `--decode-width <n>`（既定 1280）。Vision のマット解像度は quality だけで決まり入力解像度に
   依存しないため、通常は変更しない。素材が 1280 幅未満なら拡大せずその幅を使う
@@ -71,7 +81,8 @@ node bin/person-matte/person-matte.mjs \
 `--input` には**原本**を渡す。プロキシ（`proxy.mp4`）を渡してもよいが、その場合マットの RGB は
 720p の絵になる。原本と時刻対応が崩れた素材を入力にしない。
 
-成功時は 1 行の JSON が返る。`ok`、`frames`、`bytes`、`elapsed_seconds`、`vision_ms_per_frame`、
+成功時は 1 行の JSON が返る。`ok`、`frames`、`bytes`、`elapsed_seconds`、`engine`、
+Vision 時の `vision_ms_per_frame` または RVM 時の `rvm_ms_per_frame`、
 `alpha_transparent_ratio`（完全透明画素の割合）、`probe`（ffprobe の実測）を含む。
 ヘルパーは書き出した WebM が `codec_name = vp9` かつ `alpha_mode = 1` であることを確認してから
 成功を返すので、`ok: true` はアルファが落ちていないことを含意する。
@@ -79,6 +90,47 @@ node bin/person-matte/person-matte.mjs \
 `ok: false` なら `reason` を報告し、マットを諦めて `null` のまま分析を続ける。**マットが作れない
 ことを理由に分析全体を失敗扱いにしない。**
 
+## カットへ自動配線する
+
+使い分けは次のとおり。
+
+- 素材全体の解析結果として `analysis.json` の `tracks.person_matte` を作る場合は、上の
+  `person-matte.mjs` を使う。入力素材の時刻 0 とマットの時刻 0 を一致させる。
+- 編集済みの特定カットを人物レイヤーへ載せる場合は `person-cutout.mjs` を使う。カットの `in` /
+  `out` / `speed` を解決し、速度適用済みの区間マットを作って v2 `edit.json` へ自動配線する。
+
+```bash
+node skills/analyze-footage/bin/person-matte/person-cutout.mjs \
+  --project /path/to/project \
+  --cut 0
+```
+
+`--cut` は v2 `tracks` を下から上、各 `items` を宣言順に走査した visual media item の 0 始まり
+index で、`0,2,4` のように複数指定できる。自動生成済みの `person-N` item は数えない。
+`--quality fast|balanced|accurate|best`（既定 `balanced`）と、`best` の場合だけ
+`--model mobilenetv3|resnet50` を指定できる。
+
+生成物は `<project>/assets/matte/person-<cut index>.webm`。v2 は旧 `layers[]` と
+`timeline.tracks` を持たず、トップレベル `tracks[]` 自体が下→上の z 順の正本なので、コマンドは
+マットを `sources[]` に登録し、対応する media item を `person-cutout` visual track へ置く。この
+track は既存 track の相互順を変えず最前面へ移すため、HTML overlay やテロップより人物が上に来る。
+
+同じ cut へ再実行すると `person-cutout-N` source と `person-N` item を更新し、source / item / track
+を重複させない。`edit.json` は候補ファイルを v2 reader と `validate-edit.mjs` の両方で検証してから
+atomic rename し、不合格時は元ファイルを変更しない。
+
+変更内容だけを確認する場合は `--dry-run` を付ける。マットの生成、ディレクトリ作成、edit.json の
+書き換えを一切行わず、予定するマット・レイヤー互換表示・track 順を stdout の 1 行 JSON で返す。
+
+```bash
+node skills/analyze-footage/bin/person-matte/person-cutout.mjs \
+  --project /path/to/project \
+  --cut 1,3 \
+  --quality best \
+  --model resnet50 \
+  --dry-run
+```
+
 ## analysis.json へ書く
 
 返ってきた JSON の `person_matte` をそのまま使えるが、**`path` は analysis.json のディレクトリ
@@ -101,6 +153,84 @@ node bin/person-matte/person-matte.mjs \
 - `fps` が実際に書き出したマット動画の fps と一致する。
 - `path` を analysis.json の位置から解決でき、実ファイルが存在する。
 
+## Windows 実機検証手順
+
+Windows では `fast` / `balanced` / `accurate` / `best` の全段が RVM mobilenetv3 を使う。
+次の PowerShell コマンドは公開リポジトリのルートで実行する。Node.js 20 以上を前提とし、まず版を確認して
+`packages/matte-rvm` 内で依存と既定モデルを配備する。`npm install` の postinstall が
+mobilenetv3 を取得する。
+
+```powershell
+node --version
+cd packages\matte-rvm
+npm install
+cd ..\..
+```
+
+道具とモデルを検査する。
+
+```powershell
+node skills\analyze-footage\bin\person-matte\person-matte.mjs --check
+```
+
+期待する 1 行 JSON は次の形で、`available` が `true`、`rvm_model.missing` が `false` になる。
+
+```json
+{"available":true,"rvm_model":{"model":"mobilenetv3","path":"C:\\...\\rvm_mobilenetv3_fp32.onnx","missing":false,"fetchHint":"cd packages/matte-rvm && node scripts/fetch-models.mjs"}}
+```
+
+次に、人物が映る実素材 1 本を `C:\Users\owner\Videos\person-input.mp4` へ置き、`balanced` で生成する。
+出力先は必要に応じて書き換える。
+
+```powershell
+$SOURCE = "C:\Users\owner\Videos\person-input.mp4"
+$OUT = "C:\Users\owner\Videos\person-matte-balanced.webm"
+node skills\analyze-footage\bin\person-matte\person-matte.mjs --input "$SOURCE" --out "$OUT" --quality balanced
+```
+
+実際に返る 1 行 JSON から確認するキーの抜粋は次のとおりで、`ok:true`、`engine:"rvm"`、`model:"mobilenetv3"`、
+`probe.alpha_mode:"1"` を含む。`quality` は `person_matte.quality:"balanced"` として指定値のまま残る。
+
+```json
+{"ok":true,"engine":"rvm","model":"mobilenetv3","person_matte":{"path":"C:\\Users\\owner\\Videos\\person-matte-balanced.webm","fps":24,"quality":"balanced","tool":"rvm-person-matting"},"probe":{"codec_name":"vp9","alpha_mode":"1"}}
+```
+
+速度は `rvm_ms_per_frame`（RVM 推論 1 フレーム当たりのミリ秒）で読む。Mac の既存実測は
+**137〜271 ms/frame** なので、Windows の値を同じ単位で比較する。VP9 エンコードを含む全体時間では
+ないため、総所要時間は `elapsed_seconds` も併記する。
+
+実測記録欄:
+
+- Windows PC: CPU ______ / RAM ______ GB / GPU ______ / Windows ______
+- 素材: 解像度 ______ / fps ______ / 尺 ______ 秒
+- `rvm_ms_per_frame`: ______ ms/frame（Mac 137〜271 ms/frame と比較）
+- `elapsed_seconds`: ______ 秒
+
+つまずいた場合は `reason` を先に読む。
+
+- モデル不在: `rvm_model.missing:true` または reason 内の `fetchHint` を確認し、次のコマンドで
+  mobilenetv3 を取得してから再検査する。
+
+  ```powershell
+  cd packages\matte-rvm
+  node scripts\fetch-models.mjs
+  cd ..\..
+  node skills\analyze-footage\bin\person-matte\person-matte.mjs --check
+  ```
+
+- ffmpeg / ffprobe 不在: `packages/media-bin` の postinstall が同梱バイナリを配備するため、
+  次のコマンドで配備をやり直してから `--check` を再実行する。
+
+  ```powershell
+  cd packages\media-bin
+  npm install
+  cd ..\..
+  node skills\analyze-footage\bin\person-matte\person-matte.mjs --check
+  ```
+
+- `libvpx-vp9` 不在: 解決された ffmpeg が VP9 alpha を書けない。`reason` に従って media-bin の配備と
+  ffmpeg の解決元を確認する。
+
 ## 劣化
 
 道具が無い、生成に失敗した、または品質が実用に達しない場合は `tracks.person_matte` を `null` に