SCRYDOSBox-XReferenceCapturesseries_captureAlso in MAME

DOSBox-XCaptures

series_capture

Save chosen frames of the screen as PNGs beside a manifest, for image_compare to read.

series_capture(at_frames=null, first=null, last=null, step=1, crop=null, dest="", capture_path="")

Try it

On Bricks, the game this repository builds, after the record example filmed 110 frames in which a brick falls.
Ask

Save frames 95 to 108 of the video second-brick.avi as a series in a folder named series.

Call
series_capture(first=95, last=108, capture_path="./tmp/demos/tour/files/second-brick.avi",
    dest="./tmp/demos/tour/files/series")
Reply 8 of 12 fields
{
  "summary": "series_capture: 14 AVI frames 95..108, 14 distinct, manifest ... (104 characters)",
  "count": 14,
  "first": 95,
  "last": 108,
  "distinct": 14,
  "kept_after_close": true,
  "frame_source": "avi",
  "crop": [0, 0, 640, 400]
}

Fourteen frames of the video were written, all different pictures (distinct). frame_source avi says the numbers are the video's own, and crop that each PNG is the whole 640x400 frame.

The whole reply
JSON
{
  "summary": "series_capture: 14 AVI frames 95..108, 14 distinct, manifest ./tmp/demos/tour/files/series/manifest.json",
  "status": "ok",
  "manifest": "./tmp/demos/tour/files/series/manifest.json",
  "count": 14,
  "first": 95,
  "last": 108,
  "distinct": 14,
  "frames_asked": 14,
  "kept_after_close": true,
  "frame_source": "avi",
  "capture_path": "./tmp/demos/tour/files/second-brick.avi",
  "crop": [0, 0, 640, 400]
}

Arguments

at_frames array of integer, optional
The frames to keep, as an ascending list of frame numbers. Give this or first and last, never both.
first integer, optional
The first frame of an evenly spaced range, given with last.
last integer, optional
The last frame of the range. A series holds at most 1000 frames.
step integer, default 1
The spacing of the range: every step-th frame from first. Left out, 1.
crop array of integer, optional
The rectangle of the screen each PNG holds, [x, y, width, height]. Left out, the whole screen.
dest string, default ""
A new folder for the series, absolute or starting with ~, which outlives close. Left empty, a folder in the session's temporary folder, deleted at close.
capture_path string, default ""
The video to take the frames from, such as one record wrote. Left empty, the largest video of a session started with capture_video.

What comes back

manifest
The path of the series' manifest, manifest.json; the PNGs sit beside it, named by frame as f000123.png.
count
How many frames were written; first and last are their lowest and highest numbers.
distinct
How many different pictures the series holds. One means nothing changed on screen.
kept_after_close
true when the series is in a dest you named, false when close deletes it.
capture_path
The video the frames came from.
All 10 reply fields
  • capture_path (string)
  • count (integer)
  • crop (array)
  • distinct (integer)
  • first (integer)
  • frame_source (string)
  • frames_asked (integer)
  • kept_after_close (boolean)
  • last (integer)
  • manifest (string)

What it refuses

Why it works this way

The frames come out of a video, so their numbers are the video's own, from 0 at its first frame. They are not the frames a stop's frame field counts since power-on.

The call reads a file and does not run the machine, so it answers while the program runs. A session started with capture_video can hold several videos: captures lists them, and capture_path picks one.

A % in dest is refused because ffmpeg would read the path as a numbering pattern and write somewhere else.

More on why

A video's frames are the size the emulator draws them: a 320x200 mode comes out 640x400, and a crop counts those pixels.

frames_asked is how many frames the call named, and frame_source says what the numbers count: avi, the video's own frames.

The contract your client receives
Text
Capture frames as PNGs plus a manifest (read by `image_compare`).

AVI frames from 0: `at_frames`, or `first`, `last`, `step`; max 1000. `crop`:
`[x, y, w, h]`. `dest`: new directory, kept after `close`.

Reply: `manifest`, `count`, `first`, `last`, `distinct`, `kept_after_close`, `capture_path`,
`crop`. Refused: `bad_argument` (frame, crop, `dest`), `no_channel` (no `capture_video`),
`unexpected_answer` (no capture), `host_failed` (no `ffmpeg`).

Reference: REFERENCE.md, Media files.
Tools