{
  "schemaVersion": 1,
  "slug": "reference-trim-time-window",
  "locale": "en",
  "evidenceClass": "executed-local-fixture-not-provider-generation",
  "providerModelTest": false,
  "productionTaskRun": false,
  "runCommand": "node run-recipe.mjs --out ./my-run",
  "environment": {
    "nodeVersion": "v24.18.0",
    "ffmpeg": {
      "version": "ffmpeg version 6.0 Copyright (c) 2000-2023 the FFmpeg developers",
      "binarySha256": "a90e3db6a3fd35f6074b013f948b1aa45b31c6375489d39e572bea3f18336584"
    }
  },
  "title": "Trim a bounded reference-video time window and verify the kept frames",
  "description": "Trim 0.5–1.5 seconds from an original three-second clip, reject invalid windows and prove output frames match source indices 5–14 with reset timestamps.",
  "goal": "Create a one-second reference excerpt using explicit start-inclusive/end-exclusive boundaries. This recipe trims a continuous video segment; it does not choose a still frame by time base.",
  "preparation": [
    "Use Node.js plus FFmpeg and set FFMPEG_BIN if needed. The fixture builds a small 320×180, ten-FPS, three-second original reference clip.",
    "Read window.json: source duration is measured as 30 decoded frames at the fixture’s declared constant rate; selected start is 0.5 and end is 1.5 seconds.",
    "Choose a new output directory. Use the provided CFR fixture first; deriving the usable end of an arbitrary VFR or nonzero-start reference requires its own timestamp inventory."
  ],
  "steps": [
    {
      "title": "01. Establish the available source interval",
      "body": "Fully decode the original fixture and confirm thirty frames at ten FPS, establishing its three-second controlled interval. The raw construction buffer is temporary and removed in finally. Do not use this controlled CFR duration rule as an unqualified VFR duration estimator."
    },
    {
      "title": "02. Reject invalid boundaries before encoding",
      "body": "The local window validator requires finite numbers, start ≥ 0, end > start and end ≤ measured source duration. It executes separate negative cases for a negative start, equal boundaries, reversed boundaries, a past-end request and NaN."
    },
    {
      "title": "03. Trim and reset the output time origin",
      "body": "Apply trim=start=0.5:end=1.5,setpts=PTS-STARTPTS and re-encode the video. The trim filter keeps the continuous source interval, while setpts makes the excerpt start at zero. The end boundary excludes the source frame beginning at 1.5 seconds."
    },
    {
      "title": "04. Compare both endpoints and every output timestamp",
      "body": "Decode the result to ten frames and compare its first/last RGB frames against source indices 5 and 14. Parse actual showinfo output to verify PTS 0.0 through 0.9 in 0.1-second steps. The executed fixture measured zero endpoint channel difference."
    }
  ],
  "acceptance": [
    "The source actually decodes to thirty 320×180 frames at the controlled ten-FPS rate.",
    "The 0.5–1.5-second window passes the finite-number and interval rules.",
    "The excerpt decodes to exactly ten frames, corresponding to one second at ten FPS.",
    "First and last output frames match source indices 5 and 14 within four channel values; the recorded differences are zero.",
    "The observed output timestamps begin at zero and finish at 0.9 seconds.",
    "All five invalid-window cases are rejected and the eleven-check receipt retains actual showinfo evidence."
  ],
  "troubleshooting": [
    {
      "symptom": "The first timestamp is still 0.5 seconds.",
      "change": "Add or restore only setpts=PTS-STARTPTS after trim and reread the output showinfo timestamps."
    },
    {
      "symptom": "The excerpt includes a frame from 1.5 seconds.",
      "change": "Use the documented exclusive end boundary and check source index 14 as the final fixture frame; avoid increasing the requested end to compensate."
    },
    {
      "symptom": "The requested end lies beyond the reference.",
      "change": "Reduce only endSeconds to an established source boundary, or obtain the intended longer reference. Do not silently clamp an invalid request."
    }
  ],
  "ending": "Keep the requested window, measured source interval and decoded endpoint checks together. The small CFR fixture proves this trim operation and does not establish every real reference clip’s timestamp behaviour.",
  "assetCaption": "Original colour-varying reference video, actual one-second trimmed output and a unique interval diagram. No provider or model generation was run."
}