Random Containers

Random Containers

Random containers allow you to specify multiple audio files for a single track, with one randomly selected each time the track plays.

---

Concept

Instead of a single file:

thunder:
  file: "audio/thunder.ogg"

You can specify multiple files:

thunder:
  files:
    - "audio/thunder1.ogg"
    - "audio/thunder2.ogg"
    - "audio/thunder3.ogg"

Each time the track plays, one file is randomly chosen.

---

Configuration

Single File (Standard)

tracks:
  wind:
    file: "audio/wind.ogg"
    type: "random"
    volume: 0.5

Multiple Files (Random Container)

tracks:
  wind:
    files:                    # Note: 'files' not 'file'
      - "audio/wind_light.ogg"
      - "audio/wind_medium.ogg"
      - "audio/wind_strong.ogg"
    type: "random"
    volume: 0.5
    chance: 0.3
    interval: [30, 90]

---

Behavior

Selection

• One file is randomly selected when the track starts
• Selection happens each time the track begins playing
• For looping tracks, the same file loops until stopped

When Selection Occurs

Mandatory tracks:

• Selected once when arrangement starts
• Same file loops continuously

Random tracks:

• Selected when track is elevated
• New selection each elevation cycle

---

Use Cases

Sound Variations

tracks:
  footsteps:
    files:
      - "audio/step1.ogg"
      - "audio/step2.ogg"
      - "audio/step3.ogg"
      - "audio/step4.ogg"
    type: "random"
    volume: 0.4
    chance: 0.5
    interval: [5, 15]

Thunder Variety

tracks:
  thunder:
    files:
      - "audio/thunder_distant.ogg"
      - "audio/thunder_close.ogg"
      - "audio/thunder_rolling.ogg"
      - "audio/thunder_crack.ogg"
    type: "random"
    volume: 0.7
    chance: 0.2
    interval: [30, 90]

Bird Calls

tracks:
  birds:
    files:
      - "audio/bird_chirp.ogg"
      - "audio/bird_song.ogg"
      - "audio/bird_call.ogg"
      - "audio/bird_twitter.ogg"
    type: "random"
    volume: 0.5
    chance: 0.4
    interval: [20, 60]

Ambient Variations

tracks:
  room_tone:
    files:
      - "audio/room_tone_1.ogg"
      - "audio/room_tone_2.ogg"
    type: "mandatory"
    volume: 0.3

---

Complete Example

# audio_assets.yaml
tracks:
  # Base ambient - single file (loops continuously)
  forest_base:
    file: "audio/forest_ambient.ogg"
    type: "mandatory"
    volume: 0.5

  # Bird calls - random selection each time
  birds:
    files:
      - "audio/birds/songbird.ogg"
      - "audio/birds/crow.ogg"
      - "audio/birds/woodpecker.ogg"
      - "audio/birds/owl.ogg"
    type: "random"
    volume: 0.4
    chance: 0.4
    interval: [15, 45]

  # Wind gusts - variety of intensities
  wind_gust:
    files:
      - "audio/wind/gust_light.ogg"
      - "audio/wind/gust_medium.ogg"
      - "audio/wind/gust_strong.ogg"
    type: "random"
    volume: 0.6
    chance: 0.25
    interval: [30, 90]

  # Distant sounds - random environmental
  distant_sounds:
    files:
      - "audio/distant/dog_bark.ogg"
      - "audio/distant/car_horn.ogg"
      - "audio/distant/church_bell.ogg"
      - "audio/distant/train.ogg"
    type: "random"
    volume: 0.3
    chance: 0.15
    interval: [60, 180]

---

Best Practices

File Organization

audio/
├── ambient/
│   └── forest_base.ogg
├── birds/
│   ├── songbird.ogg
│   ├── crow.ogg
│   └── woodpecker.ogg
├── wind/
│   ├── gust_light.ogg
│   ├── gust_medium.ogg
│   └── gust_strong.ogg
└── thunder/
    ├── distant.ogg
    ├── close.ogg
    └── rolling.ogg

Consistent Volume

Normalize audio files to similar volume levels so random selection doesn't cause jarring volume changes.

Similar Duration

For looping tracks, keep file durations similar to maintain consistent rhythm.

Meaningful Variety

Each file should be noticeably different to justify the variety. Don't add files that sound identical.

---

Limitations

No Weighted Selection

Currently, all files have equal probability. You cannot weight certain files to play more often.

Workaround: Duplicate entries for higher probability:

tracks:
  birds:
    files:
      - "audio/common_bird.ogg"    # 50% chance
      - "audio/common_bird.ogg"    # (duplicate)
      - "audio/rare_bird.ogg"      # 25% chance
      - "audio/very_rare_bird.ogg" # 25% chance

No Sequential Playback

Files are randomly selected, not played in sequence.

Single Selection Per Play

The same file plays for the entire elevation duration. It doesn't switch mid-playback.

---

Troubleshooting

"Track has no filename"

Error: Track ID 'birds' has no filename and is not in registry.

• Check that you used files: (plural) not file:
• Ensure the list is properly formatted

Empty Container

# This will cause issues
tracks:
  empty:
    files: []    # Empty list - no files to play

Missing Files

If a file in the list doesn't exist, you'll get a Ren'Py audio error when that file is selected.

Verify all files exist:

audio/birds/songbird.ogg    ✓
audio/birds/crow.ogg        ✓
audio/birds/missing.ogg     ✗ Error when selected