Home

---

📘 Stream YAML Reference - Documentazione Completa

Indice

1. Struttura Minima
2. Parametri Globali Stream
3. Sezione grain
4. Sezione pointer
5. Sezione pitch
6. Controllo Densità
7. Parametri Output
8. Sezione dephase
9. Sistema Envelope
10. Funzionalità Avanzate
11. Tabella Riassuntiva Bounds

1. Struttura Minima

La configurazione più semplice possibile per uno stream funzionante:

streams:
  - stream_id: "minimal"
    onset: 0.0
    duration: 10.0
    sample: "audio.wav"

Con questa configurazione minima, tutti gli altri parametri assumono i valori di default:

Parametro	Default
grain.duration	0.05 (50ms)
grain.envelope	hanning
fill_factor	2.0
distribution	0.0 (sincrono)
pointer.start	0.0
pointer.speed	1.0
pitch.ratio	1.0
volume	-6.0 dB
pan	0.0 gradi

---

2. Parametri Globali Stream

Parametri Obbligatori

streams:
  - stream_id: "nome_univoco"    # Stringa identificativa
    onset: 0.0                    # Tempo di inizio (secondi)
    duration: 10.0                # Durata dello stream (secondi)
    sample: "file.wav"            # Path del file audio (relativo a ./refs/)

Parametri Opzionali Globali

streams:
  - stream_id: "esempio"
    onset: 0.0
    duration: 10.0
    sample: "file.wav"
    
    time_mode: absolute           # 'absolute' (default) | 'normalized'
    solo:                         # Presenza = solo questo stream (valore ignorato)
    mute:                         # Presenza = escludi questo stream (valore ignorato)

time_mode

Determina come interpretare i tempi negli envelope:

Valore	Comportamento
absolute (default)	I tempi sono in secondi reali
normalized	I tempi sono frazioni (0.0 - 1.0) della durata dello stream

Esempio con normalized:

streams:
  - stream_id: "normalized_example"
    onset: 0.0
    duration: 20.0
    sample: "file.wav"
    time_mode: normalized
    
    # Questo envelope va da 0s a 20s (0.5 × 20 = 10s)
    volume: [[0, -12], [0.5, -3], [1, -12]]

solo e mute

Sistema di filtraggio per il debug compositivo:

streams:
  - stream_id: "stream1"
    solo:                    # ← Solo questo verrà processato
    # ...
    
  - stream_id: "stream2"
    mute:                    # ← Questo verrà ignorato
    # ...
    
  - stream_id: "stream3"
    # Senza solo/mute: processato normalmente (se nessun solo attivo)

Logica:

• Se almeno uno stream ha solo: vengono processati SOLO quelli con solo
• Altrimenti: vengono processati tutti TRANNE quelli con mute

---

3. Sezione grain

Controlla le proprietà dei singoli grani.

Configurazione Minima

grain:
  duration: 0.05

Configurazione Completa

grain:
  duration: 0.05              # Durata grano in secondi
  duration_range: 0.01        # Variazione stocastica ±range/2
  envelope: hanning           # Tipo di inviluppo
  reverse: auto               # Direzione lettura: 'auto' | true | false

Parametri

duration

• Tipo: Numero o Envelope
• Default: 0.05 (50ms)
• Bounds: 0.0001 - 10.0 secondi
• Descrizione: Durata base di ogni grano

# Valore fisso
grain:
  duration: 0.03

# Envelope: grani che si allungano
grain:
  duration: [[0, 0.01], [10, 0.1]]

duration_range

• Tipo: Numero o Envelope
• Default: 0.0
• Bounds: 0.0 - 1.0 secondi
• Descrizione: Ampiezza della variazione stocastica (±range/2)

grain:
  duration: 0.05
  duration_range: 0.02    # Grani tra 0.04 e 0.06 secondi

envelope

• Tipo: Stringa
• Default: hanning

Tipi disponibili:

Famiglia	Tipi	Note
Standard (GEN20)	hanning, hamming, bartlett, triangle, blackman, blackman_harris, gaussian, kaiser, rectangle, sinc	Window functions classiche
Custom (GEN09)	half_sine	Mezza sinusoide
Esponenziali (GEN16)	expodec, expodec_strong, exporise, exporise_strong, rexpodec, rexporise	Asimmetrici, ottimi per percussioni

grain:
  duration: 0.05
  envelope: gaussian      # Campana stretta
  
