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

psychopy/sound/backend_ptb.py

@@ -14,10 +14,12 @@ from pathlib import Path
 from psychopy import prefs, logging, exceptions
 from psychopy.constants import (STARTED, PAUSED, FINISHED, STOPPING,
                                 NOT_STARTED)
+from psychopy.hardware.speaker import SpeakerDevice
 from psychopy.tools import systemtools
 from psychopy.tools import filetools as ft
 from .exceptions import SoundFormatError, DependencyError
 from ._base import _SoundBase, HammingWindow
+from .audioclip import AudioClip
 from ..hardware import DeviceManager
 
 try:
@@ -32,18 +34,8 @@ except Exception:
 
 import numpy as np
 
-try:
-    defaultLatencyClass = int(prefs.hardware['audioLatencyMode'][0])
-except (TypeError, IndexError):  # maybe we were given a number instead
-    defaultLatencyClass = prefs.hardware['audioLatencyMode']
-"""vals in prefs.hardware['audioLatencyMode'] are:
-     {0:_translate('Latency not important'),
-      1:_translate('Share low-latency driver'),
-      2:_translate('Exclusive low-latency'),
-      3:_translate('Aggressive low-latency'),
-      4:_translate('Latency critical')}
-Based on help at http://psychtoolbox.org/docs/PsychPortAudio-Open
-"""
+
+defaultLatencyClass = 1
 # suggestedLatency = 0.005  ## Not currently used. Keep < 1 scr refresh
 
 if prefs.hardware['audioDriver']=='auto':
@@ -56,6 +48,15 @@ if prefs.hardware['audioDevice']=='auto':
 else:
     audioDevice = prefs.hardware['audioDevice']
 
+# check if we should only use WAS host API (default is True on Windows)
+audioWASAPIOnly = False
+try:
+    wasapiPref = prefs.hardware['audioWASAPIOnly']
+except KeyError:
+    wasapiPref = False
+if sys.platform == 'win32' and wasapiPref:
+    audioWASAPIOnly = True
+
 # these will be used by sound.__init__.py
 defaultInput = None
 defaultOutput = audioDevice
@@ -80,208 +81,6 @@ def init(rate=48000, stereo=True, buffer=128):
     pass  # for compatibility with other backends
 
 
