Skip to content

Lua for Interactive Actions

Lua is an amazing language to create interactive events. You can read its 88 pages manual on English here or in Portuguese here.

I am not present the language here, there are a lot of tutorials on the internet and YouTube.

  • Very Complete here.
  • Very Fast, Complex but yet Complete tutorial if you already know how to program in another language here.
  • More complet tutorial here.
  • Text here.

Inside OpenScofo you can use Lua to create interactive events. OpenScofo provide a module where you can create deep interactions with the listening and follower module. Also OpenScofo Pure Data and Max object provide pd and max module to interact with the patches. Below I present the module and its methods.

Also check the LUAEVENT event type.

Under developement yet

Lua Module for Pure Data, Max, and OpenScofo are in developement yet.

OpenScofo Lua Module

The OpenScofo module exposes classes and functions to interact with the OpenScofo follower and listening module.

Import OpenScofo as object

local oscofo = require("OpenScofo")

OpenScofo methods

These are all functions exposed using oscofo.

  • oscofo.set_db_threshold(value)

    • input: float value in dB (default: -60).
    • output: no output.
    • description: Sets audio threshold used by the tracker.

  • oscofo.set_tuning(value)

    • input: tuning reference value (default: 440).
    • output: no output.
    • description: Sets tuning used for score parsing/tracking.

  • oscofo.set_current_event(event)

    • input: integer event index/position (default: 2).
    • output: no output.
    • description: Forces the current score position.

  • oscofo.set_harmonics(value)

    • input: integer number of harmonics (default: 10).
    • output: no output.
    • description: Sets number of harmonics used by the pitch template.

  • oscofo.set_pitch_template_sigma(value)

    • input: float sigma value (default: 0.5).
    • output: no output.
    • description: Sets pitch template sigma.

  • oscofo.get_live_bpm()

    • input: no input.
    • output: current estimated BPM (float).
    • description: Returns live tempo estimation.

  • oscofo.get_event_index()

    • input: no input.
    • output: current event index (integer).
    • description: Returns the current tracked score event.

  • oscofo.get_states()

    • input: no input.
    • output: return collection of OpenScofo.State of the current score.
    • description: Returns all score states currently loaded.

  • oscofo.get_pitch_template(freq)

    • input: frequency in Hz (float).
    • output: numeric array with the pitch template.
    • description: Returns internal pitch template for a given frequency.

  • oscofo.get_audio_description()

    • input: no input.
    • output: OpenScofo.Description object of the current audio buffer.
    • description: Computes MIR/audio features for the input block.

Exposed types in oscofo

  • OpenScofo.Description

    • mfcc
    • onset
    • silence_prob
    • spectral_magnitude
    • loudness
    • spectral_flux
    • spectral_flatness
    • harmonicity
    • db
    • rms
    • power

  • OpenScofo.State

    • position
    • type
    • markov
    • forward
    • bpm_expected
    • bpm_observed
    • onset_expected
    • onset_observed
    • phase_expected
    • phase_observed
    • ioi_phi_n
    • ioi_hat_phi_n
    • audiostates
    • duration
    • line

PureData Lua Module

The pd module inside Lua allows interaction with Pure Data functionalities, exposing the following functions:

  • pd.post("hello world")
    • input: A string message to post.
    • output: no output.
    • description: Posts a message at the default verbosity level, used for general logging.
  • pd.error("this is a message error")
    • input: A string error message.
    • output: no output.
    • description: Logs an error message in the Pure Data console, similar to a print with error severity.
  • pd.send_bang("mybang")
    • input: A string representing the destination symbol in Pure Data.
    • output: no output.
    • description: Sends a bang message to a specified destination in Pure Data.
  • pd.send_float("myfloat", 20)
    • input: A float value and a string representing the destination symbol in Pure Data.
    • output: no output.
    • description: Sends a floating-point number to a specified destination in Pure Data.
  • pd.send_symbol("mysymbol", "ola")
    • input: A string symbol and a string representing the destination symbol in Pure Data.
    • output: no output.
    • description: Sends a symbol to a specified destination in Pure Data.
  • pd.send_list("mylist", {"oi", 1, 2})
    • input: A list of values (mixed types) and a string representing the destination symbol in Pure Data.
    • output: no output.
    • description: Sends a list of values to a specified destination in Pure Data.

Max Lua Module

The max module inside Lua allows interaction with Max functionalities, exposing the following functions:

  • max.print("hello world")
    • input: A string message to print.
    • output: no output.
    • description: Logs a message to the console, similar to Max's print object.
  • max.error("this is an error")
    • input: A string error message.
    • output: no output.
    • description: Logs an error message in the Max console, similar to a print with error severity.
  • max.send_bang("mybang")
    • input: A string representing the receiver symbol in Max.
    • output: no output.
    • description: Sends a bang message to a specified receiver in Max.
  • max.send_float("myfloat", 20)
    • input: A float value and a string representing the destination symbol in Max.
    • output: no output.
    • description: Sends a floating-point number to a specified destination in Max.
  • max.send_symbol("mysymbol", "oi")
    • input: A string symbol and a string representing the destination symbol in Max.
    • output: no output.
    • description: Sends a symbol to a specified destination in Pure Data.
  • max.send_list("mylist", {1, 2, "oi"})
    • input: A list of values (mixed types) and a string representing the destination symbol in Max.
    • output: no output.
    • description: Sends a list of values to a specified destination in Max.