Lua scripting

OpenStudio ships a Lua scripting engine with native bindings for tracks, transport, FX chains, sends, automation, audio analysis, freeze, and offline render. This page covers the editor, the namespace, a compact API reference, and examples. Project-editing scripts have the synchronization limits described below.

The script editor

Open View → Script Editor. The window has two panes: the editor on top, where you write Lua, and the console below, where output lands.

1. Type or paste a script into the editor pane.
2. Click Run. The script executes against the open project.
3. Read results and errors in the console pane.
4. Use openstudio.print(...) anywhere in the script to write your own messages to the console.

Scripts call the native audio engine directly. Track, clip, mixer, and automation edits are not synchronized back into the frontend project state or its undo history, so they may not appear in the UI or survive saving. Use the UI for persistent project edits; keep reusable analysis scripts as files on disk.

The OpenStudio namespace

DAW functions are registered under openstudio.*. Older examples using s13.* do not work in this app revision. Use openstudio.addTrackJSFX(trackId, scriptPath, isInputFX) for a JSFX file and openstudio.getAvailableJSFX() to inspect available effects.

Track functions take a trackId string returned by openstudio.addTrack. Volume is in dB, pan runs from -1.0 (left) to 1.0 (right), and times are in seconds. Master volume is linear, from 0.0 to about 3.98 (+12 dB). Read the argument column in the tables below before assuming a range.

A first script

This read-only script prints the engine’s tempo, time signature, and track count. Paste it into the editor and click Run.

local signature = openstudio.getTimeSignature()
openstudio.print("Tempo: " .. openstudio.getTempo() .. " BPM")
openstudio.print("Time signature: " .. signature.num .. "/" .. signature.den)
openstudio.print("Native tracks: " .. openstudio.getTrackCount())

getTimeSignature() returns a table with num and den fields. A native track count does not provide the IDs of the tracks in the project.

API reference

Signatures below describe the native Lua bindings. Optional arguments have a ? suffix. none means no return value. Track IDs are UUID strings, not numbered positions; keep the IDs returned by addTrack(). FX and send indices are zero-based.

Track operations

Transport

FX chain

Master bus

Sends

Playback clips

Automation

Audio analysis

Track freeze

Render

MIDI

Metronome

Plugins

Utility

More examples

Analysis functions take file paths, not track ids, so they work on any audio on disk. This script measures three files and prints integrated loudness and true peak for each. Adjust the paths for your OS.

local files = { "C:/audio/verse.wav", "C:/audio/chorus.wav", "C:/audio/bridge.wav" }
for _, file in ipairs(files) do
    local stats = openstudio.measureLUFS(file)
    openstudio.print(file .. ": " .. stats.integrated .. " LUFS, peak " .. stats.truePeak .. " dBTP")
end

Use returned values to inspect the engine without changing the project. For example, list the plugin names returned by the current scan:

for _, plugin in ipairs(openstudio.getAvailablePlugins() or {}) do
    openstudio.print(plugin.name)
end

For a stereo master render of the first sixty seconds, call openstudio.renderProject("master", 0, 60, "C:/output/mix.wav", "wav", 44100, 24, 2, false, false, 0). This returns a success boolean. Choose an explicit writable output path before running the script.

Tips

• Start with read-only tasks such as inspecting engine state or batch-measuring audio files.
• openstudio.print() is the debugging tool. Print ids and return values as you go; inspect returned values before continuing.
• Native mutation bindings are available, but do not provide the UI’s project synchronization or undo guarantees. Experiment in a disposable session.
• Save commonly used scripts as files so you can reuse them across projects.