Skip to main content

Place Item In Sequence

Category: Pr Tracks & Clips Place Item In Sequence block screenshot

Places one project item into a sequence at a given time using `INSERT` or `OVERWRITE` mode. Without `sourceInSeconds` / `sourceOutSeconds`, the block keeps the legacy Premiere behavior and uses the project item's current source range. When `sourceInSeconds` and/or `sourceOutSeconds` are provided, the runtime temporarily overrides the project item's source in/out for this placement only and restores the original project-item state afterward. Explicit source ranges use source-relative seconds, where `0` is the first media frame regardless of embedded source timecode. If only `sourceInSeconds` is provided, placement runs from that time to media end. If only `sourceOutSeconds` is provided, placement runs from source-relative media start (`0`) to that time. `storePlacedItemsIn` stores uniquely resolved Track Item references from the requested video/audio target tracks for immediate use. Ambiguous identity fails without guessing. If verification fails after a uniquely identified placement is successfully removed, `storeResultIn` becomes false; if rollback cannot be proven, it retains the committed true result. When Premiere expands one placement across additional audio tracks, as with multi-mono or some 5.1 interpretations, ref capture fails explicitly instead of returning an incomplete list: the placement remains committed, `storeResultIn` remains true, and `storePlacedItemsIn` remains unset. Complete cross-track capture requires a future atomic before/after identity API. Relist affected tracks after later structural timeline edits instead of reusing those references.

Inputs​

InputRequiredValue KindTypesEnum Values
itemyesexpressionreference, string—
sequencenoexpressionreference, string, null—
modeyesexpressionenum-stringINSERT, OVERWRITE
timeSecondsyesexpressionnumber—
sourceInSecondsnoexpressionnumber—
sourceOutSecondsnoexpressionnumber—
videoTrackIndexnoexpressionnumber—
audioTrackIndexnoexpressionnumber—
limitShiftnoexpressionboolean—
disableVideonoexpression——
onErrornoexpressionenum-stringSTOP, CONTINUE, RETURN_FALSE
storeResultInnovariable-namevariable-name—
storePlacedItemsInnovariable-namevariable-name—

Replaces Older Blocks​

  • prSequenceInsertItem
  • prSequenceOverwriteItem

Notes​

  • Unified single-item timeline placement block.
  • Set mode to:
    • INSERT to insert at timeSeconds (uses limitShift when provided).
    • OVERWRITE to overwrite at timeSeconds (ignores limitShift).
  • Without sourceInSeconds / sourceOutSeconds, the block preserves Premiere's legacy behavior and places the project item's current source range. The source Project Item is read-only for permission purposes; only the destination sequence needs Premiere write access.
  • In the tested untouched-default case, that legacy behavior inserted the full clip.
  • If the project item's source in/out were explicitly set before placement, the legacy no-range form places exactly that configured source range.
  • sourceInSeconds and sourceOutSeconds override that legacy stateful behavior for this placement only.
  • Explicit source ranges use source-relative seconds: 0 is the first media frame, regardless of embedded source timecode.
  • If only sourceInSeconds is set, placement runs from that time to media end.
  • If only sourceOutSeconds is set, placement runs from source-relative media start (0) to that time.
  • When explicit source-range inputs are used, the runtime temporarily sets project-item source in/out, performs the placement, and restores the original project-item state afterward. This requires write permission for the source project item as well as the target sequence.
  • Supports explicit videoTrackIndex / audioTrackIndex.
  • When disableVideo=true, the runtime resolves the freshly placed video item, commits the disabled state, and verifies it before the host call returns. Placement plus disabling is therefore one cooperative-cancellation unit. Source-range identity tolerates Premiere snapping the temporary placement nudge back to the sequence frame grid. If disabling cannot be verified after one unique placement was resolved, the runtime removes that new video item before reporting failure so an enabled higher-track clip is not silently left behind. The option requires a non-negative video track and does not disable any placed audio item.
  • storePlacedItemsIn stores freshly placed Track Item references only when exactly one matching item with the requested source range exists on every requested target track. A missing requested VIDEO or AUDIO placement is a verification failure, even when the other requested media lane matches. Timeline start uses a strict epsilon; frame tolerance applies only to source in/out verification. Ambiguous identity fails without destructive guessing, while a uniquely identified placement that fails range verification is removed without ripple before the error is reported.
  • Placement success and placed-item reference capture are separate results. If Premiere committed the placement but reference capture then fails without a verified rollback, storeResultIn remains true; onError governs the capture failure and storePlacedItemsIn remains unset. If unique placement identity allowed the host to remove every placed item successfully, storeResultIn is changed to false for CONTINUE and RETURN_FALSE because no placement remains.
  • The current capture inspects videoTrackIndex and detects matching placement identity on later audio tracks. When Premiere expands one placement across additional audio tracks, as with multi-mono or some 5.1 interpretations, capture fails explicitly instead of returning an incomplete list or guessing which cross-track matches are fresh. The same conservative rejection can occur when the same source was intentionally layered at the same start time on later audio tracks; it can therefore depend on placement order. The placement remains committed and storeResultIn remains true. Complete capture and distinction from intentional layering require atomic before/after placement identity across all affected tracks.
  • Stored Track Item references are immediate-use snapshots: after any structural timeline mutation, relist the affected tracks instead of reusing them.
  • Track indices are 0-based (0 = first track / V1 / A1).
  • Preferred block for new scripts.

See Also​

  • Premiere Reference Paths: Explains Premiere reference path strings for project items, sequences, tracks, timeline items, markers, components, and parameters.

Examples​

Place Multiple Source Ranges From One Clip

Creates an empty sequence, then fills it with three explicit source ranges from one clip while verifying the original project-item in/out gets restored afterward.

kind: Pattern · format: runtime-dsl · validation: MCP fixture

Topics: timeline placement, source range placement, sequence creation

Source: patterns/ex-sequence-place-multiple-source-ranges-from-one-clip.json

Download JSON

Set Project Item In/Out Then Place It

Sets a clip project item's source in/out, places it into a new sequence without explicit source-range overrides, then verifies that placement used the current project-item range.

kind: Pattern · format: runtime-dsl · validation: MCP fixture

Topics: timeline placement, project item properties, source range placement

Source: patterns/ex-sequence-set-project-item-in-out-and-place.json

Download JSON

Create Empty Sequence Matching Selected Item And Place It

Creates an empty sequence whose settings match the first selected project item, stores the returned sequence ref, then places the item explicitly into that sequence.

kind: Pattern · format: runtime-dsl · validation: Manual workspace

Topics: sequence creation, project inspection, timeline placement, matched sequence settings

Source: patterns/ex-sequence-create-matching-item-and-place.json

Download JSON