ScoreVisualizer: envelope degli offset per-voce (voice_pitch/pointer_offset, pointer_range) — Fase 3 di #88

[DMGiulioRomano]

Contesto

Follow-up della #88 (PR #89, Fasi 1+2). Le Fasi 1 e 2 hanno agganciato al ScoreVisualizer gli envelope di num_voices, scatter e pointer_speed tramite estrazione per nome esplicito in _get_stream_envelopes.

Restano fuori gli offset per-voce, perche' non sono Envelope/Parameter sullo Stream ma config delle voice strategy, calcolati on-the-fly per (indice voce, tempo).

Parametri coinvolti

• voice_pitch_offset — trasposizione per-voce in semitoni (range -48..48); materializzata come pitch_factor (fattore ratio) dalla voice pitch strategy.
• voice_pointer_offset — offset della posizione di lettura nel sample (secondi, o frazione di sample_dur_sec se normalized: true); diventa pointer_offset in VoiceConfig (src/controllers/voice_manager.py:65), applicato in src/core/stream.py:494-497.
• voice_pointer_range — ampiezza/spread di quell'offset tra le voci (0..1 normalizzato).

Perche' non basta l'aggancio per nome (come Fasi 1+2)

Questi valori non sono una curva singola nel tempo: dipendono da (voice_index, time), prodotti da VoiceManager.get_voice_config(voice_index, time) delegando alle strategy (VoicePitchStrategy, VoicePointerStrategy, ...). Non esiste un stream.voice_pitch_offset da leggere come Envelope.

Stato attuale

• envelope_ranges e envelope_colors nel visualizer hanno gia' le chiavi predisposte (voice_pitch_offset, voice_pointer_offset, voice_pointer_range) — vedi src/rendering/score_visualizer.py.
• Manca l'esposizione dei valori come curve disegnabili.

Design da valutare

Estrazione dedicata dalle voice strategy, p.es.:

• valutare get_voice_config(voice_index, t) su una griglia di t per ogni voce, ricostruendo una curva per-voce per ciascun offset; oppure
• esporre dalla strategy la curva sottostante quando esiste (es. envelope di spread/range), distinguendo i casi statici da quelli time-varying.

Aperte: come rappresentare N voci nel pannello (una traccia per voce? inviluppo aggregato min/max?), come gestire num_voices time-varying (numero di voci che cambia nel tempo).

Scope

• Decidere la rappresentazione visiva (per-voce vs aggregata)
• Estrazione valori dalle voice strategy in _get_stream_envelopes (o helper dedicato)
• Test: voice_pitch_offset/voice_pointer_offset/voice_pointer_range con strategy attive → tracce raccolte; statici esclusi salvo show_static

Impatto cross-repo (PGE-ls / PGE-ui)

Da rivalutare in fase di design: parametri YAML gia' esistenti, ma se cambia la rappresentazione potrebbe interessare la visualizzazione in PGE-ui. Nessuna issue ora.

File coinvolti (previsti)

• src/rendering/score_visualizer.py
• src/controllers/voice_manager.py e/o src/strategies/voice_*_strategy.py (eventuale esposizione curve)