If you want to use a screenRecorder element, often it's easier to use the recordElements command outside an experiment instead. Type help recordElements at the MATLAB command line for more information.

A screenRecorder element captures/records the whole 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 further determined 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 and released in the inter-trial interval after. Also since writing files is relatively slow, this can extend the inter-trial interval significantly.

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

("Ends on its own" means ends automatically at that point. 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.)

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

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. Also the screen recorder will snap its capture/recording time to just when the target element shows a display, and end on its own if it is still running when the target element ends. Note you still need to set start for the screen recorder to tell it to run—generally set it to at or before when the target element will run.

size

Default: size = capture whole experiment window; or whole target element display if you set elementExpr above

You can optionally set size of the area to capture. Set to 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, the area is 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, whatever size that is.

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.

(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>.