State Read-Back

Query the current state of your project from Lua scripts. All functions return snapshots — the data is captured at the moment the script runs.

Tracks

local tracks = pl.get_tracks()

Returns an array of all tracks:

Field	Type	Description
id	number	Track ID (0–127, stable)
name	string	Display name
trackType	string	"audio", "midi", "video", "bus", "text", "face", "automation"
mute	bool	Muted
solo	bool	Solo enabled
arm	bool	Armed for recording
volume	number	Volume (0.0–2.0)
pan	number	Pan (-1.0 to 1.0)
color	number	Color as RGBA u32
freeze	bool	Frozen
lock	bool	Locked from editing
mono	bool	Mono (true) or stereo (false)
inputActive	bool	Input monitoring enabled
outputRouting	string	"stereo-out", "bus-1", etc.
instrument	table/nil	Instrument plugin { id, name, vendor, format, bypassed }
effects	array	Effect chain [{ id, name, vendor, format, bypassed }, ...]
regionCount	number	Number of regions on this track

Example

local tracks = pl.get_tracks()
for _, track in ipairs(tracks) do
    if track.mute then
        pl.log(track.name .. " is muted")
    end
end

Get a single track

local track = pl.get_track(0)  -- by ID
if track then
    pl.log(track.name .. " vol=" .. track.volume)
end

---

Regions

local regions = pl.get_regions(trackId)

Returns an array of regions on the given track:

Field	Type	Description
id	string	Unique region ID
name	string	Display name
regionType	string	"audio", "midi", "video", "text", "face", "automation"
tick	number	Position in ticks (PPQ=960)
duration	number	Duration in ticks
color	string	Hex color (e.g. "#FFD700")
muted	bool	Region muted
gain	number	Audio gain (default 1.0)
assetId	string/nil	Asset reference (audio/video regions)

MIDI regions include events

For MIDI regions, an additional events field is returned:

Field	Type	Description
events	array	[{ pitch, velocity, tick, duration, channel }, ...]

local regions = pl.get_regions(2)
for _, r in ipairs(regions) do
    pl.log(r.name .. " at tick " .. r.tick)
    if r.events then
        pl.log("  " .. #r.events .. " MIDI notes")
    end
end

---

Selection

local sel = pl.get_selection()

Returns the current selection state:

Field	Type	Description
trackIds	array	Selected track IDs [0, 3, 5]
regionIds	array	Selected region IDs ["r1", "r2"]

Example

local sel = pl.get_selection()
pl.log(#sel.trackIds .. " tracks selected")
pl.log(#sel.regionIds .. " regions selected")

-- Mute all selected tracks
for _, id in ipairs(sel.trackIds) do
    local track = pl.get_track(id)
    if track and not track.mute then
        pl.cmd("track:toggle-mute", { trackId = id })
    end
end

---

Mixer

local mixer = pl.get_mixer()

Returns mixer channel state:

Field	Type	Description
master	table	Master channel { volume, pan, mute, solo, effects[] }
fx	array	FX return channels (up to 8)
outputs	array	Output channels (up to 4)

Each channel has:

Field	Type	Description
volume	number	0.0–2.0
pan	number	-1.0 to 1.0
mute	bool	Muted
solo	bool	Solo enabled
effects	array	FX chain [{ id, name, vendor, format, bypassed }, ...]

Example

local mixer = pl.get_mixer()
pl.log("Master volume: " .. mixer.master.volume)

for i, fx in ipairs(mixer.fx) do
    if not fx.mute then
        pl.log("FX " .. i .. " vol=" .. fx.volume)
    end
end

---

Assets

local assets = pl.get_assets()

Returns an array of project assets:

Field	Type	Description
id	string	Asset ID
name	string	Display name
uri	string	Relative path from project root
assetType	string	"audio", "video", "midi", "image", "face", "script"
duration	number	Duration in seconds
sampleRate	number	Audio sample rate (Hz)
channels	number	Audio channel count
frames	number	Total audio frames

Example

local assets = pl.get_assets()
for _, a in ipairs(assets) do
    if a.assetType == "audio" then
        pl.log(a.name .. " — " .. string.format("%.1fs", a.duration))
    end
end

---

Automation

-- All automation lanes for a track
local lanes = pl.get_automation(trackId)

-- Points for a specific parameter
local points = pl.get_automation(trackId, "volume")

Returns automation data for a track. Without paramId, returns all lanes as { paramId = [points] }. With paramId, returns just the points array.

Each point:

Field	Type	Description
time	number	Time position
value	number	Parameter value
curve	number	Curve shape

Example

local lanes = pl.get_automation(0)
for param_id, points in pairs(lanes) do
    pl.log(param_id .. ": " .. #points .. " points")
end

---

Plugin Parameters

-- Instrument plugin on track
local inst = pl.get_plugin_params(trackId)

-- Effect at index (0-based)
local fx = pl.get_plugin_params(trackId, 0)

Returns plugin info { id, name, vendor, format, bypassed } or nil.

Example

local inst = pl.get_plugin_params(2)
if inst then
    pl.log("Instrument: " .. inst.name .. " (" .. inst.format .. ")")
end

local fx = pl.get_plugin_params(2, 0)
if fx then
    pl.log("First effect: " .. fx.name)
end