🎤 Audio Measurement Framework and CLI

A Python framework and CLI toolkit for real-time audio measurement with USB microphones.

• 📦 Use as a library to build custom real-time audio measurement applications
• 🕹️ Use the bundled CLI (audio-tools) for out-of-the-box measurement, recording and real-time spectrum analyzer (RTA)

Works with USB measurement microphones out of the box — auto-detects known devices, validates sample rate support, and applies per-unit calibration files.

PyPI package: umik-base-app (name reflects the project's origins; a rename is planned as the framework scope expands)

pip install umik-base-app

🎛️ Verified Hardware

The framework works with any USB audio input device. The following microphones have built-in device profiles and calibration support:

Custom device profiles can be added — see docs/FRAMEWORK.md.

⚡ Quick Start — Library

Subclass AudioSink, wire it into an AudioPipeline, and let AudioBaseApp handle device management, threading, reconnection, and calibration injection:

from umik_base_app import AppArgs, AudioBaseApp, AudioPipeline, AudioSink, PipelineContext

class LoudnessPrinter(AudioSink):
    def handle(self, ctx: PipelineContext) -> None:
        if ctx.can_calculate_dbspl():
            print(f"[{ctx.timestamp}] dBSPL: {ctx.reference_dbspl:.1f}")

def main():
    args = AppArgs.get_args()
    config = AppArgs.validate_args(args)

    pipeline = AudioPipeline(sample_rate=config.sample_rate)
    pipeline.add_sink(LoudnessPrinter())

    # If --calibration-file was passed, CalibratorAdapter is auto-injected
    app = AudioBaseApp(app_config=config, pipeline=pipeline)
    app.run()

if __name__ == "__main__":
    main()

Run it with any standard flags:

python my_app.py --calibration-file "umik-1/7175488.txt"
python my_app.py --producer --zmq-port 5555   # daemon / distributed mode

🏗️ Framework Concepts

Full API reference and examples: docs/FRAMEWORK.md

🕹️ Bundled Sample Apps (CLI)

The package ships a set of reference applications accessible via audio-tools. These demonstrate the framework and are ready to use out of the box:

🌐 Spectrum Analyzer

A browser-based Real-Time Analyzer (RTA) — comparable to the RTA panel in REW — with FFT plot, scrolling waterfall, time-series dBSPL/dBFS, noise floor baseline, and in-browser calibration loading. Opens automatically at http://localhost:8767.

audio-tools-spectrum --device <id> --calibration-file "umik-1/7175488.txt"

Full CLI reference: docs/CLI.md

📦 Installation

pip (recommended)

pip install umik-base-app

Requires system libraries:

# Linux (Debian/Ubuntu)
sudo apt install libportaudio2 libsndfile1 ffmpeg libzmq3-dev -y

# macOS
brew install portaudio libsndfile zeromq ffmpeg

APT — Linux headless deployment

For Raspberry Pi and Ubuntu servers, a .deb package installs system dependencies automatically:

curl -fsSL "https://br-se1.magaluobjects.com/audio-tools/audio-tools/pubkey.gpg" \
  | sudo gpg --dearmor -o /usr/share/keyrings/audio-tools.gpg
echo "deb [signed-by=/usr/share/keyrings/audio-tools.gpg] https://br-se1.magaluobjects.com/audio-tools/audio-tools $(lsb_release -cs) main" \
  | sudo tee /etc/apt/sources.list.d/audio-tools.list
sudo apt-get update && sudo apt-get install audio-tools

🍓 Raspberry Pi 4B verified. Suitable for headless acoustic monitoring boxes.

🔗 Related Projects

py-edge-ai-acoustic-monitoring-app — adds ML sound classification (chainsaws, glass breaking, birds) on embedded devices, built on top of this framework.

📚 Documentation