proteaAudio Lua API

Overview

Lua is a lightweight yet powerful dynamic language. proteaAudio contains almost complete Lua bindings that widely correspond to the C++ API. By default, the proteaAudio Lua bindings are compiled to a dynamic library based on the RtAudio backend which is imported via the following statement:

require("proAudioRt")

All API calls are collected in the global table proAudio. Therefore, proteaAudio is initialized (using the default parameters) by the following call:

proAudio.create()

After that the individual methods and functions may be called analogous to the C++ interface of class DeviceAudio. For further detail information, please refer to its documentation or have a look at the following minimal example:

Functions

proAudio.loaderAvailable ( suffix )

returns true in case a loader for this file type is available

proAudio.sampleDestroy ( sample )

deletes a previously created sound sample resource identified by its handle

proAudio.sampleFromFile (  filename, volume = 1.0 )

loads a sound sample from file, optionally adjusts volume, returns handle

proAudio.sampleFromMemory 	( data, sampleRate )

converts an array of numeric data into a sound sample having the defined sample rate, returns handle

proAudio.soundActive ( )

returns number of currently active sounds

proAudio.soundLoop ( sample, volumeL = 1.0, volumeR = 1.0, disparity = 0.0, pitch = 1.0 )

plays a specified sound sample continuously and sets its parameters

Parameters:

sample handle of a previously loaded sample
volumeL (optional) left volume
volumeR (optional) right volume
disparity (optional) time difference between left and right channel in seconds. Use negative values to specify a delay for the left channel, positive for the right.
pitch (optional) pitch factor for playback. 0.5 corresponds to one octave below, 2.0 to one above the original sample.

Returns: a handle to the currently played sound or -1 in case of error

proAudio.soundPlay ( sample, volumeL = 1.0, volumeR = 1.0, disparity = 0.0, pitch = 1.0 )

plays a specified sound sample once and sets its parameters

Parameters:

sample handle of a previously loaded sample
volumeL (optional) left volume
volumeR (optional) right volume
disparity (optional) time difference between left and right channel in seconds. Use negative values to specify a delay for the left channel, positive for the right.
pitch (optional) pitch factor for playback. 0.5 corresponds to one octave below, 2.0 to one above the original sample.

Returns: a handle to the currently played sound or -1 in case of error

proAudio.soundStop 	(  [ sound ] )

stops a specified sound immediately, if a sound handle is passed, or stops all sounds

proAudio.soundUpdate ( sound, volumeL, volumeR, disparity = 0.0, pitch = 1.0 )

updates parameters of a specified sound

Parameters:

sound handle of a currently active sound
volumeL left volume
volumeR right volume
disparity (optional) time difference between left and right channel in seconds. Use negative values to specify a delay for the left channel, positive for the right.
pitch (optional) pitch factor for playback. 0.5 corresponds to one octave below, 2.0 to one above the original sample.

Returns: true in case the parameters have been updated successfully

proAudio.volume 	(  left, [ right ] )

sets master volume, either for both channels uniformly, or individually

Example

-- create an audio device using default parameters or exit in case of errors
require("proAudioRt")
if not proAudio.create() then os.exit(1) end

-- load and play a sample:
sample = proAudio.sampleFromFile("sample.ogg")
if sample then proAudio.soundPlay(sample) end

-- wait until the sound has finished:
--   for the sake of simplicity busy waiting instead of a preferable sleep
while proAudio.soundActive()>0 do end

-- cleanup and exit
proAudio.destroy()
os.exit(0)

Dynamic creation of audio samples

There is no equivalent to the C++ AudioSample class in the proteaAudio Lua API. However, mono audio samples may be dynamically created by the following call:

proAudio.sampleFromMemory(data, sampleRate)

The data parameter has to be a table reference containing an array of numeric PCM data ranging from -1.0 to +1.0. The sampleRate parameter defines the number of samples per second. Typical sample rates are 22050 or 44100.

Limitations

The proteaAudio Lua API currently has no equivalent to the C++ API's DeviceAudio::loaderRegister() method.
no bindings to the SDL backend yet

impressum