DDDS Acoustic AI Workbench

Model-backed acoustic analysis for uploaded and curated WAV samples.

DDDS is a non-operational acoustic AI workbench concept for exploring drone-like sound detection from recorded audio. The app loads the trained RandomForest model from the legacy prototype, extracts MFCC features from WAV audio, scores one-second windows, and visualizes the resulting model probabilities alongside waveform and mel spectrogram views.

The project is intentionally scoped to model-backed analysis. It is not a tactical simulator, not a live deployment system, and not a localization product.

Concept

The workbench answers one narrow question:

Given a WAV recording, how does the current DDDS acoustic model score each short audio window?

That makes the prototype useful for reviewing model behavior, checking curated samples, uploading new test audio, and comparing the classifier output with the visible audio structure.

flowchart LR
  A["Curated WAV or upload"] --> B["Mono audio loader"]
  B --> C["1 second analysis windows"]
  C --> D["MFCC feature extraction"]
  D --> E["RandomForest model"]
  E --> F["Probability timeline"]
  B --> G["Waveform"]
  B --> H["Mel spectrogram"]
  B --> I["Lab-only simulated TDOA check"]

Loading

What It Does

• Loads backend/models/drone_detector_model_v2.pkl by default.
• Preserves compatibility with both known legacy model feature formats:
  • drone_detector_model_v2.pkl: 40 MFCC mean features.
  • drone_detector_model.pkl: 80 MFCC mean and standard-deviation features.
• Analyzes curated sample WAV files from backend/samples/.
• Accepts uploaded WAV audio through the FastAPI backend.
• Reports model probability over one-second windows.
• Renders waveform and mel spectrogram views from the analyzed audio.
• Exposes the prototype direction finder as a clearly labeled lab-only TDOA check using simulated microphone channels.

What It Does Not Do

• No target assignment.
• No weapon, interception, or engagement guidance.
• No live response-team coordinates.
• No tactical route planning or operational map overlays.
• No claims that simulated TDOA output is field localization.
• No invented accuracy, range, or deployment telemetry.

Application Surface

The active app is a React frontend backed by a FastAPI service.

backend/
  app/
    main.py                  FastAPI routes and static frontend serving
    config.py                backend config and environment defaults
    schemas.py               typed API response/request models
    services/
      model_loader.py        pickle loading and MFCC compatibility
      audio_analysis.py      audio loading, inference, charts, lab TDOA
  models/
    drone_detector_model.pkl
    drone_detector_model_v2.pkl
  samples/
    drone/
    noise/

src/
  App.tsx                    React workbench shell
  api/client.ts              API fetch helpers
  components/                status, controls, charts, direction, limits
  config/appConfig.ts        frontend defaults
  types/audio.ts             shared frontend API types

API Endpoints

Method	Path	Purpose
GET	/api/health	Model availability, model metadata, sample count.
GET	/api/samples	Curated WAV sample list.
POST	/api/analyze/sample	Analyze a curated sample by id.
POST	/api/analyze/upload	Analyze an uploaded audio file.

If the model is missing or inference fails, the backend returns an API error instead of fabricating results.

Run With Docker

The supported packaged path is a single container. Docker builds the Vite frontend, starts FastAPI, serves /api/*, and serves the compiled React app.

docker compose up --build

Open:

http://127.0.0.1:8080/

Local Development

Install frontend dependencies:

npm install

Install backend dependencies:

python3 -m venv .venv
source .venv/bin/activate
pip install -r backend/requirements.txt

Run the backend:

uvicorn backend.app.main:app --reload --host 127.0.0.1 --port 8000

Run the frontend:

npm run dev

Vite proxies /api to http://127.0.0.1:8000.

Configuration

Backend defaults are defined in backend/app/config.py and can be overridden with environment variables.

Variable	Default	Description
DDDS_MODEL_PATH	backend/models/drone_detector_model_v2.pkl	Pickle model path.
DDDS_SAMPLES_DIR	backend/samples	Curated WAV sample directory.
DDDS_SAMPLE_RATE	22050	Audio sample rate used for analysis.
DDDS_WINDOW_SECONDS	1.0	Inference window size.
DDDS_HOP_SECONDS	0.5	Timeline hop size.
DDDS_DETECTION_THRESHOLD	0.40	Probability threshold for displayed labels.
DDDS_MAX_AUDIO_SECONDS	45.0	Maximum analyzed duration per file.

Verification

Run the frontend production build:

npm run build

Compile backend Python files:

python3 -m py_compile backend/app/*.py backend/app/services/*.py

If backend dependencies are installed and the API is running, check:

curl http://127.0.0.1:8000/api/health

If Docker is available, also verify the packaged image:

docker compose build

Roadmap

Realistic next steps are intentionally tied to committed code and data:

1. Add backend tests for model loading and sample inference.
2. Add a confusion-matrix or evaluation endpoint only after a labeled validation split is committed.
3. Add browser microphone capture only after an explicit client-side audio ingestion path and consent flow exist.
4. Replace simulated TDOA with real multi-channel audio input if hardware recordings become available.
5. Add model metadata such as training date, dataset summary, and known limitations when those facts are documented.

Legacy Prototype Note

The previous city-ring simulator and conceptual deployment screens were removed from the active application because they did not represent the real model-backed capability currently present in this repository. The legacy prototype remains useful only as source history for the trained model files and curated sample migration.