SCRYDOSBox-XReferenceCapturesseries_captureAlso in MAME
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
record example filmed 110 frames in which a brick falls.Save frames 95 to 108 of the video second-brick.avi as a series in a folder named series.
series_capture(first=95, last=108, capture_path="./tmp/demos/tour/files/second-brick.avi",
dest="./tmp/demos/tour/files/series"){
"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
{
"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
firstandlast, 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 fromfirst. 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 outlivesclose. Left empty, a folder in the session's temporary folder, deleted atclose. - capture_path string, default
"" - The video to take the frames from, such as one
recordwrote. Left empty, the largest video of a session started withcapture_video.
What comes back
- manifest
- The path of the series' manifest,
manifest.json; the PNGs sit beside it, named by frame asf000123.png. - count
- How many frames were written;
firstandlastare their lowest and highest numbers. - distinct
- How many different pictures the series holds. One means nothing changed on screen.
- kept_after_close
truewhen the series is in adestyou named,falsewhenclosedeletes 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
- Both
at_framesand a range, or neither; a list that is not ascending; more than 1000 frames (bad_argument). - A frame past the end of the video (
bad_argument). - A
cropthat leaves the frame, or adestthat exists or holds a%(bad_argument). - No
capture_path, in a session not started withcapture_video(no_channel). - No
capture_path, in a session whose video is not written yet (unexpected_answer). - A computer with no
ffmpegon itsPATH(host_failed).
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.
Related tools
The contract your client receives
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.