README.md

Lua Auproc Documentation

Contents

• Overview
• Module Functions
  • auproc.new_audio_mixer()
  • auproc.new_midi_mixer()
  • auproc.new_midi_receiver()
  • auproc.new_midi_sender()
  • auproc.new_audio_sender()
  • auproc.new_audio_receiver()
• Connector Objects
• Processor Objects
  • processor:activate()
  • processor:deactivate()
  • processor:close()

Overview

This package provides basic Lua audio processor objects to be used for realtime audio and midi processing. The provided processor objects can be used in conjunction with Lua packages that are implementing the Auproc C API e.g. LJACK or lrtaudio.

Module Functions

• auproc.new_audio_mixer(audioIn[, audioIn]*, audioOut, mixCtrl)

  Returns a new audio mixer object. The audio mixer object is a processor object.

  • audioIn - one or more connector objects of type AUDIO IN.
  • audioOut - connector object of type AUDIO OUT.
  • mixCtrl - optional sender object for controlling the mixer, must implement the Sender C API, e.g. a mtmsg buffer.

  The mixer can be controlled by sending messages with the given mixCtrl object to the mixer. Each message should contain subsequent pairs of numbers: the first number, an integer, is the number of the audioIn connector (1 means first connector), the second number of each pair, a float, is the amplification factor that is applied to the corresponding input connector given by the first number of the pair.

  See also ljack/example06.lua.

• auproc.new_midi_mixer(midiIn[, midiIn]*, midiOut, mixCtrl)

  • midiIn - one or more connector objects of type MIDI IN.
  • midiOut - connector object of type MIDI OUT.
  • mixCtrl - optional sender object for controlling the mixer, must implement the Sender C API, e.g. a mtmsg buffer.

  The mixer can be controlled by sending messages with the given mixCtrl object to the mixer. Each message should contain subsequent triplets of integers: the first integer is the number of the midiIn connector (1 means first connector), the second integer of each triplet is the source channel (1-16) that is to be mapped and the third integer is the new channel number (1-16) that the source channel events are mapped to or may be 0 to discard events for the given source channel.

  See also ljack/example07.lua.

• auproc.new_midi_receiver(midiIn, receiver)

  Returns a new midi receiver object. The midi receiver object is a processor object.

  • midiIn - connector object of type MIDI IN.

  • receiver - receiver object for midi events, must implement the Receiver C API, e.g. a mtmsg buffer.

  The receiver object receivers for each midi event a message with two arguments:

  • the time of the midi event as integer value in frame time
  • the midi event bytes, an carray of 8-bit integer values.

  The midi receiver object is subject to garbage collection. The given port object is owned by the midi receiver object, i.e. the port object is not garbage collected as long as the midi receiver object is not garbage collected.

  See also ljack/example03.lua.

• auproc.new_midi_sender(midiOut, sender)

  Returns a new midi sender object. The midi sender object is a processor object.

  • midiOut - connector object of type MIDI OUT.

  • sender - sender object for midi events, must implement the Sender C API, e.g. a mtmsg buffer.

  The sender object should send for each midi event a message with two arguments:

  • optional the frame time of the midi event as integer value. If this value is not given, the midi event is sent as soon as possible. If this value refers to a frame time in the past, the event is discarded.
  • the midi event bytes as carray of 8-bit integer values.

  The caller is responsible for sending the events in order, i.e. for increasing the frame time, i.e. the frame time of the subsequent midi event must be equal or larger then the frame time of the preceding midi event.

  The midi sender object is subject to garbage collection. The given connector object is owned by the midi sender object, i.e. the connector object is not garbage collected as long as the midi sender object is not garbage collected.

  See also ljack/example04.lua.

• auproc.new_audio_sender(audioOut, sender)

  Returns a new audio sender object. The audio sender object is a processor object.

  • audioOut - connector object of type AUDIO OUT.

  • sender - sender object for sample data, must implement the Sender C API, e.g. a mtmsg buffer.

  The sender object should send for each chunk of sample data a message with one or two arguments:

  • optional the frame time of the sample data as integer value in frame time. If this value is not given, the samples are played as soon as possible.
  • chunk of sample data, an carray of 32-bit float values.

  The caller is responsible for sending the events in order, i.e. for increasing the frame time. The chunks of sample data may not overlap, i.e. the frame time of subsequent sample data chunks must be equal or larger then the frame time of the preceding sample data chunk plus the length of the preceding chunk.

  The audio sender object is subject to garbage collection. The given connector object is owned by the audio sender object, i.e. the connector object is not garbage collected as long as the audio sender object is not garbage collected.

  See also ljack/example05.lua.

• auproc.new_audio_receiver(audioIn, receiver)

  Returns a new audio receiver object. The audio receiver object is a processor object.

  • audioIn - connector object of type AUDIO IN.

  • receiver - receiver object for audio samples, must implement the Receiver C API, e.g. a mtmsg buffer.

  The receiver object receivers for each audio sample chunk a message with two arguments:

  • the time of the audio event as integer value in frame time.
  • the audio sample bytes, an carray of 32-bit float values.

  The audio receiver object is subject to garbage collection. The given connector object is owned by the audio receiver object, i.e. the connector object is not garbage collected as long as the audio receiver object is not garbage collected.

  See also ljack/example08.lua.

Connector Objects

Connector objects have to be provided by the package that implements the Auproc C API. They can be used to connect processor objects with each other.

Connector objects can be of type AUDIO or MIDI and can be used for either INPUT or OUTPUT direction.

Processor Objects

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

This packages includes the following procesor objects. The implementations can be seen as examples on how to implement procesor objects using the Auproc C API.

• audio mixer, implementation: audio_mixer.c.
• midi mixer, implementation: midi_mixer.c.
• midi reveicer, implementation: midi_receiver.c.
• midi sender, implementation: midi_sender.c.
• audio sender, implementation: audio_sender.c.
• audio receiver, implementation: audio_receiver.c.

The above builtin processor objects are implementing the following methods:

• processor:activate()

  Activates the processor object. A activated processor object is taking part in realtime audio processing, i.e. the associated processCallback is periodically called in the realtime thread.

• processor:deactivate()

  Deactivates the processor object. A deactivated processor object can be activated again by calling processor:activate().

• processor:close()

  Closes the processor object. A closed processor object is invalid and cannot be used furthermore.

End of document.