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

psychopy/hardware/speaker.py

@@ -1,37 +1,284 @@
+# -*- coding: utf-8 -*-
+
+"""Classes and functions managing physical speaker devices for audio playback.
+"""
+
+# Part of the PsychoPy library
+# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2025 Open Science Tools Ltd.
+# Distributed under the terms of the GNU General Public License (GPL).
+
+import io
+import sys
+import contextlib
+from types import SimpleNamespace
+import psychtoolbox.audio as ptb
+from psychopy.hardware.exceptions import DeviceNotConnectedError
+from psychopy.localization import _translate
+from psychopy.preferences import prefs
 from psychopy.hardware import BaseDevice
-from psychopy.sound import setDevice, getDevices, backend
 from psychopy import logging
+from psychopy.tools import systemtools
+
+__all__ = [
+    "SpeakerDevice",
+]
 
 
 class SpeakerDevice(BaseDevice):
-    def __init__(self, index):
-        profiles = self.getAvailableDevices()
-
-        # if index is default (-1), setup a default device index
-        if not isinstance(index, (int, float)):
-            index = profiles[0]['index']  # initialize as the first device
-
-            # check if a default device is already set and update index
-            if hasattr(backend, 'defaultOutput'):
-                defaultDevice = backend.defaultOutput
-                if isinstance(defaultDevice, (int, float)):
-                    # if a default device index is set, use it
-                    index = defaultDevice
-                elif isinstance(defaultDevice, str):
-                    # if a default device is set by name, find it
-                    for profile in profiles:
-                        if profile['deviceName'] == defaultDevice:
-                            index = profile['index']
-
-        available_index = [profile['index'] for profile in profiles] + [-1]
-        if index not in available_index:
-            logging.error("No speaker device found with index %d" % index)
-
-        # store index
+    """Class for managing a physical speaker device for audio playback.
+
+    Parameters
+    ----------
+    index : int, optional
+        Numeric index for the physical speaker device, according to psychtoolbox. Leave as None to 
+        find the speaker by name.
+    name : str, optional
+        String name for the physical speaker device, according to your operating system. Leave as 
+        None to find the speaker by numeric index.
+    latencyClass : int
+        One of:
+
+        * 0: Don't take exclusive control over the speaker, so other apps can still use it. Send 
+        sounds via the system mixer so that sample rates are all handled, even though this 
+        introduces latency.
+
+        * 1: Don't take exclusive control over the speaker, so other apps can still use it. Send 
+        sounds directly to reduce latency, so sounds will need to match the sample rate of the 
+        speaker. **Recommended in most cases; if `resample` is True then sample rates are 
+        already handled on load!**
+
+        * 2: Take exclusive control over the speaker, so other apps can't use it. Send sounds 
+        directly to reduce latency, so sounds will need to be the same sample rate as one 
+        another, but this can be any sample rate supported by the speaker.
+
+        * 3: Take exclusive control over the speaker, so other apps can't use it. Send sounds 
+        directly to reduce latency, so sounds will need to be the same sample rate as one 
+        another, but this can be any sample rate supported by the speaker. Force the system to 
+        prioritise resources towards playing sounds on this speaker for absolute minimum 
+        latency, but fallback to mode 2 if the system rejects this.
+
+        * 4: Take exclusive control over the speaker, so other apps can't use it. Send sounds 
+        directly to reduce latency, so sounds will need to be the same sample rate as one 
+        another, but this can be any sample rate supported by the speaker. Force the system to 
+        prioritise resources towards playing sounds on this speaker for absolute minimum 
+        latency, and raise an error if the system rejects this.
+    resample : bool, optional
+        If the sample rate of an audio clip doesn't match the sample rate of the speaker, should 
+        PsychoPy resample the sound on load?
+    """
+    # dict of extant streams, by numeric index
+    streams = {}
+
+    def __init__(self, index=None, name=None, latencyClass=1, resample=True):
+        if index is not None and name is not None:
+            logging.warn(
+                "Both 'index' and 'name' were provided to SpeakerDevice; ignoring 'index'"
+            )
+            index = None
+        # try simple integerisation of index
+        if isinstance(index, str):
+            try:
+                index = float(index)
+            except ValueError:
+                pass
+
+        # if index is default, get default speaker device
+        if index in (-1, None) and name is None:
+            index = None  # set to none so we can find by name later
+            pref = prefs.hardware['audioDevice']
+            pref = pref[0] if isinstance(pref, (list, tuple)) else pref
+
+            if pref in ("default", "None"):
+                # if no pref, use first device
+                name = self.getAvailableDevices()[0]['deviceName']
+                # warn the user, this speaker might be a virtual device with no audio or something
+                logging.warn(
+                    _translate(
+                        "No default speaker specified in Preferences / Hardware, using first speaker found: {}"
+                    ).format(name)
+                )
+            else:
+                # if pref is a name, use that
+                name = pref
+
+        # store name and index
+        self.name = name
         self.index = index
