v0.4.3-alpha: Merge pull request #9 from danielfcollier/feat-improve-error-handling

Release Notes: CalibratorTransformer Error Handling Update

🚀 Improvements

• Graceful Error Handling: Removed hard exits (sys.exit or implicit crashes) from the _parse_frequency_response method.
• Explicit Exceptions: The class now explicitly raises ValueError (for invalid data/formats) or FileNotFoundError when parsing calibration files fails.
• Logging Adjustments: Downgraded log levels for parsing failures from CRITICAL to ERROR, reflecting that these are now recoverable exceptions rather than system-terminating events.

⚠️ Breaking Changes

• Exception Handling Required: Consumer code instantiating CalibratorTransformer should now wrap the initialization in a try/except block to catch ValueError or FileNotFoundError if robust error recovery is desired.

Example Usage

try:
    transformer = CalibratorTransformer(file_path, ...)
except (ValueError, FileNotFoundError) as e:
    logger.error(f"Calibration failed: {e}")
    # Fallback logic here

v0.4.2-alpha

Release Notes: Calibration Logic Refactor & Strict Validation

This release encapsulates the physics math within the Transformer layer and enforces stricter validation for calibration assets.

🚀 Refactors

• Calibrator Transformer: Now internally calculates sensitivity_gain using hardware constants (nominal_sensitivity_dbfs, reference_dbspl) passed to the constructor, rather than accepting a pre-calculated gain.
• App Configuration: Updated AppArgs to pass hardware specifications directly to the transformer during initialization.

🛡️ Stability & Safety

• Strict Error Handling: The application now raises a fatal RuntimeError (stopping startup) if the calibration filter cannot be designed or loaded, preventing the system from running with invalid or missing calibration data.
• Unit Tests: Updated test_app_args.py and test_calibrator_transformer.py to align with the new dependency injection signature.

v0.4.1-alpha

Release Notes: Physics Encapsulation & Metrics Accuracy

This release consolidates audio calibration logic into the Transformer layer and improves measurement accuracy for pre-processed streams.

🚀 New Features

• Integrated Calibrator Transformer: The CalibratorTransformer now applies both Sensitivity Gain (Volume) and FIR Filter (EQ) in a single pass.
• Added sensitivity_gain to the constructor to handle absolute level correction.
• Introduced reset_state() to clear filter history, preventing artifacts when switching between audio streams (e.g., Pre-roll to Recording).

🐛 Bug Fixes

• Metrics Analyzer Fix: Resolved a "double calibration" issue where dBSPL calculations incorrectly applied sensitivity offsets to audio that was already gain-corrected.
• Real-Time Meter Accuracy: Updated sink logic to disable internal math offsets when a CalibratorTransformer is detected in the pipeline, ensuring accurate LUFS and dBSPL readings.

🛠️ Utilities

• System Telemetry: Added SystemMetrics for standardized monitoring of CPU, RAM, Disk, and Temperature across Raspberry Pi and Linux platforms.

v0.4.0-alpha

v0.4.0-alpha Release Notes

🚀 Highlights

• Python 3.9+ Support: Minimum Python requirement lowered from 3.12 to 3.9. Fully verified on versions 3.9, 3.10, 3.11, 3.12, and 3.13.
• Relaxed Dependencies: Switched from strict version pinning (~=) to minimum version constraints (>=) for pydantic, numpy, and scipy to resolve installation conflicts.
• Expanded Testing: CI pipeline now executes a build matrix to test all supported Python versions in parallel.

📋 Changelog

Infrastructure

• pyproject.toml:

• requires-python updated to >=3.9.

• pydantic relaxed to >=2.5.0 (maintaining V2 API support).

• numpy, scipy, and matplotlib baselines adjusted for older Python environments.

• pyzmq package name corrected.

• ci.yml: Implemented strategy matrix for multi-version testing.

• README.md: Updated prerequisites to reflect new compatibility.

🆙 Upgrading

To install the latest version:

pip install --upgrade umik-base-app

v0.3.1-alpha

Release Notes: v0.3.1-alpha

This release focuses on structural maturity, test reliability, and hardware flexibility. It introduces a major project restructuring, decouples the codebase from specific hardware models (paving the way for UMIK-2 support), and significantly hardens the test suite.

⚡ Architecture & Refactoring

