Set Track Item Selection

Category: Pr Tracks & Clips

Changes the selected timeline clips in the supplied sequence; when sequence is omitted, it uses the active sequence. Uses canonical clip ITEM refs from the target sequence. REPLACE is the default and an empty list clears selection. ADD/REMOVE require at least one item; CLEAR requires items to be empty or omitted. items accepts the same canonical ::ITEM\\CLIP#<index> references returned by prListSelectedTrackItems, prListTrackItems, and prForEachTrackItem. All refs are resolved and validated before the first visible selection change. Every item must belong to the target sequence. mode defaults to REPLACE. REPLACE selects exactly items; an empty list clears the selection. ADD adds the supplied clips, REMOVE removes them, and CLEAR requires an empty or omitted items input. The current public contract is clip-only because Premiere's TrackItemSelection API exposes video and audio clip Track Items. It is intentionally expressed as Track Item selection so additional public item kinds can be added later without inventing a second selection model. A linked video/audio edit consists of separate Track Items. Select both refs to select both components, or pass only the video or audio ref to select only that component. Replacing or clearing the selection also removes a visible Transition or Gap selection, although those item types cannot currently be supplied as selectable refs through Premiere's public API. Selection is editor UI state, not an undoable structural Timeline edit. The runtime commits pending Premiere actions before changing it. Relist ordinal ITEM refs after structural Timeline edits and do not persist them as durable identities. If Premiere applies an incomplete selection, the block reports failure and makes one best-effort attempt to restore the previously reported clip selection. It verifies that restore by canonical ITEM refs and reports a second explicit error when recovery is incomplete. Because Premiere does not expose selected Transitions or Gaps through TrackItemSelection.getTrackItems(), those non-clip selections cannot be snapshotted or guaranteed to survive a failed write; the visible selection may therefore be cleared or differ after a write-plus-restore failure. If sequence is omitted, the block uses the active sequence when supported. Use onError to decide whether errors stop the script, continue, or return false when the block supports it. If storeResultIn is set, the block also writes a result variable back to your graph.

Inputs

Input	Required	Value Kind	Types	Enum Values
items	no	expression	—	—
sequence	no	expression	reference, string	—
mode	no	expression	enum-string	REPLACE, ADD, REMOVE, CLEAR
onError	no	expression	enum-string	STOP, CONTINUE, RETURN_FALSE
storeResultIn	no	variable-name	—	—

Notes

• Changes the selected timeline clips in the supplied sequence; when sequence is omitted, it uses the active sequence.
• items accepts the same canonical ::ITEM\\CLIP#<index> references returned by prListSelectedTrackItems, prListTrackItems, and prForEachTrackItem. All refs are resolved and validated before the first visible selection change. Every item must belong to the target sequence.
• mode defaults to REPLACE. REPLACE selects exactly items; an empty list clears the selection. ADD adds the supplied clips, REMOVE removes them, and CLEAR requires an empty or omitted items input.
• The current public contract is clip-only because Premiere's TrackItemSelection API exposes video and audio clip Track Items. It is intentionally expressed as Track Item selection so additional public item kinds can be added later without inventing a second selection model.
• A linked video/audio edit consists of separate Track Items. Select both refs to select both components, or pass only the video or audio ref to select only that component.
• Replacing or clearing the selection also removes a visible Transition or Gap selection, although those item types cannot currently be supplied as selectable refs through Premiere's public API.
• Selection is editor UI state, not an undoable structural Timeline edit. The runtime commits pending Premiere actions before changing it. Relist ordinal ITEM refs after structural Timeline edits and do not persist them as durable identities.
• If Premiere applies an incomplete selection, the block reports failure and makes one best-effort attempt to restore the previously reported clip selection. It verifies that restore by canonical ITEM refs and reports a second explicit error when recovery is incomplete. Because Premiere does not expose selected Transitions or Gaps through TrackItemSelection.getTrackItems(), those non-clip selections cannot be snapshotted or guaranteed to survive a failed write; the visible selection may therefore be cleared or differ after a write-plus-restore failure.

See Also

• Premiere Reference Paths: Explains Premiere reference path strings for project items, sequences, tracks, timeline items, markers, components, and parameters.
• List Selected Track Items: Reads the current timeline selection from the supplied sequence; when sequence is omitted, it uses the active sequence.
• List Track Items: Returns the items on a track as a list.
• For Each Track Item: Iterates over the items of a track, with optional kind filter, time range, and order.
• Get Track Item Property: Reads the property selected in property from a track item.