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

psychopy/experiment/loops.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).
 
 """Experiment classes:
@@ -216,8 +216,15 @@ class TrialHandler(_BaseLoopHandler):
         # then run the trials loop
         code = "\nfor %s in %s:\n"
         buff.writeIndentedLines(code % (self.thisName, self.params['name']))
-        # fetch parameter info from conditions
         buff.setIndentLevel(1, relative=True)
+        # mark current trial as started
+        code = (
+            "%(name)s.status = STARTED\n"
+            "if hasattr(%(loopIndex)s, 'status'):\n"
+            "    %(loopIndex)s.status = STARTED\n"
+        )
+        buff.writeIndentedLines(code % inits)
+        # fetch parameter info from conditions
         code = (
             "currentLoop = %(name)s\n"
             "thisExp.timestampOnFlip(win, 'thisRow.t', format=globalClock.format)\n"
@@ -345,7 +352,28 @@ class TrialHandler(_BaseLoopHandler):
         )
 
     def writeLoopEndCode(self, buff):
-        # Just within the loop advance data line if loop is whole trials
+        # copy params so we can safely add to it
+        params = self.params.copy()
+        # add param for current trial name
+        params['thisName'] = self.thisName
+        # mark current trial as finished at end of each iteration
+        code = (
+            "# mark %(thisName)s as finished\n"
+            "if hasattr(%(thisName)s, 'status'):\n"
+            "    %(thisName)s.status = FINISHED\n"
+            "# if awaiting a pause, pause now\n"
+            "if %(name)s.status == PAUSED:\n"
+            "    thisExp.status = PAUSED\n"
+            "    pauseExperiment(\n"
+            "        thisExp=thisExp, \n"
+            "        win=win, \n"
+            "        timers=[globalClock], \n"
+            "    )\n"
+            "    # once done pausing, restore running status\n"
+            "    %(name)s.status = STARTED"
+        )
+        buff.writeIndentedLines(code % params)
+        # just within the loop advance data line if loop is whole trials
         if self.params['isTrials'].val == True:
             buff.writeIndentedLines(
                 "thisExp.nextEntry()\n"
@@ -353,9 +381,13 @@ class TrialHandler(_BaseLoopHandler):
             )
         # end of the loop. dedent
         buff.setIndentLevel(-1, relative=True)
-        buff.writeIndented("# completed %s repeats of '%s'\n"
-                           % (self.params['nReps'], self.params['name']))
-        buff.writeIndented("\n")
+        # mark finished
+        code = (
+            "# completed %(nReps)s repeats of '%(name)s'\n"
+            "%(name)s.status = FINISHED\n"
+            "\n"
+        )
+        buff.writeIndentedLines(code % params)
         # save data
         if self.params['isTrials'].val:
             # send final data to Liaison
@@ -385,7 +417,7 @@ class TrialHandler(_BaseLoopHandler):
                         "    dataOut=['n','all_mean','all_std', 'all_raw'])\n")
                 buff.writeIndentedLines(code % self.params)
             if saveCSV:
-                code = ("%(name)s.saveAsText(filename + '%(name)s.csv', "
+                code = ("%(name)s.saveAsText(filename + '_%(name)s.csv', "
                         "delim=',',\n"
                         "    stimOut=params,\n"
                         "    dataOut=['n','all_mean','all_std', 'all_raw'])\n")
@@ -574,7 +606,7 @@ class StairHandler(_BaseLoopHandler):
                 buff.writeIndented(code % self.params)
             if self.exp.settings.params['Save csv file'].val:
                 code = ("%(name)s.saveAsText(filename + "
-                        "'%(name)s.csv', delim=',')\n")
+                        "'_%(name)s.csv', delim=',')\n")
                 buff.writeIndented(code % self.params)
 
     def getType(self):
@@ -683,7 +715,8 @@ class MultiStairHandler(_BaseLoopHandler):
     def writeLoopStartCode(self, buff):
         # create a 'thisName' for use in "for thisTrial in trials:"
         makeLoopIndex = self.exp.namespace.makeLoopIndex
-        self.thisName = makeLoopIndex(self.params['name'].val)
+        makeLoopIndex(self.params['name'].val)
+        self.thisName = "condition"
         # create the MultistairHander
         code = ("\n# set up handler to look after randomisation of trials etc\n"
                 "conditions = data.importConditions(%(conditionsFile)s)\n"
@@ -833,7 +866,7 @@ class MultiStairHandler(_BaseLoopHandler):
                 code = "%(name)s.saveAsExcel(filename + '.xlsx')\n"
                 buff.writeIndented(code % self.params)
             if self.exp.settings.params['Save csv file'].val:
-                code = ("%(name)s.saveAsText(filename + '%(name)s.csv', "
+                code = ("%(name)s.saveAsText(filename + '_%(name)s.csv', "
                         "delim=',')\n")
                 buff.writeIndented(code % self.params)
 

psychopy/experiment/params.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).
 
 """Experiment classes:
