# EQ Coach 0.10.17 — Guided visible-neck ROI protocol (research only)

## Why this is different

The previous frozen 0.10.16 detector failed anatomical audit. A hardcoded `upper_neck` region was located mostly on beard, whereas the exposed anterior neck was lower in the frame. Three peaks in the frozen result did **not** establish detection of the larynx or Frenzel.

This new research version **does not reuse that rectangle**. The participant taps the center of visible bare-neck skin below the beard and an unobstructed face area (e.g., cheek) on the live camera preview. Both rectangles are visible before recording and their **normalized video coordinates are stored within each run** in the exported JSON. Calibration is locked following the first control run to preserve paired geometry. A captured ROI placement PNG can be exported to independently verify correct tissue. The user can adjust target ROI height and width.

## Recording protocol

- Phone on a fixed support; head, face, underside of chin, neck and upper chest visible, natural head posture.
- Pinch nose consistently in control and Frenzel, **before baseline starts**. Avoid swallowing in control.
- Each recording: 3s prep, 5s baseline, 8s action.
- Frenzel: three clear controlled movements after the scheduled cues; no unnecessary pressure.
- Optional confounds: swallowing once, jaw opening once, gentle Valsalva, in separate recordings.
- Confirm `video.requested`, collect both `.webm` and `TIMELINE.json`, plus optional ROI placement PNG.
- No microphones, no automatic upload, no anatomical diagnosis; private recordings must not be uploaded to public hosting.

## Candidate detector (offline)

`python research/neck_detector_v2.py --timeline TIMELINE.json --control control.webm --frenzel frenzel.webm --out result.json`

The script uses FFmpeg and OpenCV to extract video at 12 fps, 270×480, estimates per-frame dense Farnebäck flow, samples the user-selected neck ROI **and** the selected face-reference ROI, and computes the median vertical motion difference. Face displacement shifts both sampling rectangles together to reduce drift. Texture quality, flow dispersion and valid sample rates are recorded; incomplete/invalid studies are **not** scored as failed Frenzel.

A small number of candidate peaks can be shown as a descriptive research measure; no claim is made that each candidate corresponds to a Frenzel movement. Thresholds are predeclared in this code, but parameters are **not yet validated on new subjects**. An absence of peaks is NOT an absence of correctly performed Frenzel. The face reference can also move with jaw motion, so swallowing and jaw controls are essential.

## Test criterion

Before further tuning, compare prospective control vs Frenzel and at least jaw/swallow controls. Two independent studies with correct ROI placements and visual/video review should be conducted before considering automated guidance. No training or threshold changes on the exact same recordings used for independent testing.

## Safety and backups

- Nose module frozen exactly as 0.10; prior throat implementations available as archive.
- Existing recordings and model code remain in private research ZIP.
- Video stays on phone until downloaded, and is not included in shared public site ZIP.
- Record the version/algorithm ID for each study; never relabel old fixed-ROI data as anatomy-validated.
- Retain screenshots/ROI JSON to verify camera framing rather than presuming anatomy from MediaPipe.