Table Of Contents

Previous topic

psychopy.serial - functions for interacting with the serial port

Next topic

psychopy.tools - miscellaneous tools

This Page

Quick links

psychopy.sound - play various forms of sound

Sound

PsychoPy currently supports a choice of two sound libraries: pyo, or pygame. Select which will be used via the audioLib preference. sound.Sound() will then refer to either SoundPyo or SoundPygame. This can be set on a per-experiment basis by importing preferences, and setting the audioLib preference to use.

It is important to use sound.Sound() in order for proper initialization of the relevant sound library. Do not use sound.SoundPyo or sound.SoundPygame directly. Because they offer slightly different features, the differences between pyo and pygame sounds are described here. Pygame sound is more thoroughly tested, whereas pyo offers lower latency and more features.

class psychopy.sound.SoundPyo(value='C', secs=0.5, octave=4, stereo=True, volume=1.0, loops=0, sampleRate=44100, bits=16, hamming=True, start=0, stop=-1, name='', autoLog=True)

Create a sound object, from one of MANY ways.

value: can be a number, string or an array:
  • If it’s a number between 37 and 32767 then a tone will be generated at that frequency in Hz.
  • It could be a string for a note (‘A’,’Bfl’,’B’,’C’,’Csh’...). Then you may want to specify which octave as well
  • Or a string could represent a filename in the current location, or mediaLocation, or a full path combo
  • Or by giving an Nx2 numpy array of floats (-1:1) you can specify the sound yourself as a waveform

By default, a Hamming window (5ms duration) will be applied to a generated tone, so that onset and offset are smoother (to avoid clicking). To disable the Hamming window, set hamming=False.

secs:
Duration of a tone. Not used for sounds from a file.
start : float
Where to start playing a sound file; default = 0s (start of the file).
stop : float
Where to stop playing a sound file; default = end of file.
octave: is only relevant if the value is a note name.
Middle octave of a piano is 4. Most computers won’t output sounds in the bottom octave (1) and the top octave (8) is generally painful

stereo: True (= default, two channels left and right), False (one channel)

volume: loudness to play the sound, from 0.0 (silent) to 1.0 (max).
Adjustments are not possible during playback, only before.
loops : int
How many times to repeat the sound after it plays once. If loops == -1, the sound will repeat indefinitely until stopped.
sampleRate (= 44100): if the psychopy.sound.init() function has been called
or if another sound has already been created then this argument will be ignored and the previous setting will be used

bits: has no effect for the pyo backend

hamming: whether to apply a Hamming window (5ms) for generated tones.
Not applied to sounds from files.
getDuration()

Return the duration of the sound

getLoops()

Returns the current requested loops value for the sound (int)

getVolume()

Returns the current volume of the sound (0.0 to 1.0, inclusive)

play(loops=None, autoStop=True, log=True)

Starts playing the sound on an available channel.

loops : int
(same as above)

For playing a sound file, you cannot specify the start and stop times when playing the sound, only when creating the sound initially.

Playing a sound runs in a separate thread i.e. your code won’t wait for the sound to finish before continuing. To pause while playing, you need to use a psychopy.core.wait(mySound.getDuration()). If you call play() while something is already playing the sounds will be played over each other.

setLoops(newLoops, log=True)

Sets the current requested extra loops (int)

setVolume(newVol, log=True)

Sets the current volume of the sound (0.0 to 1.0, inclusive)

stop(log=True)

Stops the sound immediately

class psychopy.sound.SoundPygame(value='C', secs=0.5, octave=4, sampleRate=44100, bits=16, name='', autoLog=True, loops=0)

Create a sound object, from one of many ways.

Parameters:
value: can be a number, string or an array:
  • If it’s a number between 37 and 32767 then a tone will be generated at that frequency in Hz.
  • It could be a string for a note (‘A’,’Bfl’,’B’,’C’,’Csh’...). Then you may want to specify which octave as well
  • Or a string could represent a filename in the current location, or mediaLocation, or a full path combo
  • Or by giving an Nx2 numpy array of floats (-1:1) you can specify the sound yourself as a waveform

secs: duration (only relevant if the value is a note name or a frequency value)

octave: is only relevant if the value is a note name.

Middle octave of a piano is 4. Most computers won’t output sounds in the bottom octave (1) and the top octave (8) is generally painful

sampleRate(=44100): If a sound has already been created or if the

bits(=16): Pygame uses the same bit depth for all sounds once initialised

fadeOut(mSecs)

fades out the sound (when playing) over mSecs. Don’t know why you would do this in psychophysics but it’s easy and fun to include as a possibility :)

getDuration()

Get’s the duration of the current sound in secs

getVolume()

Returns the current volume of the sound (0.0:1.0)

play(fromStart=True, log=True, loops=None)

Starts playing the sound on an available channel.

fromStart : bool
Not yet implemented.
log : bool
Whether or not to log the playback event.
loops : int
How many times to repeat the sound after it plays once. If loops == -1, the sound will repeat indefinitely until stopped.

If no sound channels are available, it will not play and return None. This runs off a separate thread i.e. your code won’t wait for the sound to finish before continuing. You need to use a psychopy.core.wait() command if you want things to pause. If you call play() whiles something is already playing the sounds will be played over each other.

setVolume(newVol, log=True)

Sets the current volume of the sound (0.0:1.0)

stop(log=True)

Stops the sound immediately