Skip to content

Latest commit

 

History

History
323 lines (226 loc) · 15.1 KB

README.md

File metadata and controls

323 lines (226 loc) · 15.1 KB

lrtaudio Documentation

Contents

Overview

lrtaudio is a Lua binding for RtAudio.

This binding enables Lua scripting code to open RtAudio streams and to connect them with Lua audio processor objects for realtime processing. Realtime audio processing of Lua processor objects has to be implemented in native C code.

Module Functions

  • lrtaudio.getRtAudioVersion()

    Returns the RtAudio version as string.

  • lrtaudio.getCompiledApi()

    Returns a string list of possible audio API names that can be used for creating a new controller object with lrtaudio.new().

    Possible API names for RtAudio 5.2.0: alsa, pulse, oss, jack, core, wasapi, asio, ds.

  • lrtaudio.new([apiName])

    Creates a new lrtaudio controller object.

    • apiName - optional string, name of the audio API that is used with this controller. If not given, the default order of use is jack, pulse, alsa, oss (Linux systems) and asio, wasapi, ds (Windows systems). For possible values see: lrtaudio.getCompiledApi()

Controller Methods

Controller objects are created by invoking the function lrtaudio.new(). A controller object can be used to create and control an audio processing stream of input / output channels on specified devices.

  • controller:getCurrentApi()

    Returns the audio API name used with this controller object. For possible values see lrtaudio.getCompiledApi().

  • controller:getDeviceCount()

    Returns the number of devices.

  • controller:getDeviceInfo([deviceId])

    Returns device information.

    • deviceId - optional integer. If not given, this method returns a list of device information for all possible devices. If given it must be: 1 <= deviceId <= controller:getDeviceCount()

    Device information for one device is given as Lua table with key value pairs. Possible entries are:

    • deviceId - device ID
    • probed - boolean value, true if the device capabilities were successfully probed.
    • name - device name string
    • outputChannels - maximum number of output channels supported by device
    • inputChannels - maximum number of input channels supported by device
    • duplexChannels - maximum number of simultaneous input/output channels supported by device.
    • isDefaultOutput - boolean value, true if this is the default output device.
    • isDefaultInput - boolean value, true if this is the default input device
    • sampleRates - list of supported sample rate integer values
    • preferredSampleRate - integer value
    • nativeFormats - list of strings of supported data formats, possible values: SINT8, SINT16, SINT24, SINT32, FLOAT32, FLOAT64.

  • controller:openStream(params)

    Opens the audio stream for this controller object with the specified parameters.

    • params - lua table with stream parameters.

    The parameter params may contain the following stream parameters as key value pairs:

    • streamName - optional string. The streamName parameter can be used to set the client name when using the Jack API. By default, the client name is set to "RtApiJack". However, if you wish to create multiple instances of RtAudio with Jack, each instance must have a unique client name.

    • inputChannels - optional integer. Number of channels used for audio input.

    • outputChannels - optional integer. Number of channels used for audio output.

    • inputDevice - optional integer. Device ID of the device used for audio input.

    • outputDevice - optional integer. Device ID of the device used for audio output.

    • sampleRate - optional integer. Sample rate to be used for audio input and output. The effective value chosen can be obtained by the method controller:getStreamSampleRate().

    • bufferFrames - optional integer. Buffer size for an audio processing cylce in number of samples. If not given, a default value of 256 is used. If set to 0, RtAudio tries to figure out the lowest possible value, but this does not work in all cases. The effective value chosen can be obtained by the method controller:getStreamBufferFrames().

    • minimizeLatency - optional boolean flag. If set to true, RtAudio attempts to set stream parameters for lowest possible latency.

    • hogDevice - optional boolean flag. If set to true, RtAudio attempts to grab device for exclusive use.

    • scheduleRealtime - optional boolean flag. If set to true, RtAudio attempts to select realtime scheduling for audio processing thread.

    • alsaUseDefault - optional boolean flag. If set to true, RtAudio uses the "default" PCM device (ALSA only).

    At least one input or output channel has to be specified.

  • controller:closeStream()

    Closes the controller's stream and frees any associated stream memory.

  • controller:startStream()

    Starts the stream's audio processing.

  • controller:stopStream()

    Stops the stream's audio processing.

  • controller:getStreamSampleRate()

    Returns the actual sample rate in samples per second in use by the stream. On some systems, the sample rate used may be slightly different than that specified in the stream parameter sampleRate set in the call to controller:openStream().

  • controller:getStreamBufferFrames()

    Returns the buffer size for an audio processing cylce in number of samples. This value may differ from the value of bufferFrames set in the call to controller:openStream().

  • controller:getStreamLatency()

    Returns the internal stream latency in sample frames.

    The stream latency refers to delay in audio input and/or output caused by internal buffering by the audio system and/or hardware. For duplex streams, the returned value will represent the sum of the input and output latencies. If the API does not report latency, the return value will be zero.

  • controller:getStreamInput([id1[, id2]])

    Returns one or more input channels of the current audio processing stream.

    • id1 - optional integer channel ID of the first channel to be returned, default value is 1.
    • id2 - optional integer channel ID of the last channel to be returned, default value is id1.

    If id1 and id2 are not given, all input channels are returned. If id1 is given and id2 is not given, the input channel with id1 is returned. If both id1 and id2 are given, all channels between id1 and id2 are returned.

    The returned channel objects can be used as connector objects. They become invalid if the audio processing stream is closed.

  • controller:getStreamOutput([id1[, id2]])

    Returns one or more output channels of the current audio processing stream.

    • id1 - optional integer channel ID of the first channel to be returned, default value is 1.
    • id2 - optional integer channel ID of the last channel to be returned, default value is id1.

    If id1 and id2 are not given, all output channels are returned. If id1 is given and id2 is not given, the output channel with id1 is returned. If both id1 and id2 are given, all channels between id1 and id2 are returned.

    The returned channel objects can be used as connector objects. They become invalid if the audio processing stream is closed.

  • controller:newStreamBuffer([type])

    Creates a new stream buffer object which can be used as connector object.

    • type - optional string value, must be "AUDIO" or "MIDI". Default value is "AUDIO" if this parameter is not given.

    The returned stream buffer becomes invalid if the audio processing stream is closed.

Connector Objects

Connector objects are either input or output channels or stream buffer objects. They are used to specify input or output connections of processor objects.

Processor Objects

Processor objects are Lua objects for processing realtime audio data. They must be implemented in C using the Auproc C API.

Processor objects can be connected to audio or midi data streams using connector objects.

The lrtaudio examples are using procesor objects that are provided by the lua-auproc package.

End of document.