_{Official ZPE/YASS documentation}AudioStream

Introduction

The AudioStream object provides a simple way to load and play short audio clips from a URL or file path. Internally it uses Java's javax.sound.sampled.Clip implementation.

The typical workflow is:

• Create a new AudioStream instance
• Open an audio stream using open_stream
• Play the audio either synchronously (play) or asynchronously (play_async)
• Optionally query the clip length using length

All functions exposed by this object require a permission level of 0.

AudioStream object functions

The following is a list of internal functions the AudioStream object exposes. All functions are ZPEObjectNativeFunctions therefore run in native code.

open_stream(string url) ⇒ boolean

Opens an audio stream from a URL or file path and prepares it for playback. Returns true if the stream was successfully opened, otherwise false.

play() ⇒ boolean

Plays the currently opened clip and blocks until playback has finished. Once finished, the internal frame position is reset to the start of the clip. Returns true.

play_async() ⇒ boolean

Plays the currently opened clip without blocking the current script. The frame position is reset to the start immediately after starting playback. Returns true.

length() ⇒ number

Returns the length of the currently opened clip in milliseconds.

Examples

This example opens a clip and plays it synchronously (the program will pause until the clip finishes):

$audio = new AudioStream()

if ($audio->open_stream("sounds/notify.wav"))
    print("Length (ms): " + $audio->length())
    $audio->play()
else
    print("Failed to open audio stream.")
end

This example plays audio asynchronously, allowing your program to continue running:

$audio = new AudioStream()

if ($audio->open_stream("sounds/alert.wav"))
    $audio->play_async()
    print("Playing... program continues immediately.")
end

# Do other work here...

Notes:

• Stream must be opened first: You must call open_stream before calling play, play_async or length.
• Synchronous vs asynchronous: play blocks the script until the clip finishes, while play_async returns immediately.
• Clip length: length returns the duration in milliseconds.
• Reset behaviour: Both play and play_async reset the clip back to the start so it can be played again without re-opening.