psychopy 2025.1.1__py3-none-any.whl → 2025.2.1__py3-none-any.whl

psychopy/scripts/psyexpCompile.py

@@ -143,7 +143,7 @@ def compileScript(infile=None, version=None, outfile=None):
             The experiment object used for generating the experiment script
         """
         # import PsychoPy experiment and write script with useVersion active
-        from psychopy.app.builder import experiment
+        from psychopy import experiment
         # Check infile type
         if isinstance(infile, experiment.Experiment):
             thisExp = infile

psychopy/session.py

@@ -256,6 +256,8 @@ class Session:
         ):
         # Store root and add to Python path
         self.root = Path(root)
+        if not self.root.is_absolute():
+            self.root = self.root.absolute()
         sys.path.insert(1, str(self.root))
         # store rest message
         self.restMsg = restMsg
@@ -962,44 +964,7 @@ class Session:
                 f"Device names are not available for experiments added to Session directly as a "
                 f".py file."
             )
-        # get ready to store usages
-        usages = {}
-
-        def _process(name, emt):
-            """
-            Process an element (Component or Routine) for device names and append them to the
-            usages dict.
-
-            Parameters
-            ----------
-            name : str
-                Name of this element in Builder
-            emt : Component or Routine
-                Element to process
-            """
-            # if we have a device name for this element...
-            if "deviceLabel" in emt.params:
-                # get init value so it lines up with boilerplate code
-                inits = experiment.getInitVals(emt.params)
-                # get value
-                deviceName = inits['deviceLabel'].val
-                # if deviceName exists from other elements, add usage to it
-                if deviceName in usages:
-                    usages[deviceName].append(name)
-                else:
-                    usages[deviceName] = [name]
-
-        # iterate through routines
-        for rtName, rt in exp.routines.items():
-            if isinstance(rt, experiment.routines.BaseStandaloneRoutine):
-                # for standalone routines, get device names from params
-                _process(rtName, rt)
-            else:
-                # for regular routines, get device names from each component
-                for comp in rt:
-                    _process(comp.name, comp)
-
-        return list(usages)
+        return exp.getRequiredDeviceNames()
 
     def runExperiment(self, key, expInfo=None, blocking=True):
         """
@@ -1264,6 +1229,13 @@ class Session:
 
         # set ExperimentHandler status to PAUSED
         self.currentExperiment.pause()
+        # update Liaison if needed
+        if self.liaison is not None:
+            self.sendToLiaison({
+                'type': "experiment_status",
+                'name': self.currentExperiment.name,
+                'status': self.currentExperiment.status,
+            })
 
         return True
 
@@ -1285,6 +1257,13 @@ class Session:
             return False
         # set ExperimentHandler status to STARTED
         self.currentExperiment.resume()
+        # update Liaison if needed
+        if self.liaison is not None:
+            self.sendToLiaison({
+                'type': "experiment_status",
+                'name': self.currentExperiment.name,
+                'status': self.currentExperiment.status,
+            })
 
         return True
 
@@ -1305,8 +1284,25 @@ class Session:
             )
             return False
         self.currentExperiment.stop()
+        # update Liaison if needed
+        if self.liaison is not None:
+            self.sendToLiaison({
+                'type': "experiment_status",
+                'name': self.currentExperiment.name,
+                'status': self.currentExperiment.status,
+            })
 
         return True
