Illustrated C/C++ source sheets, symbol index, API relationship graph, compiler console and debug trace

LIVE AI / FLEXIBLE SENSING / FLIGHT CONTEXT

Sensoraia API

Live AI and sensing, connected to the flight.
See, listen, inspect and return supported results while airborne.

Loading...
Searching...
No Matches
earcam.c File Reference

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"
Include dependency graph for earcam.c:

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...

Macros

#define _POSIX_C_SOURCE   200809L
#define DEFAULT_DEVICE   "auto"
#define AUTO_DEVICE_NAME_MAX   64U
#define DEFAULT_RATE   48000U
#define DEFAULT_INTERVAL_MS   50U
#define MIN_RATE_HZ   8000U
#define MIN_INTERVAL_MS   20U
#define MAX_RATE   384000U
#define MAX_INTERVAL_MS   10000U
#define MILLISECONDS_PER_SECOND   1000U
#define MICROSECONDS_PER_SECOND   1000000U
#define NANOSECONDS_PER_SECOND   1000000000L
#define NANOSECONDS_PER_MILLISECOND   1000000U
#define NANOSECONDS_PER_MICROSECOND   1000U
#define MILLISECONDS_PER_SECOND_F   1000.0
#define CAPTURE_PERIODS_PER_SECOND   200U
#define CAPTURE_BUFFERS_PER_SECOND   50U
#define CAPTURE_MONO_CHANNELS   1U
#define CAPTURE_WAIT_MS   100
#define CAPTURE_STALL_TIMEOUT_MS   2000U
#define MAX_INTERVAL_FRAMES   ((MAX_RATE * MAX_INTERVAL_MS) / MILLISECONDS_PER_SECOND)
#define MAX_PERIOD_FRAMES   (MAX_RATE / CAPTURE_BUFFERS_PER_SECOND)
#define ALSA_OBJECT_CAPACITY   4096U
#define EARCAM_MAX_ARGUMENTS   64
#define EARCAM_MAX_PARSED_ARGUMENTS   (EARCAM_MAX_ARGUMENTS * 2 + 1)
#define DEFAULT_LOW_CUT_HZ   1800.0
#define DEFAULT_HIGH_CUT_HZ   3200.0
#define DEFAULT_MIN_LEVEL_DBFS   (-90.0)
#define DB_FLOOR   (-120.0)
#define METER_WIDTH   50U
#define TONE_BIN_COUNT   57U
#define TONE_CONTRAST_THRESHOLD_DB   (-3.0)
#define TREND_THRESHOLD_DB   0.8
#define ENVELOPE_RELEASE_DB_PER_SECOND   6.0
#define SOURCE_LEVEL_DB_SPL   95.0
#define SOURCE_REFERENCE_METERS   3.0
#define CLIP_THRESHOLD   32700
#define PI   3.14159265358979323846
#define MAX_CUTOFF_HZ   190000.0
#define MIN_CALIBRATION_DB   -300.0
#define MAX_CALIBRATION_DB   300.0
#define CONTROL_DEVICE_NAME_CAPACITY   32
#define SHORT_OPTION_STORAGE   3
#define SERVER_SAMPLE_LINE_CAPACITY   384
#define SERVER_COMMAND_CAPACITY   64
#define SERVER_READ_CHUNK_CAPACITY   64
#define BUTTERWORTH_Q   0.7071067811865476
#define FILTER_SECTIONS_PER_EDGE   2
#define PCM_S16_FULL_SCALE   32768.0
#define AMPLITUDE_FLOOR   0.000001
#define AMPLITUDE_DB_PER_DECADE   20.0
#define DB_LOG_BASE   10.0
#define HANN_TONE_AMPLITUDE_SCALE   4.0
#define HOMING_FAST_TIME_CONSTANT_S   0.20
#define HOMING_SLOW_TIME_CONSTANT_S   1.20
#define HOMING_ACQUISITION_WINDOWS   4U
#define TEST_TIMESTAMP_US   1000000
#define TEST_UNDERFLOW_TIMESTAMP_US   100
#define TEST_UNREAD_FRAMES   480
#define TEST_RATE_HZ   48000
#define TEST_EXPECTED_READ_END_US   990000
#define TEST_TARGET_HZ   2700.0
#define TEST_INTERFERENCE_HZ   800.0
#define TEST_TARGET_AMPLITUDE   0.02
#define TEST_INTERFERENCE_AMPLITUDE   0.20
#define TEST_TONE_MIN_DB   -36.0
#define TEST_TONE_MAX_DB   -32.0
#define TEST_CONTRAST_MAX_DB   -15.0
#define TEST_TREND_WINDOWS   40U
#define TEST_APPROACH_START_DB   -65.0
#define TEST_RECEDE_START_DB   -45.0
#define TEST_TREND_STEP_DB   0.3

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

