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
ear_inference.c
Go to the documentation of this file.
1/*
2 * Copyright 2026 OpenUAS
3 * SPDX-License-Identifier: Apache-2.0
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18/** @file ear_inference.c
19 * @brief One-window acoustic inference worker with source-time and measured-level evidence.
20 * @details The capture thread never shares its live sample buffer with ORT; stale generations are discarded. */
21#include "ear_inference.h"
23
24#include <math.h>
25#include <pthread.h>
26#include <stdatomic.h>
27#include <stdio.h>
28#include <string.h>
29#include <sys/stat.h>
30
31#define EAR_INFERENCE_SAMPLE_LIMIT 192000U
32
33/* One capture producer owns collected samples; the mutex protects queued/completed mailboxes. */
35static pthread_mutex_t inference_mutex = PTHREAD_MUTEX_INITIALIZER;
36static pthread_cond_t inference_available = PTHREAD_COND_INITIALIZER;
37static pthread_t inference_thread;
40static size_t collected_count;
42static uint64_t collected_error_us;
43static atomic_uint_fast64_t generation;
45static struct ear_inference_result queued_evidence, completed;
46static double score_threshold = 0.6;
47static unsigned class_index, option_seen;
48
49/** @brief Keep class/threshold selection module-owned rather than assigning acoustic semantics to the common parser. */
50static bool model_setting(void *unused, const char *key, const char *value)
51{
52 (void)unused;
53 if (!strcmp(key, "score_threshold")) {
54 if (option_seen & 1U) return false;
55 option_seen |= 1U;
56 return ini_real(value, &score_threshold) && score_threshold >= 0 && score_threshold <= 1;
57 }
58 if (!strcmp(key, "class_index")) {
59 if (option_seen & 2U) return false;
60 option_seen |= 2U;
61 uint64_t category;
62 if (!ini_uint(value, &category) || category > 4095) return false;
63 class_index = (unsigned)category;
64 return true;
65 }
66 return false;
67}
68
69bool ear_inference_configure(const char *settings_path, unsigned rate, bool *enabled,
70 char *error, size_t capacity)
71{
72 if (!enabled || !error || !capacity || started || network.storage) return false;
73 *enabled = false;
74 option_seen = 0;
75 score_threshold = 0.6;
76 class_index = 0;
77 struct inference_settings settings;
79 if (!inference_settings_read(&settings, settings_path, model_setting, NULL, error, capacity)) return false;
80 if (settings.backend == INFERENCE_NATIVE) return true;
81 if (settings.backend != INFERENCE_ONNX || settings.source != INFERENCE_LIVE ||
82 !inference_context_open(&network, &settings, "ear_pcm_classifier_v1", error, capacity)) return false;
83 const struct inference_model *model = &network.model;
84 const bool valid = model->input_count == 1 && model->output_count == 1 &&
85 model->audio_rate == rate && model->audio_samples && model->audio_samples <= rate &&
87 model->inputs[0].type == ONNX_FLOAT32 && model->inputs[0].bytes == (size_t)model->audio_samples * sizeof(float) &&
88 model->outputs[0].type == ONNX_FLOAT32 && model->outputs[0].bytes / sizeof(float) <= 4096 &&
89 class_index < model->outputs[0].bytes / sizeof(float) && !model->image.channels;
91 if (!error[0]) snprintf(error, capacity, "EAR classifier requires normalized mono PCM, matching sample rate and float probabilities");
93 return false;
94 }
95 *enabled = true;
96 return true;
97}
98
99/** @brief Accept finite probabilities without confusing them with measured loudness or localization confidence. */
101{
102 char error[1024];
103 if (!inference_context_run(&network, error, sizeof(error))) {
104 fprintf(stderr, "EARCAM_ERROR inference %s\n", error);
105 return false;
106 }
107 const float *scores = network.model.outputs[0].data;
108 const size_t count = network.model.outputs[0].bytes / sizeof(float);
109 for (size_t index = 0; index < count; ++index) {
110 if (!isfinite(scores[index]) || scores[index] < 0 || scores[index] > 1) {
111 fprintf(stderr, "EARCAM_ERROR inference invalid classifier probability\n");
112 return false;
113 }
114 }
115 result->score = scores[class_index];
116 result->category = class_index;
117 result->alarm = result->score >= score_threshold;
118 return true;
119}
120
121/** @brief Own the model session off the ALSA thread and publish only still-current capture generations. */
122static void *classify_windows(void *unused)
123{
124 (void)unused;
125 pthread_mutex_lock(&inference_mutex);
126 while (!stopping) {
127 while (!pending && !stopping) pthread_cond_wait(&inference_available, &inference_mutex);
128 if (stopping) break;
129 if (queued_generation != atomic_load(&generation)) { pending = false; continue; }
130 struct ear_inference_result result = queued_evidence;
131 const uint64_t identity = queued_generation;
132 float *input = network.model.inputs[0].data;
133 double energy = 0;
134 for (size_t index = 0; index < network.model.audio_samples; ++index) {
135 input[index] = queued[index] / 32768.0f;
136 energy += (double)input[index] * input[index];
137 }
138 /* Derive level from the same PCM window, never from classifier confidence. */
139 result.level_dbfs = energy > 0 ? 10 * log10(energy / network.model.audio_samples) : -120;
140 pending = false;
141 /* ORT may be slow; only the private input tensor remains borrowed during graph execution. */
142 pthread_mutex_unlock(&inference_mutex);
143 const bool valid = run_window(&result);
144 pthread_mutex_lock(&inference_mutex);
145 if (valid && !stopping && identity == atomic_load(&generation)) {
147 completed_generation = identity;
148 ready = true;
149 }
150 }
151 pthread_mutex_unlock(&inference_mutex);
152 return NULL;
153}
154
156{
157 if (!network.storage || started) return false;
158 stopping = pending = ready = false;
159 collected_count = 0;
160 const int result = pthread_create(&inference_thread, NULL, classify_windows, NULL);
161 if (result) { snprintf(error, capacity, "Cannot start acoustic inference worker: %s", strerror(result)); return false; }
162 started = true;
163 return true;
164}
165
166void ear_inference_push(const int16_t *samples, size_t count, uint64_t end_us, uint64_t error_us)
167{
168 if (!started || !samples || !network.model.audio_rate) return;
169 for (size_t index = 0; index < count; ++index) {
174 if (collected_count != network.model.audio_samples) continue;
175 /* Dropping an overloaded window is safer than delaying audio reads and joining samples across an overrun. */
176 if (!pthread_mutex_trylock(&inference_mutex)) {
177 queued_evidence = (struct ear_inference_result){.error_us = collected_error_us};
178 const uint64_t tail = (uint64_t)(count - index - 1) * UINT64_C(1000000) / network.model.audio_rate;
179 const uint64_t duration = (uint64_t)network.model.audio_samples * UINT64_C(1000000) / network.model.audio_rate;
180 if (collected_timing_valid && end_us > tail && end_us - tail > duration) {
181 queued_evidence.end_us = end_us - tail;
182 queued_evidence.begin_us = queued_evidence.end_us - duration;
183 }
184 static uint64_t sequence;
185 queued_evidence.sequence = ++sequence;
186 for (size_t sample = 0; sample < collected_count; ++sample) {
187 queued[sample] = collected[sample];
188 if (collected[sample] >= 32760 || collected[sample] <= -32760) queued_evidence.clipped = true;
189 }
190 queued_generation = atomic_load(&generation);
191 pending = true;
192 pthread_cond_signal(&inference_available);
193 pthread_mutex_unlock(&inference_mutex);
194 }
195 collected_count = 0;
196 }
197}
198
200{
201 if (!result || !started || pthread_mutex_trylock(&inference_mutex)) return false;
202 const bool valid = ready && completed_generation == atomic_load(&generation);
203 if (valid) *result = completed;
204 ready = false;
205 pthread_mutex_unlock(&inference_mutex);
206 return valid;
207}
208
210{
211 collected_count = 0;
212 /* A running graph cannot be recalled immediately, so its generation must become unpublishable. */
213 atomic_fetch_add(&generation, 1);
214 if (pthread_mutex_trylock(&inference_mutex)) return;
215 pending = ready = false;
216 pthread_mutex_unlock(&inference_mutex);
217}
218
220{
221 if (started) {
222 pthread_mutex_lock(&inference_mutex);
223 stopping = true;
224 pthread_cond_signal(&inference_available);
225 pthread_mutex_unlock(&inference_mutex);
227 pthread_join(inference_thread, NULL);
228 started = false;
229 }
231}
232
233int ear_inference_file(const char *filename)
234{
235 if (!network.storage || !filename) return 1;
236 struct stat info;
237 if (stat(filename, &info) || !S_ISREG(info.st_mode) || info.st_size <= 0 ||
238 (uint64_t)info.st_size % ((uint64_t)network.model.audio_samples * 2)) return 1;
239 FILE *input = fopen(filename, "rb");
240 if (!input) return 1;
241 uint64_t sequence = 0;
242 int result = 0;
243 while (!result) {
244 float *samples = network.model.inputs[0].data;
245 double energy = 0;
246 for (unsigned index = 0; index < network.model.audio_samples; ++index) {
247 unsigned char bytes[2];
248 const size_t read_count = fread(bytes, 1, 2, input);
249 if (!read_count && !index && feof(input)) goto finished;
250 if (read_count != 2) { result = 1; break; }
251 const uint16_t raw = (uint16_t)bytes[0] | (uint16_t)bytes[1] << 8;
252 const int32_t signed_sample = raw >= 32768 ? (int32_t)raw - 65536 : raw;
253 samples[index] = signed_sample / 32768.0f;
254 energy += (double)samples[index] * samples[index];
255 }
256 if (result) break;
257 struct ear_inference_result classified = {.sequence = ++sequence,
258 .level_dbfs = energy > 0 ? 10 * log10(energy / network.model.audio_samples) : -120};
259 if (!run_window(&classified)) { result = 1; break; }
260 printf("CLASS sequence=%llu level=%.6f score=%.6f class=%u alarm=%u\n",
261 (unsigned long long)classified.sequence, classified.level_dbfs, classified.score,
262 classified.category, classified.alarm ? 1U : 0U);
263 }
264finished:
265 if (ferror(input)) result = 1;
266 if (fclose(input)) result = 1;
267 return result;
268}
static bool ini_uint(const char *text, uint64_t *number)
Parse digits-only uint64; overflow and signs are rejected.
Definition bounded_ini.h:52
static bool ini_real(const char *text, double *number)
Parse finite decimal/exponent notation, rejecting range errors and suffixes.
Definition bounded_ini.h:67
static unsigned capacity[COVERAGE_CAMERAS]
uint8_t bytes[CHDK_CONTROL_REPLY_SIZE]
Definition chdk_pipe.c:144
static bool enabled(void)
Report explicit opt-in independently of process or model readiness.
static struct ear_sample samples[EAR_MAX_SAMPLES]
static uint64_t queued_generation
static pthread_mutex_t inference_mutex
static void * classify_windows(void *unused)
Own the model session off the ALSA thread and publish only still-current capture generations.
void ear_inference_stop(void)
Request termination, join the classifier and release its model; repeat calls are harmless.
static bool stopping
static bool pending
static uint64_t collected_error_us
static bool started
bool ear_inference_start(char *error, size_t capacity)
Start the sole classifier thread after successful ONNX configuration.
static unsigned option_seen
#define EAR_INFERENCE_SAMPLE_LIMIT
static uint64_t completed_generation
static int16_t queued[EAR_INFERENCE_SAMPLE_LIMIT]
bool ear_inference_take(struct ear_inference_result *result)
Consume at most one completed original-window result without blocking capture.
static bool ready
int ear_inference_file(const char *filename)
Classify exact whole windows from a regular little-endian signed-16 mono PCM file.
static double score_threshold
static bool model_setting(void *unused, const char *key, const char *value)
Keep class/threshold selection module-owned rather than assigning acoustic semantics to the common pa...
static bool collected_timing_valid
static struct ear_inference_result queued_evidence completed
static unsigned class_index
static struct inference_context network
static size_t collected_count
bool ear_inference_configure(const char *settings_path, unsigned rate, bool *enabled, char *error, size_t capacity)
Select the explicit detector and qualify an ONNX PCM contract before capture starts.
static bool run_window(struct ear_inference_result *result)
Accept finite probabilities without confusing them with measured loudness or localization confidence.
void ear_inference_push(const int16_t *samples, size_t count, uint64_t end_us, uint64_t error_us)
Supply capture samples without waiting for model execution or a busy model mailbox.
static atomic_uint_fast64_t generation
void ear_inference_discontinuity(void)
Invalidate queued/completed evidence after capture continuity breaks, including in-flight generations...
static pthread_cond_t inference_available
static int16_t collected[EAR_INFERENCE_SAMPLE_LIMIT]
static pthread_t inference_thread
Bounded PCM classification without allowing model latency to stall ALSA capture.
bool inference_context_run(struct inference_context *context, char *error, size_t capacity)
Run the currently prepared tensors using the context's timeout policy.
bool inference_context_open(struct inference_context *context, const struct inference_settings *settings, const char *adapter, char *error, size_t capacity)
Verify a bundle, map bounded tensors and bind one warm session.
void inference_context_close(struct inference_context *context)
Release the session before unmapping its borrowed tensor storage.
Integrity-checked model contracts and independently owned tensor workspaces.
bool inference_settings_read(struct inference_settings *settings, const char *filename, ini_field_handler extra, void *context, char *error, size_t capacity)
Parse one flat INI, delegate application keys and resolve paths against the selected file.
void inference_settings_init(struct inference_settings *settings, enum inference_backend backend)
Reset storage and select conservative thread/timeout defaults.
@ INFERENCE_LIVE
@ INFERENCE_NATIVE
@ INFERENCE_ONNX
struct jpeg_error_mgr error
Definition lwir_image.c:60
void onnx_session_cancel(struct onnx_session *session)
Request cooperative cancellation from another thread; join the owner before destroying storage.
@ ONNX_FLOAT32
static size_t count
Definition pose_log.c:79
One classified audio window; probability and measured level are different evidence.
Independent, noncopyable model owner; mapped tensor buffers and session are reused between jobs.
Parsed descriptor with self-referencing tensor-name pointers; do not copy after parsing.
struct inference_image_spec image
struct onnx_tensor inputs[ONNX_TENSOR_LIMIT]
struct onnx_tensor outputs[ONNX_TENSOR_LIMIT]
Per-application configuration; all resolved paths belong to this caller-owned value.
enum inference_backend backend
enum inference_source source
enum onnx_element_type type
bool valid
Definition usher.c:537
struct usher_control_result result
Definition usher.c:377