• Project Restructure: Reorganized the codebase into a cleaner src/umik_base_app layout to improve maintainability and separate core logic from application entry points.
• Simplified Application Logic: Refactored basic_recorder.py and real_time_meter.py to reduce boilerplate, leveraging the AudioBaseApp framework more effectively for initialization and cleanup.
• Modernized Analysis: Updated metrics_analyzer.py to use pandas for robust data handling and CSV export, replacing manual CSV writing logic.

⚙️ Configuration & Hardware

• Hardware Decoupling: Added TARGET_DEVICE_NAME to settings.py. The application is no longer hardcoded to "UMIK-1"; it can now be configured to auto-detect "UMIK-2" or other measurement microphones via settings.HARDWARE or environment variables.
• Dynamic Calibration: Updated HardwareSelector and AppArgs to utilize the new configuration settings for device discovery.

🧪 Testing

• Sentinel-Based Unit Tests: Refactored core unit tests (test_audio_pipeline.py, test_listener_thread.py, etc.) to use unittest.mock.sentinel. This ensures tests verify object identity passing rather than relying on arbitrary data values, making them stricter and less brittle.
• Expanded End-to-End Coverage: Overhauled tests_end-to-end.sh to include:
• Distributed Topology: New verification for Producer/Consumer modes over ZMQ.
• ZMQ Resilience: Explicit tests for umik-recorder and umik-real-time-meter operating as consumers.
• Artifact Validation: Added checks to ensure WAV files and PNG plots are actually generated.

🐛 Bug Fixes

• Calibration Signature: Fixed a TypeError in umik1_calibrator.py, real_time_meter.py, and metrics_analyzer.py where get_sensitivity_values was called without the required reference arguments. It now correctly pulls NOMINAL_SENSITIVITY_DBFS and REFERENCE_DBSPL from settings.
• ZMQ Defaults: Fixed a crash where zmq_messages could be None during transport creation; it now defaults safely to 1000.

v0.3.0-alpha

Here are the Release Notes for v0.3.0-alpha.

---

🚀 Release Notes v0.3.0-alpha

"The Distributed Update"

This release marks a major architectural shift for umik-base-app. I have broken the "Monolith" to support Distributed Audio Monitoring and Process Isolation. You can now run the audio capture ("The Ear") and the processing ("The Brain") as completely separate system processes, or even on different computers over a network.

✨ New Features

🌐 Distributed Topology (ZeroMQ)

• Introduced a Transport Layer abstraction supporting both In-Memory queues (legacy) and ZeroMQ (TCP) sockets.
• IoT Ready: You can now capture audio on a headless edge device (e.g., Raspberry Pi) and visualize/analyze it on a remote workstation.
• New CLI Flags:
• --producer: Starts the application in Capture-Only mode (broadcasts audio).
• --consumer: Starts the application in Process-Only mode (receives audio).
• --zmq-host: Specify the target IP (default: localhost).
• --zmq-port: Specify the target port (default: 5555).

🛡️ Process Isolation (Daemon Mode)

• Eliminated GIL Glitches: By running the Producer as a separate process, it can be assigned Real-Time Priority (e.g., nice -n -20) by the OS.
• Crash Resilience: The audio stream now survives even if the visualization/consumer app crashes or hangs.

🛠️ Technical Improvements

🏗️ Project Restructuring

Refactored the codebase to reflect a mature, domain-driven design structure. The project is now organized into clear functional domains:

• transports/: Contains QueueTransport and ZmqTransport logic.
• sinks/: dedicated components for data consumption (Recorder, Metrics).
• transformers/: components for signal modification (Calibration).
• core/: Threading and Pipeline logic.

🧪 Integration & E2E Testing

• Added a robust Integration Test Suite (make test-integration).
• Added Topology Tests to verify Producer-Consumer handshake over real TCP sockets.
• Updated Makefile to separate Unit Tests (make test) from Integration Tests.

📦 Dependencies

• Added: pyzmq (for distributed transport).
• Added: pytest-timeout (for integration test safety).

⚠️ Breaking Changes

• Internal API: BaseApp constructor now requires a run_mode in AppConfig.
• CLI: While standard commands (umik-real-time-meter) work as before, the underlying default transport is now explicitly managed via AppConfig.

🔧 How to Upgrade

pip install --upgrade umik-base-app
# OR
uv sync

v0.2.1-alpha

Release Notes: UMIK Series Support & Documentation Improvements

This release expands the platform's scope to the entire miniDSP UMIK Series and refines our educational resources.

🎤 Hardware: UMIK Series Expansion