-def getDevices(kind=None):
-    """Returns a dict of dict of audio devices of specified `kind`
-
-    kind can be None, 'input' or 'output'
-    The dict keys are names, and items are dicts of properties
-    """
-    if sys.platform == 'win32':
-        deviceTypes = 13  # only WASAPI drivers need apply!
-    else:
-        deviceTypes = None
-    devs = {}
-    if systemtools.isVM_CI():  # GitHub actions VM does not have a sound device
-        return devs
-    else:
-        allDevs = audio.get_devices(device_type=deviceTypes)
-
-    # annoyingly query_devices is a DeviceList or a dict depending on number
-    if isinstance(allDevs, dict):
-        allDevs = [allDevs]
-
-    for ii, dev in enumerate(allDevs):
-        if kind and kind.startswith('in'):
-            if dev['NrInputChannels'] < 1:
-                continue
-        elif kind and kind.startswith('out'):
-            if dev['NrOutputChannels'] < 1:
-                continue
-        # we have a valid device so get its name
-        # newline characters must be removed
-        devName = dev['DeviceName'].replace('\r\n', '')
-        devs[devName] = dev
-        dev['id'] = ii
-    return devs
-
-
-def getStreamLabel(sampleRate, channels, blockSize):
-    """Returns the string repr of the stream label
-    """
-    return "{}_{}_{}".format(sampleRate, channels, blockSize)
-
-
-class _StreamsDict(dict):
-    """Keeps track of what streams have been created. On macOS we can have
-    multiple streams under portaudio but under windows we can only have one.
-
-    use the instance `streams` rather than creating a new instance of this
-    """
-
-    def getStream(self, sampleRate, channels, blockSize):
-        """Gets a stream of exact match or returns a new one
-        (if possible for the current operating system)
-        """
-        # if the query looks flexible then try getSimilar
-        if channels == -1 or blockSize == -1:
-            return self._getSimilar(sampleRate,
-                                    channels=channels,
-                                    blockSize=blockSize)
-        else:
-            return self._getStream(sampleRate,
-                                   channels=channels,
-                                   blockSize=blockSize)
-
-    def _getSimilar(self, sampleRate, channels=-1, blockSize=-1):
-        """Do we already have a compatible stream?
-
-        Many sounds can allow channels and blocksize to change but samplerate
-        is generally fixed. Any values set to -1 above will be flexible. Any
-        values set to an alternative number will be fixed
-
-        usage:
-
-            label, stream = streams._getSimilar(sampleRate=44100,  # must match
-                                               channels=-1,  # any
-                                               blockSize=-1)  # wildcard
-        """
-        label = getStreamLabel(sampleRate, channels, blockSize)
-        # replace -1 with any regex integer
-        simil = re.compile(label.replace("-1", r"[-+]?(\d+)"))  # I hate REGEX!
-        for thisFormat in self:
-            if simil.match(thisFormat):  # we found a close-enough match
-                return thisFormat, self[thisFormat]
-        # if we've been given values in each place then create stream
-        if (sampleRate not in [None, -1, 0] and
-                channels not in [None, -1] and
-                blockSize not in [None, -1]):
-            return self._getStream(sampleRate, channels, blockSize)
-
-    def _getStream(self, sampleRate, channels, blockSize):
-        """Strict check for this format or create new
-        """
-        label = getStreamLabel(sampleRate, channels, blockSize)
-        # try to retrieve existing stream of that name
-        if label in self:
-            pass
-        # todo: check if this is still needed on win32
-        # on some systems more than one stream isn't supported so check
-        elif sys.platform == 'win32' and len(self):
-            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)
-            )
-        else:
-
-            # create new stream
-            self[label] = _MasterStream(sampleRate, channels, blockSize,
-                                        device=defaultOutput)
-        return label, self[label]
-
-
-streams = _StreamsDict()
-
-
-class _MasterStream(audio.Stream):
-    def __init__(self, sampleRate, channels, blockSize,
-                 device=None, duplex=False, mode=1,
-                 audioLatencyClass=None):
-        # initialise thread
-        if audioLatencyClass is None:
-            audioLatencyClass = defaultLatencyClass
-        self.streamLabel = None
-        self.streams = []
-        self.list = []
-        # sound stream info
-        self.sampleRate = sampleRate
-        self.channels = channels
-        self.duplex = duplex
-        self.blockSize = blockSize
-        self.label = getStreamLabel(sampleRate, channels, blockSize)
-        if isinstance(device, list) and len(device):
-            device = device[0]
-        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']
-            else:
-                deviceID = None
-        else:
-            deviceID = device
-        self.sounds = []  # list of dicts for sounds currently playing
-        self.takeTimeStamp = False
-        self.frameN = 1
-        # self.frameTimes = range(5)  # DEBUGGING: store the last 5 callbacks
-        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:  # noqa: F841
-                audio.Stream.__init__(self, device_id=deviceID, mode=mode+8,
-                                      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 ({}). "
-                      "This is depends on the selected latency class and device."
-                      .format(sampleRate, self.sampleRate))
-            except TypeError as e:
-                print("device={}, mode={}, latency_class={}, freq={}, channels={}"
-                      .format(device, mode+8, audioLatencyClass, sampleRate, channels))
-                raise e
-            except Exception as e:
-                if deviceID == -1:
-                    # if default device doesn't setup from ptb, pick first device
-                    for device in audio.get_devices(device_type=13):
-                        logging.error(
-                            f"System default audio device failed to connect, so using first found "
-                            f"device: {device['DeviceName']}"
-                        )
-                        audio.Stream.__init__(
-                            self,mode=mode+8,
-                            device_id=device['DeviceIndex'],
-                            freq=device['DefaultSampleRate'],
-                            channels=device['NrOutputChannels']
-                        )
-                        break
-                else:
-                    # any other problem, try with no device ID
-                    audio.Stream.__init__(
-                        self, mode=mode+8,
-                        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"
-                          "so fetching default audio device instead: \n"
-                          "    '{}'"
-                          .format(device, 'test'))
-            self.start(0, 0, 1)
-            # self.device = self._sdStream.device
-            # self.latency = self._sdStream.latency
-            # self.cpu_load = self._sdStream.cpu_load
-        self._tSoundRequestPlay = 0
-
-
 class SoundPTB(_SoundBase):
     """Play a variety of sounds using the new PsychPortAudio library
     """
