psychopy 2024.1.4__py3-none-any.whl → 2024.2.0__py3-none-any.whl

psychopy/sound/_base.py

@@ -210,10 +210,27 @@ class _SoundBase(AttributeGetSetMixin):
         elif isinstance(value, (list, numpy.ndarray,)):
             # create a sound from the input array/list
             self._setSndFromArray(numpy.array(value))
-        elif isinstance(value, AudioClip):
-            # from an audio clip object
-            self.sampleRate = value.sampleRateHz
+        elif isinstance(value, AudioClip):  # from an audio clip object
+            # check if we should resample the audio clip to match the device
+            if self.sampleRate is None:
+                logging.warning(
+                    "Sound output sample rate not set. The provided AudioClip "
+                    "requires a sample rate of {} Hz for playback which may "
+                    "not match the device settings.".format(value.sampleRateHz)) 
+
+                self.sampleRate = value.sampleRateHz
+
+            if self.sampleRate != value.sampleRateHz:
+                logging.warning(
+                    "Resampling to match sound device sample rate (from {} "
+                    "to {} Hz), distortion may occur.".format(
+                        value.sampleRateHz, self.sampleRate))
+
+                # resample with the new sample rate using the AudioClip method
+                value = value.resample(self.sampleRate, copy=True)
+
             self._setSndFromArray(value.samples)
+
         # did we succeed?
         if self._snd is None:
             pass  # raise ValueError, "Could not make a "+value+" sound"

psychopy/sound/audioclip.py

@@ -24,7 +24,8 @@ __all__ = [
 ]
 
 from pathlib import Path
-
+import shutil
+import tempfile
 import numpy as np
 import soundfile as sf
 from psychopy import prefs
@@ -403,6 +404,145 @@ class AudioClip:
 
         return AudioClip(samples, sampleRateHz=sampleRateHz)
 
