# Lua Auproc Documentation <!-- ---------------------------------------------------------------------------------------- --> ## Contents <!-- ---------------------------------------------------------------------------------------- --> * [Overview](#overview) * [Module Functions](#module-functions) * [auproc.new_audio_mixer()](#auproc_new_audio_mixer) * [auproc.new_midi_mixer()](#auproc_new_midi_mixer) * [auproc.new_midi_receiver()](#auproc_new_midi_receiver) * [auproc.new_midi_sender()](#auproc_new_midi_sender) * [auproc.new_audio_sender()](#auproc_new_audio_sender) * [auproc.new_audio_receiver()](#auproc_new_audio_receiver) * [Connector Objects](#connector-objects) * [Processor Objects](#processor-objects) * [processor:activate()](#processor_activate) * [processor:deactivate()](#processor_deactivate) * [processor:close()](#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](https://github.com/osch/lua-ljack) or [lrtaudio](https://github.com/osch/lua-lrtaudio). <!-- ---------------------------------------------------------------------------------------- --> ## Module Functions <!-- ---------------------------------------------------------------------------------------- --> * <span id="auproc_new_audio_mixer">**`auproc.new_audio_mixer(audioIn[, audioIn]*, audioOut, mixCtrl) `**</span> Returns a new audio mixer object. The audio mixer object is a [processor object](#processor-objects). * *audioIn* - one or more [connector objects](#connector-objects) of type *AUDIO IN*. * *audioOut* - [connector object](#connector-objects) 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](https://github.com/osch/lua-ljack/blob/master/examples/example06.lua). <!-- ---------------------------------------------------------------------------------------- --> * <span id="auproc_new_midi_mixer">**`auproc.new_midi_mixer(midiIn[, midiIn]*, midiOut, mixCtrl) `**</span> * *midiIn* - one or more [connector objects](#connector-objects) of type *MIDI IN*. * *midiOut* - [connector object](#connector-objects) 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](https://github.com/osch/lua-ljack/blob/master/examples/example07.lua). <!-- ---------------------------------------------------------------------------------------- --> * <span id="auproc_new_midi_receiver">**`auproc.new_midi_receiver(midiIn, receiver) `**</span> Returns a new midi receiver object. The midi receiver object is a [processor object](#processor-objects). * *midiIn* - [connector object](#connector-objects) 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](https://github.com/osch/lua-ljack/blob/master/examples/example03.lua). <!-- ---------------------------------------------------------------------------------------- --> * <span id="auproc_new_midi_sender">**`auproc.new_midi_sender(midiOut, sender) `**</span> Returns a new midi sender object. The midi sender object is a [processor object](#processor-objects). * *midiOut* - [connector object](#connector-objects) 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](https://github.com/osch/lua-ljack/blob/master/examples/example04.lua). <!-- ---------------------------------------------------------------------------------------- --> * <span id="auproc_new_audio_sender">**`auproc.new_audio_sender(audioOut, sender) `**</span> Returns a new audio sender object. The audio sender object is a [processor object](#processor-objects). * *audioOut* - [connector object](#connector-objects) 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](https://github.com/osch/lua-ljack/blob/master/examples/example05.lua). <!-- ---------------------------------------------------------------------------------------- --> * <span id="auproc_new_audio_receiver">**`auproc.new_audio_receiver(audioIn, receiver) `**</span> Returns a new audio receiver object. The audio receiver object is a [processor object](#processor-objects). * *audioIn* - [connector object](#connector-objects) 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](https://github.com/osch/lua-ljack/blob/master/examples/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](#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](#auproc_new_audio_mixer), implementation: [audio_mixer.c](../src/audio_mixer.c). * [midi mixer](#auproc_new_midi_mixer), implementation: [midi_mixer.c](../src/midi_mixer.c). * [midi reveicer](#auproc_new_midi_receiver), implementation: [midi_receiver.c](../src/midi_receiver.c). * [midi sender](#auproc_new_midi_sender), implementation: [midi_sender.c](../src/midi_sender.c). * [audio sender](#auproc_new_audio_sender), implementation: [audio_sender.c](../src/audio_sender.c). * [audio receiver](#auproc_new_audio_receiver), implementation: [audio_receiver.c](../src/audio_receiver.c). The above builtin processor objects are implementing the following methods: <!-- ---------------------------------------------------------------------------------------- --> * <span id="processor_activate">**`processor:activate() `** </span> 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. <!-- ---------------------------------------------------------------------------------------- --> * <span id="processor_deactivate">**`processor:deactivate() `** </span> Deactivates the processor object. A deactivated processor object can be activated again by calling [processor:activate()](#processor_activate). <!-- ---------------------------------------------------------------------------------------- --> * <span id="processor_close">**`processor:close() `** </span> Closes the processor object. A closed processor object is invalid and cannot be used furthermore. <!-- ---------------------------------------------------------------------------------------- --> End of document. <!-- ---------------------------------------------------------------------------------------- --> [Lua]: https://www.lua.org [auproc]: https://luarocks.org/modules/osch/auproc [auproc_cairo]: https://luarocks.org/modules/osch/auproc_cairo [auproc_opengl]: https://luarocks.org/modules/osch/auproc_opengl [mtmsg]: https://github.com/osch/lua-mtmsg#mtmsg [carray]: https://github.com/osch/lua-carray [light userdata]: https://www.lua.org/manual/5.4/manual.html#2.1 [Receiver C API]: https://github.com/lua-capis/lua-receiver-capi [Sender C API]: https://github.com/lua-capis/lua-sender-capi [Auproc C API]: https://github.com/lua-capis/lua-auproc-capi