#define _POSIX_C_SOURCE   200809L

Definition at line 18 of file earcam.c.

◆ ALSA_OBJECT_CAPACITY

#define ALSA_OBJECT_CAPACITY   4096U

Guard opaque ALSA ABI sizes at runtime rather than using direct EARcam heap storage.

Definition at line 72 of file earcam.c.

◆ AMPLITUDE_DB_PER_DECADE

#define AMPLITUDE_DB_PER_DECADE   20.0

Definition at line 106 of file earcam.c.

◆ AMPLITUDE_FLOOR

#define AMPLITUDE_FLOOR   0.000001

Definition at line 105 of file earcam.c.

◆ AUTO_DEVICE_NAME_MAX

#define AUTO_DEVICE_NAME_MAX   64U

Definition at line 50 of file earcam.c.

◆ BUTTERWORTH_Q

#define BUTTERWORTH_Q   0.7071067811865476

q = 1/sqrt(2) for each second-order Butterworth section; two sections per edge.

Definition at line 102 of file earcam.c.

◆ CAPTURE_BUFFERS_PER_SECOND

#define CAPTURE_BUFFERS_PER_SECOND   50U

Definition at line 65 of file earcam.c.

◆ CAPTURE_MONO_CHANNELS

#define CAPTURE_MONO_CHANNELS   1U

Definition at line 66 of file earcam.c.

◆ CAPTURE_PERIODS_PER_SECOND

#define CAPTURE_PERIODS_PER_SECOND   200U

ALSA asks for 5 ms periods and a 20 ms buffer; accepted periods remain bounded.

Definition at line 64 of file earcam.c.

◆ CAPTURE_STALL_TIMEOUT_MS

#define CAPTURE_STALL_TIMEOUT_MS   2000U

Definition at line 68 of file earcam.c.

◆ CAPTURE_WAIT_MS

#define CAPTURE_WAIT_MS   100

Definition at line 67 of file earcam.c.

◆ CLIP_THRESHOLD

#define CLIP_THRESHOLD   32700

Definition at line 89 of file earcam.c.

◆ CONTROL_DEVICE_NAME_CAPACITY

#define CONTROL_DEVICE_NAME_CAPACITY   32

Definition at line 96 of file earcam.c.

◆ DB_FLOOR

#define DB_FLOOR   (-120.0)

Definition at line 79 of file earcam.c.

◆ DB_LOG_BASE

#define DB_LOG_BASE   10.0

Definition at line 107 of file earcam.c.

◆ DEFAULT_DEVICE

#define DEFAULT_DEVICE   "auto"

Definition at line 49 of file earcam.c.

◆ DEFAULT_HIGH_CUT_HZ

#define DEFAULT_HIGH_CUT_HZ   3200.0

Definition at line 76 of file earcam.c.

◆ DEFAULT_INTERVAL_MS

#define DEFAULT_INTERVAL_MS   50U

Definition at line 52 of file earcam.c.

◆ DEFAULT_LOW_CUT_HZ

#define DEFAULT_LOW_CUT_HZ   1800.0

Definition at line 75 of file earcam.c.

◆ DEFAULT_MIN_LEVEL_DBFS

#define DEFAULT_MIN_LEVEL_DBFS   (-90.0)

Level and contrast gates operate before calibration; clipping is reported separately.

Definition at line 78 of file earcam.c.

◆ DEFAULT_RATE

#define DEFAULT_RATE   48000U

Definition at line 51 of file earcam.c.

◆ EARCAM_MAX_ARGUMENTS

