SCRYDOSBox-XReferenceCapturesrecordAlso in MAME

DOSBox-XCaptures

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 Bricks, the game this repository builds, stopped in play at frame 36, shortly before the ball knocks down its second brick.
Ask

Record the next 110 frames of the screen to a video named second-brick.avi.

Call
record(frames=110, dest="./tmp/demos/tour/files/second-brick.avi", seconds=60)
Reply 9 of 25 fields
{
  "summary": "record 110 frames: ELAPSED, 109 frames at ./tmp/demos/tour/files/second-brick.avi",
  "verdict": "ELAPSED",
  "frame_before": 36,
  "frame_after": 146,
  "kind": "avi",
  "frames": 110,
  "began": true,
  "ended": true,
  "avi_frames": 109
}

ELAPSED means the 110 frames ran, from frame 36 to 146, and the capture was turned off (ended). The file holds 109 frames: the first frame of this run wrote none.

The whole reply
JSON
{
  "summary": "record 110 frames: ELAPSED, 109 frames at ./tmp/demos/tour/files/second-brick.avi",
  "status": "ok",
  "verdict": "ELAPSED",
  "polls": 110,
  "pc": "<volatile>",
  "cpu_mode": "real",
  "frame": 146,
  "regs": "<volatile>",
  "watches": [
    {
      "ref": "ball_x",
      "by": "symbol",
      "mode": "show",
      "length": 8,
      "fmt": "{x:i16,y:i16,dx:i16,dy:i16}",
      "state": "evaluated",
      "value": {"x": 182, "y": 88, "dx": -2, "dy": 2},
      "bytes": "<volatile>"
    },
    {
      "ref": "score",
      "by": "symbol",
      "mode": "count",
      "length": 2,
      "fmt": "u16",
      "tally_id": "1",
      "addr": "08DF:00000615",
      "installed": true,
      "state": "tallied",
      "total": 1,
      "since_last_stop": 1,
      "overflow_values": 0,
      "overflow_pcs": 0
    },
    {
      "ref": "paddle_x",
      "by": "symbol",
      "mode": "capture",
      "length": 1,
      "fmt": "u8",
      "tally_id": "2",
      "addr": "08DF:0000061F",
      "trigger_type": "r",
      "installed": true,
      "state": "captured",
      "total": 110,
      "since_last_stop": 110,
      "rows_path": "<volatile>",
      "rows_kept": 110,
      "overflow_rows": 0,
      "rows_max": 100000
    }
  ],
  "cause": "<volatile>",
  "e9": {"lines_total": 1, "truncated": false, "lines": ["Bochs port E9h: HIT 5 6"], "mark": "<volatile>"},
  "stop_seq": 8,
  "instruction": "<volatile>",
  "emulated_before_s": "<volatile>",
  "emulated_after_s": "<volatile>",
  "frame_before": 36,
  "frame_after": 146,
  "cycles": 3595712,
  "kind": "avi",
  "frames": 110,
  "began": true,
  "ended": true,
  "path": "./tmp/demos/tour/files/second-brick.avi",
  "bytes": "<volatile>",
  "avi_frames": 109
}

Arguments

frames integer, required
How many frames of the emulated display 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 capture is turned off. false when it could not be: there is no path, and it records until close.
verdict
How the run ended, as run_for reports it: ELAPSED when every frame ran, TIMEOUT when seconds ran out first.
All 26 reply fields
  • cause (string)
  • regpoint_hit (object)
  • cpu_mode (string or object)
  • cycles (integer or object)
  • e9 (object)
  • emulated_after_s (number or object)
  • emulated_before_s (number)
  • enrichment (object)
  • frame (integer or object)
  • frame_after (integer or object)
  • frame_before (integer or object)
  • instruction (DosboxInstruction)
  • pc (string or object)
  • polls (integer)
  • regs (object)
  • retrace_pending (boolean)
  • stop_seq (integer)
  • verdict (string)
  • watches (array)
  • avi_frames (integer)
  • began (boolean)
  • bytes (integer)
  • ended (boolean)
  • frames (integer)
  • kind (string)
  • path (string or object)

What it refuses

Why it works this way

The recording is counted in frames of the emulated display, one per vertical retrace, so no time of your clock goes into the file. The debugger's CAPTURE command turns the video on at this stop and off at the stop the run reaches.

No window or menu is involved, so a session with no window records as one with a window does. A video already on is refused, never ended by a second switch.

One frame is written per frame run, but a run can write none for its first. The run from the stop start leaves is one: the display has drawn nothing yet.

More on why

The capture is turned off whatever the run did, a cancelled call included. One that could not be turned off answers ended: false.

The reply is also a stop: it carries verdict and the fields run_for returns, with the readings taken at each stop.

The contract your client receives
Text
Record exactly `frames` retraces of the screen to an AVI, then stop. Needs the machine
STOPPED and a build whose debugger has `CAPTURE`; headless or windowed.

`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.

One frame is written per retrace, but none for the first from the stop `start` leaves.
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 capture that could not be turned off is `ended: false`, no `path`, and
records until `close`.

Refused: `frames` under 2, a video capture already on (`capture_video`), a build with no
`CAPTURE`, a running machine.

Reply, once answered: `verdict`, `frames`, `path`, `began`, `ended`, `bytes`, `avi_frames`, `kind`, `note`, the run's fields as `run_for` gives
them, the stop: `pc` (`SSSS:OOOOOOOO`), `cpu_mode`, `stop_seq`, `frame`, `instruction`, `regs`, `watches`, `cause`, `regpoint_hit` (a registerpoint stopped it) and `e9`.

Reference: REFERENCE.md, Input and the screen.
Tools