Screen('OpenMovie')

Psychtoolbox › Screen.{mex*,dll} subfunction

Try to open the multimediafile 'moviefile' for playback in onscreen window
'windowPtr' and return a handle 'moviePtr' on success.
On OS-X and Windows, media files are handled by use of Apples Quicktime-7 API.
On Linux, the GStreamer multimedia framework is used. The following movie
properties are optionally returned: 'duration' Total duration of movie in
seconds. 'fps' Video playback framerate, assuming a linear spacing of
videoframes in time. There may exist exotic movie formats which don't have this
linear spacing. In that case, 'fps' would return bogus values and the check for
skipped frames would report bogus values as well. 'width' Width of the images
contained in the movie. 'height' Height of the images.
'count' Total number of videoframes in the movie. Determined by counting, so
querying 'count' can significantly increase the execution time of this command.
'aspectRatio' Pixel aspect ratio of pixels in the video frames. Typically 1.0
for square pixels. Aspect ratio is only detected with the GStreamer playback
engine. Quicktime always returns 1.0.
If you want to play multiple movies in succession with lowest possible delay
inbetween the movies then you can ask PTB to load a movie in the background
while another movie is still playing: Call this function with the 'async' flag
set to 1. This will initiate the background load operation. After some
sufficient time has passed, you can call the 'OpenMovie' function again, this
time with the 'async' flag set to zero. Now the function will return a valid
movie handle for playback. Background loading of movies currently does only work
well with movies that don't have sound, unless you use Linux.
If you use the GStreamer playback engine and all your movies have exactly the
same format and only differ in duration and content, but not in image size,
color depth or format, or fps, then you can also use an aync setting of 2 and
provide the 'moviePtr' handle of an already opened movie in the 'preloadSecs'
parameter. This will queue the movie 'moviefile' as a successor to the currently
playing moviefile in 'ḿoviePtr'. Queuing movies this way is more efficient
than async flag setting 1, although also more restricted.
'preloadSecs' This optional parameter allows to ask Screen() to load at least
the first 'preloadSecs' seconds of the movie into system RAM before the function
returns. By default, the first second of the movie file is loaded into RAM. This
potentially allows for more stutter-free playback, but your mileage may vary,
depending on movie format, storage medium and lots of other factors. In most
cases, the default setting is perfectly sufficient. The special setting -1
means: Load whole movie into RAM. Caution: Long movies may cause your system to
run low on memory and have disastrous effects on playback performance!
CAUTION: On OS/X, some movie files, e.g., MPEG-1 movies sometimes cause Matlab
to hang. This seems to be a bad interaction between parts of Apples Quicktime
toolkit and Matlabs Java Virtual Machine (JVM). If you experience stability
problems, please start Matlab with JVM and desktop disabled, e.g., with the
command: 'matlab -nojvm'. An example command sequence in a terminal window could
be: /Applications/MATLAB701/bin/matlab -nojvm