psychopy 2024.2.5__py3-none-any.whl → 2025.1.0__py3-none-any.whl

psychopy/sound/_base.py

@@ -2,22 +2,29 @@
 # -*- coding: utf-8 -*-
 
 # Part of the PsychoPy library
-# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2024 Open Science Tools Ltd.
+# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2025 Open Science Tools Ltd.
 # Distributed under the terms of the GNU General Public License (GPL).
 
+from pathlib import Path
 import numpy
 import copy
+import itertools
 from os import path
 from psychopy import logging
 from psychopy.constants import (STARTED, PLAYING, PAUSED, FINISHED, STOPPED,
                                 NOT_STARTED, FOREVER)
 from psychopy.tools.filetools import pathToString, defaultStim, defaultStimRoot
 from psychopy.tools.audiotools import knownNoteNames, stepsFromA
-from psychopy.tools.attributetools import AttributeGetSetMixin
+from psychopy.tools.attributetools import AttributeGetSetMixin, attributeSetter
+from .exceptions import SoundFormatError, DependencyError
 from sys import platform
 from .audioclip import AudioClip
 from ..hardware import DeviceManager
 from ..preferences.preferences import prefs
+try:
+    import soundfile as sf
+except Exception:
+    raise DependencyError("soundfile not working")
 
 if platform == 'win32':
     mediaLocation = "C:\\Windows\\Media"
@@ -115,27 +122,7 @@ class _SoundBase(AttributeGetSetMixin):
     # def _setSndFromFile(self, fileName):
     # def _setSndFromArray(self, thisArray):
 
-    def _parseSpeaker(self, speaker):
-        if speaker is None:
-            # if no device, populate from prefs
-            pref = prefs.hardware['audioDevice']
-            if isinstance(pref, (list, tuple)):
-                pref = pref[0]
-            speaker = pref
-        # look for device if initialised
-        device = DeviceManager.getDevice(speaker)
-        # if no matching name, try matching index
-        if device is None:
-            device = DeviceManager.getDeviceBy("index", speaker)
-        # if still no match, make a new device
-        if device is None:
-            device = DeviceManager.addDevice(
-                deviceClass="psychopy.hardware.speaker.SpeakerDevice",
-                deviceName=speaker,
-                index=speaker,
-            )
-
-        return device
+    autoLog = True
 
     def setSound(self, value, secs=0.5, octave=4, hamming=True, log=True):
         """Set the sound to be played.
@@ -169,10 +156,12 @@ class _SoundBase(AttributeGetSetMixin):
         """
         # Re-init sound to ensure bad values will raise error during setting:
         self._snd = None
-
+        # make references to default stim into absolute paths
         if isinstance(value, str) and value in defaultStim:
             value = defaultStimRoot / defaultStim[value]
-
+        # if directly given a Microphone, get its last recording
+        if hasattr(value, "lastClip"):
+            value = value.lastClip
         # Coerces pathlib obj to string, else returns inputted value
         value = pathToString(value)
         try:
@@ -194,19 +183,20 @@ class _SoundBase(AttributeGetSetMixin):
             else:
                 # try finding a file
                 self.fileName = None
-                for filePath in ['', mediaLocation]:
-                    p = path.join(filePath, value)
-                    if path.isfile(p):
-                        self.fileName = p
-                        break
-                    elif path.isfile(p + '.wav'):
-                        self.fileName = p = p + '.wav'
+                valid_paths = ['', mediaLocation]
+                valid_endings = ['', '.wav', '.mp3', '.flac', '.ogg']
+                for pre, suf in itertools.product(valid_paths, valid_endings):
+                    media_filepath = path.join(pre, value)
+                    if path.isfile(media_filepath + suf):
+                        self.fileName = media_filepath + suf
                         break
+
                 if self.fileName is None:
                     msg = "setSound: could not find a sound file named "
                     raise ValueError(msg + value)
                 else:
-                    self._setSndFromFile(p)
+                    self._setSndFromFile(self.fileName)
+
         elif isinstance(value, (list, numpy.ndarray,)):
             # create a sound from the input array/list
             self._setSndFromArray(numpy.array(value))
@@ -216,7 +206,7 @@ class _SoundBase(AttributeGetSetMixin):
                 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)) 
+                    "not match the device settings.".format(value.sampleRateHz))
 
                 self.sampleRate = value.sampleRateHz
 
