quietplace 0.2.5

Semantic noise suppression demo controlled by Gemma/Gemma-compatible models served through vLLM.

QuietPlace vLLM

QuietPlace is a package for safety-aware semantic noise suppression. The package keeps the AST event classifier, deterministic DSP executor, metrics, and plotting code as a reusable Python library, then uses a Jupyter notebook as the public demo surface.

Gemma/Gemma-compatible inference is called through a vLLM OpenAI-compatible server.

Chapter 0 — Install the package

1. Clone the repository

git clone https://github.com/akaliutau/quietplace.git
cd quietplace

2. Create and activate a Conda environment

conda create -n quietplace python=3.12 -y
conda activate quietplace

3. Install dependencies

pip install -r requirements.txt

Chapter 1 — Put the trained AST classifier in the hard-coded location

The demo assumes the AST classifier is already trained and exported with save_pretrained().

Hard-coded pointer:

/kaggle/input/quietplace-policy-ast/quietplace_policy_ast

This is defined in:

quietplace/config.py

Expected contents:

config.json
model.safetensors or pytorch_model.bin
preprocessor_config.json
policy_map.json        # optional but recommended

Chapter 2 — Start vLLM instead of Ollama

Example local server:

vllm serve google/gemma-4-e2b-it \
  --host 0.0.0.0 \
  --port 8000 \
  --dtype auto \
  --api-key EMPTY

The package calls:

http://localhost:8000/v1/chat/completions

via the official openai Python client. If your vLLM model/tool parser does not support native tool calls, the controller falls back to JSON parsing and the deterministic DSP executor still only runs whitelisted actions.

Chapter 3 — Create a realistic demo input

Best competition input: combine held-out dataset clips so the demo has known ground-truth segments.

quietplace make-demo-scene \
  --traffic-path /datasets/fsd50k/traffic_heldout.wav \
  --siren-path /datasets/urbansound8k/fold10/siren_heldout.wav \
  --speech-path /data/recorded_help.wav \
  --out data/demo_scene

No dataset files available? Use the deterministic synthetic fallback:

quietplace make-demo-scene --out data/demo_scene

Outputs:

data/demo_scene/quietplace_realistic_demo_scene.wav
data/demo_scene/events_demo.json
data/demo_scene/scene_manifest.json

Chapter 4 — Run the package pipeline

With the generated event table:

quietplace run data/demo_scene/quietplace_realistic_demo_scene.wav \
  --events-json data/demo_scene/events_demo.json \
  --backend auto \
  --vllm-base-url http://localhost:8000/v1 \
  --vllm-api-key EMPTY \
  --vllm-model google/gemma-4-e2b-it \
  --out runs/quietplace_demo

To force vLLM and fail if the server is down:

quietplace run data/demo_scene/quietplace_realistic_demo_scene.wav \
  --events-json data/demo_scene/events_demo.json \
  --backend vllm \
  --out runs/quietplace_demo

Outputs:

runs/quietplace_demo/original.wav
runs/quietplace_demo/suppressed.wav
runs/quietplace_demo/events.json
runs/quietplace_demo/controller_policy.json
runs/quietplace_demo/features.json
runs/quietplace_demo/segment_metrics.csv
runs/quietplace_demo/bandpower_metrics.csv
runs/quietplace_demo/metrics_summary.json

Chapter 5 — Generate charts for the video/writeup

quietplace charts data/demo_scene/quietplace_realistic_demo_scene.wav \
  --events-json data/demo_scene/events_demo.json \
  --backend auto \
  --out runs/quietplace_demo \
  --charts-out runs/quietplace_demo/charts

Charts:

01_before_after_spectrograms.png
02_waveform_ab.png
03_segment_metrics.png
04_bandpower_metrics.png

Chapter 6 — Create writeup chapters from the run

quietplace chapters \
  --run-dir runs/quietplace_demo \
  --out reports/chapters

This creates draft markdown chapters:

reports/chapters/01_problem.md
reports/chapters/02_architecture.md
reports/chapters/03_results.md
reports/chapters/04_demo_script.md

Use these as the structure for the Kaggle writeup and video narration.

Project structure

quietplace/audio.py        # audio IO, event schema, spectral features
quietplace/classifier.py   # hard-coded AST classifier wrapper
quietplace/controller.py   # vLLM/OpenAI-compatible policy controller
quietplace/dsp.py          # deterministic suppressor executor
quietplace/metrics.py      # calm-zone and preservation metrics
quietplace/viz.py          # notebook charts
quietplace/demo_scene.py   # realistic scene builder / synthetic fallback
quietplace/pipeline.py     # end-to-end orchestration
quietplace/cli.py          # commands used above
notebooks/00_quietplace_vllm_demo.ipynb

Build and publish the package

see the details in publish.md