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

psychopy/experiment/components/settings/eyetracking.py

@@ -0,0 +1,108 @@
+from psychopy.localization import _translate
+from psychopy.experiment import Param
+
+
+knownEyetrackerBackends = {}
+
+
+class EyetrackerBackend:
+    # label to display in Builder
+    label = None
+    # key to index this backend by
+    key = None
+
+    # information about this backend's needs (for raising alerts and etc.)
+    needsFullscreen = True
+    needsCalibration = True
+    
+    def __init_subclass__(cls):
+        # skip any classes with no key
+        if cls.key is None:
+            return
+        # append to global variable
+        global knownEyetrackerBackends
+        knownEyetrackerBackends[cls.key] = cls
+    
+    @classmethod
+    def getParams(cls):
+        """
+        Method to get the params to be added to SettingsComponent by this backend.
+        
+        Returns
+        -------
+        dict[str: Param]
+            Dict of params to add, by name
+        list[str]
+            List determining order of params (by name)
+        """
+        params = {}
+        order = []
+
+        return params, order
+    
+    @classmethod
+    def writeDeviceCode(cls, inits, buff):
+        """
+        Overload this method in a subclass to control the code that's written in the `setupDevices` 
+        function of Builder experiments when using this backend.
+
+        Parameters
+        ----------
+        comp : dict[str: psychopy.experiment.Param]
+            Dict of params from the Settings Component
+        buff : io.StringIO
+            String buffer to write to (i.e. the experiment-in-progress)
+        """
+        raise NotImplementedError()
+
+
+class MouseGazeEyetrackerBackend(EyetrackerBackend):
+    label = "MouseGaze"
+    key = "eyetracker.hw.mouse.EyeTracker"
+
+    needsFullscreen = False
+    needsCalibration = False
+
+    @classmethod
+    def getParams(cls):
+        # define order
+        order = [
+            "mgMove",
+            "mgBlink",
+            "mgSaccade",
+        ]
+        # define params
+        params = {}
+        params['mgMove'] = Param(
+            "CONTINUOUS", valType='str', inputType="choice",
+            allowedVals=['CONTINUOUS', 'LEFT_BUTTON', 'MIDDLE_BUTTON', 'RIGHT_BUTTON'],
+            hint=_translate("Mouse button to press for eye movement."),
+            label=_translate("Move button"), categ="Eyetracking"
+        )
+        params['mgBlink'] = Param(
+            "MIDDLE_BUTTON", valType='list', inputType="multiChoice",
+            allowedVals=['LEFT_BUTTON', 'MIDDLE_BUTTON', 'RIGHT_BUTTON'],
+            hint=_translate("Mouse button to press for a blink."),
+            label=_translate("Blink button"), categ="Eyetracking"
+        )
+        params['mgSaccade'] = Param(
+            0.5, valType='num', inputType="single",
+            hint=_translate("Visual degree threshold for Saccade event creation."),
+            label=_translate("Saccade threshold"), categ="Eyetracking"
+        )
+
+        return params, order
+
+    @classmethod
+    def writeDeviceCode(cls, inits, buff):
+        code = (
+            "ioConfig[%(eyetracker)s] = {\n"
+            "    'name': 'tracker',\n"
+            "    'controls': {\n"
+            "        'move': [%(mgMove)s],\n"
+            "        'blink':%(mgBlink)s,\n"
+            "        'saccade_threshold': %(mgSaccade)s,\n"
+            "    },\n"
+            "}\n"
+        )
+        buff.writeIndentedLines(code % inits)

psychopy/experiment/components/slider/__init__.py

@@ -55,7 +55,7 @@ class SliderComponent(BaseVisualComponent):
                  color="LightGray",
                  fillColor='Red',
                  borderColor='White',
-                 font="Open Sans",
+                 font="Noto Sans",
                  letterHeight=0.05,
                  startType='time (s)', startVal='0.0',
                  stopType='condition', stopVal='',
