Audio Module
Synchronized audio recording from USB microphones with real-time level monitoring and per-chunk timing data.
The Audio module records synchronized audio from USB microphones during experiment sessions. It supports multiple audio input devices and provides real-time level monitoring to help you verify audio is being captured correctly.
Getting Started
- Connect your USB microphone(s)
- Enable the Audio moduleFrom the Modules menu.
- Wait for device assignmentLevel meters appear when ready.
- Start a sessionTo begin recording.
User Interface
Device Selection
Audio devices are assigned by the main logger. When a device is assigned, a level meter appears in the control panel.
Level Meters
Real-time audio level visualization shows whether your microphone is picking up sound:
| Color | Level | Meaning |
|---|---|---|
| Green | Below -12 dB | Normal levels |
| Yellow | -12 to -6 dB | Moderate levels |
| Red | Above -6 dB | High levels / clipping risk |
For best results, aim for levels that occasionally touch yellow during normal speech but rarely go red.
Recording Sessions
Starting Recording
When you start a recording session:
- Audio streams are captured to WAV files
- Timing data is logged to companion CSV files
- Level meters continue to show real-time levels
During Recording
- One WAV file is created per microphone
- Audio is recorded continuously until you stop
- Timing CSV tracks every audio chunk for synchronization
Data Output
File Location
{session_dir}/Audio/Files Generated
For each microphone, two files are created:
| File | Description |
|---|---|
{prefix}_MIC{id}_{name}.wav | Audio recording |
{prefix}_MIC{id}_{name}_timing.csv | Timing data |
Example: 20251208_143022_AUDIO_trial001_MIC0_usb-microphone.wav and ..._timing.csv
WAV Audio Format
| Property | Value |
|---|---|
| Format | PCM (uncompressed) |
| Bit Depth | 16-bit signed integer |
| Channels | Mono (1 channel) |
| Sample Rate | 48,000 Hz default (8-192 kHz supported) |
Multi-channel devices are recorded as mono using the first channel.
Timing CSV Columns
The timing CSV contains per-chunk timing data for precise synchronization with other modules (13 columns).
| Column | Description |
|---|---|
trial | Trial number (integer, 1-based) |
module | Always “Audio” |
device_id | Microphone device identifier |
label | Optional trial label (may be empty) |
record_time_unix | Chunk capture time (Unix seconds, 6 decimals) |
record_time_mono | Chunk capture monotonic time (seconds, 9 decimals) |
device_time_unix | Device absolute time (usually empty) |
device_time_offset | Hardware ADC timestamp if available (seconds, 9 decimals) |
write_time_unix | System time when chunk was written (Unix seconds, 6 decimals) |
write_time_mono | Write time monotonic clock (seconds, 9 decimals) |
chunk_index | Sequential chunk number (1-based) |
frames | Number of audio samples in this chunk |
total_frames | Cumulative sample count since recording started |
Example row:
1,Audio,mic_0,trial_label,1702080123.456789,12.345678901,,0.123456789,1702080123.456799,12.345688901,1,2048,2048Understanding the Timestamps
The timing CSV provides multiple time sources for maximum flexibility:
| Timestamp | Use Case |
|---|---|
record_time_unix | Cross-module synchronization (matches other modules’ record_time_unix) |
record_time_mono | Precise relative timing for chunk capture (never jumps or drifts) |
write_time_unix / write_time_mono | Time when chunk was written to disk (slight delay from capture) |
device_time_offset | Sample-accurate sync via ADC timestamp (most precise, but may be empty) |
Calculating Audio Position
To find the exact time of any sample in the recording:
- Find the chunk containing that sample using
total_frames - Use
record_time_monofor that chunk as the base time - Calculate offset:
(sample_position_in_chunk / sample_rate)
To calculate recording duration:
duration_seconds = total_frames / sample_rateConfiguration
| Setting | Default | Range | Notes |
|---|---|---|---|
| Sample Rate | 48,000 Hz | 8-192 kHz | Higher = better quality, larger files |
| Channels | Mono | Fixed | Multi-channel inputs use first channel |
| Bit Depth | 16-bit | Fixed | Standard CD-quality audio |
Troubleshooting
Device not detected
- Check USB connection
- Verify device is powered on
- Check system audio settings to confirm the device is recognized
- On Linux: Run
arecord -lto list devices; ensure user is in ‘audio’ group - On macOS: Check System Preferences > Sound > Input
- On Windows: Check Sound settings > Recording devices
No audio in recording
- Check input levels in the meter display - should show activity when you speak
- Verify microphone is not muted (check physical switches)
- Check system audio input settings
- Verify the correct device is selected as the input source
Level meter shows no activity
- Speak into the microphone or tap it gently
- Check physical mute switches on the microphone
- Verify the correct device is assigned
- Restart the module
Empty device_time_offset in CSV
This is normal - not all audio devices provide hardware ADC timestamps. Use record_time_mono for synchronization instead.