Reproducible audio experimentation and versioned DSP workflow engineering in Java.
Audio Analyzer combines a desktop signal workbench with a collaborative browser-based workflow workbench. It is intended for people who want to inspect audio, compare processing results, build repeatable experiments or collaborate on a signal-processing graph while retaining deterministic Java models, semantic operations and auditable history.
The project provides stable DSP and measurement foundations, recording and replay, evidence export, server-authoritative workflow collaboration and an experimental acoustic-localization plugin. It is a research and engineering workbench—not a validated species detector, safety system or turnkey digital audio workstation.
Project status: Active development. Signal analysis, recording/replay, deterministic workflow models, collaboration and versioned checkpoints form the stable platform. Acoustic localization remains explicitly experimental and requires measured geometry, hardware calibration and validation before real-world use.
Many audio tools can visualize signals or execute processing chains. Audio Analyzer also treats the experiment and processing graph as reproducible engineering artifacts: inputs, workflow topology, accepted edits, checkpoints, recordings and evidence can be inspected, replayed, compared and audited.
The desktop and web workbenches share deterministic Java domain models rather than maintaining separate browser-local truths. This connects immediate signal inspection with collaborative workflow engineering and semantic version history.
| Goal | Current support |
|---|---|
| Reproduce an experiment | Deterministic demo sources, recording/replay, A/B reports and versioned workflow checkpoints |
| Build a workflow visually | Typed React Flow nodes and ports backed by immutable Java workflow models |
| Collaborate on a workflow | Shared sessions, ordered SSE updates, presence, revision conflicts and canonical reload |
| Undo safely | Personal or explicit shared semantic undo/redo with previews, blockers and durable history |
| Merge workflow versions | Exact base/local/remote checkpoints, typed conflicts and validated merge commits |
| Inspect a signal | Waveform, phase, spectrum, spectrogram, RMS/peak measurements and diagnostic findings |
| Preserve evidence | .aar recordings, CSV/PNG exports, evidence bundles and versioned workflow checkpoints |
| Explore localization research | Simulated microphone arrays, TDOA, beamforming, tracking and HumBugDB-oriented experiments |
Use the Swing application when the signal itself is the focus: live or deterministic input, waveform and spectrum inspection, recording, replay and evidence export.
Use the packaged web application when the processing graph, collaboration or version history is the focus. The browser is a rendering and input client; accepted workflow state remains server-owned.
The web workbench supports three immutable collaboration modes:
- Private workspace — one actor with personal undo and redo.
- Shared session with personal undo — everyone sees accepted changes, while an actor can undo only their own current operation.
- Shared session with shared undo — an explicitly selected shared operation can be undone only after a fresh server preview and confirmation.
See Collaborative workflows for the user workflow and generated screenshots.
Requirements:
- Java 21 or newer;
- the included Maven Wrapper;
- Docker only for optional Testcontainers/Playwright integration scenarios.
Build the project:
./mvnw clean packageRun the desktop workbench:
DESKTOP_JAR=$(find audio-app/target -maxdepth 1 -type f \
-name 'audio-app-*.jar' ! -name '*-workbench.jar' -print -quit)
java -jar "$DESKTOP_JAR"Run the web workflow workbench:
java -jar audio-app/target/audio-app-*-workbench.jarThen open the local URL printed by the application. The initial graph is a read-only orientation example; create or join a collaboration session before editing.
Windows users should use mvnw.cmd and launch the unclassified audio-app-<version>.jar for the desktop or the audio-app-<version>-workbench.jar for the web application.
For a guided first experiment, continue with Getting started.
A useful introduction requires no microphone:
- Start the desktop application with its deterministic demo source.
- Inspect the repeating waveform and its dominant spectral peak.
- Enable averaging or peak hold to compare steady and transient behavior.
- Record a short
.aarsession and replay it through the same analysis path. - Start the web workbench and create a workflow session.
- Add a signal generator and a gain stage.
- Open the semantic history preview before undoing the latest operation.
This path demonstrates the central design goal: the same project supports immediate signal inspection and reproducible, version-aware workflow engineering.
Workflow edits are typed operations such as creating a node, connecting ports or changing a property. The server validates the actor, collaboration mode and expected revision before appending a new canonical operation.
Undo and redo are also new audited semantic operations. They do not erase accepted history, rewrite Git commits or depend on a browser-local/Yjs undo stack. A full reload obtains the graph and current undo/redo capabilities from the server.
The production-packaged client is exercised with two isolated Chromium contexts. The test proves live convergence, stale-revision rejection, presence separation, reconnect/replay, full reload and personal/shared undo/redo without fixed-delay sleeps.
- immutable audio blocks, format descriptors and deterministic generators;
- bounded buffering and reproducible DSP pipelines;
- sample decoding, FFT, spectrum, spectrogram and measurement snapshots;
- microphone-array calibration profiles with explicit timing offsets, drift and error budgets;
- recording/replay and evidence-oriented exports;
- immutable workflow models and deterministic serialization;
- packaged React Flow client with server-authoritative collaboration;
- semantic checkpoint comparison and validated three-way merge;
- Hibernate-backed session history, transactional outbox and migration validation;
- JGit-backed workflow checkpoints through the shared storage library;
- architecture tests, static analysis, coverage, CodeQL and reproducible screenshots.
The acoustic-localization plugin contains research-grade simulation, calibration-event estimation, TDOA correction, beamforming, tracking, wingbeat features and dataset-oriented classification baselines. It exposes synchronization mode, trust status and timing-error evidence in snapshots and exports. Real microphone-array localization still requires measured geometry and validated calibration; automatic beacon detection, cycle-slip repair and continuous resampling are not claimed.
The project deliberately keeps experimental claims separate from stable platform guarantees.
Start with the task that matches your goal:
- Documentation home — guides organized for users, researchers, operators and contributors.
- Getting started — build, launch and first signal/workflow experiment.
- Feature guides — signal inspection, recording, comparison and collaborative workflows.
- Collaborative workflows — sessions, revision safety and semantic undo/redo.
- Semantic workflow merge — exact checkpoints, conflict types, resolution and audit guarantees.
- Experimental acoustic localization — capabilities, evidence and limitations.
- Architecture — audio, workflow, collaboration, persistence and module boundaries.
- Persistent workbench operation — Hibernate/JGit mode, migrations and outbox operation.
- Development — build, tests, quality gates and generated documentation.
- Plugin development — stable API, ServiceLoader registration and contribution design.
- Roadmap — current open product and research work.
audio-core immutable audio and workflow domain contracts
audio-geometry reusable 2D geometry and localization constraints
audio-acquisition microphone metadata, arrays, sources and calibration evidence
audio-dsp decoding, DSP, analysis, diagnosis and recording
audio-plugin-api stable host-facing plugin contracts
audio-experimental-acoustic optional localization and dataset research plugin
audio-web-editor React Flow source and reproducible production assets
audio-app Swing UI, Spring Boot workbench, persistence and plugin host
The optional workbench-screenshot-tests profile exercises the packaged application with Testcontainers and Java Playwright. It is not part of the default Docker-free Maven reactor.
Before a contribution is merged, the repository expects:
./mvnw clean verifyThis includes tests, formatting, architecture checks, coverage and static analysis. Browser collaboration and documentation screenshots use dedicated opt-in workflows because they require Docker and Chromium.
Generated screenshots are executable documentation: the integration test creates the documented state, asserts its semantics and only then captures the image. Hand-edited screenshots are not treated as equivalent evidence.
Releases are archived through Zenodo. Use the DOI badge above for the current citation record.
Audio Analyzer is licensed under the MIT License.