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.

Functions

proAudio.create( tracks = 8, frequency = 22050, chunkSize = 1024 )

initializes audio playback device

Parameters:

tracks (optional) number of sounds that can be played in parallel
frequency (optional) playback frequency
chunkSize (optional) size of the internal buffer in bytes. Note that a small chunkSize results in low playback latency, but may cause computational overhead and hick-ups under higher system load

Returns: true in case the device initialization was successful

proAudio.destroy( )

closes audio device and terminates playback

Returns: true in case the device was successfully closed

proAudio.loaderAvailable ( suffix )

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

proAudio.volume 	(  left, [ right ] )

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

proAudio.sleep( seconds )

Suspends the execution of the current thread for a definable number of seconds. Note that audio mixing and playback runs in its own background thread and is therefore not affected by this auxiliary call.

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.sampleDestroy ( sample )

deletes a previously created sound sample resource identified by its handle

duration, channels, sampleRate, bitsPerSample = proAudio.sampleProperties ( sample )

returns properties of a sample identified by its 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

Example 1

-- 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:
while proAudio.soundActive()>0 do
  proAudio.sleep(0.05)
end

-- close audio device
proAudio.destroy()

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. Note that for obtaining good qualities when doing dynamic pitch shifts high sample rates (up to 88200) are recommended.

Example 2

-- function creating a sine wave sample:
function sampleSine(freq, duration, sampleRate)
	local data = { }
	for i = 1,duration*sampleRate do
		data[i] = math.sin( (i*freq/sampleRate)*math.pi*2)
	end
	return proAudio.sampleFromMemory(data, sampleRate)
end

-- plays a sample shifted by a number of halftones for a definable period of time
function playNote(sample, pitch, duration, volumeL, volumeR, disparity)
	local scale = 2^(pitch/12)
	local sound = proAudio.soundLoop(sample, volumeL, volumeR, disparity, scale)
	proAudio.sleep(duration)
	proAudio.soundStop(sound)
end

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

-- generate a sample:
local sample = sampleSine(440, 0.5, 88200)

-- play scale (a major):
local duration = 0.5
for i,note in ipairs({ 0, 2, 4, 5, 7, 9, 11, 12 }) do
	playNote(sample, note, duration)
end

-- cleanup
proAudio.destroy()

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