If you just want to record an element display, often it's easiest to use the recordElements command outside an experiment. Type help recordElements at the MATLAB command line for more information. Generally screenRecorder elements are only needed if you want to record during an actual experiment, or maybe record multiple elements running simultaneously.

A screenRecorder element captures/records part or all of the experiment window, or optionally a target element display within the window. It can capture once to a single image file, or over a period of time to a series of image files or movie file. Screen recorder timing you set in properties start/end determines the limits of when capture can occur. Capture time can then be narrowed by settings such as capture mode (property fileName) and whether you target a specific element (property elementExpr)—see below.

Note at least if you record a series of images, duration of capture is limited by your system's memory since all the images are stored in memory during the trial and only written to files in the inter-trial interval after. Also since writing files is relatively slow, this can extend the inter-trial interval.

See also <PsychBench folder>/tools/images2movie if you want to render a movie file from image files you already have.

If an element will end automatically, you don't need to set an end time or condition in property end. However, you can if you want to add other end conditions that could occur earlier.

fileName
numberFile
minNumDigitsInFileName

No default: fileName
Default: numberFile = automatically number file/subfolder written
‍Default: minNumDigitsInFileName = 1

fileName is a string setting name (or name base—see below) for file(s) to write. If you include a path, it will write there. If you don't, it will write in the MATLAB current folder.

The file extension can be any format MATLAB imwrite or Psychtoolbox CreateMovie accepts (e.g. .png, .jpeg; .avi, .mov, etc.). It also determines the mode of capture: If an image file extension, the screen recorder captures a single image, then ends automatically. If a movie file extension, it records a movie. To capture a series of images, add <cds>...<cds> to an image file extension, e.g. <cds>"mypic.png..."<cds>—the screen recorder will then make a subfolder with name based on file name and write numbered image files there.

numberFile
<cd>true<cd>/<cd>false<cd>: If = <cd>true<cd> (default), the screen recorder also adds a number to file name (single image / movie) or subfolder name (series of images) to not overwrite existing files/folders. 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/subfolders numbered in the order they run in (e.g. image1.png, image2.png, image3.png, ...). If = <cd>false<cd> then the screen recorder will not add a number, and will error if the file already exists (single image / movie). For series of images, files written in the subfolder are always numbered.

minNumDigitsInFileName is a number that is the minimum number of digits to use for numbering the file (single image / movie) or subfolder (series of images). e.g. 3 → image001.png, image002.png, ... For series of images, you can optionally use a vector [n1 n2] where n1 goes to the subfolder and n2 goes to the image files in it (default = 1), or if you set numberFile = <cd>false<cd> (don't number subfolder) and leave minNumDigitsInFileName at one number then it goes to the image files.

See also record properties fileName_r, n_file below.

elementExpr

Default: don't target 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 by its variable name and possibly index, e.g. <cds>"picture"<cds>, <cds>"shapes(3)"<cds>, etc. (In the coding method this is just the variable name/index you use in the experiment script. In the visual method you can specify a name/index for an object in its object heading, default = object type name.)

If you set elementExpr then position and size of the capture area is automated based on the target element. Also the screen recorder will snap its capture/recording time to just when the target element shows a display, including ending automatically when the target element ends. You just need to set start for the screen recorder to tell it to run in the first place—generally set it to start at or before the target element.

If you don't set elementExpr, then must use properties start, end, position, and size (below) to set capture time and area manually...

size

Default: capture whole experiment window, or ignored if you use elementExpr above

If you don't use elementExpr above, you can set size of the area to capture here. This is a 1×2 vector [width height] (deg). Capture area will be centered at screen recorder position which you can set in property position (default window center).

outputWidth
outputWidthSnap

Default: outputWidth = file width same as width on screen (px)
Default: outputWidthSnap = don't snap file width

outputWidth: Width of image(s) or movie to write (px). Height scales proportionally (doesn't affect size of the area on screen captured).

outputWidthSnap (movie only): Some movie codecs require movie width to be a multiple of 4 or 16 px. You can set outputWidthSnap to a number (px), e.g. 4 or 16, to have the screen recorder scale the recorded movie size to the nearest multiple of that (doesn't affect size of the area on screen recorded). Ignored if you set outputWidth—in that case just setthat to the width you want.

frameRate

Default: 30 frames/sec

(Series of images / Movie only)
Frame rate to capture/record at (frames/sec). Note "real" frame rate in terms of actual changes between images is limited by experiment frame rate during the screen recorder, which nominally = screen refresh rate but can be lower if frames are dropped—see Timing precision. For example, if you set frameRate = 120 and capture for 2 sec then you will get 240 images, but if the experiment frame rate only = 60 frames/sec then the images will only differ at every second image.

movieOptions

Default: none

(Movie only)
A string that goes to input movieOptions of Psychtoolbox Screen('CreateMovie') setting advanced options. See help text there and help VideoRecording for usage.

auto

Default: <cd>true<cd>

Sometimes used with the tool recordElements. Ignore unless recordElements tells you otherwise.

(None)

fileName_r
n_file

fileName_r is a string recording name of file written, or name of subfolder made for series of images. This includes number added if numberFile = <cd>true<cd>.

n_file records the number added (numeric) if numberFile = <cd>true<cd>.