# 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. Use `Test VB-CABLE Output` if you want to confirm your speakers are selected.
6. Play a normal part of the video for calibration.
7. Click `Start Calibration`.
8. Let the countdown finish, or click `Arm Now` once the app has heard enough normal audio.
9. When armed, anything above the learned peak dB ceiling is capped, and the hard kill band destroys `1000-2000 Hz` when it rises over the hard cap dB slider.
10. The app reports the frequency and dB it locks onto while it gates.
11. Leave `Show Advanced Tuning` closed unless you need manual control.

Fast workflow:

- `Start Calibration`: clears old memory, starts audio, and learns normal playback.
- `Arm Now`: stops calibration early and arms the gate with the current baseline.
- `Restart Calibration`: clears the previous scene memory and learns a fresh baseline.

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

ScreamGate opens with the everyday controls visible and advanced tuning collapsed so the spectrum gets the space. The current defaults are:

- Look-ahead: `50 ms`
- Hold: `104.2 ms`
- Release: `20 ms`
- Hard kill band: `1000-2000 Hz`
- Hard cap dB: `-45.5 dB` by default, adjustable live
- Peak cap: calibrated peak plus `1.0 dB`
- Attenuation: `-96 dB`
- Intensity: `80`
- Scream fingerprint: abrupt attack plus chaotic `1000-4000 Hz` texture
- Automatic gate: `off until calibration`

If normal dialogue gets muted, lower `Intensity`.
If screams leak through, raise `Intensity` or restart calibration from a calmer section.

## 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 add a manual target.
- The click is dual-axis: X sets `Target frequency Hz`, Y sets `Target absolute dB`, and the local baseline sets `Target over baseline dB`.
- In relative mode, the gate mutes when the clicked band rises above its learned baseline by the selected margin.
- Use `Target width Hz` to make the targeted band narrower or wider.
- Use `Start Calibration` to learn normal playback, then let it arm or click `Arm Now`.
- Use `Intensity` live after calibration; it adjusts sensitivity and clamp strength without throwing away the learned baseline.
- Use `Hard cap dB` live after calibration; audio below that line is protected from suppression.
- Green is the live spectrum.
- Blue is the self-averaging baseline.
- Orange is the session maximum trace.
- Gray is the session minimum trace.
- Click `Restart Calibration` to refresh calibration, gate history, and the baseline/min/max tracking.
- When audio goes silent or the video is paused, the spectrum holds the last active frame so you can click it.

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, strong upper-frequency bands, and sustained spectral peaks.

It also watches waveform density. A scream often turns into a tightly packed wall of sound at the transition from normal audio, so ScreamGate can catch dense high-frequency walls even when a single clicked target is not enough.

The newer scream fingerprint layer adds attack-time and spectral-flux checks in the `1000-4000 Hz` presence band. That helps catch screams that do not land exactly on the hard `1000-2000 Hz` cap, while leaving under-cap audio alone.

ScreamGate is also a practical YouTube gate: route browser audio through VB-CABLE, calibrate a calm part of the video, and let the gate keep later volume spikes from jumping above the baseline.
