Python API

Python API

Complete reference for the DynamicAmbientSystem Python API.

---

Accessing the System

The system is available as a global ambient object:

$ ambient.play_arrangement("scene_name")

Or in Python blocks:

init python:
    # Access in init
    pass

label some_label:
    python:
        ambient.play_arrangement("scene_name")

---

Core Methods

play_arrangement()

Transitions to a specified arrangement.

ambient.play_arrangement(name, fade_time=None)

Parameters:

Parameter	Type	Default	Description
name	str	—	Arrangement name
fade_time	float	None	Override fade duration

Behavior:

• Auto-starts system if not active
• Stops tracks not in new arrangement
• Starts/adjusts tracks in new arrangement
• Cancels any pending auto-transition

Example:

$ ambient.play_arrangement("forest_morning")
$ ambient.play_arrangement("forest_night", fade_time=5.0)

---

stop_ambient()

Stops the ambient system.

ambient.stop_ambient(fade_out=True)

Parameters:

Parameter	Type	Default	Description
fade_out	bool	True	Smooth fade out

Behavior:

• Fades all tracks to zero (if fade_out=True)
• Stops all audio channels
• Cancels all timers
• Resets system state

Example:

$ ambient.stop_ambient()           # Smooth stop
$ ambient.stop_ambient(False)      # Immediate stop

---

stop_category()

Stops tracks of a specific category (music or ambient).

ambient.stop_category(category, fade_out=True)

Parameters:

Parameter	Type	Default	Description
category	str	—	"music" or "ambient"
fade_out	bool	True	Smooth fade out

Example:

$ ambient.stop_category("music")
$ ambient.stop_category("ambient", fade_out=False)

---

start_ambient()

Starts the ambient system without main theme.

ambient.start_ambient(delay_after_main_theme=0)

Parameters:

Parameter	Type	Default	Description
delay_after_main_theme	float	0	Delay before starting

Behavior:

• Assigns channels to tracks
• Starts mandatory tracks
• Starts random tracks at minimum volume
• Begins wave system

Example:

$ ambient.start_ambient()
$ ambient.start_ambient(delay_after_main_theme=5)

---

start_with_main_theme()

Starts the main theme → ambient sequence.

ambient.start_with_main_theme()

Behavior:

1. Plays main theme with fade in
2. Monitors playback
3. Fades out at configured time
4. Transitions to after_theme_arrangement

Example:

$ ambient.start_with_main_theme()

---

Layer Control

set_layer()

Enables or disables a layer in the current arrangement.

ambient.set_layer(layer_name, active=True, fade_time=None)

Parameters:

Parameter	Type	Default	Description
layer_name	str	—	Layer name
active	bool	True	Enable/disable
fade_time	float	None	Override fade duration

Example:

$ ambient.set_layer("rain", True)
$ ambient.set_layer("rain", False, fade_time=2.0)
$ ambient.set_layer("storm", active=True, fade_time=3.0)

---

Volume Control

set_base_volume()

Sets the master volume multiplier.

ambient.set_base_volume(volume, category=None)

Parameters:

Parameter	Type	Default	Description
volume	float	—	Volume level (0.0-1.0)
category	str	None	"music", "ambient", or None (both)

Behavior:

• Updates track target volumes for specified category
• Changes apply smoothly via fade system

Example:

$ ambient.set_base_volume(0.5)           # Sets global multiplier
$ ambient.set_base_volume(0.8, "music")  # Sets music volume
$ ambient.set_base_volume(1.0, "ambient") # Sets ambient volume

---

Playback Control

pause_ambient()

Pauses all ambient playback.

ambient.pause_ambient()

Example:

$ ambient.pause_ambient()

---

resume_ambient()

Resumes paused playback.

ambient.resume_ambient()

Example:

$ ambient.resume_ambient()

---

Scheduling

schedule_arrangement()

Schedules an arrangement transition after a delay.

ambient.schedule_arrangement(name, delay)

Parameters:

Parameter	Type	Description
name	str	Target arrangement
delay	float	Delay in seconds

Example:

$ ambient.schedule_arrangement("night_ambient", 60.0)

---

Configuration Methods

set_main_theme()

Configures the main theme.

