acoustic-engine 1.0.0__py3-none-any.whl

acoustic_engine/__init__.py

@@ -0,0 +1,54 @@
+"""Acoustic Alarm Engine - Real-time audio pattern detection.
+
+A standalone library for detecting acoustic alarm patterns including
+smoke alarms, CO detectors, appliance beeps, and other repetitive sounds.
+
+Usage:
+    from acoustic_engine import Engine, AudioConfig
+    from acoustic_engine.profiles import load_profiles_from_yaml
+
+    profiles = load_profiles_from_yaml("smoke_alarm.yaml")
+    engine = Engine(profiles, AudioConfig(), on_detection=print)
+    engine.start()
+"""
+
+__version__ = "1.0.0"
+__author__ = "Your Name"
+
+# Core exports
+from .analysis.event_buffer import EventBuffer
+from .analysis.windowed_matcher import WindowedMatcher
+from .config import EngineConfig, compute_finest_resolution
+from .engine import Engine
+from .input.listener import AudioConfig, AudioListener
+from .models import AlarmProfile, Range, ResolutionConfig, Segment
+from .processing.filter import FrequencyFilter
+from .profiles import (
+    load_profile_from_yaml,
+    load_profiles_from_yaml,
+    save_profile_to_yaml,
+)
+
+__all__ = [
+    # Version
+    "__version__",
+    # Core classes
+    "Engine",
+    "AudioConfig",
+    "AudioListener",
+    "FrequencyFilter",
+    "EventBuffer",
+    "WindowedMatcher",
+    # Configuration
+    "EngineConfig",
+    "ResolutionConfig",
+    "compute_finest_resolution",
+    # Models
+    "AlarmProfile",
+    "Segment",
+    "Range",
+    # Profile loading
+    "load_profile_from_yaml",
+    "load_profiles_from_yaml",
+    "save_profile_to_yaml",
+]

acoustic_engine/analysis/event_buffer.py

@@ -0,0 +1,85 @@
+"""Circular buffer for storing recent audio events for windowed analysis."""
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+from ..events import ToneEvent
+
+
+@dataclass
+class EventBuffer:
+    """Stores recent audio events for windowed pattern matching.
+
+    Maintains a time-ordered list of events, automatically pruning
+    events older than max_duration.
+    """
+
+    max_duration: float = 30.0  # Keep events from last 30s
+    _events: List[ToneEvent] = field(default_factory=list)
+
+    def add(self, event: ToneEvent) -> None:
+        """Add an event to the buffer.
+
+        Events are assumed to arrive roughly in order. The buffer
+        automatically prunes old events.
+
+        Args:
+            event: ToneEvent to add
+        """
+        self._events.append(event)
+
+        # Prune old events (keep those within max_duration of latest)
+        if self._events:
+            latest_time = max(e.timestamp for e in self._events)
+            cutoff = latest_time - self.max_duration
+            self._events = [e for e in self._events if e.timestamp >= cutoff]
+
+    def get_window(self, end_time: float, window_duration: float) -> List[ToneEvent]:
+        """Get all events within a time window.
+
+        Args:
+            end_time: End of the window (usually current time)
+            window_duration: How far back to look
+
+        Returns:
+            List of events within [end_time - window_duration, end_time]
+        """
+        start_time = end_time - window_duration
+        return [e for e in self._events if start_time <= e.timestamp <= end_time]
+
+    def get_events_in_range(
+        self,
+        start_time: float,
+        end_time: float,
+        freq_min: Optional[float] = None,
+        freq_max: Optional[float] = None,
+    ) -> List[ToneEvent]:
+        """Get events in a time range, optionally filtered by frequency.
+
+        Args:
+            start_time: Start of range
+            end_time: End of range
+            freq_min: Optional minimum frequency filter
+            freq_max: Optional maximum frequency filter
+
+        Returns:
+            Filtered list of events
+        """
+        events = [e for e in self._events if start_time <= e.timestamp <= end_time]
+
+        if freq_min is not None and freq_max is not None:
+            events = [e for e in events if freq_min <= e.frequency <= freq_max]
+
+        return sorted(events, key=lambda e: e.timestamp)
+
+    def clear(self) -> None:
+        """Clear all events from the buffer."""
+        self._events.clear()
+
+    @property
+    def events(self) -> List[ToneEvent]:
+        """Get all events in the buffer (read-only)."""
+        return list(self._events)
+
+    def __len__(self) -> int:
+        return len(self._events)

acoustic_engine/analysis/generator.py

