ALSA acoustic detector for motionSCOUT-style narrow-band alarm tones. More...
#include "version.h"#include <alsa/asoundlib.h>#include <errno.h>#include <fcntl.h>#include <math.h>#include <poll.h>#include <signal.h>#include <stdbool.h>#include <stddef.h>#include <stdint.h>#include <stdio.h>#include <stdlib.h>#include <string.h>#include <time.h>#include <unistd.h>#include "ear_inference.h"#include "../../src/inference_settings.h"
Go to the source code of this file.
Data Structures | |
| struct | options |
| Validated capture and reporting policy, fixed before the sample loop. More... | |
| struct | biquad |
| Normalized biquad coefficients and transposed-direct-form-II delay state. More... | |
| struct | tone_bin |
| One Goertzel recurrence; state resets at each analysis-window boundary. More... | |
| struct | homing_state |
| Peak hold and fast/slow averages; direction is guidance, not a bearing measurement. More... | |
| union | alsa_object_storage |
| Aligned bounded storage for an opaque ALSA object after its sizeof guard succeeds. More... | |
| struct | option_alias |
| Long-to-short option mapping; borrowed values are passed to standard getopt. More... | |
Functions | |
| static uint64_t | audio_read_end_us (uint64_t hardware_us, uint64_t unread_frames, unsigned int rate) |
| Subtract unread PCM duration from a monotonic ALSA timestamp. | |
| static int | normalize_long_options (int argc, char *const argv[], char *normalized[], size_t capacity, const struct option_alias aliases[], size_t alias_count) |
| Normalize –name value and –name=value into bounded getopt arguments. | |
| static void | handle_signal (int signal_number) |
| Request orderly capture-loop termination from a signal handler. | |
| static uint64_t | monotonic_ms (void) |
| Return monotonic milliseconds for correlating samples without wall-clock jumps. | |
| static void | print_usage (FILE *stream, const char *program) |
| Print command-line help or version-led usage text. | |
| static int | parse_unsigned (const char *text, unsigned int minimum, unsigned int maximum, unsigned int *value) |
| Parse a bounded unsigned command-line value. | |
| static int | find_usb_capture_device (char *name, size_t name_size) |
| Discover the first USB ALSA card offering a capture PCM. | |
| static int | parse_double_value (const char *text, double minimum, double maximum, double *value) |
| Parse a finite bounded floating-point command-line value. | |
| static int | parse_options (int argc, char **argv, struct options *options) |
| Parse and cross-validate EARcam command-line configuration. | |
| static void | configure_biquad (struct biquad *filter, double cutoff_hz, unsigned int sample_rate, bool high_pass) |
| Configure a second-order Butterworth high- or low-pass section. | |
| static double | apply_biquad (struct biquad *filter, double input) |
| Filter one PCM sample while retaining the section delay state. | |
| static double | amplitude_to_db (double amplitude) |
| Convert a linear amplitude to bounded dBFS. | |
| static void | configure_tone_bins (struct tone_bin *bins, const struct options *options) |
| Initialize evenly spaced Goertzel bins across the selected search band. | |
| static void | update_tone_bins (struct tone_bin *bins, double sample, double window) |
| Feed one windowed, band-passed sample into every Goertzel recurrence. | |
| static double | strongest_tone_db (struct tone_bin *bins, uint64_t sample_count, double *frequency_hz) |
| Extract and reset the strongest Goertzel-bin power estimate. | |
| static const char * | update_homing_state (struct homing_state *state, double tone_db, bool alarm_present, const struct options *options, double *trend_db) |
| Update envelope and fast/slow trend estimates for operator guidance. | |
| static void | analyze_test_window (struct tone_bin *bins, const struct options *options, double target_amplitude, double interference_amplitude, double *tone_db, double *contrast_db) |
| Analyze a deterministic synthetic tone mixture for self-test coverage. | |
| static int | run_self_test (const struct options *options) |
| Verify selectivity and trend classification without ALSA hardware. | |
| static void | display_homing (double level_db, double frequency_hz, double contrast_db, bool alarm_present, const char *direction, double trend_db, const struct homing_state *state, const struct options *options) |
| Render one human-facing measurement line for bench use. | |
| static int | configure_capture (snd_pcm_t *pcm, unsigned int sample_rate) |
| Configure mono signed-16 ALSA capture with low-latency period sizes. | |
| static void | emit_classifier_sample (const struct ear_inference_result *result, const struct options *options) |
| Emit one classifier window to the server's nonblocking output. | |
| static void | emit_server_sample (uint64_t timestamp_ms, double level_db, double frequency_hz, double contrast_db, double trend_db, double envelope_db, bool alarm_present, bool clipped, const struct options *options, uint64_t begin_us, uint64_t end_us, uint64_t error_us, uint64_t sequence) |
| Emit one self-describing USHER server sample without blocking capture. | |
| static int | poll_server_stdin (void) |
| Consume non-blocking STOP/QUIT commands from USHER. | |
| static int | run_meter (snd_pcm_t *pcm, const struct options *options) |
| Capture, filter, analyze, and report audio until stopped. | |
| int | main (int argc, char **argv) |
| Configure EARcam, optionally self-test it, then run the ALSA meter. | |
Variables | |
| static volatile sig_atomic_t | keep_running = 1 |
| static union alsa_object_storage | card_info_storage |
| static union alsa_object_storage | pcm_info_storage |
| static union alsa_object_storage | hardware_params_storage |
| static union alsa_object_storage | software_params_storage |
| static int16_t | capture_samples [MAX_PERIOD_FRAMES] |
| static double | analysis_window [MAX_INTERVAL_FRAMES] |
| static bool | capture_timestamps |
| static unsigned long | server_dropped_lines = 0 |
Detailed Description
ALSA acoustic detector for motionSCOUT-style narrow-band alarm tones.
EARcam captures mono PCM, isolates the configured frequency band with cascaded Butterworth biquads, measures a bank of Goertzel tone bins over short Hann windows, and emits either an operator display or machine-readable samples for USHER. The process remains independently useful for bench work and deliberately keeps the USHER server protocol simple: newline-delimited output plus STOP/QUIT input.
Definition in file earcam.c.
Macro Definition Documentation
◆ _POSIX_C_SOURCE
◆ ALSA_OBJECT_CAPACITY
| #define ALSA_OBJECT_CAPACITY 4096U |
◆ AMPLITUDE_DB_PER_DECADE
◆ AMPLITUDE_FLOOR
◆ AUTO_DEVICE_NAME_MAX
◆ BUTTERWORTH_Q
| #define BUTTERWORTH_Q 0.7071067811865476 |
◆ CAPTURE_BUFFERS_PER_SECOND
◆ CAPTURE_MONO_CHANNELS
◆ CAPTURE_PERIODS_PER_SECOND
| #define CAPTURE_PERIODS_PER_SECOND 200U |
◆ CAPTURE_STALL_TIMEOUT_MS
◆ CAPTURE_WAIT_MS
◆ CLIP_THRESHOLD
◆ CONTROL_DEVICE_NAME_CAPACITY
◆ DB_FLOOR
◆ DB_LOG_BASE
◆ DEFAULT_DEVICE
◆ DEFAULT_HIGH_CUT_HZ
◆ DEFAULT_INTERVAL_MS
◆ DEFAULT_LOW_CUT_HZ
◆ DEFAULT_MIN_LEVEL_DBFS
| #define DEFAULT_MIN_LEVEL_DBFS (-90.0) |
◆ DEFAULT_RATE
◆ EARCAM_MAX_ARGUMENTS
◆ EARCAM_MAX_PARSED_ARGUMENTS
| #define EARCAM_MAX_PARSED_ARGUMENTS (EARCAM_MAX_ARGUMENTS * 2 + 1) |
◆ ENVELOPE_RELEASE_DB_PER_SECOND
◆ FILTER_SECTIONS_PER_EDGE
◆ HANN_TONE_AMPLITUDE_SCALE
| #define HANN_TONE_AMPLITUDE_SCALE 4.0 |
◆ HOMING_ACQUISITION_WINDOWS
◆ HOMING_FAST_TIME_CONSTANT_S
| #define HOMING_FAST_TIME_CONSTANT_S 0.20 |
◆ HOMING_SLOW_TIME_CONSTANT_S
◆ MAX_CALIBRATION_DB
◆ MAX_CUTOFF_HZ
| #define MAX_CUTOFF_HZ 190000.0 |
◆ MAX_INTERVAL_FRAMES
| #define MAX_INTERVAL_FRAMES ((MAX_RATE * MAX_INTERVAL_MS) / MILLISECONDS_PER_SECOND) |
◆ MAX_INTERVAL_MS
◆ MAX_PERIOD_FRAMES
| #define MAX_PERIOD_FRAMES (MAX_RATE / CAPTURE_BUFFERS_PER_SECOND) |
◆ MAX_RATE
◆ METER_WIDTH
◆ MICROSECONDS_PER_SECOND
◆ MILLISECONDS_PER_SECOND
◆ MILLISECONDS_PER_SECOND_F
◆ MIN_CALIBRATION_DB
◆ MIN_INTERVAL_MS
◆ MIN_RATE_HZ
◆ NANOSECONDS_PER_MICROSECOND
◆ NANOSECONDS_PER_MILLISECOND
◆ NANOSECONDS_PER_SECOND
◆ PCM_S16_FULL_SCALE
◆ PI
◆ SERVER_COMMAND_CAPACITY
◆ SERVER_READ_CHUNK_CAPACITY
◆ SERVER_SAMPLE_LINE_CAPACITY
◆ SHORT_OPTION_STORAGE
◆ SOURCE_LEVEL_DB_SPL
| #define SOURCE_LEVEL_DB_SPL 95.0 |
◆ SOURCE_REFERENCE_METERS
◆ TEST_APPROACH_START_DB
◆ TEST_CONTRAST_MAX_DB
◆ TEST_EXPECTED_READ_END_US
◆ TEST_INTERFERENCE_AMPLITUDE
◆ TEST_INTERFERENCE_HZ
◆ TEST_RATE_HZ
◆ TEST_RECEDE_START_DB
◆ TEST_TARGET_AMPLITUDE
◆ TEST_TARGET_HZ
◆ TEST_TIMESTAMP_US
| #define TEST_TIMESTAMP_US 1000000 |
◆ TEST_TONE_MAX_DB
◆ TEST_TONE_MIN_DB
◆ TEST_TREND_STEP_DB
◆ TEST_TREND_WINDOWS
◆ TEST_UNDERFLOW_TIMESTAMP_US
◆ TEST_UNREAD_FRAMES
◆ TONE_BIN_COUNT
◆ TONE_CONTRAST_THRESHOLD_DB
◆ TREND_THRESHOLD_DB
Function Documentation
◆ amplitude_to_db()
|
static |
◆ analyze_test_window()
◆ apply_biquad()
|
static |
◆ audio_read_end_us()
|
static |
Subtract unread PCM duration from a monotonic ALSA timestamp.
- Returns
- End of consumed audio in microseconds, or zero if the calculation is unusable.
Arrival time alone includes buffered audio delay. This correction lets USHER associate a window with flight poses closer to its actual capture time.
◆ configure_biquad()
|
static |
◆ configure_capture()
|
static |
◆ configure_tone_bins()
◆ display_homing()
|
static |
◆ emit_classifier_sample()
|
static |
Emit one classifier window to the server's nonblocking output.
- Parameters
-
result Classification, clipping and monotonic window evidence. options Level calibration and its qualification flag.
Format and write the record as a unit. Count incomplete writes instead of letting parent backpressure stall audio acquisition.
◆ emit_server_sample()
|
static |
◆ find_usb_capture_device()
|
static |
Discover the first USB ALSA card offering a capture PCM.
- Parameters
-
name Destination ALSA device name. name_size Capacity of name.
- Returns
- 0 when a usable device is found, otherwise -1.
USB-Audio matching prevents an arbitrary onboard sound device from silently becoming the payload sensor when --device auto is used.
◆ handle_signal()
|
static |
◆ main()
| int main | ( | int | argc, |
| char ** | argv ) |
◆ monotonic_ms()
|
static |
◆ normalize_long_options()
|
static |
◆ parse_double_value()
|
static |
◆ parse_options()
|
static |
Parse and cross-validate EARcam command-line configuration.
- Returns
- 0 for a runnable configuration, 1 after help/version output, or -1 on error.
Nyquist and band-order checks happen here rather than in the DSP loop so a misconfigured filter cannot produce misleading field measurements.
◆ parse_unsigned()
|
static |
◆ poll_server_stdin()
|
static |
◆ print_usage()
|
static |
◆ run_meter()
|
static |
Capture, filter, analyze, and report audio until stopped.
- Returns
- 0 for orderly stop or -1 for unrecoverable ALSA or bounds failure.
ALSA recovery handles transient overruns. Each reporting window produces band RMS, strongest tone, contrast, and homing trend.
◆ run_self_test()
|
static |
◆ strongest_tone_db()
|
static |
Extract and reset the strongest Goertzel-bin power estimate.
- Parameters
-
bins Goertzel states to inspect and reset for the next interval. sample_count Number of samples represented by the states. frequency_hz Receives the winning bin frequency.
- Returns
- Window-normalized tone level in dBFS.
◆ update_homing_state()
|
static |
Update envelope and fast/slow trend estimates for operator guidance.
- Returns
- Stable direction label for the current acoustic evidence.
The peak-hold envelope falls gradually while two exponential averages make direction less sensitive to individual noisy windows.
◆ update_tone_bins()
|
static |
Feed one windowed, band-passed sample into every Goertzel recurrence.
- Parameters
-
bins Persistent Goertzel states for the search frequencies. sample Current band-passed PCM value normalized to [-1, 1]. window Precomputed Hann weight for this sample's interval position.
Windowing reduces spectral leakage; precomputation keeps trigonometry out of the realtime sample loop.
Variable Documentation
◆ analysis_window
|
static |
◆ capture_samples
|
static |
◆ capture_timestamps
◆ card_info_storage
|
static |
◆ hardware_params_storage
|
static |
◆ keep_running
◆ pcm_info_storage
|
static |
◆ server_dropped_lines
◆ software_params_storage
|
static |