#define EARCAM_MAX_ARGUMENTS   64

Definition at line 73 of file earcam.c.

◆ EARCAM_MAX_PARSED_ARGUMENTS

#define EARCAM_MAX_PARSED_ARGUMENTS   (EARCAM_MAX_ARGUMENTS * 2 + 1)

Definition at line 74 of file earcam.c.

◆ ENVELOPE_RELEASE_DB_PER_SECOND

#define ENVELOPE_RELEASE_DB_PER_SECOND   6.0

Definition at line 84 of file earcam.c.

◆ FILTER_SECTIONS_PER_EDGE

#define FILTER_SECTIONS_PER_EDGE   2

Definition at line 103 of file earcam.c.

◆ HANN_TONE_AMPLITUDE_SCALE

#define HANN_TONE_AMPLITUDE_SCALE   4.0

Hann coherent gain and sinusoid amplitude recovery combine to this factor.

Definition at line 109 of file earcam.c.

◆ HOMING_ACQUISITION_WINDOWS

#define HOMING_ACQUISITION_WINDOWS   4U

Definition at line 113 of file earcam.c.

◆ HOMING_FAST_TIME_CONSTANT_S

#define HOMING_FAST_TIME_CONSTANT_S   0.20

Fast/slow peak-envelope smoothing in seconds; minimum alarm windows avoids early labels.

Definition at line 111 of file earcam.c.

◆ HOMING_SLOW_TIME_CONSTANT_S

#define HOMING_SLOW_TIME_CONSTANT_S   1.20

Definition at line 112 of file earcam.c.

◆ MAX_CALIBRATION_DB

#define MAX_CALIBRATION_DB   300.0

Definition at line 95 of file earcam.c.

◆ MAX_CUTOFF_HZ

#define MAX_CUTOFF_HZ   190000.0

Parsing bounds retain room below the maximum supported sample-rate Nyquist limit.

Definition at line 93 of file earcam.c.

◆ MAX_INTERVAL_FRAMES

#define MAX_INTERVAL_FRAMES   ((MAX_RATE * MAX_INTERVAL_MS) / MILLISECONDS_PER_SECOND)

Definition at line 69 of file earcam.c.

◆ MAX_INTERVAL_MS

#define MAX_INTERVAL_MS   10000U

Definition at line 56 of file earcam.c.

◆ MAX_PERIOD_FRAMES

#define MAX_PERIOD_FRAMES   (MAX_RATE / CAPTURE_BUFFERS_PER_SECOND)

Definition at line 70 of file earcam.c.

◆ MAX_RATE

#define MAX_RATE   384000U

Definition at line 55 of file earcam.c.

◆ METER_WIDTH

#define METER_WIDTH   50U

Definition at line 80 of file earcam.c.

◆ MICROSECONDS_PER_SECOND

#define MICROSECONDS_PER_SECOND   1000000U

Definition at line 58 of file earcam.c.

◆ MILLISECONDS_PER_SECOND

#define MILLISECONDS_PER_SECOND   1000U

Definition at line 57 of file earcam.c.

◆ MILLISECONDS_PER_SECOND_F

#define MILLISECONDS_PER_SECOND_F   1000.0

Definition at line 62 of file earcam.c.

◆ MIN_CALIBRATION_DB

#define MIN_CALIBRATION_DB   -300.0

Definition at line 94 of file earcam.c.

◆ MIN_INTERVAL_MS

#define MIN_INTERVAL_MS   20U

Definition at line 54 of file earcam.c.

◆ MIN_RATE_HZ

#define MIN_RATE_HZ   8000U

Definition at line 53 of file earcam.c.

◆ NANOSECONDS_PER_MICROSECOND

#define NANOSECONDS_PER_MICROSECOND   1000U

Definition at line 61 of file earcam.c.

◆ NANOSECONDS_PER_MILLISECOND

#define NANOSECONDS_PER_MILLISECOND   1000000U

Definition at line 60 of file earcam.c.

◆ NANOSECONDS_PER_SECOND

#define NANOSECONDS_PER_SECOND   1000000000L

Definition at line 59 of file earcam.c.

◆ PCM_S16_FULL_SCALE