@@ -239,6 +229,29 @@ class _SoundBase(AttributeGetSetMixin):
                 logging.exp("Set %s sound=%s" % (self.name, value), obj=self)
             self.status = NOT_STARTED
 
+    @attributeSetter
+    def sampleRate(self, sampleRate):
+        # if given None, use sample rate from speaker
+        if sampleRate is None and hasattr(self.speaker, "sampleRateHz"):
+            sampleRate = self.speaker.sampleRateHz
+        # set as normal
+        self.__dict__['sampleRate'] = sampleRate
+
+    # alias channels, stereo and isStereo for the sake of the different backends
+
+    @attributeSetter
+    def channels(self, channels):
+        self.__dict__['channels'] = channels
+        self.__dict__['stereo'] = self.__dict__['isStereo'] = channels is None or channels > 1
+
+    @attributeSetter
+    def stereo(self, stereo):
+        self.channels = 2 if stereo else 1
+
+    @attributeSetter
+    def isStereo(self, stereo):
+        self.stereo = stereo
+
     def _setSndFromNote(self, thisNote, secs, octave, hamming=True):
         # note name -> freq -> sound
         freqA = 440.0
@@ -263,6 +276,93 @@ class _SoundBase(AttributeGetSetMixin):
             outArr = apodize(outArr, self.sampleRate)
         self._setSndFromArray(outArr)
 
+    def _setSndFromFile(self, filename):
+        # alias default names (so it always points to default.png)
+        if filename in defaultStim:
+            filename = Path(prefs.paths['assets']) / defaultStim[filename]
+        self.sndFile = f = sf.SoundFile(filename)
+        self.sourceType = 'file'
+        self.sampleRate = f.samplerate
+        if self.channels == -1:  # if channels was auto then set to file val
+            self.channels = f.channels
+        fileDuration = float(len(f)) / f.samplerate  # needed for duration?
+        # process start time
+        if self.startTime and self.startTime > 0:
+            startFrame = self.startTime * self.sampleRate
+            self.sndFile.seek(int(startFrame))
+            self.t = self.startTime
+        else:
+            self.t = 0
+        # process stop time
+        if self.stopTime and self.stopTime > 0:
+            requestedDur = self.stopTime - self.t
+            self.duration = min(requestedDur, fileDuration)
+        else:
+            self.duration = fileDuration - self.t
+        # can now calculate duration in frames
+        self.durationFrames = int(round(self.duration * self.sampleRate))
+        # are we preloading or streaming?
+        if self.preBuffer == 0:
+            # no buffer - stream from disk on each call to nextBlock
+            pass
+        elif self.preBuffer == -1:
+            # full pre-buffer. Load requested duration to memory
+            sndArr = self.sndFile.read(
+                frames=int(self.sampleRate * self.duration))
+            self.sndFile.close()
+            self._setSndFromArray(sndArr)
+        self._channelCheck(
+            self.sndArr)  # Check for fewer channels in stream vs data array
+
+    def _setSndFromArray(self, thisArray):
+        self.sndArr = numpy.asarray(thisArray).astype('float32')
+        if thisArray.ndim == 1:
+            self.sndArr.shape = [len(thisArray), 1]  # make 2D for broadcasting
+
+        # is this stereo?
+        if self.stereo == -1:  # auto stereo. Try to detect
+            if self.sndArr.shape[1] == 1:
+                self.stereo = 0
+            elif self.sndArr.shape[1] == 2:
+                self.stereo = 1
+            else:
+                raise IOError("Couldn't determine whether array is "
+                              "stereo. Shape={}".format(self.sndArr.shape))
+        # store details about array
+        self._nSamples = thisArray.shape[0]
+        self.sourceType = "array"
+
+        # catch when array is empty
+        if not len(self.sndArr):
+            logging.warning(
+                "Received a blank array for sound, playing nothing instead."
+            )
+            self.sndArr = numpy.zeros(shape=(self.blockSize, self.channels))
+
+        # create audio clip
+        clip = AudioClip(
+            samples=self.sndArr,
+            sampleRateHz=self.sampleRate
+        )
+        # set from clip
+        self._setSndFromClip(clip)
+
+    def _setSndFromClip(self, clip: AudioClip):
+        """
+        Set current sound from an AudioClip object. All other setSound methods eventually lead to
+        this - they just transform the given sound (be it an array, file, note, etc.) to an
+        AudioClip first.
+
+        Each subclass of _SoundBase (so each sound backend; ptb, pygame, etc.) will implement this
+        method in their own way.
+
+        Parameters
+        ----------
+        clip : AudioClip
+            AudioClip object to set.
+        """
+        raise NotImplementedError()
+
     def _getDefaultSampleRate(self):
         """For backends this might depend on what streams are open"""
         return 44100

