screenRecorder
elements
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.
GStreamer
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
▸ Ends on its own?
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.
Input properties
Adjustable properties
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.
position
nn_eyes
rotation
colorMask
alpha
intensity
contrastMult
(None)
(None)
fileName
numberFile
minNumDigitsInFileName
No default: fileName
Default: numberFile = automatically number files
Default: minNumDigitsInFileName = 1
fileName is a string setting name of image or movie file(s) to write. If you include a path, it will save there, and make the folder if it doesn't exist. If you don't, it will save in the MATLAB current folder.
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>.
numberFile = <cd>true<cd>/<cd>false<cd>: If = <cd>true<cd> (default), the screen recorder adds a number to file name starting at 1 and incrementing to not overwrite any existing files. This means if you have multiple screen recorder elements in an experiment, you can set fileName the same for all of them (e.g. image.png) and they will write different files numbered in the order they run (e.g. image1.png, image2.png, image3.png, ...). NOTE: If you set numberFile = <cd>false<cd> then the element will not add a number and will overwrite any existing file with the specified name. numberFile only affects single image and movie capture. For multiple image capture, the screen recorder always numbers the files.
minNumDigitsInFileName sets the minimum number of digits to use for numbering files. e.g. 3 → image001.png, image002.png, image003.png, ...
See also record properties fileName_r, n_file below.
elementExpr
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.
size
snapWidth
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.)
frameRate
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.
movieOptions
Default: none
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.
Input properties all visual elements have
Input properties all adjuster elements have
Input properties all objects have
Record properties
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
n_file
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.