grain:
  duration: 0.1
  envelope: expodec       # Attacco immediato, decay esponenziale

reverse

• Tipo: 'auto' | true | false
• Default: 'auto'
• Descrizione: Direzione di lettura del grano

Valore	Comportamento
'auto'	Segue il segno di pointer.speed (negativo = reverse)
true	Sempre al contrario
false	Sempre in avanti

grain:
  duration: 0.05
  reverse: true           # Tutti i grani al contrario

---

4. Sezione pointer

Controlla la testina di lettura nel sample.

Configurazione Minima

pointer:
  speed: 1.0

Configurazione Completa

pointer:
  start: 0.0              # Posizione iniziale (secondi)
  speed: 1.0              # Velocità di scansione
  offset_range: 0.0       # Macro-variazione (0-1, normalizzato)
  
  # Loop (opzionale)
  loop_start: 2.0         # Inizio loop (secondi)
  loop_end: 4.0           # Fine loop (secondi) - OPPURE loop_dur
  loop_dur: 2.0           # Durata loop (secondi) - OPPURE loop_end
  loop_unit: absolute     # 'absolute' | 'normalized'

Parametri

start

• Tipo: Numero
• Default: 0.0
• Descrizione: Posizione iniziale della testina in secondi

speed

• Tipo: Numero o Envelope
• Default: 1.0
• Bounds: -100.0 - 100.0
• Descrizione: Velocità di scansione del sample

Valore	Effetto
1.0	Velocità normale
0.5	Metà velocità (time-stretching)
2.0	Doppia velocità
0.0	Fermo (freeze)
-1.0	Lettura al contrario

# Accelerazione progressiva
pointer:
  speed: [[0, 0.5], [10, 2.0]]

offset_range

• Tipo: Numero o Envelope
• Default: 0.0
• Bounds: 0.0 - 1.0
• Descrizione: Macro-variazione normalizzata sulla durata del contesto (sample o loop)

pointer:
  speed: 0.0              # Testina ferma
  offset_range: 0.5       # Ma salta casualmente nel 50% del sample

Sistema Loop

Il loop permette di confinare la lettura in una porzione del sample.

Tre modalità di configurazione:

1. loop_start + loop_end (bounds fissi):

pointer:
  loop_start: 2.0
  loop_end: 4.0           # Loop tra 2s e 4s

2. loop_start + loop_dur (durata dinamica):

pointer:
  loop_start: 2.0
  loop_dur: 1.0           # Loop di 1 secondo a partire da 2s

# Con envelope (loop che si restringe)
pointer:
  loop_start: 0.0
  loop_dur: [[0, 2.0], [10, 0.1]]

3. Solo loop_start (loop fino a fine sample):

pointer:
  loop_start: 5.0         # Loop da 5s fino alla fine del file

loop_unit

• Tipo: 'absolute' | 'normalized'
• Default: eredita da time_mode dello stream
• Descrizione: Come interpretare i valori del loop

# Loop normalizzato (20%-60% del sample)
pointer:
  loop_unit: normalized
  loop_start: 0.2
  loop_end: 0.6

---

5. Sezione pitch

Controlla la trasposizione dei grani. Due modalità mutuamente esclusive.

Modalità RATIO (default)

pitch:
  ratio: 1.0              # Rapporto di frequenza
  range: 0.0              # Variazione stocastica

Modalità SEMITONI

pitch:
  shift_semitones: 0      # Trasposizione in semitoni
  range: 0.0              # Variazione in semitoni

Parametri

ratio

• Tipo: Numero o Envelope
• Default: 1.0
• Bounds: 0.125 - 8.0
• Descrizione: Rapporto di frequenza diretto

Valore	Effetto
1.0	Pitch originale
2.0	Un'ottava sopra
0.5	Un'ottava sotto

pitch:
  ratio: [[0, 1.0], [10, 2.0]]    # Glissando verso l'ottava sopra

shift_semitones

• Tipo: Numero o Envelope
• Default: N/A (usa ratio se assente)
• Bounds: -36.0 - 36.0 semitoni
• Descrizione: Trasposizione in semitoni (più intuitivo)

pitch:
  shift_semitones: 7      # Quinta giusta sopra
  
pitch:
  shift_semitones: -12    # Ottava sotto

range

