screenRecorder

elements

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.

▸ Object ends on its own?

If you capture a single image then the screen recorder ends on its own as soon as the capture occurs. Otherwise it records until it or the target element ends. If you target another element then the screen recorder ends on its own if it is still running when that element ends.

"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).

No—runs until any condition you set in property end.

Input properties

Adjustable properties

You can vary or allow the subject to adjust the following properties of an object of this type when it's running. If you need to make other properties adjustable, you can edit the element type code—see Element Type Programming Manual.

Adjustable properties

position
nn_eyes
rotation
colorMask
alpha
intensity
contrastMult
drawCodeVars

(None)

fileName
numberFile
minNumDigitsInFileName

No default: fileName
Default: numberFile = automatically number files
‍Default: minNumDigitsInFileName = 1

fileName is a string setting name for 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 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 save image files there.

numberFile
<cd>true<cd>/<cd>false<cd>: If = <cd>true<cd> (default), the screen recorder adds a number to file name (single image / movie) or subfolder name (series of images) starting at 1 and incrementing as needed to not overwrite any 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, ...). NOTE: If you set numberFile = <cd>false<cd> then the screen recorder will not add a number and will overwrite any existing files.

minNumDigitsInFileName sets the minimum number of digits to use for numbering files/subfolders. e.g. 3 → image001.png, image002.png, image003.png, ...

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 (visual method: in its object heading / coding method: 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. Also the screen recorder will snap its capture/recording interval 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 = same as width on screen (px)
Default: outputWidthSnap = don't snap width to any number of pixels

outputWidth: Width of image file(s) or movie file to write (px). This scales the file up or down (doesn't affect the area 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 up or down to the nearest multiple of that (doesn't affect the area recorded). Ignored if you set outputWidth—in that case just set outputWidth to the width (px) that 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.

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 using input property report.

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