expyriment.stimuli.Tone

class expyriment.stimuli.Tone(duration, frequency=None, samplerate=None, bitdepth=None, amplitude=None)

A class implementing a tone stimulus.

__init__(duration, frequency=None, samplerate=None, bitdepth=None, amplitude=None)

Create a Tone.

Parameters:

durationstr: duration of the file in ms
frequencyint, optional: frequency of the sine tone
samplerateint, optional: samplerate of the sine tone
bitdepthint, optional: bitdeth of the sine tone
amplitudeint, optional: amplitude of the sine tone

property amplitude: Getter for amplitude.

property bitdepth: Getter for bitdepth.

copy()

Copy the stimulus.

Returns:

copy: expyriment.stimuli.Audio

property duration: Getter for duration.

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 frequency: Getter for frequency.

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

property samplerate: Getter for samplerate.

save(filename)

Save the sine tone to a file.

Parameters:

filenamestr: filename the sine tone should be saved to (str)

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 == ...