ambient.set_main_theme(
    filename,
    duration=60,
    volume=0.8,
    fade_in_time=2.0,
    fade_out_time=3.0,
    after_theme_arrangement=None
)

Parameters:

Parameter	Type	Default	Description
filename	str	—	Audio file path
duration	float	60	Playback duration
volume	float	0.8	Volume level
fade_in_time	float	2.0	Fade in duration
fade_out_time	float	3.0	Fade out duration
after_theme_arrangement	str	None	Next arrangement

Example:

$ ambient.set_main_theme(
    "audio/theme.mp3",
    duration=45,
    volume=0.8,
    after_theme_arrangement="main_menu"
)

---

configure_track()

Configures a track programmatically.

ambient.configure_track(
    track_id,
    filename=None,
    track_type="random",
    category="ambient",
    volume=1.0,
    play_chance=0.5,
    min_duration=30,
    max_duration=120,
    fade_in_time=3.0,
    fade_out_time=3.0
)

Parameters: (See audio_assets.yaml documentation for parameter details)

• category: "music" or "ambient" (default: "ambient")

**Note:** Prefer YAML configuration. Use this for dynamic track creation.

---

### register_arrangement()

Registers an arrangement programmatically.

```python
ambient.register_arrangement(
    name,
    tracks_config,
    duration=None,
    auto_next=None,
    layers=None,
    on_enter=None,
    on_exit=None
)

Parameters:

Parameter	Type	Description
name	str	Unique arrangement name
tracks_config	dict	Track configurations
duration	float	Auto-transition delay
auto_next	str	Next arrangement
layers	dict	Layer definitions
on_enter	callable	Callback on enter
on_exit	callable	Callback on exit

Example:

$ ambient.register_arrangement(
    "custom_scene",
    tracks_config={
        "base": {"volume": 0.6},
        "effect": {"volume": 0.4}
    },
    layers={
        "rain": {
            "rain_sound": {"volume": 0.7}
        }
    }
)

---

load_config()

Reloads configuration from YAML files.

ambient.load_config()

Use case: Reload after modifying YAML during development.

---

Information Methods

get_ambient_runtime()

Returns ambient runtime in seconds.

runtime = ambient.get_ambient_runtime()

Returns: float — Seconds since ambient started, or 0 if inactive.

---

get_formatted_runtime()

Returns formatted runtime string.

runtime_str = ambient.get_formatted_runtime()

Returns: str — Format: "MM:SS" or "HH:MM:SS"

---

get_track_runtime()

Returns specific track runtime.

runtime = ambient.get_track_runtime(track_id)

Returns: float — Seconds since track started playing.

---

get_track_elevation_time()

Returns how long a random track has been elevated.

elevation_time = ambient.get_track_elevation_time(track_id)

Returns: float — Seconds at elevated volume, or 0 if not elevated.

---

Properties

is_active

if ambient.is_active:
    # System is running

active_arrangement

if ambient.active_arrangement:
    print(ambient.active_arrangement.name)

active_layers

for layer_name in ambient.active_layers:
    print(f"Layer active: {layer_name}")

tracks

for track_id, track_data in ambient.tracks.items():
    print(f"{track_id}: {track_data['current_volume']}")

base_volume

current_volume = ambient.base_volume

---

Complete Example

label complex_scene:
    python:
        # Check if ambient is running
        if not ambient.is_active:
            ambient.play_arrangement("forest_day")
        
        # Get current state
        runtime = ambient.get_formatted_runtime()
        
        # Conditional layer control
        if weather == "rainy":
            ambient.set_layer("rain", True, fade_time=3.0)
        
        # Dynamic volume based on game state
        if player_health < 30:
            ambient.set_base_volume(0.4)
        else:
            ambient.set_base_volume(0.7)
        
        # Schedule future transition
        if time_of_day == "evening":
            ambient.schedule_arrangement("forest_night", 120.0)
    
    "The forest surrounds you..."
    
    # Later...
    $ ambient.stop_ambient()

---

Error Handling

Methods generally fail silently with console warnings:

# These print warnings but don't crash
ambient.play_arrangement("nonexistent")  # "Arrangement 'nonexistent' not found."
ambient.set_layer("invalid", True)       # "Layer 'invalid' not found..."

For robust code, check state:

if "forest_day" in ambient.arrangements:
    ambient.play_arrangement("forest_day")