-        # set global device (best we can do for now)
-        setDevice(index)
 
+        # store playback prefs
+        self.resample = resample
+        self.latencyClass = latencyClass
+        # create stream
+        self.createStream()
+        # start off open
+        self.open()
+    
+    @property
+    def exclusive(self):
+        """
+        Returns
+        -------
+        bool
+            Does PsychoPy have exclusive control of this speaker? If True then other apps will not be 
+            able to play sounds on the same speaker.
+        """
+        return self.latencyClass >= 2
+    
+    def createStream(self):
+        """
+        Create the psychtoolbox audio stream
+
+        Attributes
+        ----------
+        Calling this method will set the following attributes:
+
+        profile : dict
+            The profile from psychtoolbox, a dict with the following keys: Active, State, 
+            RequestedStartTime, StartTime, CaptureStartTime, RequestedStopTime, EstimatedStopTime, 
+            CurrentStreamTime, ElapsedOutSamples, PositionSecs, RecordedSecs, ReadSecs, 
+            SchedulePosition, XRuns, TotalCalls, TimeFailed, BufferSize, CPULoad, PredictedLatency, 
+            LatencyBias, SampleRate, OutDeviceIndex, InDeviceIndex
+        index : int
+            A numeric index referring to the device. This may differ from the value of `index` this 
+            object was initialised with, as this will be the numeric index of the actual physical 
+            speaker best matching what was requested.
+        name : str
+            A string name referring to the device. This may differ from the value of `name` this 
+            object was initialised with, as this will be the system-reported name of the actual 
+            physical speaker best matching what was requested.
+        """
+
+        # get the devices from psychtoolbox
+        try:
+            wasapiPref = prefs.hardware['audioWASAPIOnly']
+        except KeyError:
+            wasapiPref = False
+            
+        if sys.platform == 'win32' and wasapiPref:
+            allFoundDevices = ptb.get_devices(device_type=13)
+        else:
+            allFoundDevices = ptb.get_devices()
+
+        if not allFoundDevices:
+            raise DeviceNotConnectedError(
+                _translate("No audio devices found!"),
+                deviceClass=SpeakerDevice
+            )
+        
+        # find ptb profile for this device
+        findByName = self.index is None and self.name is not None
+        self.profile = None
+        for thisProfile in allFoundDevices:
+            # skip input-only devices (microphones)
+            if thisProfile['NrOutputChannels'] == 0:
+                continue
+
+            if findByName and self.name == thisProfile['DeviceName']:
+                self.profile = thisProfile
+                break
+            else:  # use index instead
+                if self.index == thisProfile['DeviceIndex']:
+                    self.profile = thisProfile
+                    break
+
+        # raise error if device not found
+        if self.profile is None:
+            raise DeviceNotConnectedError(
+                _translate(
+                    "No speaker device found with {key} '{name}'"
+                ).format(name=self.name, key="name" if findByName else "index"),
+                deviceClass=SpeakerDevice
+            )
+        
+        logging.debug(
+            f"Found speaker device: {self.profile['DeviceName']} ({self.profile['DeviceIndex']})"
+        )
+            
+        # if physical device already has a stream, use it rather than making a new one
+        if self.profile['DeviceIndex'] in SpeakerDevice.streams:
+            self.stream = SpeakerDevice.streams['DeviceIndex']
+        else:
+            self.stream = None
+        # try to connect using profile at various sample rates
+        for sampleRateHz in (
+            # start with the rate from profile (this will usually work)
+            int(self.profile['DefaultSampleRate']), 
+            # if that fails, try some common sample rates
+            48000,
+            44100, 
+            22050, 
+            16000
+        ):
+            # stop trying new options once we have a stream
+            if self.stream is not None:
+                continue
+            # try this sample rate
+            try:
+                # redirect stderr to a buffer to avoid ptb error spam
+                outBuff = io.StringIO()
+                errBuff = io.StringIO()
+                with contextlib.redirect_stdout(outBuff):
+                    with contextlib.redirect_stderr(errBuff):
+                        self.stream = ptb.Stream(
+                            mode=1+8,
+                            device_id=self.profile['DeviceIndex'],
+                            freq=sampleRateHz,
+                            channels=self.profile['NrOutputChannels'],
+                            latency_class=[self.latencyClass],
+                        )
+                # if it worked, set own parameters
+                self.index = self.profile['DeviceIndex']
+                self.name = self.profile['DeviceName']
+                self.sampleRateHz = sampleRateHz
+                self.channels = self.profile['NrOutputChannels']
+                # ...and log/print the stderr from psychtoolbox (only if successful!)
+                logs = errBuff.getvalue() + outBuff.getvalue()
+                for line in logs.split("\n"):
+                    if line.startswith("PTB-INFO: "):
+                        logging.info(line[10:])
+                    elif line.startswith("PTB-ERROR: "):
+                        logging.error(line[11:])
+                    elif line.strip():
+                        print(line)
+            except:
+                pass
+        # if everything failed, raise an error
+        if self.stream is None:
+            raise ConnectionError(
+                "Failed to setup a PsychToolBox audio stream for device %(DeviceName)s "
+                "(%(DeviceIndex)s)." % self.profile
+            )
+
+        logging.info(
+            f"Created stream for speaker device: {self.profile['DeviceName']} "
+            f"({self.profile['DeviceIndex']})"
+        )
+    
+    def open(self):
+        """
+        Open the audio stream for this speaker so that sound can be played to it.
+        """
+        if not self.isOpen:
+            self.stream.start(0, 0, 1)
+    
+    def close(self):
+        """
+        Close the audio stream for this speaker.
+        """
+        if self.isOpen:
+            self.stream.close()
+    
+    @property
+    def isOpen(self):
+        """
+        Is this speaker "open", i.e. is it active and ready for a Sound to play tracks on it
+        """
+        # sometimes a closed stream will have an integer for status
+        if not isinstance(self.stream.status, dict):
+            return False
+        
+        return bool(self.stream.status['Active'])
+    
     def isSameDevice(self, other):
         """
         Determine whether this object represents the same physical speaker as a given other object.
@@ -47,7 +294,7 @@ class SpeakerDevice(BaseDevice):
         bool
             True if the two objects represent the same physical device
         """
