psychopy 2024.1.4__py3-none-any.whl → 2024.2.0__py3-none-any.whl

psychopy/hardware/microphone.py

@@ -6,7 +6,7 @@ from psychtoolbox import audio as audio
 from psychopy import logging as logging, prefs
 from psychopy.localization import _translate
 from psychopy.constants import NOT_STARTED
-from psychopy.hardware import BaseDevice
+from psychopy.hardware import BaseDevice, BaseResponse, BaseResponseDevice
 from psychopy.sound.audiodevice import AudioDeviceInfo, AudioDeviceStatus
 from psychopy.sound.audioclip import AudioClip
 from psychopy.sound.exceptions import AudioInvalidCaptureDeviceError, AudioInvalidDeviceError, \
@@ -27,6 +27,10 @@ except (ImportError, ModuleNotFoundError):
     _hasPTB = False
 
 
+class MicrophoneResponse(BaseResponse):
+    pass
+
+
 class MicrophoneDevice(BaseDevice, aliases=["mic", "microphone"]):
     """Class for recording audio from a microphone or input stream.
 
@@ -144,11 +148,42 @@ class MicrophoneDevice(BaseDevice, aliases=["mic", "microphone"]):
             # if there are none, error
             if not len(_devices):
                 raise AudioInvalidCaptureDeviceError(_translate(
-                    "Could not choose default recording device as no recording devices are "
-                    "connected."
+                    "Could not choose default recording device as no recording "
+                    "devices are connected."
                 ))
-            # use first device
-            self._device = _devices[0]
+
+            # Try and get the best match which are compatible with the user's
+            # specified settings.
+            if sampleRateHz is not None or channels is not None:
+                self._device = self.findBestDevice(
+                    index=_devices[0].deviceIndex,  # use first that shows up
+                    sampleRateHz=sampleRateHz,
+                    channels=channels
+                )
+            else:
+                self._device = _devices[0]
+            
+            # Check if the default device settings are differnt than the ones 
+            # specified by the user, if so, warn them that the default device
+            # settings are overwriting their settings.
+            if channels is None:
+                channels = self._device.inputChannels
+            elif channels != self._device.inputChannels:
+                logging.warning(
+                    "Number of channels specified ({}) does not match the "
+                    "default device's number of input channels ({}).".format(
+                        channels, self._device.inputChannels))
+                channels = self._device.inputChannels
+
+            if sampleRateHz is None:
+                sampleRateHz = self._device.defaultSampleRate
+            elif sampleRateHz != self._device.defaultSampleRate:
+                logging.warning(
+                    "Sample rate specified ({}) does not match the default "
+                    "device's sample rate ({}).".format(
+                        sampleRateHz, self._device.defaultSampleRate))
+                sampleRateHz = self._device.defaultSampleRate
+
         elif isinstance(index, str):
             # if given a str that's a name from DeviceManager, get info from device
             device = DeviceManager.getDevice(index)
@@ -167,8 +202,13 @@ class MicrophoneDevice(BaseDevice, aliases=["mic", "microphone"]):
                 channels=channels
             )
 
-        logging.info('Using audio device #{} ({}) for audio capture. Full spec: {}'.format(
-            self._device.deviceIndex, self._device.deviceName, self._device))
+        devInfoText = ('Using audio device #{} ({}) for audio capture. '
+            'Full spec: {}').format(
+                self._device.deviceIndex, 
+                self._device.deviceName, 
+                self._device)
+        
+        logging.info(devInfoText)
 
         # error if specified device is not suitable for capture
         if not self._device.isCapture:
@@ -176,11 +216,12 @@ class MicrophoneDevice(BaseDevice, aliases=["mic", "microphone"]):
                 'Specified audio device not suitable for audio recording. '
                 'Has no input channels.')
 
-        # get the sample rate
-        self._sampleRateHz = \
-            self._device.defaultSampleRate if sampleRateHz is None else int(
-                sampleRateHz)
+        # get these values from the configured device
+        self._channels = self._device.inputChannels
+        logging.debug('Set recording channels to {} ({})'.format(
+            self._channels, 'stereo' if self._channels > 1 else 'mono'))
 
+        self._sampleRateHz = self._device.defaultSampleRate
         logging.debug('Set stream sample rate to {} Hz'.format(
             self._sampleRateHz))
 
@@ -195,13 +236,6 @@ class MicrophoneDevice(BaseDevice, aliases=["mic", "microphone"]):
 
         assert 0 <= self._audioLatencyMode <= 4  # sanity check for pref
 
-        # set the number of recording channels
-        self._channels = \
-            self._device.inputChannels if channels is None else int(channels)
-
-        logging.debug('Set recording channels to {} ({})'.format(
-            self._channels, 'stereo' if self._channels > 1 else 'mono'))
-
         # internal recording buffer size in seconds
         assert isinstance(streamBufferSecs, (float, int))
         self._streamBufferSecs = float(streamBufferSecs)
@@ -268,6 +302,9 @@ class MicrophoneDevice(BaseDevice, aliases=["mic", "microphone"]):
         logging.debug('Audio capture device #{} ready'.format(
             self._device.deviceIndex))
 
+        # list to store listeners in
+        self.listeners = []
+
     def findBestDevice(self, index, sampleRateHz, channels):
         """
         Find the closest match among the microphone profiles listed by psychtoolbox as valid.
