Skip to content

How To Use the Audio Analysis Toolkit

Jump to bottom
Maxnor899 edited this page Jan 20, 2026 · 14 revisions

This document provides a practical, end‑to‑end guide to using the toolkit: from configuration to execution and result inspection.

It complements:

  • Adding a New Analysis
  • Adding Visualizations

and focuses on how to operate the system, not how to extend it.

High‑Level Workflow

Input Audio
   ↓
YAML Configuration
   ↓
Runner Execution
   ↓
Analyses
   ↓
Results (JSON)
   ↓
Optional Visualizations

Step 1 — Prepare the Input Audio

The toolkit expects:

  • one or more audio files,
  • readable by the underlying audio backend,
  • mono or multi‑channel (handled transparently).

No preprocessing (resampling, channel folding, normalization) is assumed unless explicitly configured.

for demonstration purposes put your audio file in : small-audio-toolkit\Analysis_Workspace\04_input_sounds or use the provided one small-audio-toolkit\Analysis_Workspace\04_input_sounds\sound.wav

Step 2 — Configure or select the protocol (YAML)

The YAML protocol defines what is executed.

please, please, please read : the protocol doc to understand how important it is

and also, if you dare, the protocol schema description

Typical structure:

analyses:
  spectral:
    enabled: true
    methods:
      - name: "fft"
        params:
          window: hann
          n_fft: 4096

  time_frequency:
    enabled: true
    methods:
      - name: "stft"
        params:
          hop_length: 512

Rules:

  • disabled categories are skipped entirely,
  • parameters override method defaults,
  • execution order follows the configuration order.

for demonstration purposes, we will use an existing one named "protocol_baseline_full.yaml" file in : small-audio-toolkit\Analysis_Workspace\01_protocols\01_Baseline

but you could have edited your own one, and in this case, the good location should be small-audio-toolkit\Analysis_Workspace\01_protocols\02_Focused\your_protocol.yaml

Optional Step 3 — Configure Visualization (in the protocol)

Visualization is globally controlled via the protocol in this paragraph:

visualization:
  enabled: true
  formats: [png]
  dpi: 150
  figsize: [10, 4]

If disabled:

  • analyses still compute visualization_data,
  • no figures are generated.

Step 4 — define the result output folder

for demonstration purposes use this output folder : small-audio-toolkit\Analysis_Workspace\05_results\test1

Step 5 — Run the Pipeline

Execution is handled by the runner:

  • loads protocol,
  • builds the execution context,
  • dispatches analyses via the registry,
  • collects results,
  • optionally triggers visualization.

The runner performs no analysis logic.

in a CMD window , go to your_path\small-audio-toolkit
use the following command : python 01_run_analysis.py Analysis_Workspace\04_input_sounds\sound.wav --config Analysis_Workspace\01_protocols\01_Baseline\protocol_baseline_full.yaml --output Analysis_Workspace\05_results\test1 and let the process run.

Step 6 — Inspect Results

JSON Results

All outputs are exported as structured JSON:

  • one entry per analysis method,
  • raw measurements preserved,
  • metrics and optional anomaly scores included.

The JSON is the primary, authoritative output.

in this demonstration contextt the results will be located in : small-audio-toolkit\Analysis_Workspace\05_results\test1

About Visual Outputs (If Enabled)

Generated plots:

  • are strictly descriptive,
  • never influence results,
  • are reproducible from the JSON data.

Directory layout typically follows:

output/
 ├─ results.json
 └─ visualizations/
     ├─ image1.png
     └─ ImageN.png

Common Usage Patterns

Run Without Visualization

Use this mode for:

  • batch processing,
  • statistical post‑analysis,
  • automated pipelines.

Run With Visualization

Use this mode for:

  • exploratory analysis,
  • sanity checks,
  • reporting and documentation.

Design Constraints to Keep in Mind

  • analyses never depend on visualizations,
  • visualizations never recompute data,
  • the runner only orchestrates,
  • interpretation is always external to the toolkit.

Troubleshooting Checklist

  • analysis not executed → check registry + YAML name
  • empty plots → verify visualization_data
  • missing channels → inspect context.audio_data
  • inconsistent results → confirm parameters and defaults

Summary

Task Responsibility
Define what runs YAML protocol
Compute data Analyses
Orchestrate Runner
Store results JSON export
Display data Visualization layer

This guide describes the correct way to use the toolkit, while keeping its architectural guarantees intact.

Clone this wiki locally