+    # --------------------------------------------------------------------------
+    # Speech synthesis methods
+    #
+    # These static methods are used to generate audio samples from text using
+    # text-to-speech (TTS) engines.
+    #
+
+    @staticmethod
+    def synthesizeSpeech(text, engine='gtts', synthConfig=None, outFile=None):
+        """Synthesize speech from text using a text-to-speech (TTS) engine.
+
+        This method is used to generate audio samples from text using a
+        text-to-speech (TTS) engine. The synthesized speech can be used for
+        various purposes, such as generating audio cues for experiments or
+        creating audio instructions for participants. 
+
+        This method returns an `AudioClip` object containing the synthesized
+        speech. The quality and format of the retured audio may vary depending 
+        on the TTS engine used.
+
+        Please note that online TTS engines may require an active internet
+        connection to work. This also may send the text to a remote server for
+        processing, so be mindful of privacy concerns.
+
+        Parameters
+        ----------
+        text : str
+            Text to synthesize into speech.
+        engine : str
+            TTS engine to use for speech synthesis. Default is 'gtts'.
+        synthConfig : dict or None
+            Additional configuration options for the specified engine. These
+            are specified using a dictionary (ex. 
+            `synthConfig={'slow': False}`). These paramters vary depending on 
+            the engine in use. Default is `None` which uses the default
+            configuration for the engine.
+        outFile : str or None
+            File name to save the synthesized speech to. This can be used to 
+            save the audio to a file for later use. If `None`, the audio clip 
+            will be returned in memory. If you plan on using the same audio 
+            clip multiple times, it is recommended to save it to a file and load
+            it later.
+
+        Returns
+        -------
+        AudioClip
+            Audio clip containing the synthesized speech.
+
+        Examples
+        --------
+        Synthesize speech using the default gTTS engine::
+
+            import psychopy.sound as sound
+            voiceClip = sound.AudioClip.synthesizeSpeech(
+                'How are you doing today?')
+
+        Save the synthesized speech to a file for later use::
+
+            voiceClip = sound.AudioClip.synthesizeSpeech(
+                'How are you doing today?', outFile='/path/to/speech.mp3')
+
+        Synthesize speech using the gTTS engine with a specific language, 
+        timeout, and top-level domain::
+
+            voiceClip = sound.AudioClip.synthesizeSpeech(
+                'How are you doing today?', 
+                engine='gtts', 
+                synthConfig={'lang': 'en', 'timeout': 10, 'tld': 'us'})
+
+        """
+        if engine not in ['gtts']:
+            raise ValueError('Unsupported TTS engine specified.')
+
+        synthConfig = {} if synthConfig is None else synthConfig
+
+        if engine == 'gtts':  # google's text-to-speech engine
+            logging.info('Using Google Text-to-Speech (gTTS) engine.')
+
+            try:
+                import gtts
+            except ImportError:
+                raise ImportError(
+                    'The gTTS package is required for speech synthesis.')
+
+            # set defaults for parameters if not specified
+            if 'timeout' not in synthConfig:
+                synthConfig['timeout'] = None
+                logging.warning(
+                    'The gTTS speech-to-text engine has been configured with '
+                    'an infinite timeout. The application may stall if the '
+                    'server is unresponsive. To set a timeout, specify the '
+                    '`timeout` key in `synthConfig`.')
+            
+            if 'lang' not in synthConfig:  # language
+                synthConfig['lang'] = 'en'
+                logging.info(
+                    "Language not specified, defaulting to '{}' for speech "
+                    "synthesis engine.".format(synthConfig['lang']))
+            else:
+                # check if the value is a valid language code
+                if synthConfig['lang'] not in gtts.lang.tts_langs():
+                    raise ValueError('Unsupported language code specified.')
+
+            if 'tld' not in synthConfig:  # top-level domain
+                synthConfig['tld'] = 'us'
+                logging.info(
+                    "Top-level domain (TLD) not specified, defaulting to '{}' "
+                    "for synthesis engine.".format(synthConfig['tld']))
+
+            if 'slow' not in synthConfig:  # slow mode
+                synthConfig['slow'] = False
+                logging.info(
+                    "Slow mode not specified, defaulting to '{}' for synthesis "
+                    "engine.".format(synthConfig['slow']))
+
+            try:
+                handle = gtts.gTTS(
+                    text=text, 
+                    **synthConfig)
+            except gtts.gTTSError as e:
+                raise AudioSynthesisError(
+                    'Error occurred during speech synthesis: {}'.format(e))
+
+            # this is online and needs a download, so we'll save it to a file
+            with tempfile.TemporaryDirectory() as tmpdir:
+                # always returns an MP3 file
+                tmpfile = str(Path(tmpdir) / 'psychopy_tts_output.mp3')
+                handle.save(tmpfile)
+
+                # load audio clip samples to memory
+                toReturn = AudioClip.load(tmpfile)
+
+                # copy the file if we want to save it
+                import shutil
+                if outFile is not None:
+                    shutil.copy(tmpfile, outFile)
+                    
+        return toReturn
+
     # --------------------------------------------------------------------------
     # Audio editing methods
     #
@@ -514,6 +654,154 @@ class AudioClip:
         arrview *= float(factor)
         arrview.clip(-1, 1)
 
