expyriment.stimuli.Video

class expyriment.stimuli.Video(filename, resizing=None, audio_backend=None, position=None)

A class implementing a general video stimulus.

This class uses a background thread for playing the video!

Notes

With the “pygame” audio backend, the Expyriment audiosystem is used to play the audio of the video. If the audiosystem is stopped BEFORE the video stimulus is played, (by calling expyriment.control.stop_audiosystem()), or if the “sounddevice” backend is used, a temporary audiosystem will be started with parameters (sample rate, bit depth, channels) matching the audiosystem defaults. The temporary audiosystem will be stopped when the video is stopped.

When showing videos in large dimensions, and your computer is not fast enough, frames might be dropped! When using Video.wait_frame() or Video.wait_end(), dropped video frames will be reported and logged.

__init__(filename, resizing=None, audio_backend=None, position=None)

Create a video stimulus.

Parameters:

filenamestr

filename (incl. path) of the video file

resizingint, float, bool, None, list or tuple , optional

Determines whether and how the video should be resized upon preloading. When given a single value, the value can be:

int - Resizing of video to the given height

(e.g., 1080, 720)

float - Resizing of video with given scaling factor

(e.g., 0.5 * original)

True - Resizing of video to fit screen False - No resizing of video

Resizing using a single value will always maintain the original aspect ratio. When given a list or tuple of (width, height), resizing of each dimension can be controlled individually, and the values can be:

int - Resizing of dimension to given value float - Resizing of dimension with given scaling factor True - Resizing of dimension to fit screen dimension False - No resizing of dimension None - Conditional resizing of dimension

(i.e., compute value to keep aspect ratio, given value of the other dimension; if both dimensions are None, resize to fit the screen, but only if either dimension of the original exceeds the corresponding screen dimension)

audio_backendstr, optional

audio backend to use (one of “pygame” or “sounddevice”)

position(int, int), optional

position of the stimulus

property audio_backend

Getter for audio_backend.

copy()

Copy the stimulus.

Returns:

copy: expyriment.stimuli.Audio

property filename

Getter for filename.

forward(duration)

Forward playback position by specified duration.

Parameters:

durationint, float, tuple, list or str

the duration to forward by; can be any of the following formats:

• float: seconds

• tuple: (minutes, seconds) or (hours, minutes, seconds)

• list: [minutes, seconds] or [hours, minutes, seconds]

• str: ‘hhrmm:ss’, ‘hh:mm:ss.sss’, or ‘mm:ss.sss’

Examples

>>> forward(15.4)          # seconds
>>> forward((1, 21.5))     # (min, sec)
>>> forward((1, 1, 2))     # (hr, min, sec)
>>> forward('01:01:33.5')  # (hr:min:sec)
>>> forward('01:01:33.045')
>>> forward('01:01:33,5')  # comma works too

property fps

Property to get the FSP (frames per second) of the video.

property frame

Property to get the current available video frame (0-based!).

property has_audio

Property to check if video file has audio information.

property has_video

Property to check if video fifle has video information.

property id

Getter for id.

property is_paused

Property to check if video is paused.

property is_playing

Property to check if video is playing.

property is_preloaded

Getter for is_preloaded.

property length

Property to get the length of the video.

property logging

Getter for logging.

property n_frames

Property to get the number of frames of the video.

property new_frame_available

Property to check if new video frame is available to render.

pause()

Pause the video stimulus.

play(loop=False, log_event_tag=None, audio=True)

Play the video stimulus from the current position.

Parameters:

loopbool, optional

loop video playback (will be ignored when using play to unpause!)

log_event_tagnumeral or string, optional

if log_event_tag is defined and if logging is switched on for this stimulus (default), a summary of the inter-event-intervalls are appended at the end of the event file

audiobool, optional

whether audio of video (if present) should be played (default=True)

Notes

With the “pygame” audio backend, the Expyriment audiosystem is used to play the audio of the video. If the audiosystem is stopped BEFORE the video stimulus is played, (by calling expyriment.control.stop_audiosystem()), or if the “sounddevice” backend is used, a temporary audiosystem will be started with parameters (sample rate, bit depth, channels) matching the audiosystem defaults. The temporary audiosystem will be stopped when the video is stopped.

When showing videos in large dimensions, and your computer is not fast enough, frames might be dropped! When using Video.wait_frame() or Video.wait_end(), dropped video frames will be reported and logged.

property position

Getter for position.

preload()

Preload stimulus to memory.

Returns:

timeint

the time it took to execute this method

present(log_event_tag=None)

Present next available frame.

This method waits for the next frame and presents it on the screen. When using OpenGL, the method blocks until this frame is actually being written to the screen.

Parameters:

log_event_tagnumeral or string, optional

if log_event_tag is defined and if logging is switched on for this stimulus (default), a summary of the inter-event-intervalls are appended at the end of the event file

Returns:

timeint

the time it took to execute this method

Notes

If there are no frames available anymore (end of video reached), this method will return immediately.

When showing videos in large dimensions, and your computer is not fast enough, frames might be dropped! When using this method, dropped video frames will be reported and logged.

property resizing

Getter for resizing.

rewind(duration=None)

Rewind playback position by specified duration or to beginning.”

Parameters:

durationint, float, tuple, list or str, optional

