Windows_Audio_Recorder/VERSION.md

VERSION.md — Audio Recorder Changelog

---

v1.5.0 — MP3 Recording Support

Files changed: audio_recorder_server.py, BUILD.bat, AudioRecorder.spec

Added

• MP3 output format using lameenc (pure-Python LAME wrapper, no external DLL)
  • Encodes at 192 kbps, quality=2 (high)
  • ~1.4 MB/min vs ~10 MB/min for WAV — approximately 7× smaller
  • Float32 PCM captured by sounddevice is converted to int16 before encoding
• Format size hints in Settings tab — selecting a format shows approximate MB/min (WAV ~10, FLAC ~5, OGG ~1.5, MP3 ~1.4)
• MP3 availability flag — if lameenc is not installed, the MP3 option is shown as disabled with a pip install lameenc hint rather than crashing
• lameenc added to BUILD.bat install step and AudioRecorder.spec hiddenimports

Format comparison

Format	Quality	~Size/min	Notes
WAV	Lossless	10 MB	Best for editing
FLAC	Lossless compressed	5 MB	Good archive format
OGG	Lossy	1.5 MB	Open format
MP3	Lossy 192kbps	1.4 MB	Most compatible

---

v1.4.0 — Remote Audio Visualiser + LCD Level Bar

Files changed: audio_recorder_server.py, AudioRecorderController.ino

Added

• Server-side RMS level meter computed in _audio_callback on every audio block
  • Log scale conversion: −60 dB floor → 0.0, 0 dB → 1.0
  • Peak hold: snaps up instantly, decays at ~0.012 per callback (~10 dB/s)
• /api/level endpoint — lightweight JSON poll {level, peak, state}
  • Returns in <1ms, suitable for 80–120ms polling intervals
• Dual-mode web visualiser
  • localhost → getUserMedia + Web Audio API (real frequency spectrum, 60fps)
  • Remote devices → polls /api/level every 80ms (works on all browsers/devices)
  • Automatic detection via location.hostname === 'localhost'
  • If getUserMedia is denied on localhost, falls back to server-side poll
  • Bar spread algorithm distributes single RMS value across 24 bars with centre-weighted falloff and per-bar smoothing (fast attack, slow decay)
• LCD signal bar on ESP32 (row 1 during recording)
  • 7 custom LCD characters loaded at boot: empty, 5 partial-fill levels, peak marker
  • 16 chars × 5 pixel columns = 80 pixel positions of resolution
  • Level polled from /api/level every 120ms with short 500ms HTTP timeout
  • Smoothing: attack ×0.6, decay ×0.9; peak hold with 0.03 drift-down per poll
  • Row 0 shows * REC HH:MM:SS simultaneously

Why getUserMedia fails on remote devices

Browsers enforce a security policy that blocks microphone access (getUserMedia) on non-secure origins. HTTP connections only qualify as secure if the hostname is localhost or 127.0.0.1. Any other host — including a LAN IP like 192.168.1.x — is treated as insecure, and mic access is denied regardless of user permissions. The server-side /api/level approach works everywhere.

---

v1.3.0 — File Rename + Improved Filename Format

Files changed: audio_recorder_server.py

Added

• POST /api/rename endpoint — renames a recording file
  • Validates: no path separators, no .., no overwriting existing files
  • Preserves the original file extension automatically
• Rename modal in Files tab — ✏️ button per file opens an inline modal
  • Current stem pre-filled and selected for easy overtyping
  • Enter key submits, Escape cancels, clicking outside modal closes it
  • File list refreshes from server after successful rename

Changed

• Default filename format changed from rec_YYYY-MM-DD_HH-MM-SS.ext to YYYYMMDD_DAY_HHMM.ext (e.g. 20260304_TUE_0947.wav)
  • Sorts correctly in file explorers
  • Human-readable day name
  • Shorter and cleaner

---

v1.2.0 — Settings Page + Device Selection

Files changed: audio_recorder_server.py

Added

• Settings tab in web UI with:
  • Input device dropdown (populated live from /api/devices)
  • Channels selector (Mono / Stereo)
  • Sample rate selector (22050 / 44100 / 48000 Hz)
  • File format selector (WAV / FLAC / OGG)
  • "Apply Settings" button — takes effect immediately without restart
  • Stereo Mix tip explaining how to capture system audio in Windows
• POST /api/setdevice — sets device + channels + samplerate + format atomically
• /api/devices — returns device list with resolved_rate and resolved_ch so the UI can pre-select the best supported settings
• device_name field added to /api/status response
• Active device name shown on Recorder tab below the control buttons

Fixed

• PortAudio error -9996 (Invalid device) — added resolve_device_settings() which probes the device's actual capabilities before opening the stream
  • Queries max_input_channels and default_samplerate from sounddevice
  • Clamps channel count to device maximum
  • Tries sample rates in order: requested → device native → 48000 → 44100 → 22050 → 16000
  • Uses sd.check_input_settings() to validate each candidate before committing
  • Actual rate and channels stored as _actual_rate, _actual_ch on the recorder instance and used for encoding (prevents corrupt WAV headers)

Web UI

• Converted to three-tab layout: Recorder | Files | Settings
• Files tab includes download links for all recordings
• 24-bar audio visualiser added to Recorder tab (Web Audio API / getUserMedia)

---

v1.1.0 — Stable EXE Launcher + Internal Server Error Fix

Files changed: src/launcher.py, audio_recorder_server.py, AudioRecorder.spec