-        if isinstance(other, SpeakerDevice):
+        if isinstance(other, type(self)):
             # if given another object, get index
             index = other.index
         elif isinstance(other, dict) and "index" in other:
@@ -57,8 +304,8 @@ class SpeakerDevice(BaseDevice):
             # if the other object is the wrong type or doesn't have an index, it's not this
             return False
 
-        return self.index == index
-
+        return index in (self.index, self.name)
+    
     def testDevice(self):
         """
         Play a simple sound to check whether this device is working.
@@ -67,22 +314,37 @@ class SpeakerDevice(BaseDevice):
         import time
         # create a basic sound
         snd = Sound(
-            speaker=self.index,
-            value="A"
+            speaker=self,
+            value="A",
+            stereo=self.channels > 1,
+            sampleRate=self.sampleRateHz
         )
         # play the sound for 1s
         snd.play()
         time.sleep(1)
         snd.stop()
-
+    
     @staticmethod
     def getAvailableDevices():
+        # skip in vm
+        if systemtools.isVM_CI():  # GitHub actions VM does not have a sound device
+            return []
+        # only show WASAPI drivers for Windows
+        if sys.platform == 'win32':
+            deviceType = 13
+        else:
+            deviceType = None
+        
         devices = []
-
-        for profile in getDevices(kind="output").values():
+        for profile in ptb.get_devices(device_type=deviceType):
+            # skip input-only devices (microphones)
+            if profile['NrOutputChannels'] == 0:
+                continue
+            # construct profile
             device = {
-                'deviceName': profile.get('DeviceName', "Unknown Microphone"),
+                'deviceName': profile.get('DeviceName', "Unknown Speaker"),
                 'index': profile.get('DeviceIndex', None),
+                'name': profile.get('DeviceName', None)
             }
             devices.append(device)
 

psychopy/hardware/triggerbox/__init__.py

@@ -18,7 +18,7 @@ file.
 """
 
 # 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__ = [

