SCRYDOSBox-XReferenceCapturescapturesAlso in MAME

DOSBox-XCaptures

captures

List the files this session's tools wrote, each read again now: whether it is still there, its size, what it holds.

captures()

Try it

On Bricks, the game this repository builds, at the end of a session that saved pictures, a video, a sound file and a dump of memory.
Ask

List the files this session has written so far.

Call
captures()
Reply 1 of 3 fields
{
  "summary": "captures: 10 files"
}

The session wrote ten files. captures has a row for each, with its kind, its path and whether it is still there.

The whole reply
JSON
{
  "summary": "captures: 10 files",
  "status": "ok",
  "captures": [
    {"kind": "png", "path": "./tmp/demos/tour/files/wall.png", "present": true, "bytes": "<volatile>"},
    {
      "kind": "png",
      "path": "./tmp/demos/tour/files/palette.png",
      "present": true,
      "bytes": "<volatile>"
    },
    {"kind": "bin", "path": "./tmp/demos/tour/files/wall.bin", "present": true, "bytes": "<volatile>"},
    {
      "kind": "json",
      "path": "./tmp/demos/tour/files/session.json",
      "present": true,
      "bytes": "<volatile>"
    },
    {
      "kind": "trace",
      "path": "./tmp/demos/tour/files/captures/trace-1.trace",
      "present": true,
      "bytes": "<volatile>"
    },
    {
      "kind": "avi",
      "path": "./tmp/demos/tour/files/second-brick.avi",
      "present": true,
      "bytes": "<volatile>",
      "riff_avi": true,
      "avi_frames": 109,
      "complete": true
    },
    "... 4 more"
  ]
}

Arguments

Takes no argument.

What comes back

captures
One row per file: kind, path, present and bytes. A recording adds complete and what it holds, by kind.
All 1 reply fields
  • captures (array)

Why it works this way

Every file is read again when it has changed, so the list says what is on disk now, and it answers while the program runs. A file deleted since stays listed, with present: false and no bytes.

First come the files the session's tools wrote, in the order written. Then come the videos of a session started with capture_video, largest last; two is normal, since the recording restarts when the program changes video mode.

An AVI's complete: false is not damage: frames come out of such a file. For a WAV, a DRO or a MIDI file it is a header that disagrees with the file: one its writer has not closed, or a damaged one.

More on why
kind what the row adds
avi complete, riff_avi (it opens as an AVI), avi_frames
wav complete, samples, channels, sample_rate_hz
dro complete, opl_pairs, opl_ms
mid complete, midi_bytes

Any other row's kind is its file's extension, or series for a series.

start's program runs after the configuration's [autoexec] section, so an autoexec that ends in exit quits the emulator first. A list with no avi row is the sign.

The contract your client receives
Text
Lists the files the session's tools wrote (`record` and `audio_record` among them), in
write order, re-read when changed, then the `capture_video` AVIs, largest last. Works on a
running guest.

Reply: `captures` (each `kind`, `path`, `present`, `bytes`; a recording also `complete`, and
an AVI `riff_avi`, `avi_frames`, a WAV `samples`, `channels`, `sample_rate_hz`, a DRO
`opl_pairs`, `opl_ms`, a MIDI file `midi_bytes`). A file gone has `present: false`, no
`bytes`.
Tools