psychopy/sound/audioclip.py

@@ -5,7 +5,7 @@
 """
 
 # Part of the PsychoPy library
-# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2024 Open Science Tools Ltd.
+# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2025 Open Science Tools Ltd.
 # Distributed under the terms of the GNU General Public License (GPL).
 
 __all__ = [
@@ -45,6 +45,11 @@ AUDIO_CHANNEL_RIGHT = AUDIO_EAR_RIGHT = 1
 AUDIO_CHANNEL_COUNT = AUDIO_EAR_COUNT = 2
 
 
+class AudioSynthesisError(Exception):
+    """Error raised when an issue occurs during audio synthesis."""
+    pass
+
+
 class AudioClip:
     """Class for storing audio clip data.
 
@@ -204,12 +209,16 @@ class AudioClip:
         """
         if codec is not None:
             AudioClip._checkCodecSupported(codec, raiseError=True)
-
+        # write file
         sf.write(
             filename,
             data=self._samples,
             samplerate=self._sampleRateHz,
             format=codec)
+        # log
+        logging.info(
+            f"Saved audio data to {filename}"
+        )
 
     # --------------------------------------------------------------------------
     # Tone and noise generation methods
@@ -573,6 +582,8 @@ class AudioClip:
         self._samples = np.ascontiguousarray(
             np.vstack((self._samples, other.samples)),
             dtype=np.float32)
+        
+        self._duration = len(self.samples) / float(self.sampleRateHz)
 
         return self
 
@@ -830,9 +841,10 @@ class AudioClip:
         """
         if channel is not None:
             assert 0 < channel < self.channels
-
+        # get samples
         arr = self._samples if channel is None else self._samples[:, channel]
-        rms = np.sqrt(np.mean(np.square(arr), axis=0))
+        # calculate rms
+        rms = np.nan_to_num(np.sqrt(np.nanmean(np.square(arr), axis=0)), nan=0)
 
         return rms if len(rms) > 1 else rms[0]
 
@@ -963,18 +975,25 @@ class AudioClip:
             Mono version of this object.
 
         """
-        samples = np.atleast_2d(self._samples)  # enforce 2D
+        if self.channels == 1:
+            return self
+        # log
+        logging.debug(
+            "Converted audio clip from stereo to mono"
+        )
+        # enforce 2D
+        samples = np.atleast_2d(self._samples)
+        # reduce to mono
         if samples.shape[1] > 1:
             samplesMixed = np.atleast_2d(
                 np.sum(samples, axis=1, dtype=np.float32) / np.float32(2.)).T
         else:
             samplesMixed = samples.copy()
-
+        # create copy if requested
         if copy:
             return AudioClip(samplesMixed, self.sampleRateHz)
-
-        self._samples = samplesMixed  # overwrite
-
+        # otherwise change self
+        self._samples = samplesMixed
         return self
     
     def asStereo(self, copy=True):
@@ -996,15 +1015,19 @@ class AudioClip:
         """
         if self.channels == 2:
             return self
-
-        samples = np.atleast_2d(self._samples)  # enforce 2D
+        # log
+        logging.debug(
+            "Converted audio clip from mono to stereo"
+        )
+        # enforce 2D
+        samples = np.atleast_2d(self._samples) 
+        # expand to stereo
         samples = np.hstack((samples, samples))
-
+        # create copy if requested
         if copy:
             return AudioClip(samples, self.sampleRateHz)
-
-        self._samples = samples  # overwrite
-
+        # otherwise change self
+        self._samples = samples
         return self
 
     def transcribe(self, engine='whisper', language='en-US', expectedWords=None,

psychopy/sound/audiodevice.py

@@ -5,7 +5,7 @@
 """
 
 # Part of the PsychoPy library
-# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2024 Open Science Tools Ltd.
+# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2025 Open Science Tools Ltd.
 # Distributed under the terms of the GNU General Public License (GPL).
 
 __all__ = [