@@ -87,7 +87,7 @@ class SliderComponent(BaseVisualComponent):
         # = the usual as inherited from BaseVisual plus:
         self.params['ticks'] = Param(
                 ticks, valType='list', inputType="single", allowedTypes=[], categ='Basic',
-                updates='constant',
+                updates='constant', allowedUpdates=["constant"],
                 hint=_translate("Tick positions (numerical) on the scale, "
                                 "separated by commas"),
                 label=_translate("Ticks"))
@@ -107,7 +107,7 @@ class SliderComponent(BaseVisualComponent):
         )
         self.params['labels'] = Param(
                 labels, valType='list', inputType="single", allowedTypes=[], categ='Basic',
-                updates='constant',
+                updates='constant', allowedUpdates=["constant"],
                 hint=_translate("Labels for the tick marks on the scale, "
                                 "separated by commas"),
                 label=_translate("Labels"))
@@ -118,7 +118,7 @@ class SliderComponent(BaseVisualComponent):
         )
         self.params['granularity'] = Param(
                 granularity, valType='num', inputType="single", allowedTypes=[], categ='Basic',
-                updates='constant',
+                updates='constant', allowedUpdates=["constant"],
                 hint=_translate("Specifies the minimum step size "
                                 "(0 for a continuous scale, 1 for integer "
                                 "rating scale)"),
@@ -168,7 +168,7 @@ class SliderComponent(BaseVisualComponent):
         self.params['borderColor'].hint = _translate("Color of all lines on this slider (might be overridden by the style setting)")
 
         self.params['font'] = Param(
-                font, valType='str', inputType="single", categ='Formatting',
+                font, valType='str', inputType="font", categ='Formatting',
                 updates='constant',
                 hint=_translate(
                         "Font for the labels"),

psychopy/experiment/components/sound/__init__.py

@@ -3,11 +3,12 @@
 
 """
 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
+from psychopy.alerts._alerts import alert
 from psychopy.experiment.components import BaseDeviceComponent, Param, getInitVals, \
     _translate
 from psychopy.experiment.utils import canBeNumeric
@@ -21,37 +22,49 @@ class SoundComponent(BaseDeviceComponent):
     iconFile = Path(__file__).parent / 'sound.png'
     tooltip = _translate('Sound: play recorded files or generated sounds', )
     deviceClasses = ["psychopy.hardware.speaker.SpeakerDevice"]
+    validatorClasses = ["AudioValidatorRoutine"]
 
-    def __init__(self,
-                 exp, parentName,
-                 # basic
-                 name='sound_1',
-                 sound='A',
-                 startType='time (s)', startVal='0.0',
-                 stopType='duration (s)', stopVal='1.0',
-                 startEstim='', durationEstim='',
-                 syncScreenRefresh=True,
-                 # device
-                 deviceLabel="",
-                 speakerIndex=-1,
-                 # playback
-                 volume=1,
-                 stopWithRoutine=True):
+    def __init__(
+        self,
+        exp, parentName,
+        # basic
+        name='sound_1',
+        sound='A',
+        startType='time (s)', startVal='0.0',
+        stopType='duration (s)', stopVal='1.0',
+        startEstim='', durationEstim='',
+        syncScreenRefresh=True,
+        # device
+        deviceLabel="",
+        speakerIndex=-1,
+        resample=True,
+        latencyClass=1,
+        # playback
+        volume=1,
+        stopWithRoutine=True,
+        forceEndRoutine=False,
+        # testing
+        validator="",
+        disabled=False,
+    ):
         super(SoundComponent, self).__init__(
             exp, parentName, name,
             startType=startType, startVal=startVal,
             stopType=stopType, stopVal=stopVal,
             startEstim=startEstim, durationEstim=durationEstim,
-            deviceLabel=deviceLabel
+            deviceLabel=deviceLabel,
+            disabled=disabled
         )
         self.type = 'Sound'
         self.url = "https://www.psychopy.org/builder/components/sound.html"
         self.exp.requirePsychopyLibs(['sound'])
+
+        # --- Basic params ---
         self.order += [
-            "sound",  # Basic tab
-            "volume", "hammingWindow",  # Playback tab
+            "sound",  
+            "syncScreenRefresh",
         ]
-        # params
+
         hnt = _translate("When does the Component end? (blank to use the "
                          "duration of the media)")
         self.params['stopVal'].hint = hnt
@@ -64,11 +77,6 @@ class SoundComponent(BaseDeviceComponent):
             hint=hnt,
             label=_translate("Sound"))
         _allowed = ['constant', 'set every repeat', 'set every frame']
-        self.params['volume'] = Param(
-            volume, valType='num', inputType="single", allowedTypes=[], updates='constant', categ='Playback',
-            allowedUpdates=_allowed[:],  # use a copy
-            hint=_translate("The volume (in range 0 to 1)"),
-            label=_translate("Volume"))
         msg = _translate(
             "A reaction time to a sound stimulus should be based on when "
             "the screen flipped")
@@ -77,6 +85,20 @@ class SoundComponent(BaseDeviceComponent):
             updates='constant',
             hint=msg,
             label=_translate("Sync start with screen"))
+
+        # --- Playback params ---
+        self.order += [
+            "volume", 
+            "hamming", 
+            "stopWithRoutine", 
+            "forceEndRoutine",
+        ]
+        self.params['volume'] = Param(
+            volume, valType='num', inputType="single", allowedTypes=[], updates='constant', categ='Playback',
+            allowedUpdates=_allowed[:],  # use a copy
+            hint=_translate("The volume (in range 0 to 1)"),
+            label=_translate("Volume")
+        )
         self.params['hamming'] = Param(
             True, valType='bool', inputType="bool", updates='constant', categ='Playback',
             hint=_translate(
@@ -89,15 +111,22 @@ class SoundComponent(BaseDeviceComponent):
                 "Should playback cease when the Routine ends? Untick to continue playing "
                 "after the Routine has finished."),
             label=_translate('Stop with Routine?'))
+        self.params['forceEndRoutine'] = Param(
+            forceEndRoutine, valType="bool", inputType="bool", updates="constant", categ="Playback",
+            hint=_translate(
+                "Should the end of the sound cause the end of the Routine (e.g. trial)?"
+            ),
+            label=_translate("Force end of Routine"))
 
         # --- Device params ---
         self.order += [
-            "speaker"
+            "speakerIndex",
+            "resample",
+            "latencyClass",
         ]
-
         def getSpeakerLabels():
             from psychopy.hardware.speaker import SpeakerDevice
-            labels = [_translate("Default")]
+            labels = [_translate("From preferences")]
             for profile in SpeakerDevice.getAvailableDevices():
                 labels.append(profile['deviceName'])
 
@@ -105,31 +134,70 @@ class SoundComponent(BaseDeviceComponent):
 
         def getSpeakerValues():
             from psychopy.hardware.speaker import SpeakerDevice
-            vals = [-1]
+            vals = [""]
             for profile in SpeakerDevice.getAvailableDevices():
                 vals.append(profile['index'])
 
             return vals
 
         self.params['speakerIndex'] = Param(
-            speakerIndex, valType="code", inputType="choice", categ="Device",
+            speakerIndex, valType="str", inputType="choice", categ="Device",
             allowedVals=getSpeakerValues,
             allowedLabels=getSpeakerLabels,
             hint=_translate(
                 "What speaker to play this sound on"
             ),
-            label=_translate("Speaker")
+            label=_translate("Speaker"))
+        self.params['resample'] = Param(
+            resample, valType="str", inputType="bool", categ="Device",
+            label=_translate("Resample"),
+            hint=_translate(
+                "If the sample rate of a clip doesn't match the sample rate of the speaker, should "
+                "we resample it to match?"
+            )
+        )
+        self.params['latencyClass'] = Param(
+            latencyClass, valType="code", inputType="choice", categ="Device",
+            allowedVals=[0, 1, 2, 3, 4],
+            allowedLabels=[
+                _translate("Shared"), 
+                _translate("Shared low-latency (recommended)"), 
+                _translate("Exclusive low-latency"),
+                _translate("Exclusive aggressive low-latency (with fallback)"),
+                _translate("Exclusive aggressive low-latency (no fallback)"),
+            ],
+            label=_translate("Latency/exclusivity mode"),
+            hint=_translate(
+                "How should PsychoPy handle latency? Some options will result in other apps being "
+                "denied access to the speaker while your experiment is running."
+            )
+        )
+
+        # --- Testing ---
+        self.params['validator'] = Param(
+            validator, valType="code", inputType="choice", categ="Testing",
+            allowedVals=self.getAllValidatorRoutineVals,
+            allowedLabels=self.getAllValidatorRoutineLabels,
+            label=_translate("Validate with..."),
+            hint=_translate(
+                "Name of validator Component/Routine to use to check the timing of this stimulus."
+            )
         )
 
     def writeDeviceCode(self, buff):
         inits = getInitVals(self.params)
+        # alert user to inefficient configuration
+        if self.params['resample'] and self.params['latencyClass'] == 2:
+            alert(3210, strFields={'deviceName': inits['deviceLabel']})
         # initialise speaker
         code = (
             "# create speaker %(deviceLabel)s\n"
             "deviceManager.addDevice(\n"
             "    deviceName=%(deviceLabel)s,\n"
             "    deviceClass='psychopy.hardware.speaker.SpeakerDevice',\n"
-            "    index=%(speakerIndex)s\n"
+            "    index=%(speakerIndex)s,\n"
+            "    resample=%(resample)s,\n"
+            "    latencyClass=%(latencyClass)s,\n"
             ")\n"
         )
         buff.writeOnceIndentedLines(code % inits)
@@ -189,11 +257,23 @@ class SoundComponent(BaseDeviceComponent):
                                           inits['sound'],
                                           inits['stopVal']))
         buff.writeIndented("%(name)s.setVolume(%(volume)s);\n" % (inits))
+        # until isFinished and isPlaying are added in JS, we can immitate them here
+        code = (
+            "%(name)s.isPlaying = false;\n"
+            "%(name)s.isFinished = false;\n"
+        )
+        buff.writeIndentedLines(code % self.params)
 
     def writeRoutineStartCodeJS(self, buff):
         stopVal = self.params['stopVal']
         if stopVal in ['', None, 'None']:
             stopVal = -1
+        
+        # never start a Routine marked as finished
+        code = (
+            "%(name)s.isFinished = false;"
+        )
+        buff.writeIndentedLines(code % self.params)
 
         if self.params['sound'].updates == 'set every repeat':
             buff.writeIndented("%(name)s.setValue(%(sound)s);\n" % self.params)
@@ -228,15 +308,36 @@ class SoundComponent(BaseDeviceComponent):
         # write code for stopping
         indented = self.writeStopTestCode(buff, extra=" or %(name)s.isFinished")
         if indented:
-            code = ("%(name)s.stop()\n")
+            # stop playback
+            code = (
+                "%(name)s.stop()\n"
+            )
             buff.writeIndentedLines(code % self.params)
+            # force end of Routine if asked
+            if self.params['forceEndRoutine']:
+                code = (
+                    "# %(name)s has finished playback, so force end Routine\n"
+                    "continueRoutine = False\n"
+                )
+                buff.writeIndentedLines(code % self.params)
         # because of the 'if' statement of the time test
         buff.setIndentLevel(-indented, relative=True)
 
     def writeFrameCodeJS(self, buff):
         """Write the code that will be called every frame
         """
-        # the sound object is unusual, because it is
+        # until isFinished and isPlaying are added in JS, we can immitate them here
+        code = (
+            "if (%(name)s.status === STARTED) {\n"
+            "    %(name)s.isPlaying = true;\n"
+            "    if (t >= (%(name)s.getDuration() + %(name)s.tStart)) {\n"
+            "        %(name)s.isFinished = true;\n"
+            "    }\n"
+            "}\n"
+        )
+        buff.writeIndentedLines(code % self.params)
+
+        # the sound object is unusual, because it is controlling the playback stream
         buff.writeIndented("// start/stop %(name)s\n" % (self.params))
         # do this EVERY frame, even before/after playing?
         self.writeParamUpdates(buff, 'set every frame', target="PsychoJS")
@@ -250,38 +351,27 @@ class SoundComponent(BaseDeviceComponent):
         # because of the 'if' statement of the time test
         buff.setIndentLevel(-1, relative=True)
         buff.writeIndentedLines('}\n')
-        knownNote = (self.params['sound'] in knownNoteNames) or (self.params['sound'].val.isdigit())
-        if self.params['stopVal'].val in [None, 'None', '']:
-            if not knownNote:  # Known notes have no getDuration function because duration is infinite or not None
-                # infinite sounds
-                code = ('if (t >= (%(name)s.getDuration() + %(name)s.tStart) '
-                        '    && %(name)s.status === PsychoJS.Status.STARTED) {\n'
-                        '  %(name)s.stop();  // stop the sound (if longer than duration)\n'
-                        '  %(name)s.status = PsychoJS.Status.FINISHED;\n'
-                        '}\n')
-                buff.writeIndentedLines(code % self.params)
-        else:
-            # sounds with stop values
-            self.writeStopTestCodeJS(buff)
-            code = ("if (t >= %(name)s.tStart + 0.5) {\n"
-                    "  %(name)s.stop();  // stop the sound (if longer than duration)\n"
-                    "  %(name)s.status = PsychoJS.Status.FINISHED;\n"
-                    "}\n")
-            buff.writeIndentedLines(code % self.params)
-            # because of the 'if' statement of the time test
-            buff.setIndentLevel(-1, relative=True)
-            buff.writeIndented('}\n')
 
-            # # Update status
-            # code = (
-            #     "// update %(name)s status according to whether it's playing\n"
-            #     "if (%(name)s.isPlaying) {\n"
-            #     "  %(name)s.status = PsychoJS.Status.STARTED;\n"
-            #     "} else if (%(name)s.isFinished) {\n"
-            #     "  %(name)s.status = PsychoJS.Status.FINISHED;\n"
-            #     "}\n"
-            # )
-            # buff.writeIndentedLines(code % self.params)
+        # are we stopping this frame?
+        indented = self.writeStopTestCodeJS(buff, extra=" || %(name)s.isFinished")
+        if indented:
+            # stop playback
+            code = (
+                "// stop playback\n"
+                "%(name)s.stop();\n"
+            )
+            buff.writeIndentedLines(code % self.params)
+            # end Routine if asked
+            if self.params['forceEndRoutine']:
+                code = (
+                    "// %(name)s has finished playback, so force end Routine\n"
+                    "continueRoutine = false;\n"
+                )
+                buff.writeIndentedLines(code % self.params)
+            # exit if statement(s)
+            for n in range(indented):
+                buff.setIndentLevel(-1, relative=True)
+                buff.writeIndentedLines("}\n")
 
     def writeRoutineEndCode(self, buff):
         if self.params['stopWithRoutine']:
@@ -302,20 +392,20 @@ class SoundComponent(BaseDeviceComponent):
             buff.writeIndentedLines(code % self.params)
 
     def writeParamUpdate(
-            self, 
-            buff, 
-            compName, 
-            paramName, 
-            val, 
+            self,
+            buff,
+            compName,
+            paramName,
+            val,
             updateType,
-            params=None, 
+            params=None,
             target="PsychoPy",
     ):
         """
         Overload BaseComponent.writeParamUpdate to handle special case for SoundComponent
         """
         # when writing param updates for Sound.sound, needs to be `setValue` in JS
-        # (this is intended as a temporary patch - please delete when `setSound` in JS can accept 
+        # (this is intended as a temporary patch - please delete when `setSound` in JS can accept
         # the same range of values as in Py)
         if target == 'PsychoJS' and paramName == "sound":
             # get logging string
@@ -331,12 +421,12 @@ class SoundComponent(BaseDeviceComponent):
         else:
             # do normal stuff for every other param
             BaseDeviceComponent.writeParamUpdate(
-                self, 
-                buff, 
-                compName, 
-                paramName, 
-                val, 
+                self,
+                buff,
+                compName,
+                paramName,
+                val,
                 updateType,
-                params=params, 
+                params=params,
                 target=target,
             )