+    
+    def next(self):
+        """
+        Move on to either the next trial (if in a trials loop) or the next Routine.
+        """
+        # return if there's no current experiment
+        if self.currentExperiment is None:
+            return
+        # skip trials in current loop
+        return self.currentExperiment.next()
 
     def skipTrials(self, n=1):
         """

psychopy/sound/__init__.py

@@ -34,271 +34,17 @@ After importing sound, the sound lib and driver being used will be stored as::
 # Distributed under the terms of the GNU General Public License (GPL).
 
 import sys
-import os
-import traceback
-from psychopy import logging, prefs, constants
-from psychopy.tools import systemtools
-from .exceptions import DependencyError, SoundFormatError
 from .audiodevice import *
 from .audioclip import *  # import objects related to AudioClip
-from . import microphone
+from . import microphone, sound
+from .sound import Sound
 
-__all__ = ["microphone"]
+__all__ = [
+    "microphone",
+    "Sound"
+]
 
-# # import transcription if possible
-# try:
-#     from .transcribe import *  # import transcription engine stuff
-# except ImportError as err:
-#     formatted_tb = ''.join(
-#         traceback.format_exception(type(err), err, err.__traceback__))
-#     logging.error(
-#         "Failed to import psychopy.sound.transcribe. Transcription will not be"
-#         "possible on this machine. For details see stack trace below:\n"
-#         f"{formatted_tb}")
 
 # used to check if we are on 64-bit Python
 bits32 = sys.maxsize == 2 ** 32
 
-# Globals for the sound library. We can only load one audio library at a time,
-# so once these values are populated they cannot be changed without restarting
-# Python.
-pyoSndServer = None
-Sound = None
-audioLib = None
-audioDriver = None
-backend = None
-
-# These are the names that can be used in the prefs to specifiy audio libraries.
-# The available libraries are hard-coded at this point until we can overhaul
-# the sound library to be more modular.
-_audioLibs = ['ptb', 'sounddevice', 'pyo', 'pysoundcard', 'pygame']
-failed = []  # keep track of audio libs that failed to load
-
-# check if this is being imported on Travis/Github (has no audio card)
-if systemtools.isVM_CI():
-    # for sounddevice we built in some VM protection but not in pyo
-    prefs.hardware['audioLib'] = ['ptb', 'sounddevice']
-
-# ensure that the value for `audioLib` is a list
-if isinstance(prefs.hardware['audioLib'], str):
-    prefs.hardware['audioLib'] = [prefs.hardware['audioLib']]
-
-thisLibName = None  # name of the library we are trying to load
-
-# selection and fallback mechanism for audio libraries
-for thisLibName in prefs.hardware['audioLib']:
-    # Tell the user we are trying to load the specifeid audio library
-    logging.info(f"Trying to load audio library: {thisLibName}")
-
-    # Iterate over the list of audioLibs and try to load the first one that
-    # is supported. If none are supported, load PTB as a fallback. If PTB isn't
-    # installed, raise an error.
-    thisLibName = thisLibName.lower()
-
-    # lowercased list of valid audio libraries for safe comparisons
-    validLibs = [libName.lower() for libName in _audioLibs]
-
-    # check if `thisLibName` is a valid audio library
-    if thisLibName not in validLibs:
-        failed.append(thisLibName)
-        logging.warning(f"Invalid audioLib pref: {thisLibName}. "
-                        f"Valid options are: {_audioLibs}")
-        continue
-
-    # select the backend and set the Sound class
-    if thisLibName == 'ptb':
-        # The Psychtoolbox backend is preferred, provides the best performance
-        # and is the only one that supports low-latency scheduling. If no other
-        # audio backend can be loaded, we will use PTB.
-        if not bits32:
-            try:
-                from . import backend_ptb as backend
-                Sound = backend.SoundPTB
-                audioDriver = backend.audioDriver
-            except Exception as err:
-                failed.append(thisLibName)
-                continue
-            else:
-                break
-        else:
-            logging.warning("PTB backend is not supported on 32-bit Python. "
-                            "Trying another backend...")
-            continue
-    elif thisLibName == 'pyo':
-        # pyo is a wrapper around PortAudio, which is a cross-platform audio
-        # library. It is the recommended backend for Windows and Linux.
-        try:
-            # Caution: even import failed inside, we still get a module object.
-            # This is not the case for other backends and may not be desired.
-            from . import backend_pyo as backend
-            Sound = backend.SoundPyo
-            pyoSndServer = backend.pyoSndServer
-            audioDriver = backend.audioDriver
-        except Exception:
-            failed.append(thisLibName)
-            continue
-        else:
-            break
-    elif thisLibName == 'sounddevice':
-        # sounddevice is a wrapper around PortAudio, which is a cross-platform
-        # audio library. It is the recommended backend for Windows and Linux.
-        try:
-            # Caution: even import failed inside, we still get a module object.
-            # This is not the case for other backends and may not be desired.
-            from . import backend_sounddevice as backend
-            Sound = backend.SoundDeviceSound
-        except Exception:
-            failed.append(thisLibName)
-            continue
-        else:
-            break
-    elif thisLibName == 'pygame':
-        # pygame is a cross-platform audio library. It is no longer supported by
-        # PsychoPy, but we keep it here for backwards compatibility until
-        # something breaks.
-        try:
-            from . import backend_pygame as backend
-            Sound = backend.SoundPygame
-        except Exception:
-            failed.append(thisLibName)
-            continue
-        else:
-            break
-    elif thisLibName == 'pysoundcard':
-        # pysoundcard is a wrapper around PortAudio, which is a cross-platform
-        # audio library.
-        try:
-            from . import backend_pysound as backend
-            Sound = backend.SoundPySoundCard
-        except Exception:
-            failed.append(thisLibName)
-            continue
-        else:
-            break
-    else:
-        # Catch-all for invalid audioLib prefs.
-        msg = ("audioLib pref should be one of {!r}, not {!r}"
-               .format(_audioLibs, thisLibName))
-        raise ValueError(msg)
-else:
-    # if we get here, there is no audioLib that is supported, try for PTB
-    msg = ("Failed to load any of the audioLibs: {!r}. Falling back to "
-           "PsychToolbox ('ptb') backend for sound. Be sure to add 'ptb' to "
-           "preferences to avoid seeing this message again.".format(failed))
-    logging.error(msg)
-    try:
-        from . import backend_ptb as backend
-        Sound = backend.SoundPTB
-        audioDriver = backend.audioDriver
-    except Exception:
-        failed.append(thisLibName)
-
-
-# we successfully loaded a backend if `Sound` is not None
-if Sound is not None:
-    audioLib = thisLibName
-    init = backend.init
-    getDevices = None
-    if audioLib != 'ptb' and hasattr(backend, 'getDevices'):
-        getDevices = backend.getDevices
-    else:
-        import psychopy.hardware.speaker as speaker
-
-        def _getDevices(*args, **kwargs):  # for matching function signiture
-            allDevices = speaker.SpeakerDevice.getAvailableDevices()
-            return [dev['name'] for dev in allDevices]
-
-        getDevices = _getDevices
-
-    logging.info('sound is using audioLib: %s' % audioLib)
-else:
-    # if we get here, there is no audioLib that is supported
-    logging.error(
-        "No audioLib could be loaded. Tried: {}\n Check whether the necessary "
-        "audioLibs are installed.".format(prefs.hardware['audioLib']))
-
-# warn the user
-if audioLib is not None:
-    if audioLib.lower() != 'ptb':
-        # Could be running PTB, just aren't?
-        logging.warning("We strongly recommend you activate the PTB sound "
-                        "engine in PsychoPy prefs as the preferred audio "
-                        "engine. Its timing is vastly superior. Your prefs "
-                        "are currently set to use {} (in that order)."
-                        .format(prefs.hardware['audioLib']))
-
-
-# function to set the device (if current lib allows it)
-def setDevice(dev, kind=None):
-    """Sets the device to be used for new streams being created.
-
-    Parameters
-    ----------
-    dev: str or dict
-        Name of the device to be used (name, index or sounddevice.device)
-    kind: str
-        One of [None, 'output', 'input']
-
-    """
-    if dev is None:
-        # if given None, do nothing
-        return
-
-    global backend  # pull from module namespace
-    if not hasattr(backend, 'defaultOutput'):
-        raise IOError("Attempting to SetDevice (audio) but not supported by "
-                      "the current audio library ({!r})".format(audioLib))
-
-    if hasattr(dev, 'name'):
-        dev = dev['name']
-
-    if kind is None:
-        backend.defaultInput = backend.defaultOutput = dev
-    elif kind == 'input':
-        backend.defaultInput = dev
-    elif kind == 'output':
-        backend.defaultOutput = dev
-    else:
-        if systemtools.isVM_CI():  # no audio device on CI, ignore
-            return
-        else:
-            raise TypeError("`kind` should be one of [None, 'output', 'input'] "
-                            "not {!r}".format(kind))
-
-
-# Set the device according to user prefs (if current lib allows it)
-deviceNames = []
-if backend is None:
-    raise ImportError("None of the audio library backends could be imported. "
-                      "Tried: {}\n Check whether the necessary audioLibs are "
-                      "installed and can be imported successfully."
-                      .format(prefs.hardware['audioLib']))
-elif hasattr(backend, 'defaultOutput'):
-    pref = prefs.hardware['audioDevice']
-    # is it a list or a simple string?
-    if isinstance(pref, list):
-        # multiple options so use zeroth
-        dev = pref[0]
-    else:
-        # a single option
-        dev = pref
-    # is it simply "default" (do nothing)
-    if dev == 'default' or systemtools.isVM_CI():
-        pass  # do nothing
-    elif getDevices is not None:
-        devices = getDevices(kind='output')
-        if type(devices) is dict:
-            deviceNames = sorted(devices.keys())
-        else:
-            deviceNames = sorted(devices)
-        if dev not in devices:
-            logging.warn(
-                u"Requested audio device '{}' that is not available on "
-                "this hardware. The 'audioDevice' preference should be one of "
-                "{}".format(dev, deviceNames))
-    else:
-        setDevice(dev, kind='output')
-
-
-if __name__ == "__main__":
-    pass

psychopy/sound/audioclip.py

@@ -812,7 +812,165 @@ class AudioClip:
         self._sampleRateHz = targetSampleRateHz
 
         return self
+    
+    def pad(self, direction='start', duration=1.0, units='seconds'):
+        """Pad the audio clip with silence at the start or end.
+
+        This method will modify the audio clip inplace, adding samples of
+        silence to the specified location.
+
+        Parameters
+        ----------
+        direction : str
+            Where to add the padding. Can be 'start' or 'end'. Default is 'start'.
+        duration : float or int
+            Duration of the padding in seconds. Default is `1.0`.
+        units : str
+            Units to interpret the `duration` parameter as. Can be 'seconds' or
+            'samples'. Default is 'seconds'.
+
+        Returns
+        -------
+        AudioClip
+            This audio clip object with padding added at the specified location.
+        
+        """
+        # convert duration to samples
+        if units == 'seconds':
+            padSamples = int(duration * self.sampleRateHz)
+        elif units == 'samples':
+            padSamples = int(duration)
+        else:
+            raise ValueError(
+                "Invalid value for `units`. Must be 'seconds' or 'samples'.")
+
+        # create padding samples
+        padding = np.zeros((padSamples, self.channels), dtype=np.float32)
+
+        if direction == 'start':
+            self._samples = np.vstack((padding, self._samples))
+        elif direction == 'end':
+            self._samples = np.vstack((self._samples, padding))
+        else:
+            raise ValueError(
+                "Invalid value for `direction`. Must be 'start' or 'end'.")
+        
+        # ensure the samples are contiguous and right dtype
+        self._samples = np.ascontiguousarray(self._samples, dtype=np.float32)
+
+        # recompute the duration of the new clip
+        self._duration = len(self.samples) / float(self.sampleRateHz)
+
+        return self
+    
+    def padded(self, direction='start', duration=1.0, units='seconds'):
+        """Return a new audio clip with padding added at the start or end.
+
+        This method will return a new audio clip with samples of silence added
+        to the specified location. The original audio clip will not be modified.
+
+        Parameters
+        ----------
+        direction : str
+            Where to add the padding. Can be 'start' or 'end'. Default is 'start'.
+        duration : float or int
+            Duration of the padding in seconds. Default is `1.0`.
+        units : str
+            Units to interpret the `duration` parameter as. Can be 'seconds' or
+            'samples'. Default is 'seconds'.
+
+        Returns
+        -------
+        AudioClip
+            A new audio clip with padding added at the specified location.
+        
+        """
+        # create a copy of the audio clip
+        newClip = self.copy()
+
+        # pad the copy
+        return newClip.pad(direction, duration, units)
+
+    def trim(self, direction='start', duration=1.0, units='seconds'):
+        """Trim the audio clip by removing samples from the start or end.
+
+        This method will modify the audio clip inplace, trimming off samples 
+        from the specfied direction.
 
