# EQ Coach 0.10.16 — Pre-registered video research protocol

## Status
A **frozen exploratory prototype**, not a clinical/physiological detector. The parameters listed below were selected *post-hoc* by inspecting the 2026-11-06 video pair `890871d2-88f8-4b29-b37e-3809b7a40646`. This pair is **development data**. Replaying the original pair is a software regression test, **NOT** an independent validation.

## Frozen signal chain
1. Record frontal, stable camera, full face and exposed upper neck, with the same hand closing the nose before baseline in control and Frenzel sessions.
2. Decode to 15 fps and 540×960 portrait. No mirror transformations or conditional adjustments based on condition.
3. Analyze frame-to-frame **dense Farnebäck optical flow**, at 270×480 internal working resolution (the original frame is 540×960). Farnebäck parameters: `pyr_scale=.5, levels=3, winsize=17, iterations=3, poly_n=5, poly_sigma=1.2`.
4. Use *fixed* ROIs in 540×960 coordinates, selected previously: upper neck `(218,681)-(342,727)`; beard `(233,588)-(323,659)`; cheek `(340,480)-(384,567)`; background `(451,425)-(503,619)`. These are **not general anatomical coordinates**, and require similar capture geometry. The code does **not** know where the user's larynx is.
5. Median vertical flow in upper neck minus median vertical beard flow, summed cumulatively from action start (8 s). Apply 7-frame Savitzky–Golay smoothing (order 2).
6. Find all local peaks in 8.0–15.9 s with minimum prominence **1.4 image pixels** and spacing >=**16 frames**. Detect blindly without consulting scheduled action cues. Separately, report which peaks fall within 0–2 s after cues, and the net relative upward displacement within 0.1–1.1 s of each cue.
7. Preserve the raw series, all candidate peaks, and the negative controls. No parameter tuning on the next validation data.

## First new test (before looking at its result)
- One control: maintain grip without action; one Frenzel: three gentle, marked tongue-base actions. Same smartphone mount, background, lighting, distance, hand position and shirt collar.
- Add a separate swallowing run (1 swallow) and jaw movement run (1 deliberate jaw movement). Valsalva only if safe/comfortable and gentle; never force high pressure or breath holds.
- Download *all videos* and one timeline JSON. Name and keep them together.
- The Python analyzer will run on video files **offline** after the user explicitly provides them; this web app does not send private videos to a server and does not claim real-time Frenzel detection.
- Without held-out videos it is impossible to estimate accuracy, specificity, or robustness across subjects.

## Running locally on a trusted computer
Requires Python 3, OpenCV, NumPy, SciPy, FFmpeg. For example:

```sh
python frozen_detector.py --control control.webm --frenzel frenzel.webm --timeline TIMELINE.json --output analysis.json
```

This analysis uses hand-selected **image-space** ROIs from prior footage, not an automatic larynx segmentation model; the fixed boxes can miss the neck with changed framing. If framing is materially different, report "not assessable" rather than adjusting boxes after viewing the test condition.

## Provenance and integrity
`nose/` is frozen unchanged from v0.10; all previous throat directories and historical storage keys are retained. This distribution contains no personal videos. Save the private research archive separately from this public ZIP. Never upload personal video archives to Cloudflare or other public hosting.