Automation

Automation lets you record and draw changes to track parameters over time — volume fades, pan sweeps, plugin parameter changes, MIDI CC data, and compositor layer properties.

How Automation Works

Automation data is stored as CC (Continuous Controller) events on automation regions. Each event is a tuple of:

Field	Type	Description
`tick`	i64	Position in ticks (960 PPQ)
`cc`	u8	Controller number (0–127)
`value`	u16	Controller value (0–16383 for 14-bit resolution)

Events are recorded at tick-level precision and stored per-region on automation tracks.

Automation Tracks

Automation tracks are special tracks with track_type = Automation. Each automation track is linked to a parent node via a Parent edge — this determines what the automation controls.

Parent nodes can be:

A track — automates track volume, pan, or plugin parameters
A compositor layer — automates layer transform, opacity, mask, or 3D camera properties

Recording Automation

Step by Step

Arm automation recording with the transport’s automation arm button
Start playback (or recording)
Move the parameter you want to automate — volume fader, pan knob, or plugin control
Stop playback — the recorded automation data is saved as CC events in a new region

Commands

Command	Description
`transport:toggle-record-auto`	Toggle automation record armed state
`automation:start-recording`	Start recording automation on armed tracks
`automation:stop-recording`	Stop recording and create automation regions
`automation:set-parent`	Set or clear the parent node for an automation track

Lua Examples

-- Arm automation recording
pl.cmd("transport:toggle-record-auto")

-- Check if automation is armed
local armed = plinken.get("transport", "automation_armed")

-- Start recording (usually triggered automatically with playback)
pl.cmd("automation:start-recording")

-- Stop recording and create regions
pl.cmd("automation:stop-recording")

Transport Properties

Property	Type	Default	Description
`automation_armed`	bool	`false`	Whether automation recording is armed

Editing Automation

Open the automation editor to view and edit automation curves graphically. You can:

Draw new automation shapes with the pencil tool
Adjust individual CC event points
Delete events by selecting and pressing ⌫
Copy/paste automation data between regions

Updating CC Events Programmatically

-- Update CC events on a region (for automation editing)
-- Each event: { tick, cc, value }
pl.cmd("region:update-cc-events", {
  track_id = 5,
  region_id = "r_auto_1",
  cc_events = {
    { tick = 0,    cc = 7, value = 8192 },  -- Volume at center
    { tick = 960,  cc = 7, value = 12000 }, -- Volume up
    { tick = 1920, cc = 7, value = 4000 },  -- Volume down
    { tick = 3840, cc = 7, value = 8192 },  -- Volume back to center
  }
})

Automation Mapper

CC-to-parameter mapping is configured in Settings > Automation. Each mapping defines:

Field	Description
CC number	Which controller number to listen to
Parameter ID	Which parameter to control
Transform	Linear transform: `output = input × a + b`

The transform converts the normalized internal range (−1.0 to +1.0) to real-world units for the target parameter.

See Settings > Automation for the full mapper configuration.

Compositor CC Defaults

When an automation track is linked to a compositor layer, CC numbers map to layer properties:

CC Range	Parameters
CC 0–9	Transform (position X/Y, scale X/Y, rotation, anchor X/Y, content pan/zoom)
CC 10	Opacity
CC 20–27	Mask (position, size, corner radius, feather)
CC 40–51	3D Camera (orbit target, distance, azimuth, elevation, focal length, focus, look target, deadzone)

Practical Examples

Fade-in Over 2 Bars

-- Create a volume fade-in on track 1's automation track
-- CC 7 = Volume, values in 14-bit range (0–16383)
local events = {}
for i = 0, 7680, 240 do  -- Every 16th note over 2 bars
  local normalized = i / 7680  -- 0.0 to 1.0
  local value = math.floor(normalized * 16383)
  table.insert(events, { tick = i, cc = 7, value = value })
end

Pan Sweep

-- CC 10 = Pan, center = 8192, left = 0, right = 16383
local events = {}
for i = 0, 3840, 120 do  -- Every 32nd note over 1 bar
  local phase = (i / 3840) * math.pi * 2  -- Full sweep
  local value = math.floor((math.sin(phase) * 0.5 + 0.5) * 16383)
  table.insert(events, { tick = i, cc = 10, value = value })
end