Note: If you want to use a screenRecorder element, usually the easiest way is to use the recordElements command. Type help recordElements at the MATLAB command line for more information.
A screenRecorder element records/captures another element display, or more generally the experiment window. It can capture to a single image file, a series of multiple image files at some frame rate, or record to a movie file. You can specify the size of the capture area.
Images are captured exactly as displayed on screen (or more specifically as drawn to the window's draw buffer). Note if you capture a series of images, the duration of capture is limited by your system's memory since all the images are stored in memory during the trial and image files only written in the inter-trial interval after. Also since writing image files is relatively slow, the inter-trial interval can extend to be quite long. Recording to a movie file doesn't have these limitations, but it has the tradeoff that most movie codecs apply image compression.
Psychtoolbox requires GStreamer for all display functionality on Windows, or for movie recording and other specific functionality on Mac. (On Linux it's generally pre-installed.) See here for the Psychtoolbox page on GStreamer, which contains important notes. Links to the version Psychtoolbox recommends as of PTB 3.0.19 (17 Feb 2023) are below:
Windows: GStreamer 64-bit MSVC runtime 1.20.5
Generally you can use properties start/end to set when capture starts and ends. However, if you capture a single image, the screen recorder ends on its own. Also if you target another element specifically then capture timing is more automated based on that element—see property elementExpr below.
If an element can end on its own, you don't need to set end conditions for it in property end (unless you want it to maybe end earlier).
No—runs until a condition you set in property end.
You can vary or allow the subject to adjust the following input properties of an object of this type in real time when it's running. If you need to make other properties adjustable, you can edit the element type code—see Element Type Programming Manual.
No default: fileName
Default: numberFile = automatically number files
Default: minNumDigitsInFileName = 1
The file extension can be any format MATLAB imwrite or Psychtoolbox CreateMovie understands (e.g. .png, .jpeg; .avi, .mov, etc.). It also determines the mode of recording: If it's an image file extension, the screen recorder captures a single image, then ends on its own. If it's a movie file extension, it records a movie. If you want to capture a series of images, add <cds>"..."<cds> to the file name, e.g. <cds>"mypic.png..."<cds>.
minNumDigitsInFileName sets the minimum number of digits to use for numbering files. e.g. 3 → image001.png, image002.png, image003.png, ...
Default: capture a general area in the experiment window, not a specific element
You can set this property to target another element running at the same time as the screen recorder. This is a string pointing to the target object. Specify it by variable name and possibly index you use in the experiment script, e.g. <cds>"picture"<cds>, <cds>"shapes(3)"<cds>, etc. Tip: If you have an index in a numeric variable you can use it in an <cds>"x"<cds> string (but not an <cds>'x'<cds> string) like this: <cds>"shapes("<cds><cd> + n + <cd><cds>")<cds>
If you set elementExpr then position and maybe size of the capture area is automated based on the target element—see size below for details. It also means that in all recording modes the screen recorder will wait to start recording when the target element starts showing its display and end on its own when the target element ends. You still need to set start to tell the screen recorder to run (this effectively sets the earliest that recording could start). And you can optionally set end if you want it to end before the target element.
Default: size = capture whole experiment window, or whole target element display if you set elementExpr above
Default: snapWidth = don't snap width to any number of pixels
You can set size to limit the size of the area to capture. This is a 1×2 vector [width height] (deg). If you don't set elementExpr above, the area is centered at screen recorder position. If you do set elementExpr, it's centered at target element position. In either case position can be set in property position of the respective element (default window center). Or default size = one number <cd>inf<cd> → capture whole window or whole target element display.
snapWidth (movie recording only): Some movie codecs require image width to be a multiple of 4 or 16 px. You can set snapWidth to a number (px), e.g. 4 or 16, to have the screen recorder round capture area width to a multiple of this number. (Useful since then you can set size in units of deg or leave it at default and not worry about what that converts to in px.)
Default: 30 frames/sec
Frame rate to capture multiple images or a movie at. Note actual frame rate achieved is limited by experiment frame rate during the element, which nominally = screen refresh rate but can be lower if frames are dropped—see Timing precision.
For movie recording only: A string that goes to input movieOptions of Psychtoolbox Screen('CreateMovie') setting advanced options. See help text there and help VideoRecording for usage.
PsychBench uses record properties to record information during experiments. You can't set record properties but you can see them in experiment results by listing them input property report.
fileName_r is a string recording the file name written to. This includes the number added if numberFile = <cd>true<cd> or capturing multiple images.
n_file records the number added (numeric) if numberFile = <cd>true<cd> or capturing multiple images.
For multiple image capture, these properties record information for the first image written by the screen recorder.