@@ -797,6 +834,99 @@ class MicrophoneDevice(BaseDevice, aliases=["mic", "microphone"]):
 
         return self._recording.getSegment()  # full recording
 
+    def getCurrentVolume(self, timeframe=0.2):
+        """
+        Get the current volume measured by the mic.
+
+        Parameters
+        ----------
+        timeframe : float
+            Time frame (s) over which to take samples from. Default is 0.1s.
+
+        Returns
+        -------
+        float
+            Current volume registered by the mic, will depend on relative volume of the mic but
+            should mostly be between 0 (total silence) and 1 (very loud).
+        """
+        # if mic hasn't started yet, return 0 as it's recorded nothing
+        if not self.isStarted:
+            return 0
+        # poll most recent samples
+        self.poll()
+        # get last 0.1sas a clip
+        clip = self._recording.getSegment(
+            max(self._recording.lastSample / self._sampleRateHz - timeframe, 0)
+        )
+
+        return clip.rms() * 10
+
+    def addListener(self, listener, startLoop=False):
+        """
+        Add a listener, which will receive all the same messages as this device.
+
+        Parameters
+        ----------
+        listener : str or psychopy.hardware.listener.BaseListener
+            Either a Listener object, or use one of the following strings to create one:
+            - "liaison": Create a LiaisonListener with DeviceManager.liaison as the server
+            - "print": Create a PrintListener with default settings
+            - "log": Create a LoggingListener with default settings
+        startLoop : bool
+            If True, then upon adding the listener, start up an asynchronous loop to dispatch messages.
+        """
+        # add listener as normal
+        BaseResponseDevice.addListener(self, listener, startLoop=startLoop)
+        # if we're starting a listener loop, start recording
+        if startLoop:
+            self.start()
+
+    def clearListeners(self):
+        """
+        Remove any listeners from this device.
+
+        Returns
+        -------
+        bool
+            True if completed successfully
+        """
+        # clear listeners as normal
+        BaseResponseDevice.clearListeners(self)
+        # stop recording
+        self.stop()
+
+    def dispatchMessages(self, clear=True):
+        """
+        Dispatch current volume as a MicrophoneResponse object to any attached listeners.
+
+        Parameters
+        ----------
+        clear : bool
+            If True, will clear the recording up until now after dispatching the volume. This is
+            useful if you're just sampling volume and aren't wanting to store the recording.
+        """
+        # create a response object
+        message = MicrophoneResponse(
+            logging.defaultClock.getTime(),
+            self.getCurrentVolume()
+        )
+        # clear recording if requested (helps with continuous running)
+        if clear and self.isRecBufferFull:
+            # work out how many samples is 0.1s
+            toSave = min(
+                int(0.2 * self._sampleRateHz),
+                int(self.maxRecordingSize / 2)
+            )
+            # get last 0.1s so we still have enough for volume measurement
+            savedSamples = self._recording._samples[-toSave:, :]
+            # clear samples
+            self._recording.clear()
+            # reassign saved samples
+            self._recording.write(savedSamples)
+        # dispatch to listeners
+        for listener in self.listeners:
+            listener.receiveMessage(message)
+
 
 class RecordingBuffer:
     """Class for a storing a recording from a stream.

psychopy/hardware/minolta.py

@@ -12,19 +12,12 @@ These are optional components that can be obtained by installing the
 
 """
 
-import psychopy.logging as logging
-
-try:
-    from psychopy_minolta import CS100A, LS100
-except (ModuleNotFoundError, ImportError):
-    logging.error(
-        "Support for Konica Minolta hardware is not available this session. "
-        "Please install `psychopy-minolta` and restart the session to enable "
-        "support.")
-except Exception as e:
-    logging.error(
-        "Error encountered while loading `psychopy-minolta`. Check logs for "
-        "more information.")
-
-if __name__ == "__main__":
+from psychopy.tools.pkgtools import PluginStub
+
+
+class CS100A(PluginStub, plugin="psychopy-minolta", doclink="https://psychopy.github.io/psychopy-minolta/coder/CS100A"):
+    pass
+
+
+class LS100(PluginStub, plugin="psychopy-minolta", doclink="https://psychopy.github.io/psychopy-minolta/coder/LS100"):
     pass

