audio.loadStream()

Type Function
Library audio.*
Return value Object (audio handle)
Revision Current Public Release (2017.3068)
Keywords audio, load, stream
See also audio.loadSound()
audio.dispose()
Audio Usage/Functions (guide)

Overview

Loads (opens) a file to be read as streaming audio. Streamed files are read in little chunks at a time to minimize memory use. These are intended for large/long files like background music and speech. Unlike files loaded with audio.loadSound(), these cannot be shared simultaneously across multiple channels. If you need to play multiple simulataneous instances of the same file, you must load multiple instances of the file.

This function returns a handle to a sound file.

Gotchas

Please note that you are responsible for unloading (cleaning up) any audio files you load with this API. Use the audio.dispose() API to clean up audio handles you are completely done with them and want to unload from memory to get back more RAM.

In many usage cases, you may want to use the audio file for the entire program in which case you do not need to worry about disposing of the resource.

Also note that streamed files may have slightly higher latency costs than files loaded with audio.loadSound(). They also may have slightly higher runtime (CPU) cost to play than files loaded with audio.loadSound().

See the Audio Usage/Functions guide for details on supported audio formats and notes.

Syntax

audio.loadStream( audioFileName [, baseDir ]  )
audioFileName (required)

String. Specifies the name of the audio file you want to load. Supported file formats are determined by the platform you are running on.

baseDir (optional)

Constant. By default sound files are expected to be in the project folder (system.ResourceDirectory). If the sound file is in the application documents directory, use system.DocumentsDirectory.

Example

local backgroundMusic = audio.loadStream("backgroundMusic.m4a")
local narrationSpeech = audio.loadStream("narrationSpeech.wav")