SCRYDOSBox-XReferenceCapturescapture_frame

DOSBox-XCaptures

capture_frame

Extract one frame of a video the session recorded to a PNG file.

capture_frame(frame, dest, capture_path="")

Try it

On Bricks, the game this repository builds, after the record example filmed 110 frames in which a brick falls.
Ask

Take frame 104 out of the video second-brick.avi and save it as brick-gone.png.

Call
capture_frame(frame=104, capture_path="./tmp/demos/tour/files/second-brick.avi",
    dest="./tmp/demos/tour/files/brick-gone.png")
Reply 3 of 7 fields
{
  "path": "./tmp/demos/tour/files/brick-gone.png",
  "capture_path": "./tmp/demos/tour/files/second-brick.avi",
  "frame": 104
}

Frame 104 of the video, counted from 0, is now a PNG at path.

The whole reply
JSON
{
  "summary": "<volatile>",
  "status": "ok",
  "path": "./tmp/demos/tour/files/brick-gone.png",
  "bytes": "<volatile>",
  "sha256": "<volatile>",
  "capture_path": "./tmp/demos/tour/files/second-brick.avi",
  "frame": 104
}

Arguments

frame integer, required
The frame to extract, counted from 0 at the video's first frame.
dest string, required
A new path for the PNG, absolute or starting with ~. The file is a PNG whatever its extension.
capture_path string, default ""
The video to take the frame from, such as one record wrote. Left empty, the largest video of a session started with capture_video.

What comes back

path
The PNG.
sha256
The file's SHA-256: the value a line of reference checksums holds for image_compare(method="golden").
capture_path
The video the frame came from.
All 5 reply fields
  • bytes (integer)
  • capture_path (string)
  • frame (integer)
  • path (string)
  • sha256 (string)

What it refuses

Why it works this way

The still is always a PNG, whatever dest is called. Choosing the format from the extension would let ffmpeg answer a frame past the end with an empty video file and no error.

A % anywhere in dest is refused before anything runs: ffmpeg reads the whole path as a numbering pattern, and the still is one file. Name that file, or take several frames with series_capture.

The frame shows what was displayed, in any video mode, because it comes out of a video. The call reads a file, so it answers while the program runs.

The contract your client receives
Text
Frame `frame` of a capture written to `dest` as PNG; `capture_path` defaults to the
largest. Needs `ffmpeg`, `capture_video`. Refused: `%` anywhere in `dest` (no numbering
pattern is expanded: name the one file), an existing `dest`, a frame past the end.

Reply: `path`, `bytes`, `sha256`, `capture_path`, `frame`.
Tools