Wave System

Wave System

The wave system controls how random tracks are elevated and lowered over time, creating dynamic, evolving soundscapes.

---

Overview

Instead of random tracks playing at arbitrary times, the wave system groups elevations into "waves" with rest periods between them. This creates a more natural, breathing rhythm to your ambient audio.

---

How It Works

Phase 1: Initial Cooldown

When the ambient system starts, it waits for an initial cooldown period (~15 seconds) before any random tracks can be elevated. This allows mandatory tracks to establish the base atmosphere.

Phase 2: Wave Start

The system determines how many tracks can be elevated in this wave (1-3 by default).

Phase 3: Elevation Attempts

Each random track that isn't already elevated gets a chance to be elevated:

• System rolls against the track's chance parameter
• If successful, track fades from minimum volume to target volume
• Track is marked as "elevated"

Phase 4: Elevated Playback

Elevated tracks play at their target volume for a random duration within their interval range.

Phase 5: Lowering

When a track's elevation duration expires:

• Track fades back to minimum volume
• Track is marked as "not elevated"
• System checks if wave is complete

Phase 6: Rest Period

When all elevated tracks have lowered:

• Wave counters reset
• System enters rest period (10-30 seconds)
• After rest, new wave begins

---

Visual Timeline

Time:    0s        15s       25s              55s       65s       85s
         |----------|---------|----------------|---------|---------|----
Phase:   Initial    Wave 1    Rest Period      Wave 2    Rest      Wave 3
         Cooldown

Tracks:
  A:     [min]      [ELEVATED for 30s]         [min]     [min]     [ELEVATED]
  B:     [min]      [ELEVATED for 20s]         [min]     [min]     [min]
  C:     [min]      [min]                      [ELEVATED for 25s]  [min]

---

System Parameters

These are internal defaults in DynamicAmbientSystem:

Parameter	Default	Description
initial_cooldown_time	15.0	Seconds before first wave
minimum_rest_time	10.0	Minimum rest between waves
maximum_rest_time	30.0	Maximum rest between waves
min_tracks_per_wave	1	Minimum tracks per wave
max_tracks_per_wave	3	Maximum tracks per wave
minimum_volume	0.00	Volume when not elevated

---

Track Parameters

Each random track has parameters that affect wave behavior:

tracks:
  birds:
    type: "random"
    volume: 0.5
    chance: 0.4           # 40% chance per elevation attempt
    interval: [30, 120]   # Elevated for 30-120 seconds
    fade_in: 3.0          # Fade in when elevating
    fade_out: 3.0         # Fade out when lowering

chance

Probability (0.0-1.0) that the track will be elevated when attempted.

• Higher = more likely to play
• Lower = rarer occurrence

interval

[min_seconds, max_seconds] — How long the track stays elevated.

• Actual duration is random within this range
• Longer intervals = more sustained presence

---

Wave Behavior Examples

High Activity Scene

tracks:
  effect_1:
    type: "random"
    chance: 0.7           # High chance
    interval: [20, 40]    # Short duration
  
  effect_2:
    type: "random"
    chance: 0.6
    interval: [15, 30]
  
  effect_3:
    type: "random"
    chance: 0.5
    interval: [25, 45]

Result: Frequent waves, multiple tracks elevated, busy soundscape.

Sparse Scene

tracks:
  rare_sound:
    type: "random"
    chance: 0.15          # Low chance
    interval: [60, 180]   # Long duration when it plays
  
  occasional_sound:
    type: "random"
    chance: 0.25
    interval: [45, 90]

Result: Infrequent waves, often single track, sparse atmosphere.

---

Interaction with Arrangements

Strict Isolation

Only tracks defined in the current arrangement participate in waves:

arrangements:
  forest:
    tracks:
      birds: { volume: 0.5 }      # Participates in waves
      wind: { volume: 0.4 }       # Participates in waves
      # thunder NOT listed - won't elevate even if defined in audio_assets

Layer Activation

When a layer is activated, its tracks join the wave pool:

arrangements:
  outdoor:
    tracks:
      base: { volume: 0.5 }
    layers:
      rain:
        rain_drops: { volume: 0.6 }   # Only in waves when layer active

ambient play "outdoor"
# Only 'base' in wave pool

ambient layer "rain" on
# Now 'base' AND 'rain_drops' in wave pool

---

Debugging Waves

Console Output

The system prints debug information:

DEBUG: Track birds target_volume: 0.00 -> 0.35, type=random

Debug UI

Use ambient debug ui to see:

• Current wave status (e.g., "Wave: 2/3")
• Elevated track count
• Cooldown timer
• Fading tracks count

Debug Commands

ambient debug info      # Basic system state
ambient debug tracks    # All track volumes and states

---

Tips for Wave Design

Natural Soundscapes

• Use 3-5 random tracks with varying chance values
• Mix short and long interval ranges
• Lower chance for distinctive sounds

Tension Building

• Start with low chance values
• Use arrangement override to increase chance as tension rises
• Or switch to arrangement where sounds are mandatory

Avoiding Repetition

• Use Random-Containers for variety
• Spread interval ranges to avoid predictable patterns
• Don't make all tracks have similar chance values