feat(export): export grani in JSON via --grain-json (#73)

[DMGiulioRomano]

Contesto

Chiude #73. PGE-ui (consumer tracciato in PGE-ui#13) deve disegnare i rettangoli dei singoli grani nella clip timeline di ogni stream. L'IR Grain era già calcolato in stream.voices ma mai persistito in forma strutturata (solo .sco Csound o buffer audio). Questa PR aggiunge un flag CLI --grain-json che esporta i grani in JSON.

Design

Nessuna interfaccia/ABC condivisa tra exporter (scelta deliberata). Reaper export e JSON export divergono troppo — input (aif_paths vs no), cardinalità output (1 file vs N), profondità dati (stream-level vs grain-level) — quindi un'astrazione comune ora sarebbe leaky/prematura (Rule of Three: solo 2 exporter). GrainJsonWriter nasce standalone e riusa l'unica convenzione utile del Reaper writer: split generate() (puro) / write() (I/O).

Modifiche

• src/export/grain_json_writer.py (nuovo) — GrainJsonWriter con build()/generate()/write(). Itera stream.voices per preservare l'indice voce, ordina per t, JSON compatto.
• tests/export/test_grain_json_writer.py (nuovo) — 19 test (TDD rosso→verde).
• src/main.py — flag --grain-json, attivo solo con --per-stream. I file JSON sono scritti come sidecar accanto agli stem .aif (stessa directory dell'output STEMS), così PGE-ui trova grain JSON e audio nello stesso posto. Usage aggiornato.

Schema JSON

Un file per stream, accanto allo stem audio: {output_dir}/{basename}__{stream_id}__grains.json

{"stream_id":"s1","duration":8.0,"num_voices":2,"grains":[{"t":-0.5,"dur":0.05,"vol":-9.0,"ptr":0.1,"v":1}, ...]}

• t = grain.onset - stream.onset (relativo allo stream; può essere < 0 con onset offset per-voce)
• v = indice voce; dur/vol/ptr = duration/volume/pointer_pos
• ptr ha unità variabile per stream (secondi o frazione)
• grani ordinati per t, JSON compatto (no whitespace)
• num_voices = len(stream.voices) (voci effettivamente generate)

Verifica

• make tests: 4273 passed, 2 skipped — verde.
• Output del writer verificato con il vero Grain (ordinamento, t negativo, mapping, write() == generate()).
• Nota: e2e via CLI con render reale non eseguibile nell'ambiente (refs/ privo di sample audio; il blocco grain-json gira dopo il render). Logica coperta da test unitari e verifica diretta.

Impatto cross-repo

• PGE-ls: nessuno (nessuna modifica a YAML/schema).
• PGE-ui: già tracciato come PGE-ui#13 (consumer del formato JSON). Path output cambiato in sidecar accanto agli .aif — verificare che il consumer cerchi i JSON nella directory degli stem. Nessuna nuova issue (aggiornare PGE-ui#13 se necessario).

Changelog branch

• 3b2c49f feat: implementazione iniziale --grain-json (output in cache_dir).
• 254352c fix: grain JSON scritto accanto agli stem .aif invece che in cache_dir (sidecar coerente con l'audio a cui si riferiscono; cache_dir non aveva relazione semantica con l'export e poteva non esistere senza --cache).

https://claude.ai/code/session_019N8ZDHmri8tCNCu2WgGRzc

---

Generated by Claude Code