ADR-005: Sensor Framework

Date: March 2026 Status: Accepted

Context

Effects should react to real-time input (microphone, pipeline metrics) without hardcoding sensor logic.

Decision

Sensor ABC with read() returning SensorValue:

class Sensor(ABC):
    name: str
    unit: str = ""
    
    @abstractmethod
    def read(self) -> SensorValue | None: ...

@dataclass
class SensorValue:
    sensor_name: str
    value: float
    timestamp: float
    unit: str = ""

Implementations:

MicSensor: Microphone RMS dB (via sounddevice)
PipelineMetricsSensor: FPS, frame-time
OscillatorSensor: Test sine wave generator

SensorStage provides values to effects. Effects declare param_bindings:

class GlitchEffect(EffectPlugin):
    param_bindings = {
        "intensity": {"sensor": "mic", "transform": "linear"},
    }

Transforms: linear, exponential, threshold

Consequences

Positive: Extensible - add new sensors without touching effects
Positive: Effects react to any sensor uniformly
Negative: Audio sensors require additional dependencies

References

engine/sensors/__init__.py: Sensor ABC, SensorRegistry
engine/sensors/mic.py: MicSensor
engine/pipeline/adapters.py: SensorStage