#define PCM_S16_FULL_SCALE   32768.0

Definition at line 104 of file earcam.c.

◆ PI

#define PI   3.14159265358979323846

Definition at line 90 of file earcam.c.

◆ SERVER_COMMAND_CAPACITY

#define SERVER_COMMAND_CAPACITY   64

Definition at line 99 of file earcam.c.

◆ SERVER_READ_CHUNK_CAPACITY

#define SERVER_READ_CHUNK_CAPACITY   64

Definition at line 100 of file earcam.c.

◆ SERVER_SAMPLE_LINE_CAPACITY

#define SERVER_SAMPLE_LINE_CAPACITY   384

Definition at line 98 of file earcam.c.

◆ SHORT_OPTION_STORAGE

#define SHORT_OPTION_STORAGE   3

Definition at line 97 of file earcam.c.

◆ SOURCE_LEVEL_DB_SPL

#define SOURCE_LEVEL_DB_SPL   95.0

Bench distance display assumes this reference source and free-field attenuation, not a measured range. Use only with an independently calibrated microphone chain.

Definition at line 87 of file earcam.c.

◆ SOURCE_REFERENCE_METERS

#define SOURCE_REFERENCE_METERS   3.0

Definition at line 88 of file earcam.c.

◆ TEST_APPROACH_START_DB

#define TEST_APPROACH_START_DB   -65.0

Definition at line 128 of file earcam.c.

◆ TEST_CONTRAST_MAX_DB

#define TEST_CONTRAST_MAX_DB   -15.0

Definition at line 126 of file earcam.c.

◆ TEST_EXPECTED_READ_END_US

#define TEST_EXPECTED_READ_END_US   990000

Definition at line 119 of file earcam.c.

◆ TEST_INTERFERENCE_AMPLITUDE

#define TEST_INTERFERENCE_AMPLITUDE   0.20

Definition at line 123 of file earcam.c.

◆ TEST_INTERFERENCE_HZ

#define TEST_INTERFERENCE_HZ   800.0

Definition at line 121 of file earcam.c.

◆ TEST_RATE_HZ

#define TEST_RATE_HZ   48000

Definition at line 118 of file earcam.c.

◆ TEST_RECEDE_START_DB

#define TEST_RECEDE_START_DB   -45.0

Definition at line 129 of file earcam.c.

◆ TEST_TARGET_AMPLITUDE

#define TEST_TARGET_AMPLITUDE   0.02

Definition at line 122 of file earcam.c.

◆ TEST_TARGET_HZ

#define TEST_TARGET_HZ   2700.0

Definition at line 120 of file earcam.c.

◆ TEST_TIMESTAMP_US

#define TEST_TIMESTAMP_US   1000000

Deterministic self-test fixtures, not live detector thresholds or measured calibration.

Definition at line 115 of file earcam.c.

◆ TEST_TONE_MAX_DB

#define TEST_TONE_MAX_DB   -32.0

Definition at line 125 of file earcam.c.

◆ TEST_TONE_MIN_DB

#define TEST_TONE_MIN_DB   -36.0

Definition at line 124 of file earcam.c.

◆ TEST_TREND_STEP_DB

#define TEST_TREND_STEP_DB   0.3

Definition at line 130 of file earcam.c.

◆ TEST_TREND_WINDOWS

#define TEST_TREND_WINDOWS   40U

Definition at line 127 of file earcam.c.

◆ TEST_UNDERFLOW_TIMESTAMP_US

#define TEST_UNDERFLOW_TIMESTAMP_US   100

Definition at line 116 of file earcam.c.

◆ TEST_UNREAD_FRAMES

#define TEST_UNREAD_FRAMES   480

Definition at line 117 of file earcam.c.

◆ TONE_BIN_COUNT

#define TONE_BIN_COUNT   57U

Definition at line 81 of file earcam.c.

◆ TONE_CONTRAST_THRESHOLD_DB

#define TONE_CONTRAST_THRESHOLD_DB   (-3.0)

Definition at line 82 of file earcam.c.

◆ TREND_THRESHOLD_DB

#define TREND_THRESHOLD_DB   0.8

Definition at line 83 of file earcam.c.

Function Documentation