+    def resample(self, targetSampleRateHz, resampleType='default', 
+            equalEnergy=False, copy=False):
+        """Resample audio to another sample rate.
+
+        This method will resample the audio clip to a new sample rate. The
+        method used for resampling can be specified using the `method` parameter.
+
+        Parameters
+        ----------
+        targetSampleRateHz : int
+            New sample rate.
+        resampleType : str
+            Fitler (or method) to use for resampling. The methods available
+            depend on the packages installed. The 'default' method uses 
+            `scipy.signal.resample` to resample the audio. Other methods require 
+            the user to install `librosa` or `resampy`. Default is 'default'.
+        equalEnergy : bool
+            Make the output have similar energy to the input. Option not
+            available for the 'default' method. Default is `False`.
+        copy : bool
+            Return a copy of the resampled audio clip at the new sample rate.
+            If `False`, the audio clip will be resampled inplace. Default is
+            `False`.
+        
+        Returns
+        -------
+        AudioClip
+            Resampled audio clip.
+
+        Notes
+        -----
+        * Resampling audio clip may result in distortion which is exacerbated by
+          successive resampling.
+        * When using `librosa` for resampling, the `fix` parameter is set to
+          `False`.
+        * The resampling types 'linear', 'zero_order_hold', 'sinc_best', 
+          'sinc_medium' and 'sinc_fastest' require the `samplerate` package to
+          be installed in addition to `librosa`.
+        * Specifying either the 'fft' or 'scipy' method will use the same
+          resampling method as the 'default' method, howwever it will allow for 
+          the `equalEnergy` option to be used.
+
+        Examples
+        --------
+        Resample an audio clip to 44.1kHz::
+
+            snd.resample(44100)
+
+        Use the 'soxr_vhq' method for resampling::
+
+            snd.resample(44100, resampleType='soxr_vhq')
+
+        Create a copy of the audio clip resampled to 44.1kHz::
+
+            sndResampled = snd.resample(44100, copy=True)
+
+        Resample the audio clip to be playable on a certain device::
+
+            import psychopy.sound as sound
+            from psychopy.sound.audioclip import AudioClip
+
+            audioClip = sound.AudioClip.load('/path/to/audio.wav')
+            
+            deviceSampleRateHz = sound.Sound().sampleRate
+            audioClip.resample(deviceSampleRateHz)
+
+        """
+        targetSampleRateHz = int(targetSampleRateHz)  # ensure it's an integer
+
+        # sample rate is the same, return self
+        if targetSampleRateHz == self._sampleRateHz:
+            if copy:
+                return AudioClip(
+                    self._samples.copy(), 
+                    sampleRateHz=self._sampleRateHz)
+
+            logging.info('No resampling needed, sample rate is the same.')
+
+            return self  # no need to resample
+
+        if resampleType == 'default':  # scipy
+            import scipy.signal  # hard dep, so we'll import here
+
+            # the simplest method to resample audio using the libraries we have
+            # already
+            nSamp = round(
+                len(self._samples) * float(targetSampleRateHz) / 
+                self.sampleRateHz)
+            newSamples = scipy.signal.resample(
+                self._samples, nSamp, axis=0)
+
+            if equalEnergy:
+                logging.warning(
+                    'The `equalEnergy` option is not available for the '
+                    'default resampling method.')
+
+        elif resampleType in ('kaiser_best', 'kaiser_fast'):  # resampy
+            try:
+                import resampy
+            except ImportError:
+                raise ImportError(
+                    'The `resampy` package is required for this resampling '
+                    'method ({}).'.format(resampleType))
+
+            newSamples = resampy.resample(
+                self._samples, 
+                self._sampleRateHz, 
+                targetSampleRateHz,
+                filter=resampleType,
+                scale=equalEnergy,
+                axis=0)
+
+        elif resampleType in ('soxr_vhq', 'soxr_hq', 'soxr_mq', 'soxr_lq', 
+                'soxr_qq', 'polyphase', 'linear', 'zero_order_hold', 'fft',
+                'scipy', 'sinc_best', 'sinc_medium', 'sinc_fastest'):  # librosa
+            try:
+                import librosa
+            except ImportError:
+                raise ImportError(
+                    'The `librosa` package is required for this resampling '
+                    'method ({}).'.format(resampleType))
+
+            newSamples = librosa.resample(
+                self._samples, 
+                orig_sr=self._sampleRateHz, 
+                target_sr=targetSampleRateHz,
+                res_type=resampleType,
+                scale=equalEnergy, 
+                fix=False,
+                axis=0)
+
+        else:
+            raise ValueError('Unsupported resampling method specified.')
+
+        logging.info(
+            "Resampled audio from {}Hz to {}Hz using method '{}'.".format(
+                self._sampleRateHz, targetSampleRateHz, resampleType))
+
+        if copy:  # return a new object
+            return AudioClip(newSamples, sampleRateHz=targetSampleRateHz)
+
+        # inplace resampling, need to clear the old array since the shape may
+        # have changed
+        self._samples = newSamples
+        self._sampleRateHz = targetSampleRateHz
+
+        return self
+
     # --------------------------------------------------------------------------
     # Audio analysis methods
     #