@@ -321,7 +120,14 @@ class SoundPTB(_SoundBase):
         :param autoLog: whether to automatically log every change
         :param syncToWin: if you want start/stop to sync with win flips add this
         """
-        self.speaker = self._parseSpeaker(speaker)
+        # if given the name of a managed speaker, get it
+        if isinstance(speaker, str) and DeviceManager.getDevice(speaker):
+            speaker = DeviceManager.getDevice(speaker)
+        # make sure speaker is a SpeakerDevice
+        if not isinstance(speaker, SpeakerDevice):
+            speaker = SpeakerDevice(speaker)
+        self.speaker = speaker
+        
         self.sound = value
         self.name = name
         self.secs = secs  # for any synthesised sounds (notesand freqs)
@@ -340,7 +146,6 @@ class SoundPTB(_SoundBase):
         self.stereo = stereo
         self.duplex = None
         self.autoLog = autoLog
-        self.streamLabel = ""
         self.sourceType = 'unknown'  # set to be file, array or freq
         self.sndFile = None
         self.sndArr = None
@@ -366,13 +171,6 @@ class SoundPTB(_SoundBase):
         """`True` if the audio playback has completed."""
         return self._checkPlaybackFinished()
 
-    def _getDefaultSampleRate(self):
-        """Check what streams are open and use one of these"""
-        if len(streams):
-            return list(streams.values())[0].sampleRate
-        else:
-            return 48000  # seems most widely supported
-
     @property
     def statusDetailed(self):
         if not self.track:
@@ -400,7 +198,12 @@ class SoundPTB(_SoundBase):
 
     @stereo.setter
     def stereo(self, val):
+        # if auto, get from speaker
+        if val == -1:
+            val = self.speaker.channels > 1
+        # store value
         self.__dict__['stereo'] = val
+        # convert to n channels
         if val is True:
             self.__dict__['channels'] = 2
         elif val is False:
@@ -438,84 +241,34 @@ class SoundPTB(_SoundBase):
         self.loops = self._loopsRequested
         # start with the base class method
         _SoundBase.setSound(self, value, secs, octave, hamming, log)
-
-    def _setSndFromFile(self, filename):
-        # alias default names (so it always points to default.png)
-        if filename in ft.defaultStim:
-            filename = Path(prefs.paths['assets']) / ft.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 = np.asarray(thisArray).astype('float32')
-        if thisArray.ndim == 1:
-            self.sndArr.shape = [len(thisArray), 1]  # make 2D for broadcasting
-        if self.channels == 2 and self.sndArr.shape[1] == 1:  # mono -> stereo
-            self.sndArr = self.sndArr.repeat(2, axis=1)
-        elif self.sndArr.shape[1] == 1:  # if channels in [-1,1] then pass
-            pass
-        else:
-            try:
-                self.sndArr.shape = [len(thisArray), 2]
-            except ValueError:
-                raise ValueError("Failed to format sound with shape {} "
-                                 "into sound with channels={}"
-                                 .format(self.sndArr.shape, self.channels))
-
-        # 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))
-        self._nSamples = thisArray.shape[0]
+    
+    def _setSndFromClip(self, clip: AudioClip):
+        # store clip
+        self.clip = clip
+        # resample the clip if needed and allowed
+        if self.speaker.resample:
+            if clip.sampleRateHz != self.speaker.sampleRateHz:
+                clip.resample(targetSampleRateHz=self.speaker.sampleRateHz)
+        # work out stop time
         if self.stopTime == -1:
-            self.duration = self._nSamples / float(self.sampleRate)
-        # set to run from the start:
-        self.seek(0)
-        self.sourceType = "array"
-
-        if not self.track:  # do we have one already?
-            self.track = audio.Slave(self.stream.handle, data=self.sndArr,
-                                     volume=self.volume)
+            self.duration = clip.samples.shape[0] / clip.sampleRateHz
+        # handle stereo/mono
+        if self.speaker.channels > 1:
+            clip = clip.asStereo()
         else:
+            clip = clip.asMono()
+        # create/update track
+        if  self.track:
             self.track.stop()
-            self.track.fill_buffer(self.sndArr)
+            self.track.fill_buffer(clip.samples)
+        else:
+            self.track = audio.Slave(
+                self.stream.handle, 
+                data=clip.samples,
+                volume=self.volume
+            )
+        # seek to start
+        self.seek(0)
 
     def _channelCheck(self, array):
         """Checks whether stream has fewer channels than data. If True, ValueError"""
@@ -570,7 +323,7 @@ class SoundPTB(_SoundBase):
         self._isFinished = False
         # time.sleep(0.)
         if log and self.autoLog:
-            logging.exp(u"Sound %s started" % (self.name), obj=self, t=logTime)
+            logging.exp(u"Playing sound %s on speaker %s" % (self.name, self.speaker.name), obj=self, t=logTime)
 
     def pause(self, log=True):
         """Stops the sound without reset, so that play will continue from here if needed
