Audio Stimulus Classes

Loading and generating Sounds

class +o_ptb.+stimuli.+auditory.Wav(filename)

Audio Stimulus read from a wav file.

This class provides all methods of +o_ptb.+stimuli.+auditory.Base.

Parameters

filename (string) – The filename of the wav file to load.

class +o_ptb.+stimuli.+auditory.Sine(freq, duration)

Sine wave audio stimulus.

This class provides all methods of +o_ptb.+stimuli.+auditory.Base.

Parameters

  • freq (float) – Frequency of the sine wave

  • duration (float) – Duration in seconds.

class +o_ptb.+stimuli.+auditory.WhiteNoise(duration)

White Noise stimulus.

This class provides all methods of +o_ptb.+stimuli.+auditory.Base.

Parameters

duration (float) – Duration in seconds.

class +o_ptb.+stimuli.+auditory.FromMatrix(sound_data, s_rate)

Audio Stimulus read from a matrix.

This class provides all methods of +o_ptb.+stimuli.+auditory.Base.

Parameters

  • sound_data (matrix of floats) – The sound data. One channel per row, one sample per column. The data must not exceed -1 / +1.

  • s_rate (float) – The sampling rate of the sound data.

Base classes

class +o_ptb.+stimuli.+auditory.Base

This is the base class for all auditory stimuli.

This means that:

  1. All auditory stimulus classes provide all the parameters and methods of this base class. Please refer to Using Triggers and Sound for details.

  2. In order to create your own auditory stimulus class, you need to inherit from this base class.

Note

All volume-related attributes (i.e., amplification_factor, rms, db, lufs and absmax) are related to each other. If you change one of them, the others reflect the new volume.

Note

If +o_ptb.PTB_Config.audio_system_cutoff or O_PTB_AUDIO_CUTOFF is set, rms, rms_db and lufs the sound will be lowpass filtered at that frequency before these values are computed.

Note

It is not possible to play sounds at a volume that would lead to clipping.

Note

Sampling rate conversion is done automatically.

Variables

  • amplification_factor ([float float]) – The factor by which each channel of the sound is amplified.

  • rms ([float float]) – The root-mean-square of the two channels.

  • rms_db ([float float]) – The RMS expressed in dB.

  • lufs ([float float]) – The “Loudness Unit Full Scale” of the two channels. This is a comparable to RMS but accounts for the psychophysic properties of human hearing. It is also on a logarithmic scale like dB.

  • db ([float float]) – The maximum amplitude of both channels expressed in dB. 0dB is the maximum volume.

  • absmax ([float float]) – The maximum amplitude of both channels.

  • muted_channels (int or array of ints) – If empty (i.e. []), both channels are played. If set to 1, the left channel is muted. If set to 2, the right channel is muted. If set to [1 2], both channels are muted.

  • duration (float) – The duration of the sound in seconds.

  • n_samples (int) – The number of samples of the sound.

  • angle (float) – The angle of the direction where the sound comes from. This is used to calculate the Interaural Time Difference using the “Woodworth model” (Woodworth 1938). Negative values make the sound appear from the left, positive values from the right. The unit is “radians” and must be between -pi and +pi.

  • head_radius (float) – Radius of the head in meters. Used to calculate the ITD.

amplify(factor)

Amplify the sound.

Parameters

factor (float) – Amplification factor.

amplify_db(db)

Amplify the sound by dB.

Parameters

db (float) – dB to add to the volume.

amplitude_modulate(mod_freq, mod_depth)

Apply amplitude modulation to the sound.

Parameters

  • mod_freq (float) – Frequency of the modulation

  • mod_depth (float) – Depth of the modulation

apply_cos_ramp(duration)

Apply a cosine ramp to the start and end of the sound.

Parameters

duration (float) – Duration of the ramp in seconds.

apply_hanning()

Apply a hanning window to the sound.

apply_sin_ramp(duration)

Apply a sine ramp to the start and end of the sound.

Parameters

duration (float) – Duration of the ramp in seconds.

debug_play_now()

Plays the stimulus right now. Do not use in real experiment

Warning

This method should only be used to interactively check a stimulus. It should not be used in your real experiment script!

fadeinout(fade_length)

Apply linear fade in and fade out.

Parameters

fade_length (float) – Duration of the fade in seconds.

filter_bandpass(l_freq, h_freq, l_transition_width, h_transition_width, max_passband_ripple, max_stopband_ripple)

Apply bandpass filter.

Parameters

  • l_freq (float) – Low edge frequency

  • h_freq (float) – High edge frequency

  • l_transition_width (float, optional) – Bandwidth between the lower passband and the stopband. Default = l_freq * 0.05

  • h_transition_width (float, optional) – Bandwidth between the higher passband and the stopband. Default = h_freq * 0.05

  • max_passband_ripple (float, optional) – Maximum allowed passband ripple. Default = 3

  • max_stopband_ripple (float, optional) – Maximum allowed stopband ripple. Default = 20

filter_bandstop(l_freq, h_freq, l_transition_width, h_transition_width, max_passband_ripple, max_stopband_ripple)

Apply bandstop filter.

Parameters

  • l_freq (float) – Low edge frequency

  • h_freq (float) – High edge frequency

  • l_transition_width (float, optional) – Bandwidth between the lower passband and the stopband. Default = l_freq * 0.05

  • h_transition_width (float, optional) – Bandwidth between the higher passband and the stopband. Default = h_freq * 0.05

  • max_passband_ripple (float, optional) – Maximum allowed passband ripple. Default = 3

  • max_stopband_ripple (float, optional) – Maximum allowed stopband ripple. Default = 20

filter_highpass(freq, transition_width, max_passband_ripple, max_stopband_ripple)

Apply highpass filter.

Parameters

  • freq (float) – Edge frequency

  • transition_width (float, optional) – Bandwidth between the passband and the stopband. Default = freq * 0.05

  • max_passband_ripple (float, optional) – Maximum allowed passband ripple. Default = 3

  • max_stopband_ripple (float, optional) – Maximum allowed stopband ripple. Default = 20

filter_lowpass(freq, transition_width, max_passband_ripple, max_stopband_ripple)

Apply lowpass filter.

Parameters

  • freq (float) – Edge frequency

  • transition_width (float, optional) – Bandwidth between the passband and the stopband. Default = freq * 0.05

  • max_passband_ripple (float, optional) – Maximum allowed passband ripple. Default = 3

  • max_stopband_ripple (float, optional) – Maximum allowed stopband ripple. Default = 20

flip_polarity()

Flip the polarity of the sound.

flip_sound()

Flip the sound so it will be played backwards.

plot_spectrum()

Plot spectrum

plot_waveform()

Plot waveform

plus(a, b)

Add two sounds using the + operator.

If you have two sounds sound_a and sound_b, you can add the two by doing this:

new_sound = sound_a + sound_b;
save_wav(fname, srate)

Save the sound data to a wav file.

Parameters

  • fname (string) – The filename to save the data to.

  • srate (int, optional) – Sampling rate. defaults to the sampling rate of the stimulus.

set_to_max_amplification()

Set this stimulus to the maximum volume without clipping.

vocode(n_channels, freq_range)

Vocode the sound.

Parameters

  • n_channels (int) – Number of vocoder channels.

  • freq_range ([float float], optional) – The frequency range to use for vocoding.