◆ amplitude_to_db()

double amplitude_to_db ( double amplitude)
static

Convert a linear amplitude to bounded dBFS.

Flooring avoids negative infinity propagating into detector thresholds.

Definition at line 606 of file earcam.c.

◆ analyze_test_window()

void analyze_test_window ( struct tone_bin * bins,
const struct options * options,
double target_amplitude,
double interference_amplitude,
double * tone_db,
double * contrast_db )
static

Analyze a deterministic synthetic tone mixture for self-test coverage.

Definition at line 726 of file earcam.c.

◆ apply_biquad()

double apply_biquad ( struct biquad * filter,
double input )
static

Filter one PCM sample while retaining the section delay state.

Returns
Filtered sample, or input when the section is disabled.

Definition at line 591 of file earcam.c.

◆ audio_read_end_us()

uint64_t audio_read_end_us ( uint64_t hardware_us,
uint64_t unread_frames,
unsigned int rate )
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.

Definition at line 205 of file earcam.c.

◆ configure_biquad()

void configure_biquad ( struct biquad * filter,
double cutoff_hz,
unsigned int sample_rate,
bool high_pass )
static

Configure a second-order Butterworth high- or low-pass section.

Two identical sections are cascaded to give useful out-of-band rejection before tone analysis without the latency and allocation cost of an FFT filter bank.

Definition at line 554 of file earcam.c.

◆ configure_capture()

int configure_capture ( snd_pcm_t * pcm,
unsigned int sample_rate )
static

Configure mono signed-16 ALSA capture with low-latency period sizes.

Returns
ALSA status code.

Periods target five milliseconds to keep USHER samples timely without forcing an excessively interrupt-heavy capture configuration.

Definition at line 853 of file earcam.c.

◆ configure_tone_bins()

void configure_tone_bins ( struct tone_bin * bins,
const struct options * options )
static

Initialize evenly spaced Goertzel bins across the selected search band.

The small fixed bank is cheaper and more targeted than a broad FFT because mission alarms occupy a known band and only the strongest frequency is needed.

Definition at line 617 of file earcam.c.

◆ display_homing()

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 )
static

Render one human-facing measurement line for bench use.

Definition at line 815 of file earcam.c.

◆ emit_classifier_sample()

void emit_classifier_sample ( const struct ear_inference_result * result,
const struct options * options )
static

Emit one classifier window to the server's nonblocking output.

Parameters
resultClassification, clipping and monotonic window evidence.
optionsLevel calibration and its qualification flag.

Format and write the record as a unit. Count incomplete writes instead of letting parent backpressure stall audio acquisition.

Definition at line 929 of file earcam.c.

◆ emit_server_sample()

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 )
static

Emit one self-describing USHER server sample without blocking capture.

A slow parent loses a measurement rather than stalling ALSA; the drop count remains observable for diagnostics.

Definition at line 948 of file earcam.c.

◆ find_usb_capture_device()

int find_usb_capture_device ( char * name,
size_t name_size )
static

Discover the first USB ALSA card offering a capture PCM.

Parameters
nameDestination ALSA device name.
name_sizeCapacity 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.

Definition at line 368 of file earcam.c.

◆ handle_signal()

void handle_signal ( int signal_number)
static

Request orderly capture-loop termination from a signal handler.

Parameters
signal_numberDelivered signal, intentionally unused.

sig_atomic_t is used because complex cleanup is unsafe in signal context.

Definition at line 294 of file earcam.c.

◆ main()

int main ( int argc,
char ** argv )

Configure EARcam, optionally self-test it, then run the ALSA meter.

Returns
EXIT_SUCCESS on normal termination, EXIT_FAILURE on configuration/capture errors.

Definition at line 1215 of file earcam.c.

◆ monotonic_ms()

uint64_t monotonic_ms ( void )
static

Return monotonic milliseconds for correlating samples without wall-clock jumps.

Returns
Monotonic timestamp in milliseconds.

Definition at line 302 of file earcam.c.

◆ normalize_long_options()

int normalize_long_options ( int argc,
char *const argv[],
char * normalized[],
size_t capacity,
const struct option_alias aliases[],
size_t alias_count )
static

