Home

RenPy Dynamic Ambient System

A flexible dynamic ambient audio management system for Ren'Py 8.4+ that allows playing multiple audio tracks simultaneously with configurable randomness, volume, smooth transitions, and complex audio scene arrangements.

Current Version: 2.0.0
CDS Version: Ren'Py 8.5.0+
License: MIT

---

🎯 Overview

The Dynamic Ambient System transforms how you handle background audio in Ren'Py visual novels. Instead of simple looping tracks, you can create rich, layered soundscapes that evolve over time.

Key Capabilities

• Multi-track playback — Play multiple audio tracks simultaneously on separate channels
• Independent Control — Separate channels and mixers for Music and Ambient sounds
• Track types — Mandatory (always playing) and Random (probability-based) tracks
• Smooth transitions — All volume changes use configurable fade in/out
• Arrangement system — Define complex audio scenes with layers
• YAML configuration — Easy-to-edit configuration files
• Creator-Defined Statements — Native Ren'Py commands for ambient control
• Wave system — Pseudo-random elevation of ambient layers
• Main theme support — Intro theme that transitions to ambient

---

📚 Documentation

Getting Started

• Installation — How to install and configure the system
• Quick-Start — Get up and running in 5 minutes
• Project-Structure — Understanding the file layout
• Demo-Project — Running the included demo

Core Concepts

• Track-Types — Mandatory vs Random tracks explained
• Arrangements — Creating audio scenes with layers
• Wave-System — How random track elevation works
• Main-Theme — Configuring intro music

Configuration

• Audio-Assets-YAML — Defining tracks in audio_assets.yaml
• Arrangements-YAML — Creating arrangements in arrangements.yaml
• Configuration-Reference — Complete parameter reference

Usage

• CDS-Reference — Creator-Defined Statements guide
• Python-API — Full Python API documentation
• Integration-Examples — Real-world usage patterns

Advanced

• Layers — Dynamic layer control
• Dynamic-Reconfiguration — Changing track behavior at runtime
• Random-Containers — Multiple files per track
• Debugging — Debug tools and troubleshooting

Migration & Reference

• Migration-from-v1 — Upgrading from version 1.x
• Troubleshooting — Common issues and solutions
• FAQ — Frequently asked questions

---

🚀 Quick Example

YAML Configuration:

# audio_assets.yaml
# audio_assets.yaml
music:
  bgm_forest:
    file: "music/forest_theme.ogg"
    type: "mandatory"

ambient:
  forest_base:
    file: "audio/forest_ambient.ogg"
    type: "mandatory"
    volume: 0.6

  birds:
    file: "audio/birds.ogg"
    type: "random"
    volume: 0.4
    chance: 0.3
    interval: [30, 120]

# arrangements.yaml
arrangements:
  forest_morning:
    tracks:
      forest_base: { volume: 0.6 }
      birds: { volume: 0.8 }

In your script:

label forest_scene:
    scene bg forest
    
    ambient play "forest_morning"
    
    "You enter the peaceful forest..."

---

📋 Requirements

• Ren'Py: 8.4 or higher
• Python: PyYAML library (included in installation)
• CDS: Ren'Py 8.5.0+ for Creator-Defined Statements

---

🔗 Links

• GitHub Repository
• Release Notes v2.0.0
• Issue Tracker

---

📝 Changelog Highlights (v2.0.0)

• ✅ YAML configuration system
• ✅ Creator-Defined Statements (CDS)
• ✅ Arrangement system with layers
• ✅ Automatic transitions between arrangements
• ✅ Random containers (multiple files per track)
• ✅ Strict track isolation
• ✅ Enhanced debugging tools