psychopy/hardware/triggerbox/base.py

@@ -10,7 +10,7 @@ trigger boxes from within PsychoPy.
 """
 
 # 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__ = ['BaseTriggerBox']

psychopy/hardware/triggerbox/parallel.py

@@ -8,7 +8,7 @@ port.
 """
 
 # 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__ = [

psychopy/info.py

@@ -2,7 +2,7 @@
 # -*- 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).
 
 """This module has tools for fetching data about the system or the current

psychopy/iohub/client/__init__.py

@@ -10,6 +10,7 @@ import time
 import subprocess
 import json
 import signal
+import atexit
 from weakref import proxy
 
 import psutil
@@ -31,6 +32,8 @@ from psychopy import constants
 
 getTime = Computer.getTime
 
+SHUTDOWN_FUNCS = []
+
 _currentSessionInfo = None
 
 def windowInfoDict(win):
@@ -1000,6 +1003,9 @@ class ioHubConnection():
         Computer.iohub_process_id = self._server_process.pid
         Computer.iohub_process = psutil.Process(self._server_process.pid)
 
+        global SHUTDOWN_FUNCS
+        SHUTDOWN_FUNCS.append(self._shutDownServer)
+
         # >>>>> Create open UDP port to ioHub Server
         server_udp_port = self._iohub_server_config.get('udp_port', 9000)
         from ..net import UDPClientConnection
@@ -1451,6 +1457,17 @@ class ioEvent():
                                                  self.type,
                                                  self.id)
 
+
+def shutdownActiveConnections():
+    """Shutdown any active ioHub connections that are currently running.
+    """
+    activeConnection = ioHubConnection.getActiveConnection()
+    if activeConnection is not None and hasattr(activeConnection, 'shutdown'):
+        activeConnection.shutdown()
+    
+
+atexit.register(shutdownActiveConnections)
+
 _lazyImports = """
 from psychopy.iohub.client.connect import launchHubServer
 from psychopy.iohub.client import keyboard

psychopy/iohub/client/keyboard.py

@@ -229,6 +229,11 @@ class Keyboard(ioHubDeviceView):
         """
         kb_state = self.getCurrentDeviceState()
 
+        # catch anything that is not a dictionary, usually indicates an error
+        if type(kb_state) is not dict:
+            raise RuntimeError(
+                'Keyboard device state request failed, got: %s' % kb_state)
+
         events = {int(k): v for k, v in list(kb_state.get('events').items())}
         pressed_keys = {int(k): v for k, v in list(kb_state.get('pressed_keys', {}).items())}
 

psychopy/iohub/devices/eyetracker/__init__.py

@@ -6,6 +6,7 @@ from .. import Device, ioDeviceError
 from ...constants import DeviceConstants, EyeTrackerConstants
 from . import hw
 from ...errors import print2err
+from psychopy.tools.stimulustools import serialize, actualize
 
 
 class EyeTrackerDevice(Device):
@@ -268,25 +269,16 @@ class EyeTrackerDevice(Device):
         dict
             Dict describing the given Calibration object
         """