@@ -0,0 +1,262 @@
+"""Generates discrete events from continuous DSP data."""
+
+import logging
+from dataclasses import dataclass
+from typing import List
+
+from ..events import AudioEvent, ToneEvent
+from ..processing.dsp import Peak
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ActiveTone:
+    """Tracks a currently playing tone."""
+
+    start_time: float
+    frequency: float
+    max_magnitude: float
+    last_seen_time: float
+    last_strong_time: float  # Last time the signal was above 50% of max
+    last_magnitude: float  # Last chunk's magnitude for dip detection
+    samples_count: int
+
+
+class EventGenerator:
+    """Converts continuous spectral peaks into discrete Tone/Silence events.
+
+    This class acts as the bridge between the DSP layer (frequency peaks) and
+    the pattern matchers (audio events). It handles:
+    - **Debouncing**: Ignoring short transient noises.
+    - **Continuity**: Stitching together spectral peaks across multiple
+      chunks into coherent `ToneEvent`s.
+    - **Dropout Tolerance**: Allowing short gaps in a signal (due to noise
+      or interference) without breaking the tone event.
+    - **Temporal Sorting**: Ensuring events are emitted in strict chronological order.
+    """
+
+    def __init__(
+        self,
+        sample_rate: int,
+        chunk_size: int,
+        min_tone_duration: float = 0.1,
+        dropout_tolerance: float = 0.15,
+        frequency_tolerance: float = 50.0,
+        freq_smoothing: float = 0.3,
+        dip_threshold: float = 0.6,
+        strong_signal_ratio: float = 0.5,
+        coalesce_ratio: float = 0.5,
+    ):
+        """Initialize the event generator.
+
+        Args:
+            sample_rate: Audio sample rate in Hz.
+            chunk_size: Number of samples per chunk.
+            min_tone_duration: Minimum duration for a detected tone to be valid.
+            dropout_tolerance: Maximum silence gap allowed within a single tone.
+            frequency_tolerance: Hz range to consider peaks as the same tone.
+            freq_smoothing: Alpha for EMA frequency tracking.
+            dip_threshold: Ratio for instantaneous dip detection.
+            strong_signal_ratio: Ratio to consider signal "strong" for duration.
+            coalesce_ratio: Overlap ratio for merging concurrent events.
+        """
+        self.sample_rate = sample_rate
+        self.chunk_size = chunk_size
+        self.chunk_duration = chunk_size / sample_rate
+
+        # Safeguard: Ensure dropout tolerance is at least 1.5x chunk duration
+        # to prevent single-chunk noise from breaking tones.
+        safe_dropout = self.chunk_duration * 1.5
+        if dropout_tolerance < safe_dropout:
+            logger.warning(
+                f"dropout_tolerance ({dropout_tolerance:.3f}s) is too low for "
+                f"chunk_duration ({self.chunk_duration:.3f}s). "
+                f"Increasing to {safe_dropout:.3f}s for stability."
+            )
+            dropout_tolerance = safe_dropout
+
+        # Configuration
+        self.min_tone_duration = min_tone_duration
+        self.dropout_tolerance = dropout_tolerance
+        self.frequency_tolerance = frequency_tolerance
+        self.freq_smoothing = freq_smoothing
+        self.dip_threshold = dip_threshold
+        self.strong_signal_ratio = strong_signal_ratio
+        self.coalesce_ratio = coalesce_ratio
+
+        # State
+        self.active_tones: List[ActiveTone] = []
+        self.last_process_time = 0.0
+
+        # Buffer for events to ensure chronological output
+        self.pending_output: List[ToneEvent] = []
+
+    def process(self, peaks: List[Peak], timestamp: float) -> List[AudioEvent]:
+        """Process spectral peaks for a time slice and return completed events.
+
+        This function should be called for every analyzed audio chunk.
+
+        Args:
+            peaks: List of significant spectral peaks detected by the DSP layer.
+            timestamp: The end time of the current audio chunk in seconds.
+
+        Returns:
+            A list of completed `ToneEvent` objects. Note that events are only
+            emitted *after* they have finished (and the dropout tolerance timer
+            has expired), so there is inherent latency equal to `dropout_tolerance`.
+        """
+        # 1. Update active tones
+        current_active_indices = set()
+
+        for peak in peaks:
+            matched = False
+            for i, tone in enumerate(self.active_tones):
+                if abs(peak.frequency - tone.frequency) < self.frequency_tolerance:
+                    # 2. Track frequency history/smoothing
+                    tone.frequency = (
+                        1.0 - self.freq_smoothing
+                    ) * tone.frequency + self.freq_smoothing * peak.frequency
+
+                    # Upgrade: Instantaneous Dip Detection (Grandmaster feature)
+                    # If magnitude drops by >40% compared to PREVIOUS chunk,
+                    # we are likely entering the reverb tail.
+                    magnitude_ratio = peak.magnitude / (
+                        tone.last_magnitude if tone.last_magnitude > 0 else 1.0
+                    )
+
+                    if magnitude_ratio < self.dip_threshold:
+                        # Significant dip - This is likely the end of the beep and start of reverb.
+                        # We force a disconnect here so the beep duration isn't stretched.
+                        matched = False
+                        break
+
+                    if peak.magnitude > tone.max_magnitude * self.strong_signal_ratio:
+                        # Signal is still strong and consistent
+                        tone.last_strong_time = timestamp
+
+                    if peak.magnitude > tone.max_magnitude:
+                        tone.max_magnitude = peak.magnitude
+
+                    tone.last_magnitude = peak.magnitude  # Track for NEXT dip check
+                    tone.last_seen_time = timestamp
+                    tone.samples_count += 1
+                    current_active_indices.add(i)
+                    matched = True
+                    break
+
+            if not matched:
+                # New potential tone
+                new_tone = ActiveTone(
+                    start_time=timestamp,
+                    frequency=peak.frequency,
+                    max_magnitude=peak.magnitude,
+                    last_seen_time=timestamp,
+                    last_strong_time=timestamp,
+                    last_magnitude=peak.magnitude,
+                    samples_count=1,
+                )
+                self.active_tones.append(new_tone)
+                current_active_indices.add(len(self.active_tones) - 1)
+
+        # 2. Check for ended tones
+        active_tones_next: List[ActiveTone] = []
+        new_events: List[ToneEvent] = []
+
+        for i, tone in enumerate(self.active_tones):
+            if i in current_active_indices:
+                active_tones_next.append(tone)
+            else:
+                time_since_seen = timestamp - tone.last_seen_time
+
+                if time_since_seen > self.dropout_tolerance:
+                    # Tone ended - Use 'last_strong_time' for precision duration (Elite feature)
+                    # This cuts off the reverb tail and restores the true pattern rhythm.
+                    duration = (tone.last_strong_time - tone.start_time) + self.chunk_duration
+
+                    # Safety check: ensure duration is at least one chunk
+                    duration = max(self.chunk_duration, duration)
+
+                    if duration >= self.min_tone_duration:
+                        event = ToneEvent(
+                            timestamp=tone.start_time,
+                            duration=duration,
+                            frequency=tone.frequency,
+                            magnitude=tone.max_magnitude,
+                            confidence=1.0,
+                        )
+                        new_events.append(event)
+                        logger.debug(
+                            f"Generated Tone: {event.frequency:.0f}Hz, {event.duration:.2f}s"
+                        )
+                else:
+                    # Keep waiting (dropout tolerance)
+                    active_tones_next.append(tone)
+
+        self.active_tones = active_tones_next
+        self.last_process_time = timestamp
+
+        # 3. Add new events to pending output buffer
+        if new_events:
+            self.pending_output.extend(new_events)
+            # Sort pending events by start time
+            self.pending_output.sort(key=lambda e: e.timestamp)
+
+        # 4. Safe Release Logic:
+        # We can only release events that started BEFORE the oldest active tone's start time.
+        # This guarantees that no future event will be generated with an EARLIER timestamp
+        # than what we release now.
+
+        ready_events: List[ToneEvent] = []
+
+        if not self.active_tones:
+            # No active tones -> Safe to release everything
+            ready_events = self.pending_output
+            self.pending_output = []
+        else:
+            # Find the oldest start time among active tones
+            min_active_start = min(t.start_time for t in self.active_tones)
+
+            # Release events that definitely happen before any potential new event
+            # (Note: allowing a small margin for float equality)
+            split_idx = 0
+            for i, event in enumerate(self.pending_output):
+                if event.timestamp < min_active_start:
+                    split_idx = i + 1
+                else:
+                    break
+
+            if split_idx > 0:
+                ready_events = self.pending_output[:split_idx]
+                self.pending_output = self.pending_output[split_idx:]
+
+        # 5. Coalesce overlapping ready events
+        if len(ready_events) > 1:
+            coalesced_events = []
+
+            if ready_events:
+                current_event = ready_events[0]
+
+                for next_event in ready_events[1:]:
+                    # Check for overlap
+                    current_end = current_event.timestamp + current_event.duration
+                    next_start = next_event.timestamp
+
+                    # If they overlap significantly (more than 50% of the shorter one)
+                    overlap = max(
+                        0, min(current_end, next_event.timestamp + next_event.duration) - next_start
+                    )
+                    min_dur = min(current_event.duration, next_event.duration)
+
+                    if overlap > self.coalesce_ratio * min_dur:
+                        # Overlap detected - coalescing
+                        if next_event.duration > current_event.duration:
+                            current_event = next_event
+                    else:
+                        coalesced_events.append(current_event)
+                        current_event = next_event
+
+                coalesced_events.append(current_event)
+                ready_events = coalesced_events
+
+        return ready_events