• Tipo: Numero o Envelope
• Default: 0.0
• Bounds (semitoni): 0.0 - 36.0
• Bounds (ratio): 0.0 - 2.0
• Descrizione: Ampiezza della variazione stocastica

# Variazione in semitoni
pitch:
  shift_semitones: 0
  range: 12               # ±6 semitoni (un'ottava totale)

# Variazione in ratio
pitch:
  ratio: 1.0
  range: 0.5              # ±0.25 ratio

---

6. Controllo Densità

Due modalità mutuamente esclusive per controllare quanti grani al secondo.

Modalità FILL_FACTOR (default, consigliata)

fill_factor: 2.0          # density = fill_factor / grain_duration
distribution: 0.0

Modalità DENSITY diretta

density: 50               # Grani al secondo (fisso)
distribution: 0.0

Parametri

fill_factor

• Tipo: Numero o Envelope
• Default: 2.0
• Bounds: 0.001 - 50.0
• Descrizione: Fattore di sovrapposizione. La densità si adatta automaticamente alla durata del grano.

Valore	Significato
1.0	Grani giustapposti (no overlap)
2.0	Grani sovrapposti del 50% (Roads: "covered texture")
0.5	Grani separati (gaps)

# Fill factor che aumenta
fill_factor: [[0, 1.0], [10, 4.0]]

density

• Tipo: Numero o Envelope
• Default: N/A (usa fill_factor se assente)
• Bounds: 0.1 - 4000.0 grani/secondo
• Descrizione: Numero esatto di grani al secondo

density: 100              # 100 grani al secondo, indipendente dalla durata

distribution

• Tipo: Numero o Envelope
• Default: 0.0
• Bounds: 0.0 - 1.0
• Descrizione: Grado di irregolarità temporale (modello Truax)

Valore	Comportamento
0.0	Sincrono: inter-onset fisso (regolare)
1.0	Asincrono: inter-onset random (0, 2×media)
0.5	Interpolazione 50% sync + 50% async

# Transizione da regolare a caotico
distribution: [[0, 0.0], [10, 1.0]]

---

8. Parametri Output

Controllo del volume e della posizione stereo.

volume: -6.0              # Volume in dB
volume_range: 0.0         # Variazione stocastica ±range/2

pan: 0.0                  # Posizione stereo (gradi)
pan_range: 0.0            # Variazione stocastica ±range/2

Parametri

volume

• Tipo: Numero o Envelope
• Default: -6.0 dB
• Bounds: -120.0 - 12.0 dB

# Fade in/out
volume: [[0, -40], [2, -6], [8, -6], [10, -40]]

volume_range

• Tipo: Numero o Envelope
• Default: 0.0
• Bounds: 0.0 - 12.0 dB

volume: -6.0
volume_range: 6.0         # Grani tra -9dB e -3dB

pan

• Tipo: Numero o Envelope
• Default: 0.0 (centro)
• Bounds: -3600.0 - 3600.0 gradi

# Movimento circolare
pan: [[0, -90], [5, 90], [10, -90]]

pan_range

• Tipo: Numero o Envelope
• Default: 0.0
• Bounds: 0.0 - 360.0 gradi

pan: 0.0
pan_range: 180            # Grani sparsi su tutto il fronte stereo

---

9. Sezione dephase

Sistema di gate probabilistico per le variazioni stocastiche. Crea irregolarità, glitch e sfasamenti.

Configurazione

dephase:
  pc_rand_reverse: 0      # Probabilità flip reverse (0-100%)
  pc_rand_duration: 0     # Probabilità variazione durata
  pc_rand_pan: 0          # Probabilità variazione pan
  pc_rand_volume: 0       # Probabilità variazione volume

Logica di Funzionamento

Il sistema dephase + range lavora insieme secondo tre scenari:

Scenario A: Classico (Range senza Dephase)

volume: -6.0
volume_range: 6.0         # Range applicato al 100% dei grani
# dephase: (assente)

→ Tutti i grani variano continuamente. Texture "viva" classica.

Scenario B: Implicit Jitter (Dephase senza Range)

volume: -6.0
volume_range: 0.0         # Range zero
dephase:
  pc_rand_volume: 20      # 20% di probabilità

→ L'80% dei grani ha volume fisso. Il 20% ha micro-variazioni (default jitter interno).

Scenario C: Gated Modulation (Dephase + Range)