@@ -583,37 +871,6 @@ class AudioClip:
         self._sampleRateHz = int(value)
         # recompute duration after updating sample rate
         self._duration = len(self._samples) / float(self._sampleRateHz)
-    
-    def resample(self, targetSampleRateHz, resampleType='soxr_hq', 
-                 equalEnergy=False):
-        """Resample audio to another sample rate.
-
-        Parameters
-        ----------
-        targetSampleRateHz : int
-            New sample rate.
-        resampleType : str or None
-            Method to use for resampling. 
-        equalEnergy : bool
-            Make the output have similar energy to the input.
-
-        Notes
-        -----
-        * Resampling audio clip may result in distortion which is exacerbated by
-          successive resampling.
-
-        """
-        import librosa
-
-        self.samples = librosa.resample(
-            self.samples, 
-            self._sampleRateHz, 
-            targetSampleRateHz,
-            res_type=resampleType,
-            scale=equalEnergy, 
-            axis=0)
-
-        self.sampleRateHz = targetSampleRateHz  # update
 
     @property
     def duration(self):
@@ -719,6 +976,36 @@ class AudioClip:
         self._samples = samplesMixed  # overwrite
 
         return self
+    
+    def asStereo(self, copy=True):
+        """Convert the audio clip to stereo (two channel audio).
+
+        Parameters
+        ----------
+        copy : bool
+            If `True` an :class:`~psychopy.sound.AudioClip` containing a copy
+            of the samples will be returned. If `False`, channels will be
+            mixed inplace resulting in the same object being returned. User data
+            is not copied.
+
+        Returns
+        -------
+        :class:`~psychopy.sound.AudioClip`
+            Stereo version of this object.
+
+        """
+        if self.channels == 2:
+            return self
+
+        samples = np.atleast_2d(self._samples)  # enforce 2D
+        samples = np.hstack((samples, samples))
+
+        if copy:
+            return AudioClip(samples, self.sampleRateHz)
+
+        self._samples = samples  # overwrite
+
+        return self
 
     def transcribe(self, engine='whisper', language='en-US', expectedWords=None,
                    config=None):
@@ -826,7 +1113,7 @@ def load(filename, codec=None):
     """
     # alias default names (so it always points to default.png)
     if filename in ft.defaultStim:
-        filename = Path(prefs.paths['resources']) / ft.defaultStim[filename]
+        filename = Path(prefs.paths['assets']) / ft.defaultStim[filename]
     return AudioClip.load(filename, codec)
 
 

psychopy/sound/backend_ptb.py

@@ -86,7 +86,7 @@ def getDevices(kind=None):
     kind can be None, 'input' or 'output'
     The dict keys are names, and items are dicts of properties
     """
-    if sys.platform=='win32':
+    if sys.platform == 'win32':
         deviceTypes = 13  # only WASAPI drivers need apply!
     else:
         deviceTypes = None
@@ -97,7 +97,7 @@ def getDevices(kind=None):
         allDevs = audio.get_devices(device_type=deviceTypes)
 
     # annoyingly query_devices is a DeviceList or a dict depending on number
-    if type(allDevs) == dict:
+    if isinstance(allDevs, dict):
         allDevs = [allDevs]
 
     for ii, dev in enumerate(allDevs):
@@ -180,13 +180,13 @@ class _StreamsDict(dict):
             raise SoundFormatError(
                 "Tried to create audio stream {} but {} already exists "
                 "and {} doesn't support multiple portaudio streams"
-                    .format(label, list(self.keys())[0], sys.platform)
+                .format(label, list(self.keys())[0], sys.platform)
             )
         else:
 
             # create new stream
             self[label] = _MasterStream(sampleRate, channels, blockSize,
-                                       device=defaultOutput)
+                                        device=defaultOutput)
         return label, self[label]
 
 
@@ -209,9 +209,9 @@ class _MasterStream(audio.Stream):
         self.duplex = duplex
         self.blockSize = blockSize
         self.label = getStreamLabel(sampleRate, channels, blockSize)
-        if type(device) == list and len(device):
+        if isinstance(device, list) and len(device):
             device = device[0]
