Spaces:
Running
Running
| # Voice Analyzer Internal API Contract | |
| This document defines the stable interface between the DSP analyzer and UI/game modes. | |
| ## Analyzer output contract | |
| `VoiceAnalyzer.metrics` emits normalized values in `[0, 1]`: | |
| - `bounce`: pitch-variance expressiveness. | |
| - `tempo`: transition-rate/tempo variation. | |
| - `vowel`: sustained voiced-vowel continuity. | |
| - `articulation`: high-frequency consonant clarity (noise-floor normalized). | |
| - `syllable`: onset impulse for separated syllables. | |
| - `pitch`: user-adaptive pitch position. | |
| - `energy`: adaptive energy position (P50/P90 normalized). | |
| - `resonance`: smoothed resonance/formant-derived signal. | |
| ## Confidence contract | |
| Consumers should treat the following analyzer fields as quality indicators: | |
| - `pitchConfidence` | |
| - `formantConfidence` | |
| - `spectralTiltConfidence` | |
| Frame reliability is computed with `computeFrameReliability()` in `voice-analyzer-core.js`. | |
| ## UI integration rules | |
| - UI/game logic should read metrics only through `analyzer.metrics`. | |
| - Do not re-normalize metrics in mode-specific renderers. | |
| - Feature additions that need raw DSP values should be introduced via explicit analyzer fields and documented here. | |
| ## Module boundary (phase 1) | |
| `voice-analyzer-core.js` now owns shared normalization/reliability math. | |
| Future extractions should continue this split: | |
| 1. `voice-analyzer-core.js`: pure math + gating helpers. | |
| 2. `voice-analyzer-engine.js`: WebAudio capture + frame extraction. | |
| 3. `voice-analyzer-state.js`: profile learning and state transitions. | |
| 4. UI/game modes consume only the stable contract above. | |