psychopy/hardware/photodiode.py

@@ -1,5 +1,5 @@
 import json
-from psychopy import layout, logging
+from psychopy import core, layout, logging
 from psychopy.hardware import base, DeviceManager
 from psychopy.localization import _translate
 from psychopy.hardware import keyboard
@@ -100,8 +100,62 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
                 matches.append(resp)
 
         return matches
+    
+    def findChannels(self, win):
+        """
+        Flash the entire window white to check which channels are detecting light from the given 
+        window.
 
-    def findPhotodiode(self, win, channel):
+        Parameters
+        ----------
+        win : psychopy.visual.Window
+            Window to flash white.
+        """
+        from psychopy import visual
+        # clock for timeouts
+        timeoutClock = core.Clock()
+        # box to cover screen
+        rect = visual.Rect(
+            win,
+            size=(2, 2), pos=(0, 0), units="norm",
+            autoDraw=False
+        )
+        win.flip()
+        # show black
+        rect.fillColor = "black"
+        rect.draw()
+        win.flip()
+        # wait 250ms for flip to happen and photodiode to catch it
+        timeoutClock.reset()
+        while timeoutClock.getTime() < 0.25:
+            self.dispatchMessages()
+        # finish dispatching any messages which are only partially received               
+        while self.hasUnfinishedMessage():
+            self.dispatchMessages()
+        # clear caught messages so we're starting afresh
+        self.clearResponses()
+        # show white
+        rect.fillColor = "white"
+        rect.draw()
+        win.flip()
+        # wait 250ms for flip to happen and photodiode to catch it
+        timeoutClock.reset()
+        while timeoutClock.getTime() < 0.25:
+            self.dispatchMessages()
+        # finish dispatching any messages which are only partially received               
+        while self.hasUnfinishedMessage():
+            self.dispatchMessages()
+        # start off with no channels
+        channels = []
+        # iterate through potential channels
+        for i, state in enumerate(self.state):
+            # if any detected the flash, append it
+            if state:
+                channels.append(i)
+        
+        return channels
+    
+    def findPhotodiode(self, win, channel=None):
         """
         Draws rectangles on the screen and records photodiode responses to recursively find the location of the diode.
 
@@ -114,6 +168,8 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
             Size of the area of certainty. Essentially, the size of the last (smallest) rectangle which the photodiode
             was able to detect.
         """
+        # timeout clock
+        timeoutClock = core.Clock()
         # keyboard to check for escape
         kb = keyboard.Keyboard(deviceName="photodiodeValidatorKeyboard")
         # stash autodraw
@@ -130,7 +186,7 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
         # add low opacity label
         label = visual.TextBox2(
             win,
-            text="Finding photodiode...",
+            text=f"Finding photodiode...",
             fillColor=(0, 0, 0), color=(80, 80, 80), colorSpace="rgb255",
             pos=(0, 0), size=(2, 2), units="norm",
             alignment="center",
@@ -144,9 +200,29 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
             autoDraw=False
         )
 
-        def scanQuadrants():
+        # if not given a channel, use first one which is responsive to the win
+        if channel is None:
+            # get responsive channels
+            responsiveChannels = self.findChannels(win=win)
+            # use first responsive channel
+            if responsiveChannels:
+                channel = responsiveChannels[0]
+            else:
+                # if no channels are responsive, use 0th channel and let scanQuadrants fail cleanly
+                channel = 0
+        # update label text once we have a channel
+        label.text = f"Finding photodiode {channel}..."
+
+        def scanQuadrants(responsive=False):
             """
-            Recursively shrink the rectangle around the position of the photodiode until it's too small to detect.
+            Recursively shrink the rectangle around the position of the photodiode until it's too 
+            small to detect.
+
+            Parameters
+            ----------
+            responsive : bool
+                When calling manually, this should always be left as False! Will be set to True if 
+                any response was received from the photodiode.
             """
             # work out width and height of area
             w, h = rect.size
@@ -162,6 +238,11 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
                 (r - w / 4, t - h / 4),  # top right
                 (l + w / 4, b + h / 4),  # bottom left
                 (r - w / 4, b + h / 4),  # bottom right
