SCRYMAMEReferenceCapturesrecordAlso in DOSBox-X
record
Record an exact number of frames of the screen to an AVI video, then stop the program again.
record(frames, dest="", seconds=60.0)
Try it
Record the next 30 frames of the screen to a video named card.avi.
record(frames=30, dest="./tmp/demos/tour/card.avi", seconds=300){
"summary": "record: 30 frames, 5659194 bytes at ./tmp/demos/tour/card.avi",
"verdict": "ELAPSED",
"frame_begin": 562,
"frame_end": 591,
"began": true,
"ended": true,
"avi_frames": 30,
"view": "native"
}The video holds 30 frames, 562 to 591, and the recording is closed (ended). ELAPSED means every frame ran, and native is the MAME view the video was drawn through.
The whole reply
{
"summary": "record: 30 frames, 5659194 bytes at ./tmp/demos/tour/card.avi",
"status": "ok",
"verdict": "ELAPSED",
"frame_before": 561,
"frame_after": 594,
"emulated_before_s": 9.495573,
"emulated_after_s": 10.053138,
"cycles": 696956,
"polls": 33,
"lines_ahead": 0,
"thread_errors": 0,
"console_reruns": 0,
"path": "./tmp/demos/tour/card.avi",
"frames": 30,
"began": true,
"frame_begin": 562,
"recording_after": true,
"ended": true,
"bytes": 5659194,
"avi_frames": 30,
"frame_end": 591,
"cause": "the `gvblank` stop of the last frame asked",
"stop_seq": 57,
"pc": "0x0000fd80",
"cpu": ":maincpu",
"frame": 594,
"regs": {
"A": "0x00",
"B": "0xfc",
"D": "0x00fc",
"X": "0x0014",
"Y": "0xf2e6",
"U": "0x4071",
"PC": "0xfd80",
"S": "0x07f4",
"CC": "0xd4",
"DP": "0x00"
},
"instruction": {"address": "FD80", "bytes": "0CB2", "text": "INC <$B2", "symbol": "irq", "delta": 0},
"following": ["FD82: 96 B2 LDA <$B2", "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", "... 9 more"],
"errorlog": "<volatile>",
"view": "native"
}Arguments
- frames integer, required
- How many emulated frames to record: 2 or more.
- dest string, default
"" - An absolute
.avipath that does not exist yet. Left empty, the file goes to the session's temporary folder, deleted atclose. - seconds number (> 0, <= 600.0), default
60.0 - The time limit of the whole call, in seconds of your clock. Left out, 60.
What comes back
- path
- The AVI, once the reply has read it back as a finished file.
- avi_frames
- How many frames the file's own header says it holds.
- ended
trueonce the recording is closed.falsewhen a stop cut the run short: it stays open until the machine reachesframe_end_planned.- began
falsewhen a stop came before the first frame: the recording begins atframe_begin_planned.- verdict
- How the run ended, as
run_forreports it:ELAPSEDwhen every frame ran,TIMEOUTwhensecondsran out first. - view
- The MAME view the video was drawn through, chosen at
start.
All 40 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)ended(boolean)frame_after(integer)frame_before(integer)frame_begin(integer or object)frame_begin_planned(integer)frame_end(integer)frame_end_planned(integer)frames(integer)instructions_completed(integer)lines_ahead(integer)mode(string)path(string)pending(boolean)polls(integer)reader_steps(integer)recording_after(boolean or object)regpoint_hit(object)avi_frames(integer or object)began(boolean)bytes(integer or object)cycles(integer or object)drain_steps(integer)tagged_lines(array)verdict(string)view(string or object)watch_hit(object)
What it refuses
framesunder 2, or adestthat is not a new.avipath (bad_argument).- A machine that is running (
not_stopped). - A machine with no screen or no frame counter (
no_channel). - A file that does not read back as a finished AVI with frames in it (
readback_refused). - A script that answered and logged no mark, not even the line it writes as it is evaluated (
readback_refused). - A script MAME's console ran twice, which begins two recordings on one file (
console_rerun). - A run that did not come to a stop within
secondsand could not be ended (not_settled).
Why it works this way
The recording is counted in emulated frames, so no time of your clock goes into the file. A script inside MAME begins and ends it as frames are drawn, and it cannot end a recording on the frame that begins it: one frame is refused.
A stop that is not the time limit, such as a breakpoint, cuts the run short and leaves the recording open or not begun. It goes on when the machine reaches the planned frame, unless the next record call cancels it.
When seconds runs out first, the recording is closed there and the reply reads the file back: ended: true, with the frames it ran.
More on why
Lines already waiting in MAME's console are run before the script is sent, one instruction each, so the frames asked for are the recording's own.
The reply is also a stop: it carries verdict and the fields run_for returns, with the readings taken at each stop. frame_before and frame_after say how far the machine moved.
A reply with pending: true means the console had not run the script when the call ended, so nothing is known about the recording yet.
- The script proves each step by a mark in MAME's
error.log, carrying this call's own number, so a stale mark is never taken for a later call's. - A frame notifier that fails leaves no mark, so the reply says
began: falseorended: false, never a finished empty file. frame_begin_plannedis predicted from the frame counter as the script is evaluated, one frame later inside a vertical blank.- A refusal after the run began says how far the machine moved, in
frame_beforeandframe_after. - A
not_settledrun leaves out the recording's fields, and its message says whether the frame notifier may still be armed.
Related tools
The contract your client receives
Record exactly `frames` emulated frames of the screen to an AVI, then stop.
Needs the machine STOPPED (else `not_stopped`).
`dest`: an absolute `.avi` path not there yet; empty lands in the session's scratch, gone at `close`, and the reply names it either way. `frames` is 2 or more. `seconds` bounds the wait for the recording. The AVI is read before its path is given.
A run cut at that bound is released before the reply: when the release answers, the reply says `ended: true` and names the AVI it read back, and a file that does not read as finished is INVALID. A release that does not answer leaves the run's own refusal. A stop that is
not the bound leaves the recording open (`ended: false`) until the machine reaches its last
frame.
Reply, once answered: `verdict`, `frames`, `path`, `began`, `ended`, `bytes`, `avi_frames`, `view`, `note`, the stop survey. Without an answer, `pending`.
Reference: REFERENCE.md, Input and the screen.