the duration to rewind by; can be any of the following formats:

• float: seconds

• tuple: (minutes, seconds) or (hours, minutes, seconds)

• list: [minutes, seconds] or [hours, minutes, seconds]

• str: ‘hhrmm:ss’, ‘hh:mm:ss.sss’, or ‘mm:ss.sss’

Examples

>>> rewind(15.4)          # seconds
>>> rewind((1, 21.5))     # (min, sec)
>>> rewind((1, 1, 2))     # (hr, min, sec)
>>> rewind('01:01:33.5')  # (hr:min:sec)
>>> rewind('01:01:33.045')
>>> rewind('01:01:33,5')  # comma works too

seek(time)

Seek playback position to specified time.

Parameters:

timeint, float, list or str

the time to seek to; can be any of the following formats:

• float: seconds

• tuple: (minutes, seconds) or (hours, minutes, seconds)

• list: [minutes, seconds] or [hours, minutes, seconds]

• str: ‘hhrmm:ss’, ‘hh:mm:ss.sss’, or ‘mm:ss.sss’

Examples

>>> seek(15.4)          # seconds
>>> seek((1, 21.5))     # (min, sec)
>>> seek((1, 1, 2))     # (hr, min, sec)
>>> seek('01:01:33.5')  # (hr:min:sec)
>>> seek('01:01:33.045')
>>> seek('01:01:33,5')  # comma works too

set_logging(onoff)

Set logging of this object on or off

Parameters:

onoffbool

set logging on (True) or off (False)

See also

expyriment.design.Experiment.set_log_level

property size

Getter for size.

stop()

Stop the video stimulus.

property time

Property to get the current playback time (in seconds).

unload(**kwargs)

Unload stimulus from memory.

This removes the reference to the object in memory. It is up to the garbage collector to actually remove it from memory.

Returns:

timeint

the time it took to execute this method

update(blocking=True)

Update the screen with the current frame.

Parameters:

blockingbool, optional

whether to block on vertical retrace (OpenGL only; default=True)

Notes

When showing videos in large dimensions, and your computer is not fast enough, frames might be dropped! When using this method, dropped video frames will be reported and logged.

wait_end(time=None, callback_function=None, process_control_events=True)

Wait until video has ended and constantly update screen.

Parameters:

callback_functionfunction, optional

function to repeatedly execute during waiting loop

process_control_eventsbool, optional

process io.Keyboard.process_control_keys() and io.Mouse.process_quit_event() (default = True)

Notes

This will also by default process control events (quit and pause). Thus, keyboard events will be cleared from the cue and cannot be received by a Keyboard().check() anymore! If keyboard events should not be cleared, a loop has to be created manually, for instance like:

while video.is_playing:
    if video.new_frame_available:
        video.update()
    else:
        key = exp.keyboard.check()
        if key == ...

When showing videos in large dimensions, and your computer is not fast enough, frames might be dropped! When using this method, dropped video frames will be reported and logged.

wait_frame(frame, callback_function=None, process_control_events=True)

Wait until specified frame and constantly update screen.

Parameters:

frameint

number of the frame to wait until

callback_functionfunction, optional

function to repeatedly execute during waiting loop

process_control_eventsbool, optional

process io.Keyboard.process_control_keys() and io.Mouse.process_quit_event() (default = True)

Notes

This will also by default process control events (quit and pause). Thus, keyboard events will be cleared from the cue and cannot be received by a Keyboard().check() anymore! If keyboard events should not be cleared, a loop has to be created manually, for instance like:

while video.is_playing and video.frame < frame:
    if video.new_frame_available:
        video.update()
    else:
        key = exp.keyboard.check()
        if key == ...

When showing videos in large dimensions, and your computer is not fast enough, frames might be dropped! When using this method, dropped video frames will be reported and logged.

wait_time(time, callback_function=None, process_control_events=True)

Wait until specified time and constantly update screen.

Parameters:

timeint, float, tuple, list or str

time to wait until; can be any of the following formats:

• float: seconds

• tuple: (minutes, seconds) or (hours, minutes, seconds)

• list: [minutes, seconds] or [hours, minutes, seconds]

• str: ‘hhrmm:ss’, ‘hh:mm:ss.sss’, or ‘mm:ss.sss’

callback_functionfunction, optional

function to repeatedly execute during waiting loop

process_control_eventsbool, optional

process io.Keyboard.process_control_keys() and io.Mouse.process_quit_event() (default = True)

Notes

This will also by default process control events (quit and pause). Thus, keyboard events will be cleared from the cue and cannot be received by a Keyboard().check() anymore! If keyboard events should not be cleared, a loop has to be created manually, for instance like:

while video.is_playing and video.time < time:
    if video.new_frame_available:
        video.update()
    else:
        key = exp.keyboard.check()
        if key == ...

When showing videos in large dimensions, and your computer is not fast enough, frames might be dropped! When using this method, dropped video frames will be reported and logged.

Examples

>>> wait_time(15.4)          # seconds
>>> wait_time((1, 21.5))     # (min, sec)
>>> wait_time((1, 1, 2))     # (hr, min, sec)
>>> wait_time('01:01:33.5')  # (hr:min:sec)
>>> wait_time('01:01:33.045')
>>> wait_time('01:01:33,5')  # comma works too