• Broader Support: Officially shifted focus from "UMIK-1" to "UMIK Series" support.
• UMIK-2 Ready: Added native 32-bit float support and auto-switching for high sample rates (up to 192kHz) to utilize UMIK-2 capabilities.

📚 Documentation Updates

• Improments in all Posts:

v0.2.0-alpha

Release v0.2.0-alpha

Status: 🟢 Stable / Alpha Focus: Reliability, CLI Robustness, and Integration Testing.

This release marks a significant milestone in project stability. We have successfully implemented a comprehensive End-to-End integration testing suite that verifies the entire pipeline - from audio discovery to analysis and visualization - ensuring all entry points work correctly in both development and "production-like" (pip installed) environments.

🚀 Key Highlights

🛡️ Robust Integration Testing

• Added make test-integration target running tests_integration.sh.
• Validates 100% of CLI entry points (umik-recorder, umik-real-time-meter, etc.) and Makefile targets.
• Covers three critical usage scenarios:
  1. Default Microphone: Standard operation without calibration.
  2. UMIK-1 (Explicit): Passing calibration files via CLI flags.
  3. UMIK-1 (Environment): Auto-detection using CALIBRATION_FILE env var.

🔧 CLI & Application Fixes

• Auto-Calibration Logic: The applications now intelligently fallback to the CALIBRATION_FILE environment variable if no flag is provided, or strictly respect the --default flag to ignore it.
• Headless Plotting: Fixed umik-metrics-plot crashing in CI/Headless environments by lazy-loading matplotlib and enforcing the Agg backend when saving files.
• Analysis Robustness: The metrics-analyzer now gracefully handles empty or silent audio files without crashing.

📦 Dependency Management

• Fixed version conflicts in pyproject.toml to ensure smooth installation via uv and pip.
• Moved pandas and matplotlib to core dependencies to ensure visualization tools work out-of-the-box.

🐛 Bug Fixes

• Fixed AttributeError: 'Namespace' object has no attribute 'default' in Config parser.
• Fixed ValueError: max() iterable argument is empty when analyzing silent/failed recordings.
• Fixed Makefile indentation errors preventing test execution.

🛠️ How to Test

1. Install: make install
2. Unit Tests: make test
3. Integration Tests: make test-integration (Requires a connected microphone or dummy devices).

v0.1.0

Release v0.1.0

Status: Alpha / Initial Release Focus: Core Architecture, Calibration Support, and Basic Tooling.

This is the first public release of umik-base-app, a Python framework designed to simplify working with the UMIK-1 measurement microphone. This version establishes the core "Producer-Consumer" audio pipeline, ensuring thread-safe audio capture, robust calibration handling, and a suite of CLI tools for recording and analysis.

✨ Key Features

🎙️ Core Audio Engine

• Hardware Abstraction: Robust device discovery and selection wrapper around sounddevice.
• UMIK-1 Integration: Native support for parsing UMIK-1 calibration files (.txt), including sensitivity data extraction.
• Pipeline Architecture: A robust, thread-safe architecture separating audio capture (ListenerThread) from processing (ConsumerThread) to prevent buffer underruns.

🛠️ Included CLI Applications

The package installs several command-line entry points:

• umik-list-devices: Quickly lists and identifies input devices and their IDs.
• umik-calibrate: Validates calibration files and pre-calculates FIR filters for use.
• umik-real-time-meter: A console-based real-time monitor for dBFS, LUFS, and RMS levels.
• umik-recorder: A calibrated audio recorder with buffer management.
• umik-metrics-analyzer: A post-processing tool that generates scientific metrics (RMS, Flux, LUFS, dBSPL) from WAV files.
• umik-metrics-plot: A visualization tool to chart audio metrics over time.

⚙️ Developer Experience

• Modern Tooling: Built using uv for lightning-fast dependency management and ruff for linting/formatting.
• Type Safety: 100% type-hinted codebase verified with mypy.
• Makefile: Comprehensive Makefile included for easy installation, testing, and running common tasks.

📦 Installation

git clone https://github.com/danielfcollier/py-umik-base-app.git
cd py-umik-base-app
make install

📝 Quick Start Examples

1. Record Audio (with Calibration):

make record-umik-1 F="umik-1/calibration.txt" OUT="test.wav"

2. Analyze the Recording:

make metrics-analyzer IN="test.wav" CSV_OUT="analysis.csv"

3. Visualize the Data:

make plot-view IN="analysis.csv"

Contributors:

• Daniel Collier (@danielfcollier)