Audio Playing

You can play any sound you want anytime by calling the cave.playSound function. You'll need to pass the asset name for the sound (exactly how it is written in the asset browser) and the optional parameters:

Parameter	Description
volume	How loud or quiet the sound will be. 0 means muted, 1 means max.
fadeIn	In seconds, if greated than zero, it will slowly fade in the sound by the amount of time you pass.
loop	How many times you want the sound to be played. -1 means that it will play forever, zero means that it will play once and 1 (or more) means that it will play and repeat by 1 (or the number you pass).

This function returns an AudioTrackInstance that allows you to later change those values, pause/resume the sound and more. Reference code:

cave.playSound(name: str, volume=1.0, fadeIn=0.0, loop=0) -> AudioTrackInstance

---

The Audio Handler

As explained above, by calling cave.playSound, the function will return AudioTrackInstance. Here is everything you need to know about it:

cave.AudioTrackInstance

Here is an example of the AudioTrackInstance in action. The following component only plays the sound if the scene is NOT paused:

class AudioExample(cave.Component):
    def start(self, scene):
        self.handler = cave.playAudio("MyCoolSound.ogg", 1.0)

    def update(self):
        if self.handler.isPaused():
            self.handler.resume()

    def pausedUpdate(self):
        if self.handler.isPlaying():
            self.handler.pause()

Variables

You can use this variable to adjust the sound volume. Keep in mind that it must be between 0 and 1.

volume : float

Methods

Here is the basic operations to work with the sound (pause, resume and stop):

pause()
resume()

# If you pass a fadeout (in seconds), if will slowly fade out the audio until it stops.
stop(fadeOut=0.0)

You can also use the handler to check certain things and status of it:

# Returns true if the track is being played or is paused. False if not:
isActive() -> bool

isPlaying() -> bool
isPaused()  -> bool
isFadingIn()  -> bool
isFadingOut() -> bool

# Returns the channel that this audio is being played at:
getChannel() -> int

3D Sounds:

Cave Engine supports 3D sounds, but you'll need to manually call this method every frame in order to update it:

calculate3D(audioPos: Vector3, maxDistance=100.0)