@@ -621,28 +374,7 @@ class SoundPTB(_SoundBase):
         """Read-only property returns the stream on which the sound
         will be played
         """
-        if not self.streamLabel:
-            try:
-                label, s = streams.getStream(sampleRate=self.sampleRate,
-                                             channels=self.channels,
-                                             blockSize=self.blockSize)
-            except SoundFormatError as err:
-                # try to use something similar (e.g. mono->stereo)
-                # then check we have an appropriate stream open
-                altern = streams._getSimilar(sampleRate=self.sampleRate,
-                                             channels=-1,
-                                             blockSize=-1)
-                if altern is None:
-                    raise SoundFormatError(err)
-                else:  # safe to extract data
-                    label, s = altern
-                # update self in case it changed to fit the stream
-                self.sampleRate = s.sampleRate
-                self.channels = s.channels
-                self.blockSize = s.blockSize
-            self.streamLabel = label
-
-        return streams[self.streamLabel]
+        return self.speaker.stream
 
     def __del__(self):
         if self.track:

psychopy/sound/backend_pygame.py

@@ -153,7 +153,7 @@ class SoundPygame(_SoundBase):
                  hamming=False, speaker=None):
         self.name = name  # only needed for autoLogging
         self.autoLog = autoLog
-        self.speaker = self._parseSpeaker(speaker)
+        self.speaker = speaker
 
         if stereo == True:
             stereoChans = 2
@@ -172,6 +172,8 @@ class SoundPygame(_SoundBase):
             init()
             inits = mixer.get_init()
         self.sampleRate, self.format, self.isStereo = inits
