_________________________ ,, ___________________________________
      db                `7MM                                    
     ;MM:                 MM                                    
    ,V^MM.  `7MM  `7MM    MM `7M'   `MF'M"""MMV .gP"Ya `7Mb,od8 
   ,M  `MM    MM    MM    MM   VA   ,V  '  AMV ,M'   Yb  MM' "' 
   AbmmmqMA   MM    MM    MM    VA ,V     AMV  8M""""""  MM     
  A'     VML  MM    MM    MM     VVV     AMV  ,YM.    ,  MM     
.AMA.   .AMMA.`Mbod"YML..JMML.   ,V     AMMmmmM `Mbmmd'.JMML.   
______________________________  ,V _____________________________
                             OOb"                               
Aulyzer -- Scientific Audio Measurement Instrument          v1.1
(c)Alex Radzishevsky, 2026 - EOL                                
Web: Radzishevsky.com, AudioWatermarking.com, Sonoworx.com     
________________________________________________________________


/// Introduction into 'Aulyzer' -- Audio Analyzer

Aulyzer is a cross-platform, command-line tool for detailed audio analysis. It is designed for engineers, researchers, and audio professionals who need to perform precise, repeatable measurements on audio files, either individually or in comparison to a reference. Aulyzer is built for unattended operation and automation through scripting. 

/// Purpose

The primary purpose of Aulyzer is to provide a comprehensive suite of audio quality and characteristic metrics. It excels in two main scenarios:
1. Single-File Analysis: Extracting a wide range of metrics from a single audio file to assess its properties. This is useful for quality control, file validation, and general signal characterization.
2. Pairwise Comparison: Comparing one or more "probe" audio files against a "reference" file to quantify differences in level, time, and frequency domains. This is particularly useful for testing audio processing chains, evaluating codec quality, and ensuring signal integrity after any modification.

/// Key Features

* Comprehensive Measurements: Peak/true-peak (ISP), RMS, crest factor, DC offset, clipping statistics, activity analysis, bandwidth, spectral centroids, and more.
* Advanced Pairwise Comparison: Cross-correlation based lag detection, RMS and peak deltas, band-power differences, log-spectral distance, and frequency-response deviation metrics.
* Batch Processing: Feed one reference and many probes in a single command; each probe gets its own console and JSON report plus optional exports.
* Fragment Analysis: Target specific time ranges from each file without modifying the sources.
* Configurable Limits & Alerts: Attach min/max/delta constraints to nearly every measurement; out-of-range values are flagged in reports for automated QC pipelines.
* Optional Processing Steps: Controlled resampling, dithering, band-pass preparation, lag compensation, and compensated audio renders for deeper investigations.
* Extensive Parameter System: Every measurement, limit, action, and formatting option is addressable through `key=value` arguments. Run `aulyzer --list-params` to browse defaults.
* Flexible Reporting:
    - Console Output: Human-readable blocks with optional long descriptions or alert-only filtering.
    - JSON Export: Every run produces machine-readable JSON files under the report directory for downstream tooling.
* Visualization Outputs: Generates Gnuplot scripts and PNGs for waveform and spectrogram views with customizable palettes, fonts, and dimensions.
* Cross-Platform: Works in Windows and Linux.

/// Measurement Categories

Single-file metrics:
    - Duration & detected sample rate / bit depth (nominal and inferred true bit depth).
    - Peak and true-peak level with timestamps, RMS window statistics (peak/mean/min/total).
    - Crest-factor trace, frame power, spectral centroid, DC offset, clipping percentage, event counts, and click detection via abs-delta PCM.
    - Activity timing and bandwidth estimation when enabled.

Pairwise metrics:
    - Lag detection via cross-correlation with optional automatic compensation.
    - RMS difference vectors (abs/peak/mean/min/total) with optional level compensation.
    - Band-power deltas, log-spectral distance, per-band frequency-response deviation, and configurable export of aligned or EQ-adjusted probe WAVs.

Optional actions & exports:
    - Controlled resampling (`analysis.fft_size_pts`, `action.resample.*`, `pairwise.action.resample.*`).
    - Dither injection for single-file and pairwise flows (`action.dither.*`, `pairwise.action.dither.*`).
    - Waveform and spectrogram PNG creation with full styling control (by means of gnuplot script generation).
    - Intermediate audio renders: aligned probe/reference, frequency-response compensated probe, and filtered variants when requested.

/// Outputs & Artifacts

* Console report summarizing the reference, each probe, and pairwise comparison sections.
* JSON reports stored in `report_dir` (default `res/`) for the reference and every probe comparison.
* Optional PNG images and WAV intermediates placed in `report_dir` mirroring the analyzed filenames.
* Alerts clearly flagged when any measurement violates configured limits (`*.min`, `*.max`, `*.delta_*`).

/// Supported Formats & Requirements

* Input format: mono PCM WAV files using one of the supported sample rates (2 kHz - 192 kHz).
* Fragment notation: wrap file name and optional start/stop seconds in braces {"file.wav",start,stop}.
* Multichannel files must be pre-converted to mono before analysis.

/// Command-Line Syntax

The basic command format is:
    aulyzer <reference_file> [probe_file(s)...] [parameter=value ...]

* <reference_file>: Mandatory. Supports plain paths or fragment notation.
* [probe_file(s)]: Optional list. Each probe is analyzed individually and compared to the reference.
* [parameter=value]: Optional overrides. Parameters are evaluated in order so later entries replace earlier ones.

* Quote arguments containing spaces or braces when required by your shell (e.g., "{file.wav,0,5}").
Common global flags:
    - `--no_splash`      : Skip the startup banner.
    - `--list-params`    : Print the categorized parameter catalog and exit.

Key parameter groups (browse with `aulyzer --list-params`):
    - `analysis.*`       : FFT size, hop percentage, resampling target.
    - `measure.*`        : Enable/disable specific measurements (RMS, crest, activity, etc.).
    - `action.*`         : Single-file exports (waveform/spectrogram/dither/resample settings).
    - `pairwise.action.*`: Probe processing (resample, band-pass, lag compensation, dither, exports).
    - `report.display.*` : Console formatting options (alerts-only mode, column width, vector truncation).
    - `report.json.*`    : JSON formatting controls (delimiters, long descriptions).
    - `precision.*`      : Numerical rounding/precision of various units.
    - Measurement families (e.g., `duration.*`, `peak.*`, `rms.*`, `crest_factor.*`) accept `.min`, `.max`, `.delta_min`, `.delta_max` suffixes.

/// Usage Examples

1. Analyze a single file with default settings:
   aulyzer track.wav

2. Compare a probe file to a reference file:
   aulyzer reference.wav probe.wav

3. Compare multiple probe files to a single reference:
   aulyzer reference.wav probe1.wav probe2.wav

4. Analyze a specific 5-second segment of a file (from 10.5s to 15s), with no image or waveform saves:
   aulyzer {my_file.wav,10.5,15} action.waveform.save.do=false action.spectrogram.save.do=false

5. Compare a fragment of a probe to a fragment of a reference:
   aulyzer {ref.wav,5,10} {probe.wav,5.1,10.1}

6. Change the output directory and disable RMS measurement:
   aulyzer song.wav report.dir=my_reports rms.do=false

7. Enable spectrogram saving with custom colors and size:
   aulyzer song.wav action.spectrogram.save.do=true action.spectrogram.save.width_px=1024 action.spectrogram.save.height_px=768 action.spectrogram.save.color.palette=viridis

8. Tighten peak limits and enforce alert highlighting only:
   aulyzer mix.wav peak.min=-3 peak.max=-0.1 report.display.alerts_only=true

9. Run a pairwise comparison but disable lag compensation:
   aulyzer ref.wav probe.wav pairwise.action.lag.compensation.do=false

10. A complex command showing multiple settings:
    aulyzer ref.wav probe.wav report.display.alerts_only=true analysis.fft_size_pts=2048 amplitude.clipping.threshold_dbfs=-0.1

/// Workflow Tips

* Start with default limits, then tighten individual `.min/.max/.delta_*` thresholds (or `cfg.pairwise.*`) to match your acceptance criteria.
* Use `report.display.alerts_only=true` for automated pipelines where only failures matter.
* Enable `pairwise.action.save_aligned_audio.do=true` to audit synchronization or codec-induced drift directly in the exported WAVs.
* Adjust `precision.*` values when preparing publishable reports that require specific decimal formatting.
* All parameter overrides are persisted only for the current run; create wrapper scripts or .bat files for repeatable batches.

/// Listing All Parameters

To see a complete, categorized list of all configurable parameters, their descriptions, and default values, run:
   aulyzer --list-params
Add --no_splash to skip the splash screen.

/// Disclaimer & License

This tool is provided "as is", without warranties of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.

