Regions

Regions are rectangular clips placed on tracks that represent audio, MIDI, video, or text content. Each region has a position (in ticks), a duration, and a reference to its source content.

Region Types

Type	Description
Audio	References a WAV/AIFF asset file. Has sample-accurate start/end positions.
MIDI	Contains MIDI note events and CC data. Routed to instruments.
Video	References a video asset. Composited visually.
Text	Contains text content (lyrics, captions, cue notes).
Automation	Contains CC automation curves linked to parameters.

Region Properties

Property	Type	Default	Description
`id`	string	auto	Unique region identifier
`name`	string	—	Display name
`region_type`	enum	—	`Audio`, `MIDI`, `Video`, `Text`, `Automation`
`color`	string	`"#3B82F6"`	Color as hex string
`tick`	i64	`0`	Position on timeline in ticks (960 PPQ)
`duration`	i64	—	Length in ticks (minimum 240 = 1/16 note)
`offset`	i64	`0`	Offset into source content (how far into the file to start reading)
`lock`	bool	`false`	Position lock mode
`start`	i64	`0`	Start position in samples (audio/video regions)
`end`	i64	`0`	End position in samples (audio/video regions)
`asset_id`	string?	`None`	Referenced asset ID (audio/video regions)
`gain`	f64	`1.0`	Region gain multiplier
`pan`	f64	`0.0`	Region pan (−1.0 to +1.0)
`muted`	bool	`false`	Mute this region
`fade_in`	f64	`0.0`	Fade-in duration
`fade_out`	f64	`0.0`	Fade-out duration
`warp_enabled`	bool	`false`	Time-stretch / warp mode
`parent_id`	NodeRef?	`None`	Parent node for hierarchical grouping

Region Commands

Command	Shortcut	Description
`region:move`	—	Move a region to a new tick position (same or different track)
`region:resize`	—	Resize a region (change duration)
`region:trim-start`	—	Trim the start of a region (adjusts offset, position, and duration)
`region:delete`	⌫	Delete a region from the timeline
`region:create-text`	—	Create an empty text region at the playhead
`region:select-next`	→	Select the next region on the current track
`region:select-prev`	←	Select the previous region on the current track
`region:select-next-add`	⇧→	Add next region to selection
`region:select-prev-add`	⇧←	Add previous region to selection
`edit:cut-at-playhead`	Y	Split selected regions at the playhead
`edit:copy`	⌘C	Copy selected regions to clipboard
`edit:paste`	⌘V	Paste regions from clipboard at playhead
`edit:delete-selected`	⌫	Delete all selected regions
`region:check-asset-usage`	—	Check if a region’s asset is used by other regions

Moving Regions

Click and drag a region to move it along the timeline or between tracks. If snapping is enabled, the region will snap to the nearest grid position.

For audio and video regions, moving also updates the sample-accurate start/end positions to keep playback synchronized.

-- Move region to tick 3840 (bar 2) on the same track
pl.cmd("region:move", {
  track_id = 1,
  region_id = "r_abc_0",
  tick = 3840
})

-- Move region to a different track
pl.cmd("region:move", {
  track_id = 1,
  region_id = "r_abc_0",
  target_track_id = 2,
  tick = 0
})

Resizing Regions

Drag the right edge of a region to change its duration. The minimum duration is 240 ticks (one sixteenth note). For audio/video regions, resizing also updates the sample-accurate end position.

-- Resize region to 2 bars (7680 ticks in 4/4)
pl.cmd("region:resize", {
  track_id = 1,
  region_id = "r_abc_0",
  duration = 7680
})

Trimming the Start

Drag the left edge of a region to trim the start. This simultaneously adjusts the region’s position, offset, and duration — the end point stays fixed while the start moves.

-- Trim region start to tick 480 (offset 480 ticks into source)
pl.cmd("region:trim-start", {
  track_id = 1,
  region_id = "r_abc_0",
  tick = 480,
  offset = 480,
  duration = 3360
})

Splitting Regions

Place the playhead at the desired split point and press Y (or Edit > Split at Playhead). All selected regions that span the playhead position will be split into two separate regions.

-- Split selected regions at the playhead
pl.cmd("edit:cut-at-playhead")

The split operation:

Creates a new region starting at the playhead position
Adjusts the original region’s duration to end at the playhead
Handles child regions (parent-child hierarchies are preserved)

Copying & Pasting

Select regions and use ⌘C to copy, then ⌘V to paste. The pasted regions are placed at the current playhead position.

-- Copy selection
pl.cmd("edit:copy")

-- Paste at playhead
pl.cmd("edit:paste")

Deleting Regions

Select one or more regions and press ⌫ to delete them.

-- Delete a specific region
pl.cmd("region:delete", {
  track_id = 1,
  region_id = "r_abc_0"
})

-- Delete all selected regions
pl.cmd("edit:delete-selected")

Selecting Regions

Navigate between regions on the current track with the arrow keys.

Shortcut	Command	Description
→	`region:select-next`	Select the next region
←	`region:select-prev`	Select the previous region
⇧→	`region:select-next-add`	Extend selection to next region
⇧←	`region:select-prev-add`	Extend selection to previous region

-- Select the next region on the current track
pl.cmd("region:select-next")

-- Extend selection to include next region
pl.cmd("region:select-next-add")

Text Regions

Text regions hold lyrics, cue notes, or scene descriptions. Create them on text tracks with the region:create-text command.

-- Create a text region at the playhead
pl.cmd("region:create-text")

Text regions support:

text_content — Raw text content
text_words — Word-level timing data
text_notes — Editable text notes
text_language — Language code (BCP-47)
text_link_group — Group ID for linked text regions

Overlap Protection

Regions on the same track cannot overlap. When moving or duplicating regions, the operation is rejected if it would cause an overlap with existing regions on the target track.

Undo/Redo

All region operations (move, resize, trim, split, delete, copy, paste) support full undo/redo. Press ⌘Z to undo and ⌘⇧Z to redo.