Add sounddevice backend for gapless audio playback. (#494)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Eric Larson <larson.eric.d@gmail.com>

Author: 3 people

.github/workflows/tests.yml

@@ -51,15 +51,15 @@ jobs:
           set -xeo pipefail
           if [[ "${{ runner.os }}" == "Windows" ]]; then
             echo "Setting env vars for Windows"
-            echo "AZURE_CI_WINDOWS=true" >> $GITHUB_ENV
-            echo "SOUND_CARD_BACKEND=rtmixer" >> $GITHUB_ENV
-            echo "SOUND_CARD_NAME=Speakers" >> $GITHUB_ENV
-            echo "SOUND_CARD_FS=48000" >> $GITHUB_ENV
-            echo "SOUND_CARD_API=Windows WDM-KS" >> $GITHUB_ENV
+            echo "AZURE_CI_WINDOWS=true" | tee -a $GITHUB_ENV
+            echo "SOUND_CARD_BACKEND=rtmixer" | tee -a $GITHUB_ENV
+            echo "SOUND_CARD_NAME=Sound Mapper" | tee -a $GITHUB_ENV
+            echo "SOUND_CARD_FS=48000" | tee -a $GITHUB_ENV
+            echo "SOUND_CARD_API=MME" | tee -a $GITHUB_ENV
           elif [[ "${{ runner.os }}" == "Linux" ]]; then
             echo "Setting env vars for Linux"
-            echo "_EXPYFUN_SILENT=true" >> $GITHUB_ENV
-            echo "SOUND_CARD_BACKEND=pyglet" >> $GITHUB_ENV
+            echo "_EXPYFUN_SILENT=true" | tee -a $GITHUB_ENV
+            echo "SOUND_CARD_BACKEND=pyglet" | tee -a $GITHUB_ENV
           elif [[ "${{ runner.os }}" == "macOS" ]]; then
             echo "Setting env vars for macOS"
           fi

expyfun/_experiment_controller.py

@@ -27,7 +27,6 @@
     ZeroClock,
     _check_pyglet_version,
     _fix_audio_dims,
-    _get_args,
     _get_display,
     _sanitize,
     _TempDir,
@@ -143,6 +142,17 @@ class ExperimentController:
         The trigger duration to use (sec). Must be 0.01 for TDT.
     joystick : bool
         Whether or not to enable joystick control.
+    gapless : bool
+        Whether or not to use sounddevice, allowing gapless playback. Setting
+        this to True (default False) requires:
+
+        1. AUDIO_CONTROLLER must be ``"sound_card"``
+        2. SOUND_CARD_BACKEND must be ``"sounddevice"``
+        3. SOUND_CARD_TRIGGER_ID_AFTER_ONSET must be set to ``True``.
+        4. On Windows, SOUND_CARD_API must be ``"ASIO"``, ``"MME"``, or ``"WASAPI"``
+
+        Note that for gapless playback, you should not use ``ec.wait_secs()`` or
+        ``ec.stop()`` in the experiment loop.
     verbose : bool, str, int, or None
         If not None, override default verbose level (see expyfun.verbose).
 
@@ -167,6 +177,7 @@ def __init__(
         stim_fs=24414,
         stim_db=65,
         noise_db=45,
+        *,
         noise_array=None,
         output_dir="data",
         window_size=None,
@@ -184,6 +195,7 @@ def __init__(
         n_channels=2,
         trigger_duration=0.01,
         joystick=False,
+        gapless=False,
         verbose=None,
     ):
         from . import __version__
@@ -209,6 +221,7 @@ def __init__(
         self._data_file = None
         self._clock = ZeroClock()
         self._master_clock = self._clock.get_time
+        self._gapless = gapless
 
         # put anything that could fail in this block to ensure proper cleanup!
         try:
@@ -249,7 +262,8 @@ def __init__(
             # dictionary for experiment metadata
             self._exp_info = OrderedDict()
 
-            for name in _get_args(self.__init__):
+            spec = inspect.getfullargspec(self.__init__)
+            for name in spec.args[1:] + spec.kwonlyargs:
                 if name != "self":
                     self._exp_info[name] = locals()[name]
             self._exp_info["date"] = date_str()
@@ -368,6 +382,12 @@ def __init__(
                     "type %s" % (type(audio_controller),)
                 )
             audio_type = audio_controller["TYPE"].lower()
+            if self._gapless:
+                if audio_type != "sound_card":
+                    raise RuntimeError(
+                        'audio_controller must be "sound_card" for gapless '
+                        'playback, got "%s"' % audio_type
+                    )
 
             #
             # parse response device
@@ -1867,7 +1887,7 @@ def load_buffer(self, samples):
         ExperimentController.start_stimulus
         ExperimentController.stop
         """
-        if self._playing:
+        if self._playing and not self._gapless:
             raise RuntimeError(
                 "Previous audio must be stopped before loading the buffer"
             )
@@ -1899,7 +1919,7 @@ def play(self):
 
     def _play(self):
         """Play the audio buffer."""
-        if self._playing:
+        if self._playing and not self._gapless:
             raise RuntimeError("Previous audio must be stopped before playing")
         self._ac.play()
         logger.debug("Expyfun: started audio")

expyfun/_sound_controllers/_rtmixer.py

@@ -7,13 +7,12 @@
 import sys
 
 import numpy as np
-import sounddevice
 from rtmixer import Mixer, RingBuffer
 
 from .._utils import get_config, logger
+from ._sounddevice import _find_device
 
 _PRIORITY = 100
-_DEFAULT_NAME = None
 
 
 # only initialize each mixer once and reuse it until this gets garbage
@@ -23,7 +22,7 @@
 class _MixerRegistry(dict):
     def __del__(self):
         for mixer in self.values():
-            print(f"Closing {mixer}")
+            logger.debug(f"Closing {mixer}")
             mixer.abort()
             mixer.close()
         self.clear()
@@ -52,56 +51,12 @@ def _get_mixer(self, fs, n_channels, api, name, api_options):
 
 
 def _init_mixer(fs, n_channels, api, name, api_options=None):
-    devices = sounddevice.query_devices()
-    if len(devices) == 0:
-        raise OSError("No sound devices found!")
-    apis = sounddevice.query_hostapis()
-    valid_apis = []
-    for ai, this_api in enumerate(apis):
-        if this_api["name"] == api:
-            api = this_api
-            break
-        else:
-            valid_apis.append(this_api["name"])
-    else:
-        m = 'Could not find host API %s. Valid choices are "%s"'
-        raise RuntimeError(m % (api, ", ".join(valid_apis)))
-    del this_api
-
-    # Name
-    if name is None:
-        name = get_config("SOUND_CARD_NAME", None)
-    if name is None:
-        global _DEFAULT_NAME
-        if _DEFAULT_NAME is None:
-            di = api["default_output_device"]
-            _DEFAULT_NAME = devices[di]["name"]
-            logger.exp("Selected default sound device: %r" % (_DEFAULT_NAME,))
-        name = _DEFAULT_NAME
-    possible = list()
-    for di, device in enumerate(devices):
-        if device["hostapi"] == ai:
-            possible.append(device["name"])
-            if name in device["name"]:
-                break
-    else:
-        raise RuntimeError(
-            "Could not find device on API %r with name "
-            "containing %r, found:\n%s" % (api["name"], name, "\n".join(possible))
-        )
-    param_str = "sound card %r (devices[%d]) via %r" % (device["name"], di, api["name"])
-    extra_settings = None
-    if api_options is not None:
-        if api["name"] == "Windows WASAPI":
-            # exclusive mode is needed for zero jitter on Windows in testing
-            extra_settings = sounddevice.WasapiSettings(**api_options)
-        else:
-            raise ValueError(
-                'api_options only supported for "Windows WASAPI" backend, '
-                "using %s backend got api_options=%s" % (api["name"], api_options)
-            )
-        param_str += " with options %s" % (api_options,)
-    param_str += ", %d channels" % (n_channels,)
+    device, param_str, extra_settings, all_devices = _find_device(
+        n_channels,
+        api,
+        name,
+        api_options=api_options,
+    )
     if fs is not None:
         param_str += " @ %d Hz" % (fs,)
     try:
@@ -110,11 +65,11 @@ def _init_mixer(fs, n_channels, api, name, api_options=None):
             latency="low",
             channels=n_channels,
             dither_off=True,
-            device=di,
+            device=device["index"],
             extra_settings=extra_settings,
         )
-    except Exception as exp:
-        raise RuntimeError(f"Could not set up {param_str}:\n{exp}") from None
+    except Exception:
+        raise RuntimeError(f"Could not set up {param_str}:\n\n{all_devices}")
     assert mixer.channels == n_channels
     if fs is None:
         param_str += " @ %d Hz" % (mixer.samplerate,)

expyfun/_sound_controllers/_sound_controller.py

@@ -65,7 +65,7 @@ class SoundCardController:
     Params should contain string values:
 
     - 'SOUND_CARD_BACKEND' : str
-        The backend to use. Can be 'auto' (default), 'rtmixer', 'pyglet'.
+        The backend to use. Can be 'auto' (default), 'rtmixer', 'pyglet', 'sounddevice'.
     - 'SOUND_CARD_API' : str
         The API to use for the sound card.
         See :func:`sounddevice.query_hostapis`.
@@ -162,6 +162,30 @@ def __init__(self, params, stim_fs, n_channels=2, trigger_duration=0.01, ec=None
             key: params["SOUND_CARD_" + key.upper()]
             for key in ("fs", "api", "name", "fixed_delay", "api_options")
         }
+        if self.backend_name == "sounddevice":  # use this or next line
+            # ensure id triggers are after onset for gapless playback
+            if not self.ec._gapless:
+                raise NotImplementedError(
+                    "Currently, only gapless=True is allowed for sounddevice backend"
+                )
+            else:
+                if not self._id_after_onset:
+                    raise ValueError(
+                        "SOUND_CARD_TRIGGER_ID_AFTER_ONSET must be True for"
+                        " gapless playback."
+                    )
+            # make sure the API is one that works with sounddevice
+            allowed_apis = ["MME", "Windows WASAPI", "ASIO", None]
+            if os.name == "nt" and (params["SOUND_CARD_API"] not in allowed_apis):
+                raise ValueError(
+                    f"SOUND_CARD_API must be one of {allowed_apis[:-1]} for gapless "
+                    f"playback, got {params['SOUND_CARD_API']}."
+                )
+        elif self.ec._gapless:
+            raise RuntimeError(
+                'SOUND_CARD_BACKEND must be "sounddevice" for gapless '
+                f"playback, got {self.backend_name!r}"
+            )
         temp_sound = np.zeros((self._n_channels_tot, 1000))
         temp_sound = self.backend.SoundPlayer(temp_sound, **self._kwargs)
         self.fs = float(temp_sound.fs)
@@ -271,10 +295,11 @@ def load_buffer(self, samples):
             The sound samples.
         """
         assert samples.ndim == 2
-        self.stop(wait=False)
-        if self.audio is not None:
-            self.audio.delete()
-            self.audio = None
+        if not self.ec._gapless:
+            self.stop(wait=False)
+            if self.audio is not None:
+                self.audio.delete()
+                self.audio = None
         if self._n_channels_stim > 0:
             stim = self._make_digital_trigger([1] + self._extra_onset_triggers)
             stim_len = len(stim)
@@ -413,7 +438,7 @@ def stamp_triggers(
 
     def play(self):
         """Play."""
-        assert not self.playing
+        assert not self.playing or self.ec._gapless
         if self.audio is not None:
             self.audio.play()
         self.playing = True