Bpod Wiki - PsychToolboxVideoPlayer

PsychToolboxVideoPlayer()

Description

Plays video stimuli on a second video monitor attached to the Bpod computer using PsychToolbox.

A "Sync Patch" is automatically generated for each video frame. The patch is set to a high pixel intensity on the first frame, and alternates between "off" and high intensity for subsequent frames. This allows an optical sensor mounted on the corner of the screen (i.e. Frame2TTL) to indicate the actual onset time of each video frame to an acquisition system, providing high precision reaction time and visual evidence update measurements.

Videos are matrices defined in MATLAB.
- Each video frame is a matrix of 8-bit pixel values (0-255).
- Single frames may be a grayscale intensity matrix of dimensions (Y, X) or a color matrix of dimensions (Y, X, 3)
- The three color layers are intensity matrices for red, green and blue layers respectively.
Multiple frames are stacked in an additional dimension to create a video.
- e.g. a color video is a 4-D matrix: Y x X x 3 x Nframes
Videos are loaded to the player and assigned an index (1 - 100).
Videos can be played by index, allowing a byte to specify which video to start.
Text strings can be loaded by index in place of videos, to display prompts to human subjects
By default, playing a video blocks the MATLAB command line.
- In default mode, a loop loads frames into the video buffer. Frames are presented at regular intervals.
- In timer mode, a MATLAB timer callback loads each frame into the video buffer. This makes the command line available during playback.

Object

After running Bpod, a PsychToolboxVideoPlayer object is initialized with the following syntax:

V = PsychToolboxVideoPlayer(MonitorID, ViewPortSize, ViewPortOffset, SyncPatchSize, SyncPatchYOffset)

MonitorID = The index of the second monitor attached to the PC. This is usually 2.

ViewPortSize = [X, Y] of the video to display (in pixels). The video width must leave enough room for the sync patch.

ViewPortOffset = [X, Y] offset of the viewport from left screen edge, and bottom screen edge respectively. (units = pixels)

SyncPatchSize = [X, Y] dimensions of the sync patch (units = pixels)

SyncPatchYOffset = distance of sync patch from bottom of the window (in pixels)

The PsychToolboxVideoPlayer is controlled in 2 ways:

Setting the PsychToolboxVideoPlayer object's fields
Calling the PsychToolboxVideoPlayer object's functions

Object Fields

- Window
  - PsychToolbox Window object (for advanced usage, see documentation)
- DetectedFrameRate
  - Detected frame rate of the target display in Hz
- Videos
  - Cell array containing videos loaded with obj.loadVideo()
- TextStrings
  - Cell array containing text strings loaded with obj.loadText()
- TimerMode
  - TimerMode can be one of the following:
    - 0 (video buffer fed by loop, blocking the MATLAB command line)
    - 1 (video buffer fed by MATLAB timer object, non-blocking playback)
- ShowViewportBorder
  - ShowViewportBorder can be one of:
    - 0 (no border)
    - 1 - a thin gray border is drawn around the viewport (video portion of the window).
      - This is useful for initial layout, and should be disabled during stimulus presentation
- ViewPortDimensions
  - X,Y Dimensions of videos that can be loaded (specified on startup)
- SyncPatchIntensity
  - Intensity of the sync patch pixels. Range = [0, 255]. Default = 128.
- SyncPatchActiveArea
  - Fraction of the sync patch dimensions set to white when drawing a white patch. Range = [0, 1].
  - Permanently dark pixels surrounding the optical sensor can help to hide the sync patch from the test subject and improve tolerance for sensor misalignment

Object Functions

loadVideo(videoIndex, video)
- Loads a video to the PsychToolboxVideoPlayer, formatted for playback with correct offset and sync patch
- videoIndex= index of the video (1-100)
- video = a Y x X x N MATLAB array of pixel intensities (0-255)
  - Y is the height of the video. It must match height of viewport. The height is given in ViewPortDimensions(2)
  - X is the width of the video. It must match width of viewport. The width is given in ViewPortDimensions(1)
  - N is the number of frames in the video
- Color videos may be loaded as Y x X x 3 x N, where the third dimension are red, green and blue color layers respectively
loadText(textIndex, textString, [textStringLine2], [fontSize], [leftOffset])
- Loads 1 or 2 lines of text to display on a single video frame (for online human subject instructions)
- textIndex = index of the text string (1-100). A video on the player cannot have the same index.
- textString = a character array of text to display
- textStringLine2 (optional) - a character array to display on line 2
- fontSize = font size of text to display
play(stimulusIndex)
- Plays video or text frame at the specified index, loaded previously with loadVideo() or loadText().
- If obj.TimerMode is set to 0, this function will block the MATLAB command line until video playback is complete.
stop()
- Stops ongoing video playback if obj.TimerMode is set to 1 (non-blocking playback)

Cleanup

Clear the PsychToolboxVideoPlayer object with clear:

V = PsychToolboxVideoPlayer(args);

... % Use the video player

clear V

Clearing the object closes the PsychToolbox window.
If a PsychToolboxVideoPlayer object is created as a local variable inside a MATLAB function, the object is cleared automatically when the function returns.

Example

% This code creates a noise video, loads it to the video player, plays it and then closes the player.

MyVideo = (rand(480,640, 30)*255); % Create noise video

% Initialize video player for a 640 x 480 video, with a 30 x 10 sync patch

V = PsychToolboxVideoPlayer(2, [640 480], [0 0], [30 10], 0);

% Load noise video into player at index 1

V.loadVideo(1, myVideo);

% play the video

V.play(1);

% close the video player

clear V

An example behavior protocol using PsychToolboxVideoServer is given in the Bpod_Gen2 repository, here.