## Sound The Training Village uses the **Raspberry Pi DAC Pro** HAT (the Audio HAT) for audio output. Connect it directly on top of the Raspberry Pi or on top of the Main HAT if one is installed. Audio playback from within tasks is handled by the Python `pyalsaaudio` library, which talks to ALSA directly, without going through PortAudio. --- ### Setup 1. Connect headphones or speakers to the DAC output. 2. Right-click the volume icon in the top system bar and select **Device Profiles**. The **RPi DAC Pro** entry should appear in the list. Select it and set the output profile to **Stereo Output**. 3. Play any audio to verify the DAC is working correctly. 4. Once confirmed, return to **Device Profiles**, select **RPi DAC Pro** again, and set the profile to **Off**. The operating system will no longer use the device, leaving it free for `pyalsaaudio` to access directly. 5. Launch the Training Village and select your soundcard in `SOUND_DEVICE` (`SETTINGS` → `SOUND SETTINGS`). ```{admonition} Why the DAC must be released from the system before use :class: warning When the DAC is set as the active audio output in the desktop environment, the operating system holds exclusive access to the device, preventing the Training Village from using it. Setting the profile to **Off** releases the device and makes it available for the Training Village. ``` ```{admonition} Note :class: note This configuration step only needs to be done once. The "Off" profile selection persists across reboots, so the DAC will remain available to the Training Village after the system restarts. ``` --- ### Using It in Tasks Sounds can be numpy arrays or audio files (WAV files). Audio files are read from the project's **media directory**: `~/village_projects//media`. This path is shown in `SETTINGS` → `MAIN SETTINGS` → `PROJECT` as `MEDIA_DIRECTORY`. Place WAV files there and reference them by filename only (no path needed). Load a sound once, then play it as many times as you want — `load` only needs to be called again to change the sound. Calling `play` before anything has ever been loaded does nothing and reports an error. `stop` is optional, only needed to cut a sound short before it finishes on its own. 1. **`load`** — prepares the sound for the sound card (it converts the arrays to the card's format and applies the ramp, see below) and leaves the card ready, so that `play` starts at once. Its time grows with the length of the sound, and if a sound is playing it cuts it first, which adds some tens of ms. So call it before the sound is needed: in the inter-trial interval, or in `create_trial` before the trial starts. Only repeat it to change the sound. 2. **`play`** — starts playback of the loaded sound from the beginning. This is fast — measured latencies are below 5 ms — with one exception (see below). Calling `play` while a sound is still playing is ignored. 3. **`stop`** *(optional)* — interrupts playback mid-sound. Non-blocking (returns immediately; the sound finishes stopping in the background). To replay the same sound, just call `play` again — no reload needed. The one case where `play` is **not** instant is calling it right after a `stop` that hasn't finished yet: `play` then waits for that stop to complete and plays immediately after. You don't need to register when the sound plays: during a trial, every time a sound starts playing the system adds a `sound` event to the trial data, with the moment it started (see [Trial data](../protocols/tasks_bpod.md#trial-data)). ```{admonition} Fade-in / fade-out ramp :class: note If the `SOUND_RAMP_MS` setting (`SETTINGS` → `SOUND SETTINGS`) is set to a value other than zero, a raised-cosine ramp of that duration is applied automatically to every sound: at its start, at its end, and whenever `stop` cuts playback short. This smooths out the abrupt amplitude changes that would otherwise cause audible clicks. Setting it to `0` disables the ramp entirely. ``` ##### Examples ```python from village.devices.sound_device import sound_device # Option 1 — play a WAV file from the media directory gain = 0.5 # volume, from 0.0 (silent) to 1.0 (full scale) left, right = sound_device.get_sound_from_wav("tone.wav", gain) sound_device.load(left, right) sound_device.play() # To play the same sound again, no reload is needed — just play again sound_device.play() # Option 2 — generate a tone with numpy and play it import numpy as np samplerate = 96000 # must match the SAMPLERATE setting (96000 by default) duration = 0.5 # seconds frequency = 5000 # Hz # volume calibrated so the tone measures 70 dB from the right speaker (speaker 1), # using the calibration of tone_5000 in sound_functions.py (the same 5000 Hz tone) gain = self.calibrations.sound_calibration.get_sound_gain( speaker=1, dB=70.0, sound_name="tone_5000" ) t = np.linspace(0, duration, int(samplerate * duration), endpoint=False) tone = (gain * np.sin(2 * np.pi * frequency * t)).astype(np.float32) sound_device.load(None, tone) # right speaker only, the left one stays silent sound_device.play() ``` In the sound calibration and in `get_sound_gain`, speaker `0` is the left speaker and `1` the right one. Each one is calibrated separately: to play a sound through both speakers at a given level, get the gain of each one and load each channel with its own gain. `get_sound_from_wav` resamples the audio if the WAV's sample rate does not match `SAMPLERATE`, and returns both channels as `float32` arrays in the range `[-1.0, 1.0]`, scaled by `gain`. ```{admonition} Prefer a matching sample rate :class: warning Resampling is a fallback, not something to rely on. It costs extra time on every `get_sound_from_wav` call and can degrade audio quality. Whenever possible, save your WAV files at the same sample rate as the `SAMPLERATE` setting so no resampling is needed. ``` #### Method reference | Method | Arguments | Description | |--------|-----------|-------------| | `get_sound_from_wav(file, gain)` | `file`: filename, `gain`: volume, `0.0`–`1.0` | Reads a WAV from `MEDIA_DIRECTORY`, applies `gain`, returns `(left, right)` arrays. | | `load(left, right)` | numpy arrays, equal length | Builds and stages stereo audio for playback (only needed to change the sound). Pass `None` for a silent channel. | | `play()` | — | Plays the loaded sound from the start; replayable without reloading. Errors if nothing was ever loaded. | | `stop()` | — | Interrupts playback. Non-blocking. | --- ### Sound Functions Your project's `code/sound_functions.py` holds the functions that generate sounds. It holds two kinds of functions: 1. **Generic generators** (e.g. `tone_generator`, `whitenoise_generator`) that take whatever arguments they need and return a numpy waveform array. Call them from anywhere — a direct function, a task, a trigger — and pass the result to `sound_device.load()`. 2. **Calibration-sound wrappers** — thin wrappers around a generic generator that fix every argument except `duration` and `gain`, since that's the signature the Sound Calibration panel always calls them with. They are listed in `sound_calibration_functions`, which fills the `SOUND` dropdown in the [Sound Calibration](../calibrations/sound.md) panel. ```python def tone_generator(duration: float, gain: float, frequency: int): ... # returns a numpy array def tone_600(duration: float, gain: float): return tone_generator(duration=duration, gain=gain, frequency=600) sound_calibration_functions = [tone_600, ...] ``` ```{admonition} Keep names in sync :class: warning A wrapper's `__name__` (`"tone_600"` above) is stored as the sound's identity in the calibration data, and is what you pass as `sound_name=` to `get_sound_gain(...)` everywhere else in the project. Rename a wrapper here and every call site referencing its old name has to be updated too, or the calibration lookup silently stops matching and raises a "not calibrated" error. ``` ```{admonition} sound_functions.py must have this exact name :class: warning The [Sound Calibration](../calibrations/sound.md) panel looks for a file named exactly `sound_functions.py` in `code/` to fill its `SOUND` dropdown with `sound_calibration_functions`. Unlike the classes of the other files, it is found by its name. ``` ```{toctree} :hidden: Sound Functions Example <../examples/sound_functions.md> ```