@@ -56,9 +56,11 @@ inputDefaults = {
 # silence any "future version" warnings
 legacyParams = [
     # in 2021.1, we standardised colorSpace to be object-wide rather than param-specific
-    'lineColorSpace', 'borderColorSpace', 'fillColorSpace', 'foreColorSpace', 
+    "lineColorSpace", "borderColorSpace", "fillColorSpace", "foreColorSpace", 
     # in 2024.2.0, we removed some superfluous params from the pupil labs backend
     "plCompanionRecordingEnabled", "plPupilCaptureRecordingEnabled",
+    # from 2025.1, latency priority is handled by SpeakerDevice
+    "Audio latency priority",
 ]
 
 
@@ -137,7 +139,7 @@ class Param():
             - code: Some code, will be compiled verbatim or translated to JS (no ")
             - extendedCode: A block of code, will be compiled verbatim or translated to JS and
               linebreaks will be preserved
-            - file: A file path, will be compiled like str but will replace unescaped \ with /
+            - file: A file path, will be compiled like str but will replace unescaped \\ with /
             - list: A list of values, will be compiled like code but if there's no [] or () then
               these are added
             Note that, if value begins with a $, it will always be treated as code regardless of
@@ -178,7 +180,7 @@ class Param():
             Mostly used by the test suite to check that params which should be used are used.
         canBePath : bool
             Is it possible for this parameter to be a path? Setting to False will disable
-            filepath sanitization (e.g. for textbox you may not want to replace \ with /)
+            filepath sanitization (e.g. for textbox you may not want to replace \\ with /)
         ctrlParams : dict
             Extra information to pass to the control, such as the Excel template file to use in a
             `table` control.

psychopy/experiment/plugins.py

@@ -1,3 +1,6 @@
+from psychopy import logging
+
+
 class PluginDevicesMixin:
     """
     Mixin for Components and Routines which adds behaviour to get parameters and values from
@@ -78,6 +81,10 @@ class DeviceBackend:
     deviceClasses = []
 
     def __init_subclass__(cls):
+        logging.debug(
+            f"Registered backend for {cls.component.__name__}: {cls.label} ({cls.key}) from "
+            f"{cls.__module__}:{cls.__name__}"
+        )
         # add class to list of backends for ButtonBoxComponent
         cls.component.backends = cls.component.backends.copy()
         cls.component.backends.append(cls)
@@ -106,7 +113,7 @@ class DeviceBackend:
         """
         Add any required module/package imports for this backend
         """
-        raise NotImplementedError()
+        return
 
     def writeDeviceCode(self, buff):
         """

psychopy/experiment/py2js.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).
 
 """Converting code parameters and components from python (PsychoPy)

psychopy/experiment/py2js_transpiler.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).
 
 import ast

psychopy/experiment/routines/__init__.py

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

psychopy/experiment/routines/_base.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).
 
 """Describes the Flow of an experiment
@@ -30,6 +30,8 @@ class BaseStandaloneRoutine:
     version = "0.0.0"
     # is it still in beta?
     beta = False
+    # hide this Component in Builder view?
+    hidden = False
 
     def __init__(self, exp, name='',
                  stopType='duration (s)', stopVal='',
@@ -680,16 +682,6 @@ class Routine(list):
                 '\n# --- Run Routine "{name}" ---\n')
         buff.writeIndentedLines(code.format(name=self.name,
                                             clockName=self._clockName))
-        # check for the trials loop ending this Routine
-        if len(self.exp.flow._loopList):
-            loop = self.exp.flow._loopList[-1]
-            code = (
-                "# if trial has changed, end Routine now\n"
-                "if isinstance({name}, data.TrialHandler2) and {thisName}.thisN != {"
-                "name}.thisTrial.thisN:\n"
-                "    continueRoutine = False\n"
-            ).format(name=loop.name, thisName=loop.thisName)
-            buff.writeIndentedLines(code)
 
         # initial value for forceRoutineEnded (needs to happen now as Code components will have executed
         # their Begin Routine code)
@@ -705,6 +697,15 @@ class Routine(list):
         buff.writeIndented(code)
 
         buff.setIndentLevel(1, True)
+        # check for the trials loop ending this Routine
+        if len(self.exp.flow._loopList):
+            loop = self.exp.flow._loopList[-1]
+            code = (
+                "# if trial has changed, end Routine now\n"
+                "if hasattr({thisName}, 'status') and {thisName}.status == STOPPING:\n"
+                "    continueRoutine = False\n"
+            ).format(thisName=loop.thisName)
+            buff.writeIndentedLines(code)
         # on each frame
         code = ('# get current time\n'
                 't = {clockName}.getTime()\n'
@@ -720,8 +721,8 @@ class Routine(list):
         for event in self:
             if event.type == 'Static':
                 continue  # we'll do those later
-            event.writeFrameCode(buff)
             event.writeEachFrameValidationCode(buff)
+            event.writeFrameCode(buff)
         # update static component code last
         for event in self.getStatics():
             event.writeFrameCode(buff)
@@ -741,27 +742,20 @@ class Routine(list):
             "    return\n"
         )
         buff.writeIndentedLines(code)
-
-        # handle pausing
-        playbackComponents = [
-            comp.name for comp in self
-            if type(comp).__name__ in ("MovieComponent", "SoundComponent")
-        ]
-        playbackComponentsStr = ", ".join(playbackComponents)
+        # write code (work out playback and dispatch comps at runtime)
         code = (
             "# pause experiment here if requested\n"
             "if thisExp.status == PAUSED:\n"
             "    pauseExperiment(\n"
             "        thisExp=thisExp, \n"
             "        win=win, \n"
-            "        timers=[routineTimer], \n"
-            "        playbackComponents=[{playbackComponentsStr}]\n"
+            "        timers=[routineTimer, globalClock], \n"
+            "        currentRoutine=%(name)s,\n"
             "    )\n"
             "    # skip the frame we paused on\n"
             "    continue"
         )
-        code = code.format(playbackComponentsStr=playbackComponentsStr)
-        buff.writeIndentedLines(code)
+        buff.writeIndentedLines(code % self.params)
 
         # are we done yet?
         code = (
@@ -826,6 +820,8 @@ class Routine(list):
                 "t = 0;\n"
                 "frameN = -1;\n"
                 "continueRoutine = true; // until we're told otherwise\n"
+                "// keep track of whether this Routine was forcibly ended\n"
+                "routineForceEnded = false;\n"
                 % self.params)
         buff.writeIndentedLines(code)
         # can we use non-slip timing?
@@ -926,6 +922,7 @@ class Routine(list):
         code = ("// check if the Routine should terminate\n"
                 "if (!continueRoutine) {"
                 "  // a component has requested a forced-end of Routine\n"
+                "  routineForceEnded = true;\n"
                 "  return Scheduler.Event.NEXT;\n"
                 "}\n\n"
                 "continueRoutine = false;  "
@@ -1016,7 +1013,9 @@ class Routine(list):
         # reset routineTimer at the *very end* of all non-nonSlip routines
         if useNonSlip:
             code = (
-                "if (%(name)sMaxDurationReached) {{\n"
+                "if (routineForceEnded) {{\n"
+                "    routineTimer.reset();"
+                "}} else if (%(name)sMaxDurationReached) {{\n"
                 "    %(name)sClock.add(%(name)sMaxDuration);\n"
                 "}} else {{\n"
                 "    %(name)sClock.add({:f});\n"

psychopy/experiment/routines/audioValidator/__init__.py

@@ -0,0 +1,343 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+from pathlib import Path
+from psychopy.alerts._alerts import alert
+from psychopy.experiment import Param
+from psychopy.experiment.plugins import PluginDevicesMixin, DeviceBackend
+from psychopy.experiment.components import getInitVals
+from psychopy.experiment.routines import Routine, BaseValidatorRoutine
+from psychopy.localization import _translate
+
+
+class AudioValidatorRoutine(BaseValidatorRoutine, PluginDevicesMixin):
+    """
+    Use a sound sensor (voicekey or microphone) to confirm that audio stimuli are presented when they should be.
+    """
+    targets = ['PsychoPy']
+
+    categories = ['Validation']
+    iconFile = Path(__file__).parent / 'audio_validator.png'
+    tooltip = _translate(
+        "Use a sound sensor to confirm that audio stimuli are presented when they should "
+        "be."
+    )
+    deviceClasses = ["psychopy.validation.voicekey.AudioValidator"]
+    version = "2025.1.0"
+
+    def __init__(
+            self,
+            # basic
+            exp, name='audioVal',
+            threshold=0.5,
+            # device
+            deviceLabel="", deviceBackend="microphone", channel="0",
+    ):
+
+        self.exp = exp  # so we can access the experiment if necess
+        self.params = {}
+        self.depends = []
+        super(AudioValidatorRoutine, self).__init__(exp, name=name)
+        self.order += []
+        self.type = 'AudioValidator'
+
+        exp.requirePsychopyLibs(["validation"])
+
+        # --- Basic ---
+        self.order += [
+            "threshold",
+        ]
+        self.params['threshold'] = Param(
+            threshold, valType="code", inputType="single", categ="Basic",
+            label=_translate("Threshold"),
+            hint=_translate(
+                "Arbitrary volume threshold at which the sound sensor should register a positive, units go from 0 (least volume) to 1 (most volume)."
+            )
+        )
+        del self.params['stopType']
+        del self.params['stopVal']
+
+        # --- Device ---
+        self.order += [
+            "deviceLabel",
+            "deviceBackend",
+            "channel",
+        ]
+        self.params['deviceLabel'] = Param(
+            deviceLabel, valType="str", inputType="single", categ="Device",
+            label=_translate("Device name"),
+            hint=_translate(
+                "A name to refer to this Component's associated hardware device by. If using the "
+                "same device for multiple components, be sure to use the same name here."
+            )
+        )
+        self.params['deviceBackend'] = Param(
+            deviceBackend, valType="code", inputType="choice", categ="Device",
+            allowedVals=self.getBackendKeys,
+            allowedLabels=self.getBackendLabels,
+            label=_translate("Sound sensor type"),
+            hint=_translate(
+                "Type of sound sensor to use."
+            ),
+            direct=False
+        )
+        self.params['channel'] = Param(
+            channel, valType="code", inputType="single", categ="Device",
+            label=_translate("Sound sensor channel"),
+            hint=_translate(
+                "If relevant, a channel number attached to the sound sensor, to distinguish it "
+                "from other sound sensors on the same port. Leave blank to use the first sound sensor "
+                "which can detect the speaker."
+            )
+        )
+
+        self.loadBackends()
+
+    def writeDeviceCode(self, buff):
+        """
+        Code to setup the CameraDevice for this component.
+
+        Parameters
+        ----------
+        buff : io.StringIO
+            Text buffer to write code to.
+        """
+        # do usual backend-specific device code writing
+        PluginDevicesMixin.writeDeviceCode(self, buff)
+        # get inits
+        inits = getInitVals(self.params)
+        # get device handle
+        code = (
+            "%(deviceLabelCode)s = deviceManager.getDevice(%(deviceLabel)s)\n"
+            "%(deviceLabelCode)s.setThreshold(%(threshold)s, channel=%(channel)s)\n"
+        )
+        buff.writeOnceIndentedLines(code % inits)
+
+    def writeMainCode(self, buff):
+        inits = getInitVals(self.params)
+        # get diode
+        code = (
+            "# diode object for %(name)s\n"
+            "%(name)sDevice = deviceManager.getDevice(%(deviceLabel)s)\n"
+        )
+        buff.writeIndentedLines(code % inits)
+
+        if self.params['threshold']:
+            code = (
+                "%(name)sDevice.setThreshold(%(threshold)s, channel=%(channel)s)\n"
+            )
+            buff.writeIndentedLines(code % inits)
+        # create validator object
+        code = (
+            "# validator object for %(name)s\n"
+            "%(name)s = validation.AudioValidator(\n"
+            "    %(name)sDevice, %(channel)s,\n"
+            ")\n"
+        )
+        buff.writeIndentedLines(code % inits)
+        # connect stimuli
+        for stim in self.findConnectedStimuli():
+            code = (
+                "# connect {stim} to %(name)s\n"
+                "%(name)s.connectStimulus({stim})\n"
+            ).format(stim=stim.params['name'])
+            buff.writeIndentedLines(code % inits)
+
+    def writeRoutineStartValidationCode(self, buff, stim):
+        """
+        Write the routine start code to validate a given stimulus using this validator.
+
+        Parameters
+        ----------
+        buff : StringIO
+            String buffer to write code to.
+        stim : BaseComponent
+            Stimulus to validate
+
+        Returns
+        -------
+        int
+            Change in indentation level after writing
+        """
+        # get starting indent level
+        startIndent = buff.indentLevel
+
+        # choose a clock to sync to according to component's params
+        if "syncScreenRefresh" in stim.params and stim.params['syncScreenRefresh']:
+            clockStr = ""
+        else:
+            clockStr = "clock=routineTimer"
+        # sync component start/stop timers with validator clocks
+        code = (
+            f"# synchronise device clock for %(name)s with Routine timer\n"
+            f"%(name)s.resetTimer({clockStr})\n"
+        )
+        buff.writeIndentedLines(code % self.params)
+
+        # return change in indent level
+        return buff.indentLevel - startIndent
+
+    def writeEachFrameValidationCode(self, buff, stim):
+        """
+        Write the each frame code to validate a given stimulus using this validator.
+
+        Parameters
+        ----------
+        buff : StringIO
+            String buffer to write code to.
+        stim : BaseComponent
+            Stimulus to validate
+
+        Returns
+        -------
+        int
+            Change in indentation level after writing
+        """
+        # get starting indent level
+        startIndent = buff.indentLevel
+
+        # validate start time
+        code = (
+            "# validate {name} start time\n"
+            "if {name}.status == STARTED and %(name)s.status == STARTED:\n"
+            "    %(name)s.tStart, %(name)s.tStartDelay = %(name)s.validate(state=True, t={name}.tStartRefresh)\n"
+            "    if %(name)s.tStart is not None:\n"
+            "        %(name)s.status = FINISHED\n"
+        )
+        if stim.params['saveStartStop']:
+            # save validated start time if stim requested
+            code += (
+            "        thisExp.addData('{name}.%(name)s.started', %(name)s.tStart)\n"
+            "        thisExp.addData('{name}.%(name)s.startDelay', %(name)s.tStartDelay)\n"
+            )
+        buff.writeIndentedLines(code.format(**stim.params) % self.params)
+
+        # validate stop time
+        code = (
+            "# validate {name} stop time\n"
+            "if {name}.status == FINISHED and %(name)s.status == STARTED:\n"
+            "    %(name)s.tStop, %(name)s.tStopDelay = %(name)s.validate(state=False, t={name}.tStopRefresh)\n"
+            "    if %(name)s.tStop is not None:\n"
+            "        %(name)s.status = FINISHED\n"
+        )
+        if stim.params['saveStartStop']:
+            # save validated start time if stim requested
+            code += (
+            "        thisExp.addData('{name}.%(name)s.stopped', %(name)s.tStop)\n"
+            "        thisExp.addData('{name}.%(name)s.stopDelay', %(name)s.tStopDelay)\n"
+            )
+        buff.writeIndentedLines(code.format(**stim.params) % self.params)
+
+        # return change in indent level
+        return buff.indentLevel - startIndent
+
+    def findConnectedStimuli(self):
+        # list of linked components
+        stims = []
+        routines = []
+        # inspect each Routine
+        for emt in self.exp.flow:
+            # skip non-standard Routines
+            if not isinstance(emt, Routine):
+                continue
+            # inspect each Component
+            for comp in emt:
+                # get validators for this component
+                compValidator = comp.getValidator()
+                # look for self
+                if compValidator == self:
+                    # if found, add the comp to the list
+                    stims.append(comp)
+                    # add to list of Routines containing comps
+                    if emt not in routines:
+                        routines.append(emt)
+        # if any rt has two validated comps, warn
+        if len(routines) < len(stims):
+            alert(3610, obj=self, strFields={'validator': self.name})
+
+        return stims
+
+
+class MicrophoneSoundSensorValidatorBackend(DeviceBackend):
+    """
+    Adds a microphone sound sensor emulation backend for AudioValidator, as well as acting as an
+    example for implementing other sound sensor device backends.
+    """
+
+    key = "microphone"
+    label = _translate("Microphone")
+    component = AudioValidatorRoutine
+    deviceClasses = ["psychopy.hardware.soundsensor.MicrophoneSoundSensor"]
+
+    def getParams(self: AudioValidatorRoutine):
+        # define order
+        order = [
+            'microphone',
+            'dbRange',
+            'samplingWindow'
+        ]
+        # define params
+        params = {}
+        def getDeviceIndices():
+            from psychopy.hardware.microphone import MicrophoneDevice
+            profiles = MicrophoneDevice.getAvailableDevices()
+
+            return [None] + [profile['index'] for profile in profiles]
+
+        def getDeviceNames():
+            from psychopy.hardware.microphone import MicrophoneDevice
+            profiles = MicrophoneDevice.getAvailableDevices()
+
+            return ["default"] + [profile['deviceName'] for profile in profiles]
+
+        params['microphone'] = Param(
+            None, valType='str', inputType="choice", categ="Device",
+            allowedVals=getDeviceIndices,
+            allowedLabels=getDeviceNames,
+            label=_translate("Microphone"),
+            hint=_translate(
+                "What microphone device to use?"
+            )
+        )
+        params['dbRange'] = Param(
+            (0, 1), valType="list", inputType="single", categ="Device",
+            label=_translate("Decibel range"),
+            hint=_translate(
+                "Range of possible decibels to expect mic responses to be in, by default (0, 1)"
+            )
+        )
+        params['samplingWindow'] = Param(
+            0.03, valType="code", inputType="single", categ="Device",
+            label=_translate("Sampling window"),
+            hint=_translate(
+                "How long (s) to average samples from the microphone across? Larger sampling "
+                "windows reduce the chance of random spikes, but also reduce sensitivity."
+            )
+        )
+
+        return params, order
+
+    def addRequirements(self):
+        # needs microphone
+        self.exp.requireImport(
+            importName="MicrophoneDevice",
+            importFrom="psychopy.hardware.microphone"
+        )
+
+    def writeDeviceCode(self: AudioValidatorRoutine, buff):
+        # get inits
+        inits = getInitVals(self.params)
+        # make MicrophoneVoiceKey object
+        code = (
+            "%(name)sDevice = MicrophoneDevice(\n"
+            "    index=%(microphone)s\n"
+            ")\n"
+            "deviceManager.addDevice(\n"
+            "    deviceClass='psychopy.hardware.soundsensor.MicrophoneSoundSensor',\n"
+            "    deviceName=%(deviceLabel)s,\n"
+            "    device=%(name)sDevice, \n"
+            "    dbRange=%(dbRange)s, \n"
+            "    samplingWindow=%(samplingWindow)s, \n"
+            ")\n"
+        )
+        buff.writeOnceIndentedLines(code % inits)