# ScreamGate for Windows

A small Windows-friendly realtime audio gate for loud, high-pitched scream-like audio.

It is built around a look-ahead delay line: the program analyzes incoming audio immediately, delays the output by a few milliseconds, and pulls the gain down before the delayed spike reaches your headphones.

## What it does

- Gates loud, high-frequency, vocal-like spikes.
- Uses a look-ahead buffer, instant attack, hold time, and smooth release.
- Lets you choose input and output devices in a simple Tkinter GUI.
- Shows live RMS, high-band ratio, spectral centroid, and gate state.

## What it does not do

- It does not classify gender or identity.
- It cannot intercept all Windows audio by itself. Windows needs an audio routing path.
- It is not a kernel audio driver or a professional VST host.

## Recommended Windows Routing

Use a virtual cable such as VB-CABLE:

1. Set the loud app/game/browser output device to `CABLE Input`.
2. Open this program.
3. Select `CABLE Output` as the input device.
4. Select your headphones/speakers as the output device.
5. Click `Start`.

Use input and output devices from the same Windows backend. For example:

```text
Input:  9: CABLE Output (VB-Audio Virtual Cable) (Windows DirectSound)
Output: 12: Realtek HD Audio 2nd output (Realtek(R) Audio) (Windows DirectSound)
```

The app now prefers input device `9` and output device `12` when Windows exposes those indices. Do not mix `Windows WASAPI` input with `MME`, `DirectSound`, or `WDM-KS` output. PortAudio will reject that with `PaErrorCode -9993`.

Your audio path becomes:

```text
App audio -> Virtual Cable -> Scream Gate -> Headphones
```

## Install

Python 3.11+ is recommended. This workspace was verified with Python 3.14.

```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
```

Then run:

```powershell
.\.venv\Scripts\python.exe scream_gate.py
```

If you only want to list audio devices:

```powershell
.\.venv\Scripts\python.exe scream_gate.py --list-devices
```

## Distributable Build

The packaged Windows build is created at:

```text
dist\ScreamGate\ScreamGate.exe
dist\ScreamGate.zip
```

Upload `dist\ScreamGate.zip` to your site. Users should extract it and run `ScreamGate.exe`. The quick guide is included as `HOW_TO_USE.md`.

## Tuning

Start with:

- Look-ahead: `15 ms`
- Hold: `104.2 ms`
- Release: `20 ms`
- RMS threshold: `-34 dBFS`
- High-band ratio: `0.32`
- Centroid: `2300 Hz`
- Attenuation: `-12 dB`
- Auto-Kill: `on`

If normal dialogue gets muted, raise the RMS threshold or high-band ratio.
If screams leak through, lower the RMS threshold, lower the ratio, or increase look-ahead slightly.

## Spectrum Viewer

The realtime spectrum viewer sits at the bottom of the main window.

- Move the mouse over the graph to inspect frequency and level.
- Click a visible spike to enable `Target Clicked Spike`.
- The click sets `Target frequency Hz`, `Target absolute dB`, and `Target over baseline dB`.
- In relative mode, the gate mutes when the clicked band rises above its learned baseline by the selected margin.
- The target detector also requires the sound's spectral center to be high enough, so loud bass is less likely to false-trigger it.
- Use `Target width Hz` to make the targeted band narrower or wider.
- Turn off `Broad Detector` if you only want the clicked frequency band to control muting.
- `Auto-Kill` is on by default. It learns from real audio that has already passed through and kills new high-frequency spikes that rise above that heard history.
- Green is the live spectrum.
- Blue is the self-averaging baseline.
- Orange is the session maximum trace.
- Gray is the session minimum trace.
- Use `Reset Spectrum Memory` to restart the baseline/min/max tracking.

For best results, click slightly below the top of a spike you want blocked. That gives the detector a little margin before the next spike hits.

## Notes

This is a practical realtime tool, not a medically or legally meaningful classifier. It looks for acoustic features that often describe harsh screams: high energy, a strong 1.6-8 kHz band, and a high spectral centroid.