-        if type(device)==str:  # we need to convert name to an ID or make None
+        if isinstance(device, str):  # we need to convert name to an ID or make None
             devs = getDevices('output')
             if device in devs:
                 deviceID = devs[device]['DeviceIndex']
@@ -226,16 +226,16 @@ class _MasterStream(audio.Stream):
         if not systemtools.isVM_CI():  # Github Actions VM does not have a sound device
             try:
                 audio.Stream.__init__(self, device_id=deviceID, mode=mode+8,
-                                    latency_class=audioLatencyClass,
-                                    freq=sampleRate, 
-                                    channels=channels,
-                                    )  # suggested_latency=suggestedLatency
-            except OSError as e:
+                                      latency_class=audioLatencyClass,
+                                      freq=sampleRate,
+                                      channels=channels,
+                                      )  # suggested_latency=suggestedLatency
+            except OSError as e:  # noqa: F841
                 audio.Stream.__init__(self, device_id=deviceID, mode=mode+8,
-                                    latency_class=audioLatencyClass,
-                                    # freq=sampleRate, 
-                                    channels=channels,
-                                    )
+                                      latency_class=audioLatencyClass,
+                                      # freq=sampleRate,
+                                      channels=channels,
+                                      )
                 self.sampleRate = self.status['SampleRate']
                 print("Failed to start PTB.audio with requested rate of "
                       "{} but succeeded with a default rate ({}). "
@@ -244,14 +244,14 @@ class _MasterStream(audio.Stream):
             except TypeError as e:
                 print("device={}, mode={}, latency_class={}, freq={}, channels={}"
                       .format(device, mode+8, audioLatencyClass, sampleRate, channels))
-                raise(e)
+                raise e
             except Exception as e:
                 audio.Stream.__init__(self, mode=mode+8,
-                                    latency_class=audioLatencyClass,
-                                    freq=sampleRate, 
-                                    channels=channels,
-                                    )
-                
+                                      latency_class=audioLatencyClass,
+                                      freq=sampleRate,
+                                      channels=channels,
+                                      )
+
                 if "there isn't any audio output device" in str(e):
                     print("Failed to load audio device:\n"
                           "    '{}'\n"
@@ -329,7 +329,7 @@ class SoundPTB(_SoundBase):
         self.sndArr = None
         self.hamming = hamming
         self._hammingWindow = None  # will be created during setSound
-        self.win=syncToWin
+        self.win = syncToWin
         # setSound (determines sound type)
         self.setSound(value, secs=self.secs, octave=self.octave,
                       hamming=self.hamming)
@@ -340,12 +340,14 @@ class SoundPTB(_SoundBase):
     @property
     def isPlaying(self):
         """`True` if the audio playback is ongoing."""
+        # This will update _isPlaying if sound has stopped by _EOS()
+        _ = self._checkPlaybackFinished()
         return self._isPlaying
 
     @property
     def isFinished(self):
         """`True` if the audio playback has completed."""
-        return self._isFinished
+        return self._checkPlaybackFinished()
 
     def _getDefaultSampleRate(self):
         """Check what streams are open and use one of these"""
@@ -360,27 +362,6 @@ class SoundPTB(_SoundBase):
             return None
         return self.track.status
 
-    @property
-    def status(self):
-        """status gives a simple value from psychopy.constants to indicate
-        NOT_STARTED, STARTED, FINISHED, PAUSED
-
-        Psychtoolbox sounds also have a statusDetailed property with further info"""
-
-        if self.__dict__['status']==STARTED:
-            # check portaudio to see if still playing
-            pa_status = self.statusDetailed
-            if not pa_status['Active'] and pa_status['State']==0:
-                # we were playing and now not so presumably FINISHED
-                self._EOS()
-
-        return self.__dict__['status']
-
-
-    @status.setter
-    def status(self, newStatus):
-        self.__dict__['status'] = newStatus
-
     @property
     def volume(self):
         return self.__dict__['volume']
@@ -403,9 +384,9 @@ class SoundPTB(_SoundBase):
     @stereo.setter
     def stereo(self, val):
         self.__dict__['stereo'] = val
-        if val == True:
+        if val is True:
             self.__dict__['channels'] = 2
-        elif val == False:
+        elif val is False:
             self.__dict__['channels'] = 1
         elif val == -1:
             self.__dict__['channels'] = -1
@@ -444,7 +425,7 @@ class SoundPTB(_SoundBase):
     def _setSndFromFile(self, filename):
         # alias default names (so it always points to default.png)
         if filename in ft.defaultStim:
-            filename = Path(prefs.paths['resources']) / ft.defaultStim[filename]
+            filename = Path(prefs.paths['assets']) / ft.defaultStim[filename]
         self.sndFile = f = sf.SoundFile(filename)
         self.sourceType = 'file'
         self.sampleRate = f.samplerate
@@ -479,7 +460,6 @@ class SoundPTB(_SoundBase):
         self._channelCheck(
             self.sndArr)  # Check for fewer channels in stream vs data array
 
-
     def _setSndFromArray(self, thisArray):
 
         self.sndArr = np.asarray(thisArray).astype('float32')
@@ -529,12 +509,20 @@ class SoundPTB(_SoundBase):
                 "experiment settings**".format(self.channels, array.shape[1]))
             logging.error(msg)
             raise ValueError(msg)