acoustic_engine/analysis/matcher.py

@@ -0,0 +1,228 @@
+"""State machine for matching event streams against alarm profiles."""
+
+import logging
+from typing import List, Optional, Tuple
+
+from ..events import AudioEvent, PatternMatchEvent, ToneEvent
+from ..models import AlarmProfile
+
+logger = logging.getLogger(__name__)
+
+
+class MatcherState:
+    """Tracks progress of a single profile match."""
+
+    def __init__(self, profile: AlarmProfile):
+        self.profile = profile
+        self.current_segment_index = 0
+        self.cycle_count = 0
+        self.last_event_time = 0.0
+        self.start_time = 0.0
+
+        # Pre-compute the valid frequency range for this profile
+        self.freq_ranges: List[Tuple[float, float]] = []
+        for seg in profile.segments:
+            if seg.type == "tone" and seg.frequency:
+                self.freq_ranges.append((seg.frequency.min, seg.frequency.max))
+
+    def reset(self):
+        """Reset matching state."""
+        self.current_segment_index = 0
+        self.cycle_count = 0
+        self.last_event_time = 0.0
+
+    def is_relevant_frequency(self, freq: float) -> bool:
+        """Check if a frequency is within any expected range for this profile."""
+        for fmin, fmax in self.freq_ranges:
+            if fmin <= freq <= fmax:
+                return True
+        return False
+
+
+class SequenceMatcher:
+    """Matches incoming events against multiple alarm profiles using a state machine.
+
+    This class maintains an independent tracking state for each monitored profile.
+    It receives audio events (like Tones) and sequentially verifies if they match
+    the expected segments (Tones/Silences) of an alarm pattern.
+
+    Key Features:
+    - **Noise Immunity**: Tones that do not match ANY expected frequency range
+      across the profile are ignored. This effectively makes the matcher "deaf"
+      to background noise like speech or music, provided they don't overlap
+      with alarm frequencies.
+    - **Parallel Matching**: Can track multiple optional profiles simultaneously.
+    - **Resilience**: Handles missing or imperfect events up to a certain tolerance.
+    """
+
+    def __init__(self, profiles: List[AlarmProfile]):
+        """Initialize with list of profiles to match against.
+
+        Args:
+            profiles: List of AlarmProfile objects defining the patterns to detect.
+        """
+        self.profiles = profiles
+        self.states = {p.name: MatcherState(p) for p in profiles}
+
+    def process(self, event: AudioEvent) -> List[PatternMatchEvent]:
+        """Process a new audio event and check for pattern matches.
+
+        This is the main entry point for the matcher. It updates the state
+        of every profile with the new event.
+
+        Args:
+            event: An AudioEvent (usually a ToneEvent) detected by the Generator.
+
+        Returns:
+            List of PatternMatchEvent objects for any profiles that completed
+            their full pattern match sequence with this event.
+        """
+        matches = []
+
+        for profile in self.profiles:
+            match_event = self._update_profile(self.states[profile.name], event)
+            if match_event:
+                matches.append(match_event)
+
+        return matches
+
+    def _update_profile(
+        self, state: MatcherState, event: AudioEvent
+    ) -> Optional[PatternMatchEvent]:
+        """Update matching state for a single profile.
+
+        Internal method that advances the state machine for a specific profile.
+
+        Args:
+            state: The tracking state for the profile.
+            event: The new audio event to evaluate.
+
+        Returns:
+            A PatternMatchEvent if the profile's confirmation cycles are complete,
+            otherwise None.
+        """
+        p = state.profile
+
+        if state.current_segment_index >= len(p.segments):
+            state.current_segment_index = 0
+
+        expected = p.segments[state.current_segment_index]
+
+        if isinstance(event, ToneEvent):
+            # KEY FIX: Ignore tones that don't match any expected frequency
+            # This filters out ambient noise that would break pattern matching
+            if not state.is_relevant_frequency(event.frequency):
+                # This tone is outside all expected ranges - ignore it completely
+                logger.debug(f"[{p.name}] Ignoring out-of-band tone: {event.frequency:.0f}Hz")
+                return None
+
+            # Check silence gap before this tone
+            gap_duration = event.timestamp - state.last_event_time
+
+            # If expecting silence, check if gap matches
+            if expected.type == "silence":
+                # Handle overlapping events (negative gap)
+                # If we have a negative gap, it means this new event started BEFORE the previous one ended.
+                # If this new event matches the PREVIOUSLY matched tone segment, we can treat it as part of that event
+                # and just extend the timeline, effectively merging them.
+                if gap_duration < 0 and state.current_segment_index > 0:
+                    prev_idx = state.current_segment_index - 1
+                    # Wrap around not needed because index increments only after silence
+                    # Wait, if current is silence, previous was TONE.
+                    prev_seg = p.segments[prev_idx]
+
+                    if prev_seg.type == "tone" and prev_seg.frequency:
+                        if prev_seg.frequency.contains(event.frequency):
+                            # This is likely a parallel detection of the previous tone
+                            logger.debug(
+                                f"[{p.name}] Merging overlapping tone: {event.frequency:.0f}Hz "
+                                f"(gap {gap_duration:.2f}s)"
+                            )
+                            # Extend the last event time if this one lasts longer
+                            state.last_event_time = max(
+                                state.last_event_time, event.timestamp + event.duration
+                            )
+                            return None
+
+                if expected.duration.contains(gap_duration):
+                    state.current_segment_index += 1
+                    logger.debug(f"[{p.name}] Silence matched: {gap_duration:.2f}s")
+
+                    if state.current_segment_index >= len(p.segments):
+                        state.cycle_count += 1
+                        state.current_segment_index = 0
+                        logger.debug(
+                            f"[{p.name}] Cycle {state.cycle_count}/{p.confirmation_cycles} complete"
+                        )
+
+                        if state.cycle_count >= p.confirmation_cycles:
+                            state.cycle_count = 0
+                            return PatternMatchEvent(
+                                timestamp=event.timestamp,
+                                duration=0,
+                                profile_name=p.name,
+                                cycle_count=p.confirmation_cycles,
+                            )
+
+                    expected = p.segments[state.current_segment_index]
+                else:
+                    if state.current_segment_index > 0:
+                        logger.debug(
+                            f"[{p.name}] Reset: Gap {gap_duration:.2f}s doesn't match "
+                            f"expected {expected.duration.min:.2f}-{expected.duration.max:.2f}s"
+                        )
+                        state.reset()
+                        expected = p.segments[0]
+
+            # Now check if this tone matches current expectation
+            is_match = False
+            if expected.type == "tone" and expected.frequency:
+                freq_match = expected.frequency.contains(event.frequency)
+                dur_match = expected.duration.contains(event.duration)
+
+                if freq_match and dur_match:
+                    is_match = True
+                    logger.debug(
+                        f"[{p.name}] Tone matched step {state.current_segment_index}: "
+                        f"{event.frequency:.0f}Hz, {event.duration:.2f}s"
+                    )
+                elif freq_match and not dur_match:
+                    # Frequency matches but duration doesn't - reset
+                    logger.debug(
+                        f"[{p.name}] Duration mismatch: got {event.duration:.2f}s, "
+                        f"expected {expected.duration.min:.2f}-{expected.duration.max:.2f}s"
+                    )
+                    if state.current_segment_index > 0:
+                        state.reset()
+                        expected = p.segments[0]
+                        # Try matching step 0 with this event
+                        if (
+                            expected.type == "tone"
+                            and expected.frequency
+                            and expected.frequency.contains(event.frequency)
+                            and expected.duration.contains(event.duration)
+                        ):
+                            is_match = True
+
+            # Advance state if matched
+            if is_match:
+                state.last_event_time = event.timestamp + event.duration
+                state.current_segment_index += 1
+
+                if state.current_segment_index >= len(p.segments):
+                    state.cycle_count += 1
+                    state.current_segment_index = 0
+                    logger.debug(
+                        f"[{p.name}] Cycle {state.cycle_count}/{p.confirmation_cycles} complete"
+                    )
+
+                    if state.cycle_count >= p.confirmation_cycles:
+                        state.cycle_count = 0
+                        return PatternMatchEvent(
+                            timestamp=event.timestamp,
+                            duration=0,
+                            profile_name=p.name,
+                            cycle_count=p.confirmation_cycles,
+                        )
+
+        return None