Fixed (critical)

• Infinite EXE spawn loop crashing Windows
  • Root cause: subprocess.Popen in a frozen PyInstaller app re-executes the EXE entry point, spawning endless launcher copies
  • Fix 1: multiprocessing.freeze_support() as absolute first line of launcher
  • Fix 2: Server now runs as threading.Thread — no subprocess spawning at all
  • Fix 3: Flask runs with use_reloader=False — prevents Flask's file-watcher from spawning its own child process
• _tkinter ModuleNotFoundError
  • tkinter does not bundle reliably with PyInstaller on Python 3.14
  • Replaced entire launcher GUI with pystray system tray icon + PIL for the icon image. No window, no tkinter dependency.
• audio_recorder_server.py not found (Missing File dialog)
  • sys._MEIPASS path was being set after the path variable was evaluated
  • Fix: path resolution moved to module top level before any imports
  • BUNDLE_DIR = sys._MEIPASS (bundled read-only files in temp dir)
  • BASE_DIR = Path(sys.executable).parent (writable dir next to EXE)
• Internal Server Error (500) on web UI
  • Jinja2 template engine interpreted CSS/JS curly braces (e.g. {display:flex}) as template variables and raised UndefinedError
  • Fix: removed render_template_string() entirely. HTML returned as: return html, 200, {"Content-Type": "text/html; charset=utf-8"}
  • build_ui_html() builds HTML via Python string concatenation (no triple-quotes to avoid any risk of template engine involvement)
• ValueError: signal only works in main thread
  • signal.signal() calls were at module top level in audio_recorder_server.py
  • When launcher imports the module from a background thread, these execute immediately and crash
  • Fix: moved both signal.signal() calls inside if __name__ == "__main__":

Added

• Full startup logging to recorder_launcher.log next to the EXE
  • Logs Python version, frozen state, BUNDLE_DIR, BASE_DIR, sys.path
  • Lists relevant files found in BUNDLE_DIR
  • Captures full traceback if server thread raises an exception
  • Accessible via tray menu → "Show Log"
• Tray icon with right-click menu: Open Web UI, Start, Pause/Resume, Stop, Save, Show Log, Quit
• Tray tooltip updates every 3 seconds showing state + elapsed time + LAN IP
• Error dialog on startup failure shows full Python traceback (not just "server failed to start") using ctypes.windll.user32.MessageBoxW (no tkinter)

---

v1.0.1 — PyInstaller Path Fix

Files changed: AudioRecorder.spec, BUILD.bat

Fixed

• ERROR: script not found during PyInstaller build
  • AudioRecorder.spec used os.path.dirname(SPECPATH) which went one directory up from the spec file instead of using the spec file's own directory
  • Fix: SRC_DIR = os.path.join(SPECPATH, 'src') — SPECPATH is already the correct directory
• BUILD.bat added cd /d "%~dp0" as first command to ensure it always runs from its own directory regardless of where it is launched from
• BUILD.bat now passes full absolute path to PyInstaller: pyinstaller "%~dp0AudioRecorder.spec" instead of bare AudioRecorder.spec

---

v1.0.0 — Initial Release

Files: audio_recorder_server.py, src/launcher.py, AudioRecorderController.ino, AudioRecorder.spec, BUILD.bat

Server (audio_recorder_server.py)

• Flask HTTP server on port 5000 (configurable)
• Real-time audio capture via sounddevice with float32 PCM buffering
• Encoding via soundfile — WAV (PCM_16), FLAC (PCM_16), OGG (Vorbis)
• RecorderState machine: IDLE → RECORDING → PAUSED → SAVING
• Thread-safe audio callback with threading.Lock
• Elapsed time tracking with pause accumulation
• Auto-timestamped filenames
• File listing with size and modification date
• Recordings served for download via /recordings/<filename>
• Startup info printed to console with local IP address
• --list-devices flag to enumerate audio inputs

Launcher (src/launcher.py)

• System tray icon with recording controls
• Server started as background thread
• wait_for_server() polls /api/status up to 12 seconds
• Auto-opens browser on startup (configurable)
• Graceful shutdown: saves active recording before exit
• recorder_config.json persisted next to EXE

Arduino (AudioRecorderController.ino)

• ESP32-S3 with LCD Keypad Shield LCD1602
• Resistor-ladder button reading on ADC pin (SELECT/LEFT/DOWN/RIGHT/UP)
• WiFi connection with NVS-persisted credentials
• Config portal (AP mode) on first boot
• HTTP GET commands forwarded to PC server
• Status polling every 6 seconds
• Elapsed timer displayed on LCD row 0
• Web UI hosted on ESP32 — forwards commands to PC server
• Settings page (WiFi SSID, PC IP, PC port) with reboot-to-apply

Build system

• Single-file EXE via PyInstaller (console=False, upx=False)
• BUILD.bat installs all dependencies and builds in one step
• debug_test.py diagnostic tool for troubleshooting without building EXE

---

Dependency Versions (as tested)

Package	Version	Purpose
Python	3.14.2	Runtime
Flask	3.x	HTTP server
sounddevice	0.4.x	Audio capture
soundfile	0.12.x	WAV/FLAC/OGG encoding
numpy	1.x+	Audio data processing
Pillow	10.x	Tray icon rendering
pystray	0.19.x	System tray
lameenc	1.x	MP3 encoding
PyInstaller	6.19.0	EXE bundling
ArduinoJson	7.x	ESP32 JSON parsing