+        targetAttributes = serialize(calib.target, includeClass=True)
+        # target animation
+        targetAttributes['animate'] = {
+            'enable': calib.movementAnimation,
+            'expansion_ratio': calib.expandScale,
+            'contract_only': calib.expandScale == 1,
+        }
+        
         return {
-            'target_attributes': {
-                # target outer circle
-                'outer_diameter': calib.target.radius * 2,
-                'outer_stroke_width': calib.target.outer.lineWidth,
-                'outer_fill_color': getattr(calib.target.outer._fillColor, calib.colorSpace) if calib.target.outer._fillColor else getattr(calib.target.win._color, calib.colorSpace),
-                'outer_line_color': getattr(calib.target.outer._borderColor, calib.colorSpace) if calib.target.outer._borderColor else getattr(calib.target.win._color, calib.colorSpace),
-                # target inner circle
-                'inner_diameter': calib.target.innerRadius * 2,
-                'inner_stroke_width': calib.target.inner.lineWidth,
-                'inner_fill_color': getattr(calib.target.inner._borderColor, calib.colorSpace) if calib.target.inner._borderColor else getattr(calib.target.win._color, calib.colorSpace),
-                'inner_line_color': getattr(calib.target.inner._borderColor, calib.colorSpace) if calib.target.inner._borderColor else getattr(calib.target.win._color, calib.colorSpace),
-                # target animation
-                'animate':{
-                    'enable': calib.movementAnimation,
-                    'expansion_ratio': calib.expandScale,
-                    'contract_only': calib.expandScale == 1,
-                },
-            },
+            'target_attributes': targetAttributes,
             'type': calib.targetLayout,
             'randomize': calib.randomisePos,
             'auto_pace': calib.progressMode == "time",

psychopy/iohub/devices/eyetracker/calibration/procedure.py

@@ -12,6 +12,7 @@ from psychopy.iohub.constants import EventConstants as EC
 from psychopy.iohub.devices.keyboard import KeyboardInputEvent
 from psychopy.iohub.errors import print2err
 from psychopy.constants import PLAYING
+from psychopy.tools.stimulustools import serialize, actualize
 
 currentTime = Computer.getTime
 
@@ -46,7 +47,11 @@ class BaseCalibrationProcedure:
         self._lastCalibrationOK = False
         self._device_config = self._eyetracker.getConfiguration()
         display = self._eyetracker._display_device
-        updateSettings(self._device_config.get('calibration'), calibration_args)
+        # apply calibration args to defaults
+        self._device_config['calibration'].update(calibration_args)
+        # get target attributes (ignore default keys as args can vary)
+        self._device_config['calibration']['target_attributes'] = calibration_args['target_attributes']
+        # use modified default config for calibration args
         self._calibration_args = self._device_config.get('calibration')
         unit_type = self.getCalibSetting('unit_type')
         if unit_type is None:
@@ -154,38 +159,15 @@ class BaseCalibrationProcedure:
         color_type = self.getCalibSetting('color_type')
         unit_type = self.getCalibSetting('unit_type')
 
-        def setDefaultCalibrationTarget():
-            # convert sizes to stimulus units
-            radiusPix = self.getCalibSetting(['target_attributes', 'outer_diameter']) / 2
-            radiusObj = layout.Size(radiusPix, units=unit_type, win=self.window)
-            radius = getattr(radiusObj, unit_type)[1]
-            innerRadiusPix = self.getCalibSetting(['target_attributes', 'inner_diameter']) / 2
-            innerRadiusObj = layout.Size(innerRadiusPix, units=unit_type, win=self.window)
-            innerRadius = getattr(innerRadiusObj, unit_type)[1]
-            # make target
-            self.targetStim = visual.TargetStim(
-                self.window, name="CP", style="circles",
-                radius=radius,
-                fillColor=self.getCalibSetting(['target_attributes', 'outer_fill_color']),
-                borderColor=self.getCalibSetting(['target_attributes', 'outer_line_color']),
-                lineWidth=self.getCalibSetting(['target_attributes', 'outer_stroke_width']),
-                innerRadius=innerRadius,
-                innerFillColor=self.getCalibSetting(['target_attributes', 'inner_fill_color']),
-                innerBorderColor=self.getCalibSetting(['target_attributes', 'inner_line_color']),
-                innerLineWidth=self.getCalibSetting(['target_attributes', 'inner_stroke_width']),
-                pos=(0, 0),
-                units=unit_type,
-                colorSpace=color_type,
-                autoLog=False
-            )
-
-        if self._calibration_args.get('target_type') == 'CIRCLE_TARGET':
-            setDefaultCalibrationTarget()
-        else:
-            self.targetStim = createCustomCalibrationStim(self.window, self._calibration_args)
-            if self.targetStim is None:
-                # Error creating custom stim, so use default target stim type
-                setDefaultCalibrationTarget()
+        # get attributes to create target
+        targetAttrs = self._calibration_args.get('target_attributes').copy()
+        # sanitize for creating
+        if "animate" in targetAttrs:
+            targetAttrs.pop("animate")
+        if "win" in targetAttrs:
+            targetAttrs['win'] = self.window
+        
+        self.targetStim = actualize(targetAttrs)
 
         self.originalTargetSize = self.targetStim.size
         self.targetClassHasPlayPause = hasattr(self.targetStim, 'play') and hasattr(self.targetStim, 'pause')

psychopy/iohub/devices/eyetracker/hw/pupil_labs/neon/__init__.py

@@ -14,6 +14,7 @@ try:
     import psychopy_eyetracker_pupil_labs.pupil_labs.pupil_core as __plugin__
     from psychopy_eyetracker_pupil_labs.pupil_labs.neon import (
         __file__,
+        MonocularEyeSampleEvent,
         BinocularEyeSampleEvent,
         EyeTracker)
 except (ModuleNotFoundError, ImportError, NameError):

psychopy/iohub/devices/mouse/linux2.py

@@ -6,7 +6,8 @@
 from ctypes import cdll
 
 from . import MouseDevice
-from .. import Keyboard, Computer, Device, xlib
+from .. import Computer, Device, xlib
+from ..keyboard import Keyboard
 from ...constants import MouseConstants
 from ...errors import print2err, printExceptionDetailsToStdErr
 
@@ -90,6 +91,10 @@ class Mouse(MouseDevice):
                 logged_time = currentSec()
                 event_array = event[0]
 
+                if self._iohub_server is None or self._iohub_server._psychopy_windows is None:
+                    # Do not report event if no ioHub server is running or no psychopy window is open
+                    return True
+
                 psychowins = self._iohub_server._psychopy_windows.keys()
                 report_all = self.getConfiguration().get('report_system_wide_events', True)
                 if report_all is False and psychowins and event_array[-1] not in psychowins:

psychopy/iohub/devices/mouse/win32.py

@@ -178,6 +178,11 @@ class Mouse(MouseDevice):
         if self.isReportingEvents():
             logged_time = currentSec()
             report_system_wide_events = self.getConfiguration().get('report_system_wide_events', True)
+
+            if self._iohub_server is None or self._iohub_server._psychopy_windows is None:
+                # Do not report event if no ioHub server is running or no psychopy window is open
+                return True
+
             pyglet_window_hnds = self._iohub_server._psychopy_windows.keys()
             if event.Window in pyglet_window_hnds:
                 pass

psychopy/layout.py

@@ -2,7 +2,7 @@
 # -*- 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).
 
 """Classes and functions for working with coordinates systems."""