expyriment.stimuli.Audio

class expyriment.stimuli.Audio(filename)

A class implementing a general auditory stimulus.

See also

expyriment.control.start_audiosystem
expyriment.control.stop_audiosystem
expyriment.control.get_audiosystem_is_playing
expyriment.control.wait_end_audiosystem
__init__(filename)

Create an audio stimulus.

Parameters:
filenamestr

filename (incl. path) of the audio file

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 id

Getter for id.

property is_playing

Property to check if audio is playing.

property is_preloaded

Getter for is_preloaded.

property length

Property to get the length of the audio.

property logging

Getter for logging.

play(loops=0, maxtime=0, fade_ms=0, log_event_tag=None)

Play the audio stimulus.

The function returns immediately after the sound started to play. A pygame.mixer.Channel object is returned.

Parameters:
loopsint, optional

how often to repeat (-1 = forever) (default = 0)

maxtimeint

stop after given amount of milliseconds (default = 0)

fade_msint, optional

fade in time in milliseconds (default = 0)

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

Notes

If seek(), forward() or rewind() have been used to set a new playback position before calling this method, the loop start will be the newly set position.

Using seek(), forward() or rewind() to set a new playback position after calling this method (i.e. during playback), will reset loops, maxtime and fade_ms to 0.

preload()

Preload stimulus to memory.

Returns:
timeint

the time it took to execute this method

present(log_event_tag=None)

Presents the sound.

The function is identical to Audio.play(loops=0, maxtime=0, fade_ms=0) and returns also immediately after the sound started to play.

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-intervals are appended at the end of the event file

Notes

See Audio.play for more information.

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
stop()

Stop the audio 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

wait_end(callback_function=None, process_control_events=True)

Wait until audio has ended playing.

Blocks until the audios is not playing anymore and only returns then.

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 audio.is_playing:
    key = exp.keyboard.check()
    if key == ...
wait_time(time, callback_function=None, process_control_events=True)

Wait until specified time.

Blocks until specified time is reached and only returns then.

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 audio.is_playing and audio.time < time:
    key = exp.keyboard.check()
    if key == ...