volume: -6.0
volume_range: 20.0        # Range ampio
dephase:
  pc_rand_volume: 5       # Solo 5% di probabilità

→ Il 95% dei grani è pulito. Il 5% "esplode" con variazioni enormi.

Parametri

pc_rand_reverse

• Tipo: Numero o Envelope
• Default: None (mai flip)
• Bounds: 0.0 - 100.0 %
• Descrizione: Probabilità che il grano venga riprodotto al contrario rispetto alla norma

dephase:
  pc_rand_reverse: 10     # 10% dei grani al contrario

pc_rand_duration

• Tipo: Numero o Envelope
• Default: None
• Bounds: 0.0 - 100.0 %
• Descrizione: Gate per grain.duration_range

pc_rand_pan

• Tipo: Numero o Envelope
• Default: None
• Bounds: 0.0 - 100.0 %
• Descrizione: Gate per pan_range

pc_rand_volume

• Tipo: Numero o Envelope
• Default: None
• Bounds: 0.0 - 100.0 %
• Descrizione: Gate per volume_range

Esempio Completo Dephase

streams:
  - stream_id: "glitch_texture"
    onset: 0.0
    duration: 30.0
    sample: "pippo.wav"
    
    grain:
      duration: 0.05
      duration_range: 0.02
      
    volume: -6.0
    volume_range: 12.0
    
    pan: 0.0
    pan_range: 90.0
    
    dephase:
      # Probabilità che crescono nel tempo
      pc_rand_reverse:
        type: step
        points: [[0, 0], [10, 10], [20, 50], [30, 100]]
      pc_rand_duration: 30
      pc_rand_pan: 50
      pc_rand_volume: 20

---

10. Sistema Envelope

Qualsiasi parametro numerico può essere sostituito da un envelope per creare variazioni nel tempo.

Formati Supportati

1. Lista semplice (lineare)

parameter: [[0, 10], [5, 50], [10, 10]]
#           tempo, valore

2. Dict con tipo esplicito

parameter:
  type: cubic             # 'linear' | 'cubic' | 'step'
  points: [[0, 10], [5, 50], [10, 10]]

3. Dict con normalizzazione locale

parameter:
  type: linear
  time_unit: normalized   # Override del time_mode dello stream
  points: [[0, 10], [0.5, 50], [1, 10]]

Tipi di Interpolazione

linear (default)

Interpolazione lineare tra i breakpoints.

volume: [[0, -12], [10, -3]]

cubic

Interpolazione cubica Hermite (Fritsch-Carlson). Curve morbide senza overshoot.

volume:
  type: cubic
  points: [[0, -12], [5, -3], [10, -12]]

step

Valori a gradini (sample-and-hold). Utile per cambi discreti.

volume:
  type: step
  points: [[0, 1], [5, 4], [10, 2]]

Comportamento ai Bordi

• Prima del primo breakpoint: mantiene il primo valore
• Dopo l'ultimo breakpoint: mantiene l'ultimo valore

---

11. Funzionalità Avanzate

Espressioni Matematiche

Il parser YAML supporta espressioni matematiche racchiuse tra parentesi:

streams:
  - stream_id: "math_example"
    onset: 0.0
    duration: (60 * 2)              # 120 secondi
    sample: "file.wav"
    
    grain:
      duration: (1/20)              # 0.05 secondi
      
    pointer:
      speed: (1/3)                  # Un terzo della velocità
      
    pitch:
      shift_semitones: (12 + 7)     # 19 semitoni (ottava + quinta)

Funzioni disponibili:

• Operatori: +, -, *, /
• Funzioni: abs, int, float, min, max, pow
• Costanti: pi, e

pan: (pi * 180 / 3.14159)           # Conversione radianti → gradi
volume: (max(-12, -6 - 3))          # -9 dB

Sezione Composition

Metadati opzionali per la composizione:

composition:
  title: "Nome della composizione"

streams:
  - stream_id: "stream1"
    # ...

---

12. Tabella Riassuntiva Bounds

Parametri Principali