Normalize –name value and –name=value into bounded getopt arguments.

Returns
Argument count, or -1 for unknown options, missing values or capacity exhaustion.

Pointers borrow argv/static alias strings; no copied argument payload or heap is needed.

Definition at line 224 of file earcam.c.

◆ parse_double_value()

int parse_double_value ( const char * text,
double minimum,
double maximum,
double * value )
static

Parse a finite bounded floating-point command-line value.

Returns
0 on success or -1 for malformed, non-finite, or out-of-range input.

Definition at line 417 of file earcam.c.

◆ parse_options()

int parse_options ( int argc,
char ** argv,
struct options * 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.

Definition at line 437 of file earcam.c.

◆ parse_unsigned()

int parse_unsigned ( const char * text,
unsigned int minimum,
unsigned int maximum,
unsigned int * value )
static

Parse a bounded unsigned command-line value.

Returns
0 on success, otherwise -1 without modifying the output value.

Definition at line 344 of file earcam.c.

◆ poll_server_stdin()

int poll_server_stdin ( void )
static

Consume non-blocking STOP/QUIT commands from USHER.

Returns
1 when capture should stop, otherwise 0.

Chunked input accepts fragmented commands while avoiding one syscall per character and never delaying audio acquisition.

Definition at line 991 of file earcam.c.

◆ print_usage()

void print_usage ( FILE * stream,
const char * program )
static

Print command-line help or version-led usage text.

Parameters
streamDestination stream.
programExecutable name shown in examples.

Definition at line 314 of file earcam.c.

◆ run_meter()

int run_meter ( snd_pcm_t * pcm,
const struct options * options )
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.

Definition at line 1030 of file earcam.c.

◆ run_self_test()

int run_self_test ( const struct options * options)
static

Verify selectivity and trend classification without ALSA hardware.

Returns
0 on expected detector behavior, otherwise -1.

Definition at line 763 of file earcam.c.

◆ strongest_tone_db()

double strongest_tone_db ( struct tone_bin * bins,
uint64_t sample_count,
double * frequency_hz )
static

Extract and reset the strongest Goertzel-bin power estimate.

Parameters
binsGoertzel states to inspect and reset for the next interval.
sample_countNumber of samples represented by the states.
frequency_hzReceives the winning bin frequency.
Returns
Window-normalized tone level in dBFS.

Definition at line 657 of file earcam.c.

◆ update_homing_state()

const char * update_homing_state ( struct homing_state * state,
double tone_db,
bool alarm_present,
const struct options * options,
double * trend_db )
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.

Definition at line 682 of file earcam.c.

◆ update_tone_bins()

void update_tone_bins ( struct tone_bin * bins,
double sample,
double window )
static

Feed one windowed, band-passed sample into every Goertzel recurrence.

Parameters
binsPersistent Goertzel states for the search frequencies.
sampleCurrent band-passed PCM value normalized to [-1, 1].
windowPrecomputed Hann weight for this sample's interval position.

Windowing reduces spectral leakage; precomputation keeps trigonometry out of the realtime sample loop.

Definition at line 640 of file earcam.c.

Variable Documentation

◆ analysis_window

double analysis_window[MAX_INTERVAL_FRAMES]
static

Definition at line 196 of file earcam.c.

◆ capture_samples

int16_t capture_samples[MAX_PERIOD_FRAMES]
static

Definition at line 195 of file earcam.c.

◆ capture_timestamps

bool capture_timestamps
static

Definition at line 197 of file earcam.c.

◆ card_info_storage

union alsa_object_storage card_info_storage
static

Definition at line 189 of file earcam.c.

◆ hardware_params_storage

union alsa_object_storage hardware_params_storage
static

Definition at line 191 of file earcam.c.

◆ keep_running

volatile sig_atomic_t keep_running = 1
static

Definition at line 181 of file earcam.c.

◆ pcm_info_storage

union alsa_object_storage pcm_info_storage
static

Definition at line 190 of file earcam.c.

◆ server_dropped_lines

unsigned long server_dropped_lines = 0
static

Definition at line 922 of file earcam.c.

◆ software_params_storage

union alsa_object_storage software_params_storage
static

Definition at line 192 of file earcam.c.