SCRYDOSBox-XReferenceCapturescapture_frame
capture_frame
Extract one frame of a video the session recorded to a PNG file.
capture_frame(frame, dest, capture_path="")
Try it
record example filmed 110 frames in which a brick falls.Take frame 104 out of the video second-brick.avi and save it as brick-gone.png.
capture_frame(frame=104, capture_path="./tmp/demos/tour/files/second-brick.avi",
dest="./tmp/demos/tour/files/brick-gone.png"){
"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
{
"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
recordwrote. Left empty, the largest video of a session started withcapture_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
- A
%anywhere indest, or adestthat exists (bad_argument). - No
capture_path, in a session not started withcapture_video(no_channel). - No
capture_path, in a session whose video is not written yet (unexpected_answer). - A frame past the end of the video, or a computer with no
ffmpegon itsPATH(host_failed).
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.
Related tools
The contract your client receives
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`.