Parametro	Min	Max	Default	Unità
grain.duration	0.0001	10.0	0.05	secondi
grain.duration_range	0.0	1.0	0.0	secondi
fill_factor	0.001	50.0	2.0	ratio
density	0.1	4000.0	-	grani/s
distribution	0.0	1.0	0.0	ratio
pointer.speed	-100.0	100.0	1.0	ratio
pointer.offset_range	0.0	1.0	0.0	normalizzato
pitch.ratio	0.125	8.0	1.0	ratio
pitch.shift_semitones	-36.0	36.0	-	semitoni
pitch.range (semi)	0.0	36.0	0.0	semitoni
pitch.range (ratio)	0.0	2.0	0.0	ratio
volume	-120.0	12.0	-6.0	dB
volume_range	0.0	12.0	0.0	dB
pan	-3600.0	3600.0	0.0	gradi
pan_range	0.0	360.0	0.0	gradi

Parametri Dephase

volume pan

---

Esempio Completo Progressivo

Livello 1: Minimo

streams:
  - stream_id: "basic"
    onset: 0.0
    duration: 10.0
    sample: "sound.wav"

Livello 2: Con Grain e Pointer

streams:
  - stream_id: "level2"
    onset: 0.0
    duration: 10.0
    sample: "sound.wav"
    
    grain:
      duration: 0.03
      envelope: gaussian
      
    pointer:
      speed: 0.5

Livello 3: Con Density e Pitch

streams:
  - stream_id: "level3"
    onset: 0.0
    duration: 10.0
    sample: "sound.wav"
    
    grain:
      duration: [[0, 0.02], [10, 0.08]]
      envelope: hanning
      
    pointer:
      speed: [[0, 1.0], [10, 0.1]]
      
    fill_factor: 3.0
    distribution: [[0, 0], [10, 1]]
    
    pitch:
      shift_semitones: -12
      range: 3

Livello 4: Multi-Voice

streams:
  - stream_id: "level4"
    onset: 0.0
    duration: 10.0
    sample: "sound.wav"
    time_mode: normalized
    
    grain:
      duration: 0.05
      duration_range: 0.01
      envelope: blackman
      
    pointer:
      speed: 0.5
      loop_start: 0.2
      loop_end: 0.8
      loop_unit: normalized
      
    fill_factor: [[0, 1], [1, 4]]
    distribution: 0.3
    
    pitch:
      shift_semitones: 0
      range: 7
      
    voices:
      number: [[0, 1], [0.5, 6], [1, 2]]
      offset_pitch: 7
      pointer_offset: 0.1
      
    volume: [[0, -20], [0.1, -6], [0.9, -6], [1, -20]]
    pan: [[0, -45], [1, 45]]
    pan_range: 30

Livello 5: Con Dephase (Glitch)

streams:
  - stream_id: "full_glitch"
    onset: 0.0
    duration: 30.0
    sample: "voice.wav"
    time_mode: normalized
    
    grain:
      duration:
        type: cubic
        points: [[0, 0.01], [0.5, 0.08], [1, 0.02]]
      duration_range: 0.01
      envelope: expodec
      reverse: auto
      
    pointer:
      start: 0.0
      speed: [[0, 1], [0.3, 0.5], [0.7, 2], [1, 0.1]]
      offset_range: [[0, 0], [0.5, 0.3], [1, 0]]
      loop_unit: normalized
      loop_start: 0.1
      loop_dur:
        type: cubic
        points: [[0, 0.8], [1, 0.05]]
        
    fill_factor: [[0, 2], [0.5, 5], [1, 1]]
    distribution: [[0, 0], [0.3, 0.5], [0.7, 1], [1, 0.3]]
    
    pitch:
      shift_semitones: [[0, 0], [0.5, 12], [1, -7]]
      range: [[0, 0], [1, 12]]
      
    voices:
      number:
        type: step
        points: [[0, 1], [0.2, 4], [0.6, 8], [0.9, 2]]
      offset_pitch:
        type: cubic
        points: [[0, 0], [0.5, 12], [1, 5]]
      pointer_offset: [[0, 0], [0.5, 0.3], [1, 0]]
      pointer_range: 0.05
      
    volume: [[0, -30], [0.05, -6], [0.95, -6], [1, -30]]
    volume_range: 6.0
    
    pan: [[0, 0], [0.25, -60], [0.5, 60], [0.75, -30], [1, 0]]
    pan_range: [[0, 0], [0.5, 90], [1, 20]]
    
    dephase:
      pc_rand_reverse:
        type: step
        time_unit: normalized
        points: [[0, 0], [0.3, 10], [0.6, 30], [0.9, 80]]
      pc_rand_duration: 40
      pc_rand_pan: [[0, 0], [1, 60]]
      pc_rand_volume: 15