PsychToolboxVideoServer

PsychToolboxVideoServer()

Description

Plays video stimuli on the governing computer's video monitor using PsychToolbox

A "Sync Patch" is automatically generated for each video frame. The patch is set to maximum intensity on the first frame, and alternates between "off" and max 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 server 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, for display 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.
    • An experimental mode is available, that uses a MATLAB timer to load each frame into the video buffer. This makes the command line available during playback, but adds jitter to the inter-frame intervals. Future versions of the plugin will seek to minimize frame onset jitter in timer mode. Timer mode is necessary to play videos while running Bpod.
Object

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

V = PsychToolboxVideoServer(WindowSize, WindowYoffset, ViewPortSize, ViewPortOffset, SyncPatchSize, SyncPatchYOffset)

WindowSize = [Width, Height] of a window containing the video and the sync patch (units = pixels)
WindowYoffset = distance of window from monitor bottom (in pixels). The window always extends to the monitor's right-hand edge.
ViewPortSize = [Width, Height] of the video to display (in pixels). The video width must leave enough room for the sync patch.
ViewPortOffset = [Y, X] offset of the viewport from left edge of window, and bottom of window respectively. (units = pixels)
SyncPatchSize = [Width, Height] of the sync patch (units = pixels)
SyncPatchYOffset = distance of sync pactch from bottom of the window (in pixels)

The initialization parameters are illustrated in this figure:


The PsychToolboxVideoServer is controlled in 2 ways: 
  • Setting the PsychToolboxVideoServer object's fields
  • Calling the PsychToolboxVideoServer object's functions
Object Fields

  • Movies 
    • Cell array containing movies loaded with obj.loadMovie()
  • 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 playback)
      • 1 (video buffer fed by MATLAB timer object, non-blocking playback, may cause uneven frame intervals)
  • 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
  • FontName
    • Name of the font used to display text instructions when loading text with obj.loadText()
    • To view a list of installed fonts, run: listfonts; at the command line.
Object Functions

  • loadVideo(videoIndex, video)
    • Loads a video to the PsychToolboxVideoServer, formatted for playback with correct offset and sync patch
    • videoIndex= index of the video (1-100)
    • video = a X x Y x N MATLAB array of pixel intensities (0-255)
      • X is the width of the video. It must match width of viewport (see ViewPortSize(1) in figure above)
      • Y is the height of the video. It must match height of viewport (see ViewPortSize(2) in figure above)
      • N is the number of frames in the video
    • Color videos may be loaded as X x Y x 3 x N, where the third dimension are red, green and blue color layers
  • 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 server 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 PsychToolboxVideoServer object with clear:
    V = PsychToolboxVideoServer(args);
    ... % Use the video server
    clear V
  • Clearing the object closes the PsychToolbox window.
  • If a PsychToolboxVideoServer 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 server, plays it and then closes the server

MyVideo = (rand(480,640, 30)*255);% Create noise video
% Initialize video server in an 800 x 600 window for a 640 x 480 video, with a 30 x 10 sync patch
V = PsychToolboxVideoServer([800 600], 50, [640 480], [0 0], [30 10], 50)
% Load noise video into server at index 1
V.loadVideo(1, myVideo); 
% play the video
V.play(1); 
% close the video server
clear V 


Comments