SCRYMAMEReferenceCapturesrecordAlso in DOSBox-X

MAMECaptures

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

On Gridlee, a free ROM from mamedev.org, stopped on the card that announces a level, right after START is pressed with two credits.
Ask

Record the next 30 frames of the screen to a video named card.avi.

Call
record(frames=30, dest="./tmp/demos/tour/card.avi", seconds=300)
Reply 8 of 31 fields
{
  "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
JSON
{
  "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 .avi path that does not exist yet. Left empty, the file goes to the session's temporary folder, deleted at close.
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
true once the recording is closed. false when a stop cut the run short: it stays open until the machine reaches frame_end_planned.
began
false when a stop came before the first frame: the recording begins at frame_begin_planned.
verdict
How the run ended, as run_for reports it: ELAPSED when every frame ran, TIMEOUT when seconds ran 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

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: false or ended: false, never a finished empty file.
  • frame_begin_planned is 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_before and frame_after.
  • A not_settled run leaves out the recording's fields, and its message says whether the frame notifier may still be armed.
The contract your client receives
Text
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.
Tools