# aronjohn20/acoustic-localization architecture

> Architecture diagram of the GitHub repository aronjohn20/acoustic-localization, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aronjohn20/acoustic-localization
- Repository: https://github.com/aronjohn20/acoustic-localization

## Overview

This is a simulated acoustic-surveillance application: it generates multichannel room audio, detects sound events, localizes qualifying events, and can display and report session results. The principal runtime flow is owned by `stream/pipeline.py`, which consumes generated chunks, runs SED, conditionally computes GCC-PHAT features and runs DOA, then optionally sends results to the dashboard. Training and dataset-generation capabilities are included as separate branches. Some subsystem links rely on README or source-index references because those implementation files were not excerpted.

Main entry points: [`stream/pipeline.py`](https://github.com/aronjohn20/acoustic-localization/blob/main/stream/pipeline.py) (Inference orchestrator), [`stream/generator.py`](https://github.com/aronjohn20/acoustic-localization/blob/main/stream/generator.py) (Room stream generator), [`web_visualization/dashboard.py`](https://github.com/aronjohn20/acoustic-localization/blob/main/web_visualization/dashboard.py) (Live dashboard), [`doa/training_pipeline/train.py`](https://github.com/aronjohn20/acoustic-localization/blob/main/doa/training_pipeline/train.py) (DOA model training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_simulation["Audio simulation"]
  node_config["System configuration<br/>[config.py]"]
  node_generator["Room stream generator<br/>[generator.py]"]
end

subgraph group_inference["Detection and localization"]
  node_pipeline["Inference orchestrator<br/>[pipeline.py]"]
  node_sed_api["SED predictor<br/>[api.py]"]
  node_sed_model["CNN14 model<br/>[main.py]"]
  node_doa_api["DOA predictor<br/>[api.py]"]
  node_doa_model["SSL localization model<br/>[main.py]"]
  node_dsp["Signal processing<br/>[main.py]"]
end

subgraph group_training["Model training"]
  node_doa_data["DOA data generation<br/>[generate_data.py]"]
  node_doa_train_config["DOA training settings<br/>[train_config.py]"]
  node_doa_train["DOA model training<br/>[train.py]"]
  node_sed_dataset["SED dataset<br/>[dataset.py]"]
  node_sed_train["SED model training<br/>[train.py]"]
end

subgraph group_visualization["Visualization and reporting"]
  node_dashboard["Live dashboard<br/>[dashboard.py]"]
  node_server["Flask Socket.IO server<br/>[server.py]"]
  node_client["Browser visualization<br/>[app.js]"]
  node_report["Session report<br/>[report.py]"]
end

node_operator(("Operator"))

node_operator -->|"starts"| node_pipeline
node_pipeline -->|"starts generator"| node_generator
node_generator -->|"queues audio chunks"| node_pipeline
node_generator -->|"reads settings"| node_config
node_generator -->|"uses coordinates"| node_dsp
node_pipeline -->|"reads thresholds"| node_config
node_pipeline -->|"runs detection"| node_sed_api
node_sed_api -->|"runs model"| node_sed_model
node_pipeline -->|"computes GCC-PHAT"| node_dsp
node_pipeline -->|"runs localization"| node_doa_api
node_doa_api -->|"runs model"| node_doa_model
node_pipeline -->|"forwards results"| node_dashboard
node_dashboard -->|"posts updates"| node_server
node_dashboard -->|"generates report"| node_report
node_server -->|"broadcasts events"| node_client
node_doa_data -->|"uses settings"| node_doa_train_config
node_doa_train -->|"reads settings"| node_doa_train_config
node_doa_train -->|"trains model"| node_doa_model
node_sed_train -->|"loads dataset"| node_sed_dataset
node_sed_train -->|"trains model"| node_sed_model

click node_config "https://github.com/aronjohn20/acoustic-localization/blob/main/config.py"
click node_generator "https://github.com/aronjohn20/acoustic-localization/blob/main/stream/generator.py"
click node_pipeline "https://github.com/aronjohn20/acoustic-localization/blob/main/stream/pipeline.py"
click node_sed_api "https://github.com/aronjohn20/acoustic-localization/blob/main/sed/api.py"
click node_sed_model "https://github.com/aronjohn20/acoustic-localization/blob/main/sed/model/main.py"
click node_doa_api "https://github.com/aronjohn20/acoustic-localization/blob/main/doa/api.py"
click node_doa_model "https://github.com/aronjohn20/acoustic-localization/blob/main/doa/model/main.py"
click node_dsp "https://github.com/aronjohn20/acoustic-localization/blob/main/dsp/main.py"
click node_doa_data "https://github.com/aronjohn20/acoustic-localization/blob/main/doa/training_pipeline/data_gen/generate_data.py"
click node_doa_train_config "https://github.com/aronjohn20/acoustic-localization/blob/main/doa/training_pipeline/train_config.py"
click node_doa_train "https://github.com/aronjohn20/acoustic-localization/blob/main/doa/training_pipeline/train.py"
click node_sed_dataset "https://github.com/aronjohn20/acoustic-localization/blob/main/sed/training_pipeline/dataset.py"
click node_sed_train "https://github.com/aronjohn20/acoustic-localization/blob/main/sed/training_pipeline/train.py"
click node_dashboard "https://github.com/aronjohn20/acoustic-localization/blob/main/web_visualization/dashboard.py"
click node_server "https://github.com/aronjohn20/acoustic-localization/blob/main/web_visualization/server.py"
click node_client "https://github.com/aronjohn20/acoustic-localization/blob/main/web_visualization/static/js/app.js"
click node_report "https://github.com/aronjohn20/acoustic-localization/blob/main/web_visualization/report.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_config,node_generator toneBlue
class node_pipeline,node_sed_api,node_sed_model,node_doa_api,node_doa_model,node_dsp toneAmber
class node_doa_data,node_doa_train_config,node_doa_train,node_sed_dataset,node_sed_train toneMint
class node_dashboard,node_server,node_client,node_report toneRose
class node_operator toneIndigo
```

## Components

### Audio simulation

- [System configuration](https://github.com/aronjohn20/acoustic-localization/blob/main/config.py): `config.py`
- [Room stream generator](https://github.com/aronjohn20/acoustic-localization/blob/main/stream/generator.py): `stream/generator.py`

### Detection and localization

- [Inference orchestrator](https://github.com/aronjohn20/acoustic-localization/blob/main/stream/pipeline.py): `stream/pipeline.py`
- [SED predictor](https://github.com/aronjohn20/acoustic-localization/blob/main/sed/api.py): `sed/api.py`
- [CNN14 model](https://github.com/aronjohn20/acoustic-localization/blob/main/sed/model/main.py): `sed/model/main.py`
- [DOA predictor](https://github.com/aronjohn20/acoustic-localization/blob/main/doa/api.py): `doa/api.py`
- [SSL localization model](https://github.com/aronjohn20/acoustic-localization/blob/main/doa/model/main.py): `doa/model/main.py`
- [Signal processing](https://github.com/aronjohn20/acoustic-localization/blob/main/dsp/main.py): `dsp/main.py`

### Model training

- [DOA data generation](https://github.com/aronjohn20/acoustic-localization/blob/main/doa/training_pipeline/data_gen/generate_data.py): `doa/training_pipeline/data_gen/generate_data.py`
- [DOA training settings](https://github.com/aronjohn20/acoustic-localization/blob/main/doa/training_pipeline/train_config.py): `doa/training_pipeline/train_config.py`
- [DOA model training](https://github.com/aronjohn20/acoustic-localization/blob/main/doa/training_pipeline/train.py): `doa/training_pipeline/train.py`
- [SED dataset](https://github.com/aronjohn20/acoustic-localization/blob/main/sed/training_pipeline/dataset.py): `sed/training_pipeline/dataset.py`
- [SED model training](https://github.com/aronjohn20/acoustic-localization/blob/main/sed/training_pipeline/train.py): `sed/training_pipeline/train.py`

### Visualization and reporting

- [Live dashboard](https://github.com/aronjohn20/acoustic-localization/blob/main/web_visualization/dashboard.py): `web_visualization/dashboard.py`
- [Flask Socket.IO server](https://github.com/aronjohn20/acoustic-localization/blob/main/web_visualization/server.py): `web_visualization/server.py`
- [Browser visualization](https://github.com/aronjohn20/acoustic-localization/blob/main/web_visualization/static/js/app.js): `web_visualization/static/js/app.js`
- [Session report](https://github.com/aronjohn20/acoustic-localization/blob/main/web_visualization/report.py): `web_visualization/report.py`

### Other components

- **Operator**

## Connections

- Operator → Inference orchestrator: starts (evidence: `README.md`)
- Inference orchestrator → Room stream generator: starts generator (evidence: `stream/pipeline.py`)
- Room stream generator → Inference orchestrator: queues audio chunks (evidence: `stream/pipeline.py`)
- Room stream generator → System configuration: reads settings (evidence: `stream/generator.py`)
- Room stream generator → Signal processing: uses coordinates (evidence: `stream/generator.py`)
- Inference orchestrator → System configuration: reads thresholds (evidence: `stream/pipeline.py`)
- Inference orchestrator → SED predictor: runs detection (evidence: `stream/pipeline.py`)
- SED predictor → CNN14 model: runs model (evidence: `sed/api.py`)
- Inference orchestrator → Signal processing: computes GCC-PHAT (evidence: `stream/pipeline.py`)
- Inference orchestrator → DOA predictor: runs localization (evidence: `stream/pipeline.py`)
- DOA predictor → SSL localization model: runs model (evidence: `doa/api.py`)
- Inference orchestrator → Live dashboard: forwards results (evidence: `stream/pipeline.py`)
- Live dashboard → Flask Socket.IO server: posts updates (evidence: `web_visualization/dashboard.py`)
- Live dashboard → Session report: generates report (evidence: `web_visualization/dashboard.py`)
- Flask Socket.IO server → Browser visualization: broadcasts events (evidence: `README.md`)
- DOA data generation → DOA training settings: uses settings (evidence: `doa/training_pipeline/data_gen/generate_data.py`)
- DOA model training → DOA training settings: reads settings (evidence: `doa/training_pipeline/train.py`)
- DOA model training → SSL localization model: trains model (evidence: `doa/training_pipeline/train.py`)
- SED model training → SED dataset: loads dataset (evidence: `sed/training_pipeline/train.py`)
- SED model training → CNN14 model: trains model (evidence: `sed/training_pipeline/train.py`)