+        self.startTime = 0
+        self.stopTime = secs
 
         if hamming:
             logging.warning("Hamming was requested using the 'pygame' sound "
@@ -285,9 +287,11 @@ class SoundPygame(_SoundBase):
             logging.error(msg % fileName)
             raise ValueError(msg % fileName)
 
-    def _setSndFromArray(self, thisArray):
-        # get a mixer.Sound object from an array of floats (-1:1)
+    def _setSndFromClip(self, clip):
+        self.clip = clip
+        thisArray = self.clip.samples
 
+        # get a mixer.Sound object from an array of floats (-1:1)
         # make stereo if mono
         if (self.isStereo == 2 and
                 (len(thisArray.shape) == 1 or

psychopy/sound/backend_pyo.py

@@ -8,26 +8,57 @@ These are optional components that can be obtained by installing the
 
 """
 
-import psychopy.logging as logging
-from .exceptions import DependencyError
-
-try:
-    from psychopy_pyo import (
-        init,
-        get_devices_infos,
-        get_input_devices,
-        get_output_devices,
-        getDevices,
-        SoundPyo)
-except (ModuleNotFoundError, ImportError):
-    logging.error(
-        "Support for the `pyo` audio backend is not available this session. "
-        "Please install `psychopy-pyo` and restart the session to enable "
-        "support.")
-except (NameError, DependencyError):
-    logging.error(
-        "Error encountered while loading `psychopy-pyo`. Check logs for more "
-        "information.")
-
-if __name__ == "__main__":
+
+from psychopy.plugins import PluginStub
+
+
+class SoundPyo(
+    PluginStub,
+    plugin="psychopy-pyo",
+    docsHome="https://github.com/psychopy/psychopy-pyo",
+):
+    pass
+
+
+class init(
+    PluginStub,
+    plugin="psychopy-pyo",
+    docsHome="https://github.com/psychopy/psychopy-pyo",
+):
+    pass
+
+
+class get_devices_infos(
+    PluginStub,
+    plugin="psychopy-pyo",
+    docsHome="https://github.com/psychopy/psychopy-pyo",
+):
+    pass
+
+
+class get_input_devices(
+    PluginStub,
+    plugin="psychopy-pyo",
+    docsHome="https://github.com/psychopy/psychopy-pyo",
+):
+    pass
+
+
+class get_output_devices(
+    PluginStub,
+    plugin="psychopy-pyo",
+    docsHome="https://github.com/psychopy/psychopy-pyo",
+):
     pass
+
+
+class getDevices(
+    PluginStub,
+    plugin="psychopy-pyo",
+    docsHome="https://github.com/psychopy/psychopy-pyo",
+):
+    pass
+
+
+pyoSndServer: SoundPyo
+audioDriver: str

psychopy/sound/backend_pysound.py

@@ -174,12 +174,14 @@ class SoundPySoundCard(_SoundBase):
         self.name = name  # only needed for autoLogging
         self.autoLog = autoLog
 
-        self.speaker = self._parseSpeaker(speaker)
+        self.speaker = speaker
 
         self.sampleRate = sampleRate
         self.bufferSize = bufferSize
         self.volume = volume
 
+        self.channels = 2
+
         # try to create sound
         self._snd = None
         # distinguish the loops requested from loops actual because of
@@ -267,33 +269,13 @@ class SoundPySoundCard(_SoundBase):
         attributetools.setAttribute(self, 'volume', value, log, operation)
         return value  # this is returned for historical reasons
 
-    def _setSndFromFile(self, fileName):
-        # alias default names (so it always points to default.png)
-        if fileName in ft.defaultStim:
-            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
-            logging.error(msg)
-            raise ValueError(msg)
-        self.fileName = fileName
-        # in case a tone with inf loops had been used before
-        self.loops = self.requestedLoops
-        try:
-            self.sndFile = sndfile.SoundFile(fileName)
-            sndArr = self.sndFile.read()
-            self.sndFile.close()
-            self._setSndFromArray(sndArr)
-
-        except Exception:
-            msg = "Sound file %s could not be opened using pysoundcard for sound."
-            logging.error(msg % fileName)
-            raise ValueError(msg % fileName)
-
-    def _setSndFromArray(self, thisArray):
+    def _setSndFromClip(self, clip):
         """For pysoundcard all sounds are ultimately played as an array so
         other setSound methods are going to call this having created an arr
         """
+        self.clip = clip
+        thisArray = self.clip.samples
+
         self._callbacks = _PySoundCallbackClass(sndInstance=self)
         if defaultOutput is not None and type(defaultOutput) != int:
             devs = getDevices()
@@ -307,7 +289,7 @@ class SoundPySoundCard(_SoundBase):
         self._stream = soundcard.Stream(samplerate=self.sampleRate,
                                         device=device,
                                         blocksize=self.bufferSize,
-                                        channels=1,
+                                        channels=self.channels,
                                         callback=self._callbacks.fillBuffer)
         self._snd = self._stream
         chansIn, chansOut = self._stream.channels
@@ -329,4 +311,5 @@ class SoundPySoundCard(_SoundBase):
         self._isPlaying = False
 
     def __del__(self):
-        self._stream.close()
+        if hasattr(self, "_stream"):
+            self._stream.close()