Pick Review Frame Indices for a Motion Reference in Node.js

A motion reference can look fine in its first frame and still change pose, framing, or visibility halfway through. When building a review tool, start by agreeing on which frames to inspect. A short, deterministic list makes it possible for two reviewers to talk about the same moment by index.

This Node.js example takes an existing frame count and a review budget. It outputs zero-based indices in presentation order. It works on a local JSON manifest and does not read, decode, or submit a video.

Decide what a frame index means

Treat the first frame as index 0. An 11-frame clip has indices 0 through 10, so the frame count is never itself a valid index.

Get the count from the same decoded frame sequence your reviewer will inspect. A count from one proxy and frame numbers from another can disagree. Avoid estimating the count by multiplying rounded duration by nominal frames per second.

Request two or more frames when comparing the beginning and end matters. With a budget of one, the function picks the lower middle index. When a clip has fewer frames than requested, it returns each available index once.

Divide the span into review intervals

For four selections there are three intervals. At each step, multiply the step number by the last index and divide by the interval count, discarding the fractional part. For last index 10, the four results are 0, 3, 6, and 10.

The first and last results land on the endpoints. Because the selection count is clamped to the frame count, the step between ideal positions is at least one, so flooring cannot repeat an index. The gaps can differ by one frame when the span does not divide evenly.

Use BigInt for the intermediate product. Even when the last index is a safe Number, multiplying it by a step number can exceed that range. Each final index is bounded by the original last index and can be converted back to Number. The 1,000-selection cap limits this example's output size.

Write the sampler

Save the following as pick-review-frames.mjs. Reject missing counts, fractions, and numeric strings so invalid manifest data does not silently change which frames are selected.

const MAX_REVIEW_FRAMES = 1000;

export function pickReviewFrames(frameCount, requested) {
  if (!Number.isSafeInteger(frameCount) || frameCount < 1) {
    throw new RangeError("frameCount must be a positive safe integer");
  }
  if (!Number.isSafeInteger(requested) ||
      requested < 1 || requested > MAX_REVIEW_FRAMES) {
    throw new RangeError("requested must be an integer from 1 to 1000");
  }

  const count = Math.min(frameCount, requested);
  const last = BigInt(frameCount - 1);
  if (count === 1) return [Number(last / 2n)];

  const intervals = BigInt(count - 1);
  return Array.from({ length: count }, (_, i) =>
    Number((BigInt(i) * last) / intervals)
  );
}

Run it on a local manifest

Save this entry point as review-frames.mjs beside the sampler. A valid plan goes to standard output. A read, parse, or validation failure goes to standard error and sets exit status 1.

import { readFile } from "node:fs/promises";
import { pickReviewFrames } from "./pick-review-frames.mjs";

try {
  const args = process.argv.slice(2);
  if (args.length !== 1) {
    throw new Error("Usage: node review-frames.mjs manifest.json");
  }
  const input = JSON.parse(await readFile(args[0], "utf8"));
  const { frameCount, requested } = input;
  console.log(JSON.stringify({
    frameCount,
    requested,
    frameIndices: pickReviewFrames(frameCount, requested)
  }));
} catch (error) {
  console.error(error.message);
  process.exitCode = 1;
}

Save this fixture as manifest.json. The values describe a hypothetical clip.

{"frameCount":11,"requested":4}

Run the following command from the same folder. The second line shows the expected output.

node review-frames.mjs manifest.json
# {"frameCount":11,"requested":4,"frameIndices":[0,3,6,10]}

Turn the list into a review

Use the returned indices to request stills from your own decoder or review tool, then label each still with the clip version and index. For a gesture reference, compare whether the subject remains in frame and whether the key limb positions are readable.

Uniform sampling can miss a fast turn or a brief occlusion. When the reviewer already knows the index of an important event, add it explicitly or inspect the neighboring frames. For variable frame rate footage, equal gaps in frame indices do not imply equal gaps in time; sample presentation timestamps if the review needs time-based spacing.

Test the edges before wiring this into a batch job: two frames with a request for four should return both indices, four frames with a request for one should return index 1, and a zero frame count should fail.

Sources and disclosure

Technical reference: ECMAScript BigInt division. Positive BigInt division truncates toward zero, which is the floor operation needed here.

Workflow background: PixMind’s guide to choosing a Kling route explains where driving clips fit. The frame selection policy in this article is a local review technique, with no provider API requirement or quality claim.

AI disclosure: AI assisted with drafting this article. The Node.js examples were checked on synthetic manifests. No frames were extracted, no media was generated, and no images are included.