umik-base-app 0.8.0

Base utilities for working with the Umik-1 microphone in Python applications.

🎤 audio-tools — Audio Measurement CLI

A modular Python CLI for real-time audio measurement with USB microphones.

Supports UMIK-1, UMIK-2, Dayton UMM-6, Earthworks M23/M30, and other USB measurement mics. Auto-detects known devices, validates sample rate support, and applies per-unit calibration files.

📦 Installation

APT — Linux (Recommended for Raspberry Pi and Ubuntu)

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

System dependencies (libportaudio2, libsndfile1, ffmpeg, libzmq3-dev) are installed automatically.

🍓 Raspberry Pi 4B verified. Perfect headless acoustic monitoring box.

pip

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

🕹️ CLI Reference

audio-tools --<command> [options]

Command	Description
audio-tools --devices	🔍 List available audio input devices
audio-tools --meter	📊 Real-time SPL / LUFS / dBFS meter
audio-tools --record	🎙️ Calibrated audio recorder (WAV)
audio-tools --calibrate	🔧 Generate FIR filter from a calibration file
audio-tools --analyze	🔬 Analyze a WAV file and export metrics to CSV
audio-tools --plot	📈 Plot a metrics CSV as a chart
audio-tools --batch	📁 Batch-analyze a directory of WAV files
audio-tools --enhance	✨ Filter and enhance voice audio
audio-tools --convert	🔄 Convert WAV recordings to OGG / MP3 / AAC

Pass --help after any command for full options:

audio-tools --meter --help
audio-tools --convert --help

⚡ Quick Start

# 1. Find your microphone's device ID
audio-tools --devices

# 2. Run the SPL meter (system default mic)
audio-tools --meter

# 3. Run with UMIK-1 calibration file
audio-tools --meter --calibration-file "umik-1/7175488.txt"

# 4. Record calibrated audio
audio-tools --record --calibration-file "umik-1/7175488.txt" --output-dir recordings/

🏃 Run Modes

Monolithic (Default)

Single process — simplest for desktop and testing.

audio-tools --meter --calibration-file "umik-1/7175488.txt"

👹 Daemon Mode — Unstoppable Ear

Run capture at high priority. Processing crashes never interrupt the audio stream.

# Terminal 1: high-priority capture process
sudo nice -n -20 audio-tools --meter --producer \
  --calibration-file "umik-1/7175488.txt" --zmq-port 5555

# Terminal 2: connect consumer (safe to open/close/crash)
audio-tools --meter --consumer --zmq-host localhost --zmq-port 5555

🌐 Distributed Mode — Remote Sentry

Capture on a Raspberry Pi, visualize on your laptop.

# On the Raspberry Pi
audio-tools --meter --producer \
  --calibration-file "umik-1/7175488.txt" --zmq-port 5555

# On your laptop
audio-tools --meter --consumer --zmq-host 192.168.1.50 --zmq-port 5555

🎛️ Calibration Files

Download the per-unit calibration file for your UMIK from miniDSP.

Auto-discovery

Place the file in one of these locations and it will be picked up automatically on the next run — no --calibration-file flag needed:

Location	Scope
~/.config/audio-tools/	Per-user
/etc/audio-tools/	System-wide

If multiple files are found, the app prompts you to select one interactively. If a calibrated microphone is detected but no file is found, the app warns you and asks for confirmation before running uncalibrated.

Sample files (installed with the package)

The .deb package ships sample calibration files to:

/usr/share/audio-tools/calibration/

These are not auto-discovered — they are reference copies only. To activate one, copy it to an auto-discovery location:

# Per-user (recommended)
mkdir -p ~/.config/audio-tools
cp /usr/share/audio-tools/calibration/7175488_90deg.txt ~/.config/audio-tools/

# Or system-wide
sudo cp /usr/share/audio-tools/calibration/7175488_90deg.txt /etc/audio-tools/

File layout

umik-1/
├── 7175488.txt           ← 0° on-axis. Use when pointing at a speaker.
├── 7175488_90deg.txt     ← 90° ambient. Use when pointing at the ceiling.
└── 7175488_fir_*.npy     ← [Generated] FIR filter cache (created on first run).

Generate or verify the FIR filter cache:

audio-tools --calibrate "umik-1/7175488.txt"

🖥️ Real-Time Dashboard (TUI)

Add --tui to get a live terminal dashboard instead of scrolling log output:

audio-tools --meter --tui
audio-tools --meter --tui --calibration-file "umik-1/7175488.txt"

Built with Textual:

┌───────────────────────────────────────────────────────┐
│  audio-tools --meter          Calibration: FULL (FIR) │
├──────────────────────┬────────────────────────────────┤
│  dBFS  ████████░░░░  │  dBSPL   72.4 dB               │
│ -24.3  ████████░░░░  │  LUFS   -28.1 LUFS             │
│        ████████░░░░  │  RMS     0.0241                │
│                      │  Flux    38.6                  │
├──────────────────────┴────────────────────────────────┤
│  Mode: MONOLITHIC    SR: 48000 Hz   ● REC   [R] Stop  │
└───────────────────────────────────────────────────────┘

Key	Action
R	🔴 Toggle recording on/off
Q	❌ Quit

Press R to start recording — audio is saved to recordings/ as a timestamped WAV. Press R again to stop; a notification pops with the filename.

🔬 Analysis & Visualization

# Analyze one file → CSV
audio-tools --analyze "recording.wav" --calibration-file "umik-1/7175488.txt"

# Batch analyze a directory → CSV per file
audio-tools --batch recordings/ --calibration-file "umik-1/7175488.txt"

# View chart (popup window)
audio-tools --plot "recording_metrics.csv"

# Save chart to PNG
audio-tools --plot "recording_metrics.csv" --save

🔄 Convert Audio

Convert WAV recordings to share-friendly formats. Requires ffmpeg.

# OGG/Opus — smallest, WhatsApp-compatible
audio-tools --convert recordings/ --format ogg

# Multiple formats in one pass
audio-tools --convert recordings/session.wav --format ogg mp3

# Output to a different directory
audio-tools --convert recordings/ --format ogg --out converted/

# Overwrite existing files
audio-tools --convert recordings/ --format ogg --overwrite

Format	Use Case
ogg	📱 WhatsApp voice notes (smallest)
mp3	🎵 Universal
aac	🍎 Apple-friendly (.m4a)

🔗 Related Projects

AI Acoustic Monitor — adds ML sound classification (chainsaws, glass breaking, birds) on embedded devices, built on this framework: py-edge-ai-acoustic-monitoring-app

🛠️ For Developers

Building a custom app on this framework? See CONTRIBUTING.md.

Full technical documentation: docs/

• Architecture — Producer-Consumer design, pipeline internals
• Audio Metrics — RMS, LUFS, dBFS, dBSPL explained
• UMIK Series Guide — Hardware-specific details