+                rect.pos,  # center
+                (l + w / 2, t - h / 4),  # top center
+                (l + w / 2, b + h / 4),  # bottom center
+                (l + w / 4, b + h / 2),  # center left
+                (r - w / 4, b + h / 2),  # center right
             ]:
                 # position rect
                 rect.pos = (x, y)
@@ -170,24 +251,97 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
                 label.draw()
                 rect.draw()
                 win.flip()
-                # dispatch parent messages
-                self.dispatchMessages()
+                # wait for flip to happen and photodiode to catch it (max 250ms)
+                timeoutClock.reset()
+                self.clearResponses()
+                while not self.responses and timeoutClock.getTime() < 0.25:
+                    self.dispatchMessages()
+                # finish dispatching any messages which are only partially received               
+                while self.hasUnfinishedMessage():
+                    self.dispatchMessages()
                 # check for escape before entering recursion
                 if kb.getKeys(['escape']):
-                    return
+                    return None
                 # poll photodiode
                 if self.getState(channel):
+                    # mark that we've got a response
+                    responsive = True
                     # if it detected this rectangle, recur
-                    return scanQuadrants()
+                    return scanQuadrants(responsive=responsive)
             # if none of these have returned, rect is too small to cover the whole photodiode, so return
-            return
+            return responsive
 
         # reset state
         self.state = [None] * self.channels
         self.dispatchMessages()
         self.clearResponses()
         # recursively shrink rect around the photodiode
-        scanQuadrants()
+        responsive = scanQuadrants()
+        # if cancelled, warn and continue
+        if responsive is None:
+            logging.warn(
+                "`findPhotodiode` procedure cancelled by user."
+            )
+            return (
+                layout.Position(self.pos, units="norm", win=win),
+                layout.Position(self.size, units="norm", win=win),
+            )
+        # if we didn't get any responses at all, prompt to try again
+        if not responsive:
+            # set label text to alert user
+            label.text = (
+                "Received no responses from photodiode during `findPhotodiode`. Photodiode may not "
+                "be connected or may be configured incorrectly.\n"
+                "\n"
+                "To continue, use the arrow keys to move the photodiode patch and use the "
+                "plus/minus keys to resize it.\n"
+                "\n"
+                "Press ENTER when finished."
+            )
+            label.foreColor = "red"
+            # revert to defaults
+            self.units = rect.units = "norm"
+            self.size = rect.size = (0.1, 0.1)
+            self.pos = rect.pos = (0.9, -0.9)
+            # start a frame loop until they press enter
+            keys = []
+            res = 0.05
+            while "return" not in keys:
+                # get keys
+                keys = kb.getKeys()
+                # skip if escape pressed
+                if "escape" in keys:
+                    return None
+                # move rect according to arrow keys
+                pos = list(rect.pos)
+                if "left" in keys:
+                    pos[0] -= res
+                if "right" in keys:
+                    pos[0] += res
+                if "up" in keys:
+                    pos[1] += res
+                if "down" in keys:
+                    pos[1] -= res
+                rect.pos = self.pos = pos
+                # resize rect according to +- keys
+                size = rect.size
+                if "equal" in keys:
+                    size = [sz * 2 for sz in size]
+                if "minus" in keys:
+                    size = [sz / 2 for sz in size]
+                rect.size = self.size = size
+                # show label and square
+                label.draw()
+                rect.draw()
+                # flip
+                win.flip()
+            # wait for a keypress
+            kb.waitKeys()
+            # return defaults
+            return (
+                layout.Position(self.pos, units="norm", win=win),
+                layout.Position(self.size, units="norm", win=win),
+            )
         # clear all the events created by this process
         self.state = [None] * self.channels
         self.dispatchMessages()
@@ -207,7 +361,17 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
             layout.Position(self.size, units="norm", win=win),
         )
 
-    def findThreshold(self, win, channel):
+    def findThreshold(self, win, channel=None):
+        # if not given a channel, find for all channels
+        if channel is None:
+            thresholds = []
+            # iterate through channels
+            for channel in range(self.channels):
+                thresholds.append(
+                    self.findThreshold(win, channel=channel)
+                )
+            # return array of thresholds
+            return thresholds
         # keyboard to check for escape/continue
         kb = keyboard.Keyboard(deviceName="photodiodeValidatorKeyboard")
         # stash autodraw
