{"id":35131488,"url":"https://github.com/danielfcollier/py-umik-base-app","last_synced_at":"2026-05-24T02:07:31.233Z","repository":{"id":320495183,"uuid":"1081939121","full_name":"danielfcollier/py-umik-base-app","owner":"danielfcollier","description":"Audio Base App and Framework","archived":false,"fork":false,"pushed_at":"2026-05-17T22:53:29.000Z","size":1595,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-18T00:44:44.025Z","etag":null,"topics":["audio","audio-analysis","audio-processing","audio-recorder","audio-streaming","calibration-tool","edge-computing","pubsub","python3","raspberry-pi","zmq-tcp"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/umik-base-app/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/danielfcollier.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-23T14:01:48.000Z","updated_at":"2026-05-17T22:49:31.000Z","dependencies_parsed_at":"2025-10-24T05:36:51.879Z","dependency_job_id":"7fbdb72b-e116-4a99-903c-28bc4500b9a3","html_url":"https://github.com/danielfcollier/py-umik-base-app","commit_stats":null,"previous_names":["danielfcollier/py-umik-base-app"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/danielfcollier/py-umik-base-app","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielfcollier%2Fpy-umik-base-app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielfcollier%2Fpy-umik-base-app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielfcollier%2Fpy-umik-base-app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielfcollier%2Fpy-umik-base-app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danielfcollier","download_url":"https://codeload.github.com/danielfcollier/py-umik-base-app/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielfcollier%2Fpy-umik-base-app/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33418555,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T22:14:44.296Z","status":"online","status_checked_at":"2026-05-24T02:00:06.296Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio","audio-analysis","audio-processing","audio-recorder","audio-streaming","calibration-tool","edge-computing","pubsub","python3","raspberry-pi","zmq-tcp"],"created_at":"2025-12-28T05:54:46.695Z","updated_at":"2026-05-24T02:07:31.218Z","avatar_url":"https://github.com/danielfcollier.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🎤 audio-tools — Audio Measurement CLI\n\n**A modular Python CLI for real-time audio measurement with USB microphones.**\n\nSupports UMIK-1, UMIK-2, Dayton UMM-6, Earthworks M23/M30, and other USB measurement mics.\nAuto-detects known devices, validates sample rate support, and applies per-unit calibration files.\n\n## 📦 Installation\n\n### APT — Linux *(Recommended for Raspberry Pi and Ubuntu)*\n\n```bash\ncurl -fsSL \"https://br-se1.magaluobjects.com/audio-tools/audio-tools/pubkey.gpg\" \\\n  | sudo gpg --dearmor -o /usr/share/keyrings/audio-tools.gpg\necho \"deb [signed-by=/usr/share/keyrings/audio-tools.gpg] https://br-se1.magaluobjects.com/audio-tools/audio-tools $(lsb_release -cs) main\" \\\n  | sudo tee /etc/apt/sources.list.d/audio-tools.list\nsudo apt-get update \u0026\u0026 sudo apt-get install audio-tools\n```\n\nSystem dependencies (`libportaudio2`, `libsndfile1`, `ffmpeg`, `libzmq3-dev`) are installed automatically.\n\n\u003e 🍓 **Raspberry Pi 4B verified.** Perfect headless acoustic monitoring box.\n\n### pip\n\n```bash\npip install umik-base-app\n```\n\nRequires system libraries:\n\n```bash\n# Linux (Debian/Ubuntu)\nsudo apt install libportaudio2 libsndfile1 ffmpeg libzmq3-dev -y\n\n# macOS\nbrew install portaudio libsndfile zeromq ffmpeg\n```\n\n\n## 🕹️ CLI Reference\n\n```\naudio-tools --\u003ccommand\u003e [options]\n```\n\n| Command | Description |\n|---------|-------------|\n| `audio-tools --devices` | 🔍 List available audio input devices |\n| `audio-tools --meter` | 📊 Real-time SPL / LUFS / dBFS meter |\n| `audio-tools --record` | 🎙️ Calibrated audio recorder (WAV) |\n| `audio-tools --calibrate` | 🔧 Generate FIR filter from a calibration file |\n| `audio-tools --analyze` | 🔬 Analyze a WAV file and export metrics to CSV |\n| `audio-tools --plot` | 📈 Plot a metrics CSV as a chart |\n| `audio-tools --batch` | 📁 Batch-analyze a directory of WAV files |\n| `audio-tools --enhance` | ✨ Filter and enhance voice audio |\n| `audio-tools --convert` | 🔄 Convert WAV recordings to OGG / MP3 / AAC |\n| `audio-tools-spectrum` | 🌐 Browser-based real-time spectrum analyzer |\n\nPass `--help` after any command for full options:\n\n```bash\naudio-tools --meter --help\naudio-tools --convert --help\n```\n\n## ⚡ Quick Start\n\n```bash\n# 1. Find your microphone's device ID\naudio-tools --devices\n\n# 2. Run the SPL meter (system default mic)\naudio-tools --meter\n\n# 3. Run with UMIK-1 calibration file\naudio-tools --meter --calibration-file \"umik-1/7175488.txt\"\n\n# 4. Record calibrated audio\naudio-tools --record --calibration-file \"umik-1/7175488.txt\" --output-dir recordings/\n```\n\n## 🏃 Run Modes\n\n### Monolithic *(Default)*\n\nSingle process — simplest for desktop and testing.\n\n```bash\naudio-tools --meter --calibration-file \"umik-1/7175488.txt\"\n```\n\n### 👹 Daemon Mode — Unstoppable Ear\n\nRun capture at high priority. Processing crashes never interrupt the audio stream.\n\n```bash\n# Terminal 1: high-priority capture process\nsudo nice -n -20 audio-tools --meter --producer \\\n  --calibration-file \"umik-1/7175488.txt\" --zmq-port 5555\n\n# Terminal 2: connect consumer (safe to open/close/crash)\naudio-tools --meter --consumer --zmq-host localhost --zmq-port 5555\n```\n\n### 🌐 Distributed Mode — Remote Sentry\n\nCapture on a Raspberry Pi, visualize on your laptop.\n\n```bash\n# On the Raspberry Pi\naudio-tools --meter --producer \\\n  --calibration-file \"umik-1/7175488.txt\" --zmq-port 5555\n\n# On your laptop\naudio-tools --meter --consumer --zmq-host 192.168.1.50 --zmq-port 5555\n```\n\n## 🎛️ Calibration Files\n\nDownload the per-unit calibration file for your UMIK from miniDSP.\n\n### Auto-discovery\n\nPlace the file in one of these locations and it will be picked up automatically\non the next run — no `--calibration-file` flag needed:\n\n| Location | Scope |\n|---|---|\n| `~/.config/audio-tools/` | Per-user |\n| `/etc/audio-tools/` | System-wide |\n\nIf multiple files are found, the app prompts you to select one interactively.\nIf a calibrated microphone is detected but no file is found, the app warns you\nand asks for confirmation before running uncalibrated.\n\n### Sample files (installed with the package)\n\nThe `.deb` package ships sample calibration files to:\n\n```\n/usr/share/audio-tools/calibration/\n```\n\nThese are **not** auto-discovered — they are reference copies only.\nTo activate one, copy it to an auto-discovery location:\n\n```bash\n# Per-user (recommended)\nmkdir -p ~/.config/audio-tools\ncp /usr/share/audio-tools/calibration/7175488_90deg.txt ~/.config/audio-tools/\n\n# Or system-wide\nsudo cp /usr/share/audio-tools/calibration/7175488_90deg.txt /etc/audio-tools/\n```\n\n### File layout\n\n```\numik-1/\n├── 7175488.txt           ← 0° on-axis. Use when pointing at a speaker.\n├── 7175488_90deg.txt     ← 90° ambient. Use when pointing at the ceiling.\n└── 7175488_fir_*.npy     ← [Generated] FIR filter cache (created on first run).\n```\n\nGenerate or verify the FIR filter cache:\n\n```bash\naudio-tools --calibrate \"umik-1/7175488.txt\"\n```\n\n\n## 🖥️ Real-Time Dashboard (TUI)\n\nAdd `--tui` to get a live terminal dashboard instead of scrolling log output:\n\n```bash\naudio-tools --meter --tui\naudio-tools --meter --tui --calibration-file \"umik-1/7175488.txt\"\n```\n\nBuilt with [Textual](https://textual.textualize.io/):\n\n```\n┌───────────────────────────────────────────────────────┐\n│  audio-tools --meter          Calibration: FULL (FIR) │\n├──────────────────────┬────────────────────────────────┤\n│  dBFS  ████████░░░░  │  dBSPL   72.4 dB               │\n│ -24.3  ████████░░░░  │  LUFS   -28.1 LUFS             │\n│        ████████░░░░  │  RMS     0.0241                │\n│                      │  Flux    38.6                  │\n├──────────────────────┴────────────────────────────────┤\n│  Mode: MONOLITHIC    SR: 48000 Hz   ● REC   [R] Stop  │\n└───────────────────────────────────────────────────────┘\n```\n\n| Key | Action |\n|-----|--------|\n| `R` | 🔴 Toggle recording on/off |\n| `Q` | ❌ Quit |\n\nPress **R** to start recording — audio is saved to `recordings/` as a timestamped WAV. Press **R** again to stop; a notification pops with the filename.\n\n\n## 🌐 Real-Time Spectrum Analyzer\n\n\u003cimg src=\"spectrum-analyzer.png\" width=\"700\" alt=\"Spectrum Analyzer UI\"\u003e\n\nA browser-based live spectrum analyzer for UMIK-1 and compatible USB measurement microphones. Opens a local web server and launches your browser automatically.\n\n### Quick Start\n\n```bash\n# 1. Find your microphone's device ID\naudio-tools --devices\n\n# 2. Launch (opens browser at http://localhost:8767)\naudio-tools-spectrum --device \u003cid\u003e\n\n# 3. With calibration file\naudio-tools-spectrum --device \u003cid\u003e --calibration-file \"umik-1/7175488.txt\"\n\n# 4. Custom port, suppress auto-open\naudio-tools-spectrum --device \u003cid\u003e --port 9000 --no-open\n```\n\n### Features\n\n| Feature | Description |\n|---|---|\n| **FFT plot** | 256 log-spaced bins (20 Hz – Nyquist), Hann window, configurable peak labels |\n| **Waterfall** | Scrolling spectrogram with time-zoom and time-range CSV export |\n| **Time-series graph** | Rolling 30 s dBSPL/dBFS and SNR; y-axis auto-scales on calibration load/clear |\n| **Noise floor** | 5-second quiet room baseline; per-bin SNR with OK / LOW / NOISE status |\n| **Calibration** | Load a UMIK-1 `.txt` calibration file directly from the browser toolbar |\n| **Device selector** | Switch microphone input from the toolbar without restarting |\n| **Recording** | WAV recording via the REC button; calibration is applied to the saved file |\n\n\u003e **Calibration note:** When a file is loaded the status bar switches to **dBSPL** and the time graph rescales to 20–120 dB. Switching devices automatically clears the loaded calibration.\n\n## 🔬 Analysis \u0026 Visualization\n\n```bash\n# Analyze one file → CSV\naudio-tools --analyze \"recording.wav\" --calibration-file \"umik-1/7175488.txt\"\n\n# Batch analyze a directory → CSV per file\naudio-tools --batch recordings/ --calibration-file \"umik-1/7175488.txt\"\n\n# View chart (popup window)\naudio-tools --plot \"recording_metrics.csv\"\n\n# Save chart to PNG\naudio-tools --plot \"recording_metrics.csv\" --save\n```\n\n## 🔄 Convert Audio\n\nConvert WAV recordings to share-friendly formats. Requires `ffmpeg`.\n\n```bash\n# OGG/Opus — smallest, WhatsApp-compatible\naudio-tools --convert recordings/ --format ogg\n\n# Multiple formats in one pass\naudio-tools --convert recordings/session.wav --format ogg mp3\n\n# Output to a different directory\naudio-tools --convert recordings/ --format ogg --out converted/\n\n# Overwrite existing files\naudio-tools --convert recordings/ --format ogg --overwrite\n```\n\n| Format | Use Case |\n|--------|----------|\n| `ogg` | 📱 WhatsApp voice notes (smallest) |\n| `mp3` | 🎵 Universal |\n| `aac` | 🍎 Apple-friendly (`.m4a`) |\n\n\n## 🔗 Related Projects\n\n**AI Acoustic Monitor** — adds ML sound classification (chainsaws, glass breaking, birds) on embedded devices, built on this framework:\n[py-edge-ai-acoustic-monitoring-app](https://github.com/danielfcollier/py-edge-ai-acoustic-monitoring-app)\n\n## 🛠️ For Developers\n\nBuilding a custom app on this framework? See [CONTRIBUTING.md](./CONTRIBUTING.md).\n\nFull technical documentation: [docs/](./docs/)\n- [Architecture](./docs/ARCHITECTURE.md) — Producer-Consumer design, pipeline internals\n- [Audio Metrics](./docs/METRICS.md) — RMS, LUFS, dBFS, dBSPL explained\n- [UMIK Series Guide](./docs/UMIK-Series.md) — Hardware-specific details\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanielfcollier%2Fpy-umik-base-app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanielfcollier%2Fpy-umik-base-app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanielfcollier%2Fpy-umik-base-app/lists"}