SCRYMAMEReferenceCapturesseries_captureAlso in DOSBox-X
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="", seconds=60.0)
Try it
Keep every eighth frame from 557 to 581 as pictures in a folder named series.
series_capture(first=557, last=581, step=8, dest="./tmp/demos/tour/series", seconds=300){
"summary": "series_capture: 4 frames 557..581, 3 distinct, manifest ./tm ... (93 characters)",
"verdict": "ELAPSED",
"frame_before": 553,
"frame_after": 583,
"count": 4,
"distinct": 3,
"lost": [],
"kept_after_close": true
}Four frames between 557 and 581 were kept, three of them different pictures, and none was lost. ELAPSED means the run reached its end: the machine went from frame 553 to 583.
The whole reply
{
"summary": "series_capture: 4 frames 557..581, 3 distinct, manifest ./tmp/demos/tour/series/manifest.json",
"status": "ok",
"verdict": "ELAPSED",
"frame_before": 553,
"frame_after": 583,
"emulated_before_s": 9.3604,
"emulated_after_s": 9.86728,
"cycles": 633600,
"polls": 31,
"cause": "series_capture: one step",
"stop_seq": 24,
"pc": "0x0000fd82",
"cpu": ":maincpu",
"frame": 583,
"regs": {
"A": "0x01",
"B": "0x10",
"D": "0x0110",
"X": "0x0014",
"Y": "0xf2e6",
"U": "0x4071",
"PC": "0xfd82",
"S": "0x07f4",
"CC": "0xd0",
"DP": "0x00"
},
"instruction": {"address": "FD82", "bytes": "96B2", "text": "LDA <$B2", "symbol": "irq", "delta": 2},
"following": ["FD84: 84 03 ANDA #$03", "FD86: 26 04 BNE $FD8C", "FD88: 0C B3 INC <$B3", "FD8A: 0C B4 INC <$B4", "FD8C: B6 03 BE LDA $03BE", "FD8F: 26 28 BNE $FDB9", "... 9 more"],
"errorlog": "<volatile>",
"manifest": "./tmp/demos/tour/series/manifest.json",
"count": 4,
"first": 557,
"last": 581,
"distinct": 3,
"crop": [0, 0, 256, 240],
"lost": [],
"frames_asked": 4,
"kept_after_close": true,
"frame_source": "frame_number",
"thread_errors": 0,
"console_reruns": 0
}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. - seconds number (> 0, <= 600.0), default
60.0 - The time limit of the run, in seconds of your clock. Left out, 60.
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.- lost
- Frames asked for that the emulator skipped drawing, as
[first, last]ranges. They have no picture and are left out. - verdict
- How the run ended, as
run_forreports it:ELAPSEDwhen every frame ran.
All 29 reply fields
console_reruns(integer)cpu(string)following(array of string)instruction(StopInstruction)errorlog(object)frame(integer)pc(string)regs(object)resent(integer)stop_seq(integer)thread_errors(integer)watches(array)emulated_after_s(number or object)emulated_before_s(number or object)count(integer)crop(array)cycles(integer)distinct(integer)first(integer)frame_after(integer)frame_before(integer)frame_source(string)frames_asked(integer)kept_after_close(boolean)last(integer)lost(array)manifest(string)polls(integer)verdict(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 that is not ahead of the frame the machine is at (
bad_argument). - A
cropthat leaves the screen, or adestthat exists (bad_argument). - An
at_frameslist too long for one console line: givefirst,lastandstep(bad_argument). - A run another stop ends before the last frame is read: no series is written from part of one (
cut_by_other_stop). - A run in which every frame asked for was skipped (
no_progress). - A machine with no screen (
no_channel), or one that is running (not_stopped).
Why it works this way
Frame numbers are the emulated frame counter, the one run_for(frames=) counts, and every frame asked for must still be ahead. The call runs the program to two frames past the last one and stops there.
Each picture is MAME's own rendering of its frame, in the colours the palette held at the frame's end, read one frame later. A frame the emulator skipped drawing is listed in lost, never filled in.
A series frame is always an RGB PNG, because a series is for comparing what the screen showed. gfx_film may write the same frame as an indexed PNG, so their checksums never match: compare the two with image_compare(method="image").
More on why
The reply is also a stop: it carries verdict and the fields run_for returns, with the readings taken at each stop.
frames_asked is how many frames the call named, and frame_source says what the numbers count: frame_number, the emulated frame counter.
Related tools
The contract your client receives
Screen frames kept inside MAME as PNGs and a manifest, for `image_compare`. Stops two frames
past the last.
Frames by `run_for`'s counter, all ahead: `at_frames` or `first`, `last`, `step`, at most
1000. `crop` is `[x, y, width, height]`. `dest`: a new absolute or `~`-led
directory, kept after `close`. Needs a stopped machine; `seconds` bounds the read.
Reply: `manifest`, `count`, `first`, `last`, `crop`, `distinct`, `lost`, `kept_after_close`,
`run_for`'s fields. Refused: `bad_argument`, `cut_by_other_stop`.
Reference: REFERENCE.md, Media files.