@@ -223,7 +387,7 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
         # add low opacity label
         label = visual.TextBox2(
             win,
-            text="Finding best threshold for photodiode...",
+            text=f"Finding best threshold for photodiode {channel}...",
             fillColor=None, color=(0, 0, 0), colorSpace="rgb",
             pos=(0, 0), size=(2, 2), units="norm",
             alignment="center",
@@ -294,8 +458,10 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
         win.retrieveAutoDraw()
         # flip
         win.flip()
+        # set to found threshold
+        self._setThreshold(int(threshold), channel=channel)
 
-        return threshold
+        return int(threshold)
 
     def setThreshold(self, threshold, channel):
         if isinstance(channel, (list, tuple)):
@@ -485,6 +651,9 @@ class ScreenBufferSampler(BasePhotodiodeGroup):
             win = self.win
         else:
             self.win = win
+        # handle None
+        if channel is None:
+            channel = 0
         # there's no physical photodiode, so just pick a reasonable place for it
         self._pos = layout.Position((0.95, -0.95), units="norm", win=win)
         self._size = layout.Size((0.05, 0.05), units="norm", win=win)
@@ -493,7 +662,13 @@ class ScreenBufferSampler(BasePhotodiodeGroup):
         return self._pos, self._size
 
     def findThreshold(self, win=None, channel=0):
-        self.win = win
+        if win is None:
+            win = self.win
+        else:
+            self.win = win
+        # handle None
+        if channel is None:
+            channel = 0
         # there's no physical photodiode, so just pick a reasonable threshold
         self.setThreshold(127, channel=channel)
 
@@ -503,7 +678,7 @@ class ScreenBufferSampler(BasePhotodiodeGroup):
 class PhotodiodeValidator:
 
     def __init__(
-            self, win, diode, channel,
+            self, win, diode, channel=None,
             variability=1/60,
             report="log",
             autoLog=False):

psychopy/hardware/photometer/__init__.py

@@ -18,34 +18,23 @@ __all__ = [
     'getAllPhotometerClasses'
 ]
 
-import sys
+from psychopy.tools.pkgtools import PluginStub
 
 # Special handling for legacy classes which have been offloaded to optional
 # packages. This will change to allow more flexibility in the future to avoid
 # updating this package for additions to these sub-packages. We'll need a
 # photometer type to do that, but for now we're doing it like this.
-try:
-    from ..crs import ColorCAL, OptiCAL
-except Exception:
-    ColorCAL = OptiCAL = None
+from psychopy.hardware.crs.colorcal import ColorCAL
+from psychopy.hardware.crs.optical import OptiCAL
 
 # Photo Resaerch Inc. spectroradiometers
-try:
-    from ..pr import PR655, PR650
-except Exception:
-    PR655 = PR650 = None
+from psychopy.hardware.pr import PR655, PR650
 
 # Konica Minolta light-measuring devices
-try:
-    from ..minolta import LS100, CS100A
-except Exception:
-    LS100 = CS100A = None
+from psychopy.hardware.minolta import LS100, CS100A
 
 # Gamma scientific devices
-try:
-    from ..gammasci import S470
-except Exception:
-    S470 = None
+from psychopy.hardware.gammasci import S470
 
 # photometer interfaces will be stored here after being registered
 photometerInterfaces = {}
@@ -123,8 +112,11 @@ def getAllPhotometers():
         'ColorCAL', 'OptiCAL', 'S470', 'PR650', 'PR655', 'LS100', 'CS100A')
     incPhotomList = []
     for photName in optionalPhotometers:
-        photClass = getattr(sys.modules[__name__], photName)
-        if photClass is None:  # not loaded if `None`
+        try:
+            photClass = globals()[photName]
+        except (ImportError, AttributeError):
+            continue
+        if issubclass(photClass, PluginStub):
             continue
         incPhotomList.append(photClass)
 

psychopy/hardware/pr.py

@@ -12,19 +12,12 @@ These are optional components that can be obtained by installing the
 
 """
 
-import psychopy.logging as logging
-
-try:
-    from psychopy_photoresearch import PR650, PR655
-except (ModuleNotFoundError, ImportError):
-    logging.error(
-        "Support for Photo Research Inc. hardware is not available this "
-        "session. Please install `psychopy-photoresearch` and restart the "
-        "session to enable support.")
-except Exception as e:
-    logging.error(
-        "Error encountered while loading `psychopy-photoresearch`. Check logs "
-        "for more information.")
-
-if __name__ == "__main__":
+from psychopy.tools.pkgtools import PluginStub
+
+
+class PR650(PluginStub, plugin="psychopy-photoresearch", doclink="https://psychopy.github.io/psychopy-photoresearch/coder/PR650"):
+    pass
+
+
+class PR655(PluginStub, plugin="psychopy-photoresearch", doclink="https://psychopy.github.io/psychopy-photoresearch/coder/PR655"):
     pass