Sound Calibration

Calibrates speaker output so a requested sound level in dB corresponds to an actual, measured volume — per speaker (left/right) and per sound, so tasks can request a sound in dB instead of a raw gain value.

Note

Only available when USE_SOUNDCARD is ON.

Note

The SOUND dropdown lists the functions in sound_calibration_functions, defined in your project’s code/sound_functions.py. Each function takes gain and duration and returns a mono NumPy waveform array; see the demo-village-project for examples.

Calibrating

Pick a sound and a speaker, enter a gain (0-1) and a duration in seconds, then click CALIBRATE — the sound is played once through that speaker. Measure the resulting volume with a sound level meter and enter it in dB, then click ADD to save the point — it’s added to the calibration curve, plotted immediately, and listed under CALIBRATION POINTS, where each point can be removed individually with its - button if it turns out to be an outlier. Repeat with a few different gain values per speaker/sound pair (at least two points are required) to build a gain → dB curve. If the sound device fails to play the sound, an error dialog is shown and the inputs are reset instead of prompting for a measurement.

Once you’re happy with the curve, click SAVE CALIBRATION to persist it. Any speaker/sound pair left with fewer than two points is dropped from the save, with a warning listing which ones. Saved calibrations are never overwritten — every save gets a new calibration_number and the full history is kept, but tasks and the testing panel always use the most recent one per speaker/sound pair. DELETE CALIBRATION discards the points collected so far (after confirmation) without saving them.

Testing

Check whether the latest saved calibration for a speaker/sound pair is still accurate. Pick the sound and speaker, enter a target dB and a duration, then click TEST — the panel looks up the gain the calibration curve predicts for that dB. If the pair hasn’t been calibrated yet, or the target dB falls outside the calibrated range, you get a warning immediately and nothing is played. Otherwise the sound is played at that gain; measure the actual dB the same way as during calibration and enter it back — the panel shows the resulting error and plots the test point against the existing curve.

  • If the error is acceptable, click OK. The measurement is recorded for reference (it does not affect get_sound_gain, since it’s stored with calibration_number -1) and the panel is cleared for another test.

  • If the error is too large, click FAIL instead. The measurement is recorded the same way, but it’s also used as the first point of a brand-new calibration for that speaker/sound pair, so you can immediately continue adding points to it (as in Calibrating above) and save a corrected curve.

Using it in tasks

gain = self.calibrations.sound_calibration.get_sound_gain(speaker, dB, sound_name)

Given a speaker (0 = left, 1 = right), a target dB, and the sound’s function name, this interpolates the gain from that speaker/sound pair’s most recent saved calibration curve. dB=0 always returns a gain of 0.0 without needing a calibration. Otherwise, if the pair hasn’t been calibrated yet, or dB falls outside the calibrated range, it raises a ValueError explaining the problem so it’s easy to tell whether the sound needs calibrating or the requested dB needs adjusting.

Data is stored in sound_calibration.csv (columns: date, speaker, sound_name, gain, dB_obtained, calibration_number, dB_expected, error(%)).

Want to write your own calibration panel? See Custom Calibrations.