+        Parameters
+        ----------
+        direction : str
+            Where to remove audio samples from. Can be 'start' or 'end'. Default
+            is 'start'.
+        duration : float or int
+            How many samples to remove from the start or end of the audio clip.
+        units : str
+            Units to interpret the `duration` parameter as. Can be 'seconds' or
+            'samples'. Default is 'seconds'.
+
+        Returns
+        -------
+        AudioClip
+            This audio clip object with padding removed at the specified 
+            location.
+        
+        """
+        # convert duration to samples
+        if units == 'seconds':
+            trimSamples = int(duration * self.sampleRateHz)
+        elif units == 'samples':
+            trimSamples = int(duration)
+        else:
+            raise ValueError(
+                "Invalid value for `units`. Must be 'seconds' or 'samples'.")
+
+        if direction == 'start':
+            self._samples = self._samples[trimSamples:, :]
+        elif direction == 'end':
+            self._samples = self._samples[:-trimSamples, :]
+        else:
+            raise ValueError(
+                "Invalid value for `direction`. Must be 'start' or 'end'.")
+        
+        # ensure the samples are contiguous and right dtype
+        self._samples = np.ascontiguousarray(self._samples, dtype=np.float32)
+
+        # recompute the duration of the new clip
+        self._duration = len(self.samples) / float(self.sampleRateHz)
+
+        return self
+    
+    def trimmed(self, direction='start', duration=1.0, units='seconds'):
+        """Return a new audio clip with samples removed from the start or end.
+
+        This method will return a new audio clip with samples of silence removed
+        from the specified location. The original audio clip will not be 
+        modified.
+
+        Parameters
+        ----------
+        direction : str
+            Where to remove audio samples from. Can be 'start' or 'end'. Default
+            is 'start'.
+        duration : float or int
+            How many samples to remove from the start or end of the audio clip.
+        units : str
+            Units to interpret the `duration` parameter as. Can be 'seconds' or
+            'samples'. Default is 'seconds'.
+
+        Returns
+        -------
+        AudioClip
+            A new audio clip with padding removed at the specified location.
+        
+        """
+        # create a copy of the audio clip
+        newClip = self.copy()
+
+        # trim the copy
+        return newClip.trim(direction, duration, units)
+
+    
     # --------------------------------------------------------------------------
     # Audio analysis methods
     #
@@ -884,6 +1042,12 @@ class AudioClip:
         # recompute duration after updating sample rate
         self._duration = len(self._samples) / float(self._sampleRateHz)
 
+    @property
+    def totalSamples(self):
+        """Total number of audio samples stored in this object (`int`).
+        """
+        return self._samples.shape[0]  # number of rows
+
     @property
     def duration(self):
         """The duration of the audio in seconds (`float`).