-        
+
     def _checkPlaybackFinished(self):
         """Checks whether playback has finished by looking up the status.
         """
+        # get detailed status from backend
         pa_status = self.statusDetailed
-        self._isFinished = not pa_status['Active'] and pa_status['State'] == 0
+        # was the sound already finished?
+        wasFinished = self._isFinished
+        # is it finished now?
+        isFinished = self._isFinished = not pa_status['Active'] and pa_status['State'] == 0
+        # if it wasn't finished but now is, do end of stream behaviour
+        if isFinished and not wasFinished:
+            self._EOS()
+
         return self._isFinished
 
     def play(self, loops=None, when=None, log=True):
@@ -546,7 +534,7 @@ class SoundPTB(_SoundBase):
         """
         if self._checkPlaybackFinished():
             self.stop(reset=True)
-        
+
         if loops is not None and self.loops != loops:
             self.setLoops(loops)
 
@@ -570,8 +558,8 @@ class SoundPTB(_SoundBase):
     def pause(self, log=True):
         """Stops the sound without reset, so that play will continue from here if needed
         """
-        if self.isPlaying:
-            self.stop(reset=False)
+        if self._isPlaying:
+            self.stop(reset=False, log=False)
             if log and self.autoLog:
                 logging.exp(u"Sound %s paused" % (self.name), obj=self)
 
@@ -579,7 +567,7 @@ class SoundPTB(_SoundBase):
         """Stop the sound and return to beginning
         """
         # this uses FINISHED for some reason, all others use STOPPED
-        if not self.isPlaying:
+        if not self._isPlaying:
             return
 
         self.track.stop()
@@ -601,11 +589,12 @@ class SoundPTB(_SoundBase):
         """Function called on End Of Stream
         """
         self._loopsFinished += 1
-        if self.loops == 0:
-            self.stop(reset=reset, log=False)
-            self._isFinished = True
-        elif 0 < self.loops <= self._loopsFinished:
+        if self._loopsFinished >= self._loopsRequested:
+            # if we have finished all requested loops
             self.stop(reset=reset, log=False)
+        else:
+            # reset _isFinished back to False
+            self._isFinished = False
 
         if log and self.autoLog:
             logging.exp(u"Sound %s reached end of file" % self.name, obj=self)

psychopy/sound/backend_pygame.py

@@ -269,7 +269,7 @@ class SoundPygame(_SoundBase):
     def _setSndFromFile(self, fileName):
         # alias default names (so it always points to default.png)
         if fileName in ft.defaultStim:
-            fileName = Path(prefs.paths['resources']) / ft.defaultStim[fileName]
+            fileName = Path(prefs.paths['assets']) / ft.defaultStim[fileName]
         # load the file
         if not path.isfile(fileName):
             msg = "Sound file %s could not be found." % fileName