Skip to main content

qualia_core_db/audio/
bioacoustics.rs

1//! Bioacoustic classification and SPARQL-MM observation pipeline (§GAP-03 / F5).
2//!
3//! Bridges raw time-frequency surfaces (`TfSurface`) to SPARQL-MM media fragments
4//! (`mm:TemporalFragment`, `qualia:AcousticObservation`). Enables species call detection,
5//! spectral bounding, confidence scoring, and zero-heap conversion into queryable Quins.
6
7use crate::audio::tf_surface::TfSurface;
8use crate::{q_hash, NQuin};
9
10/// SPARQL-MM and Media Annotation Ontology predicate URIs.
11pub const MM_TEMPORAL_FRAGMENT: &str = "http://www.w3.org/ns/ma-ont#MediaFragment";
12pub const QUALIA_ACOUSTIC_OBSERVATION: &str = "qualia:AcousticObservation";
13pub const MA_HAS_START_TIME: &str = "http://www.w3.org/ns/ma-ont#hasStartTime";
14pub const MA_HAS_END_TIME: &str = "http://www.w3.org/ns/ma-ont#hasEndTime";
15pub const MA_IS_FRAGMENT_OF: &str = "http://www.w3.org/ns/ma-ont#isFragmentOf";
16pub const QUALIA_TAXON_ID: &str = "qualia:speciesTaxonId";
17pub const QUALIA_SPECIES_CONFIDENCE: &str = "qualia:speciesConfidence";
18pub const QUALIA_FREQ_LOW: &str = "qualia:frequencyLowHz";
19pub const QUALIA_FREQ_HIGH: &str = "qualia:frequencyHighHz";
20
21/// Detected bioacoustic vocalization event.
22#[derive(Debug, Clone, Copy, PartialEq)]
23pub struct BioacousticVocalization {
24    /// Start time in seconds.
25    pub start_time_s: f32,
26    /// End time in seconds.
27    pub end_time_s: f32,
28    /// Lower frequency boundary in Hz.
29    pub low_freq_hz: f32,
30    /// Upper frequency boundary in Hz.
31    pub high_freq_hz: f32,
32    /// Peak energy / magnitude in decibels.
33    pub peak_magnitude_db: f32,
34    /// Taxon identifier (e.g. GBIF taxon key or FNV-1a hash of scientific name).
35    pub taxon_id: u64,
36    /// Classification confidence score in `[0.0, 1.0]`.
37    pub confidence: f32,
38}
39
40impl Default for BioacousticVocalization {
41    fn default() -> Self {
42        Self {
43            start_time_s: 0.0,
44            end_time_s: 0.0,
45            low_freq_hz: 0.0,
46            high_freq_hz: 0.0,
47            peak_magnitude_db: 0.0,
48            taxon_id: 0,
49            confidence: 0.0,
50        }
51    }
52}
53
54/// Detects acoustic vocalization energy clusters from a `TfSurface`.
55///
56/// Scans the surface for contiguous time-frames exceeding `threshold_db` across frequency bins.
57/// Populates `out` with detected call intervals that exceed `min_duration_s`.
58/// Zero-heap hot path.
59pub fn detect_bioacoustic_vocalizations(
60    surface: &TfSurface,
61    threshold_db: f32,
62    min_duration_s: f32,
63    assigned_taxon_id: u64,
64    out: &mut [BioacousticVocalization],
65) -> usize {
66    if surface.frame_count == 0 || surface.bin_count == 0 || out.is_empty() {
67        return 0;
68    }
69
70    let mut detected_count = 0usize;
71    let mut in_call = false;
72    let mut call_start_frame = 0usize;
73    let mut min_bin = surface.bin_count;
74    let mut max_bin = 0usize;
75    let mut peak_val = f32::NEG_INFINITY;
76
77    for f in 0..surface.frame_count {
78        let mut frame_peak = f32::NEG_INFINITY;
79        let mut frame_min_bin = surface.bin_count;
80        let mut frame_max_bin = 0usize;
81
82        for b in 0..surface.bin_count {
83            let val = surface.get(f, b);
84            if val >= threshold_db {
85                if val > frame_peak {
86                    frame_peak = val;
87                }
88                if b < frame_min_bin {
89                    frame_min_bin = b;
90                }
91                if b > frame_max_bin {
92                    frame_max_bin = b;
93                }
94            }
95        }
96
97        let frame_active = frame_peak >= threshold_db;
98
99        if frame_active {
100            if !in_call {
101                in_call = true;
102                call_start_frame = f;
103                min_bin = frame_min_bin;
104                max_bin = frame_max_bin;
105                peak_val = frame_peak;
106            } else {
107                if frame_peak > peak_val {
108                    peak_val = frame_peak;
109                }
110                if frame_min_bin < min_bin {
111                    min_bin = frame_min_bin;
112                }
113                if frame_max_bin > max_bin {
114                    max_bin = frame_max_bin;
115                }
116            }
117        } else if in_call {
118            // Call completed
119            let duration = surface.frame_to_time(f) - surface.frame_to_time(call_start_frame);
120            if duration >= min_duration_s {
121                let low_f = surface.bin_to_freq_linear(min_bin);
122                let high_f = surface.bin_to_freq_linear(max_bin);
123                // Confidence normalized against threshold
124                let confidence = ((peak_val - threshold_db) / 20.0).clamp(0.1, 1.0);
125
126                out[detected_count] = BioacousticVocalization {
127                    start_time_s: surface.frame_to_time(call_start_frame),
128                    end_time_s: surface.frame_to_time(f),
129                    low_freq_hz: low_f,
130                    high_freq_hz: high_f,
131                    peak_magnitude_db: peak_val,
132                    taxon_id: assigned_taxon_id,
133                    confidence,
134                };
135                detected_count += 1;
136                if detected_count >= out.len() {
137                    return detected_count;
138                }
139            }
140            in_call = false;
141        }
142    }
143
144    // Flush active call at the end of surface
145    if in_call && detected_count < out.len() {
146        let duration =
147            surface.frame_to_time(surface.frame_count) - surface.frame_to_time(call_start_frame);
148        if duration >= min_duration_s {
149            let low_f = surface.bin_to_freq_linear(min_bin);
150            let high_f = surface.bin_to_freq_linear(max_bin);
151            let confidence = ((peak_val - threshold_db) / 20.0).clamp(0.1, 1.0);
152
153            out[detected_count] = BioacousticVocalization {
154                start_time_s: surface.frame_to_time(call_start_frame),
155                end_time_s: surface.frame_to_time(surface.frame_count),
156                low_freq_hz: low_f,
157                high_freq_hz: high_f,
158                peak_magnitude_db: peak_val,
159                taxon_id: assigned_taxon_id,
160                confidence,
161            };
162            detected_count += 1;
163        }
164    }
165
166    detected_count
167}
168
169/// Compile bioacoustic vocalizations into SPARQL-MM observation Quins.
170/// Produces `(fragment_uri, predicate, object)` triples for each vocalization:
171/// - `rdf:type` -> `qualia:AcousticObservation`
172/// - `ma:isFragmentOf` -> `recording_uri`
173/// - `ma:hasStartTime` -> start time in milliseconds
174/// - `ma:hasEndTime` -> end time in milliseconds
175/// - `qualia:speciesTaxonId` -> taxon ID
176/// - `qualia:speciesConfidence` -> confidence weight
177///
178/// Zero-heap: writes directly into caller-supplied `out` slice.
179pub fn compile_vocalizations_to_sparql_mm(
180    recording_uri: u64,
181    vocalizations: &[BioacousticVocalization],
182    out: &mut [NQuin],
183) -> usize {
184    let p_type = q_hash("http://www.w3.org/1999/02/22-rdf-syntax-ns#type");
185    let o_obs_type = q_hash(QUALIA_ACOUSTIC_OBSERVATION);
186    let p_fragment_of = q_hash(MA_IS_FRAGMENT_OF);
187    let p_start_time = q_hash(MA_HAS_START_TIME);
188    let p_end_time = q_hash(MA_HAS_END_TIME);
189    let p_taxon = q_hash(QUALIA_TAXON_ID);
190    let p_conf = q_hash(QUALIA_SPECIES_CONFIDENCE);
191
192    let mut written = 0usize;
193
194    for (idx, voc) in vocalizations.iter().enumerate() {
195        if written + 6 > out.len() {
196            break;
197        }
198
199        // Derive deterministic fragment URI from recording_uri and index
200        let fragment_uri = recording_uri ^ q_hash(&format!("frag:acoustic:{}", idx));
201
202        let make_quin = |p: u64, o: u64, meta: u64| {
203            let mut q = NQuin {
204                subject: fragment_uri,
205                predicate: p,
206                object: o,
207                context: recording_uri,
208                metadata: meta,
209                parity: 0,
210            };
211            q.parity = q.subject ^ q.predicate ^ q.object ^ q.context;
212            q
213        };
214
215        // 1. rdf:type
216        out[written] = make_quin(p_type, o_obs_type, 0);
217        written += 1;
218
219        // 2. isFragmentOf
220        out[written] = make_quin(p_fragment_of, recording_uri, 0);
221        written += 1;
222
223        // 3. hasStartTime (ms)
224        let start_ms = (voc.start_time_s * 1000.0) as u64;
225        out[written] = make_quin(p_start_time, start_ms, start_ms << 16);
226        written += 1;
227
228        // 4. hasEndTime (ms)
229        let end_ms = (voc.end_time_s * 1000.0) as u64;
230        out[written] = make_quin(p_end_time, end_ms, end_ms << 16);
231        written += 1;
232
233        // 5. taxon ID
234        out[written] = make_quin(p_taxon, voc.taxon_id, 0);
235        written += 1;
236
237        // 6. confidence (fixed point integer 0..1000 in object)
238        let conf_fixed = (voc.confidence * 1000.0) as u64;
239        out[written] = make_quin(p_conf, conf_fixed, 0);
240        written += 1;
241    }
242
243    written
244}
245
246#[cfg(test)]
247mod tests {
248    use super::*;
249
250    #[test]
251    fn test_detect_bioacoustic_vocalizations() {
252        // 10 frames x 4 bins raster
253        let mut raster = vec![0.0f32; 40];
254        // Inject vocalization between frames 2 and 6 on bin 2
255        for f in 2..6 {
256            raster[f * 4 + 2] = 25.0; // 25 dB
257        }
258
259        let surface = TfSurface::new(&raster, 10, 4, 16000, 160);
260        let mut out = [BioacousticVocalization::default(); 4];
261
262        let count = detect_bioacoustic_vocalizations(&surface, 20.0, 0.02, 0x1234, &mut out);
263        assert_eq!(count, 1);
264        assert_eq!(out[0].taxon_id, 0x1234);
265        assert!(out[0].start_time_s >= 0.02);
266        assert!(out[0].end_time_s > out[0].start_time_s);
267        assert_eq!(out[0].peak_magnitude_db, 25.0);
268    }
269
270    #[test]
271    fn test_compile_vocalizations_to_sparql_mm() {
272        let voc = BioacousticVocalization {
273            start_time_s: 1.5,
274            end_time_s: 2.2,
275            low_freq_hz: 1200.0,
276            high_freq_hz: 3400.0,
277            peak_magnitude_db: 32.0,
278            taxon_id: 0x9999,
279            confidence: 0.95,
280        };
281
282        let recording = q_hash("urn:recording:forest_night_01");
283        let mut quins = [NQuin::default(); 12];
284
285        let n = compile_vocalizations_to_sparql_mm(recording, &[voc], &mut quins);
286        assert_eq!(n, 6);
287
288        // Check rdf:type
289        assert_eq!(
290            quins[0].predicate,
291            q_hash("http://www.w3.org/1999/02/22-rdf-syntax-ns#type")
292        );
293        assert_eq!(quins[0].object, q_hash(QUALIA_ACOUSTIC_OBSERVATION));
294
295        // Check start time = 1500ms
296        assert_eq!(quins[2].object, 1500);
297        // Check end time = 2200ms
298        assert_eq!(quins[3].object, 2200);
299        // Check taxon ID
300        assert_eq!(quins[4].object, 0x9999);
301        // Check confidence
302        assert_eq!(quins[5].object, 950);
303    }
304}