psychopy/sound/backend_ptb.py

@@ -34,6 +34,11 @@ except Exception:
 
 import numpy as np
 
+__all__ = [
+    "SoundPTB",
+    "Sound"
+]
+
 
 defaultLatencyClass = 1
 # suggestedLatency = 0.005  ## Not currently used. Keep < 1 scr refresh
@@ -396,3 +401,6 @@ class SoundPTB(_SoundBase):
             self.__dict__['track'] = None
         else:
             self.__dict__['track'] = weakref.ref(track)
+
+
+Sound = SoundPTB

psychopy/sound/backend_pygame.py

@@ -19,6 +19,13 @@ except ImportError as err:
     raise DependencyError(repr(err))
 
 
+
+__all__ = [
+    "SoundPygame",
+    "Sound"
+]
+
+
 def getDevices(kind=None):
     """Get audio playback and recording devices via the backend's audio API.
 
@@ -311,3 +318,6 @@ class SoundPygame(_SoundBase):
             thisArray = ((thisArray + 1) * 2**7).astype(numpy.uint8)
 
         self._snd = sndarray.make_sound(thisArray)
+
+
+Sound = SoundPygame

psychopy/sound/backend_pysound.py

@@ -21,6 +21,12 @@ from os import path
 import weakref
 
 
+__all__ = [
+    "SoundPySoundCard",
+    "Sound"
+]
+
+
 def init(rate=44100, stereo=True, buffer=128):
     pass
     # for compatibility with other backends but not needed
@@ -313,3 +319,6 @@ class SoundPySoundCard(_SoundBase):
     def __del__(self):
         if hasattr(self, "_stream"):
             self._stream.close()
+
+
+Sound = SoundPySoundCard

psychopy/sound/microphone.py

@@ -347,6 +347,9 @@ class Microphone:
     def getRecording(self):
         return self.device.getRecording()
 
+    def getCurrentVolume(self):
+        return self.device.getCurrentVolume()
+
 
 if __name__ == "__main__":
     pass