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. Track indices must be integers. Values `0` and above are 0-based target tracks. Exactly one index may be `-1` to request video-only (`audioTrackIndex=-1`) or audio-only (`videoTrackIndex=-1`) placement. Values below `-1`, fractional indices, and `-1` for both lanes are invalid. Premiere's native Project Item placement API does not document negative indices as lane-disable controls and Premiere Beta 27 routes `-1` to track 0. Because no safe single-call implementation could be verified, Automation Agent currently rejects every single-lane `prSequencePlaceItem` before changing Project Item source ranges or the destination sequence. Normal A/V placement requires two non-negative indices. `storePlacedItemsIn` reads the source Project Item's actual VIDEO/AUDIO capabilities and stores only uniquely resolved Track Item references whose Project Item, target track, Timeline start, source in/out, and enabled state match. Absent source components are verified absent across every track, so a genuine video-only or audio-only Project Item may safely use non-negative paired indices. For an explicit source range, verified audio-only input selects the AUDIO In/Out domain even with paired non-negative indices; video-capable input selects VIDEO. Ambiguous identity, a missing or unexpected component, an enabled-state mismatch, or channel-expanded audio fails capture without guessing or destructive place-then-delete cleanup; the placement remains committed, `storeResultIn` remains true, and `storePlacedItemsIn` remains unset. Use a disposable or explicitly incomplete output sequence when verification is required. Relist affected tracks after later structural Timeline edits.

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.
  • Restoration is protected by normal error handling, but it is not crash-atomic: if Premiere or the UXP process terminates during the native placement call, the shared Project Item can retain the temporary source in/out. Workflows with stronger recovery requirements should use dedicated source items or persist enough pre-call state to repair this manually after restart.
  • Supports explicit integer videoTrackIndex / audioTrackIndex values. Non-negative values are 0-based (0 = V1 / A1). Exactly one index may be -1 to request video-only (audioTrackIndex=-1) or audio-only (videoTrackIndex=-1) placement. Values below -1, fractional indices, and disabling both lanes are rejected.
  • Premiere's native Project Item placement API does not define -1 as a disabled lane. Live tests in Premiere Beta 27 placed the supposedly disabled media on track 0 for both INSERT and OVERWRITE; even single-Track-Item clone/move actions retained cached A/V linkage when orchestrated inside this placement host call. Automation Agent therefore never forwards -1 to Premiere and currently rejects every single-lane prSequencePlaceItem before changing Project Item source ranges or the destination sequence.
  • This -1 fail-closed limitation applies regardless of whether the Project Item is A/V, video-only, audio-only, mono, stereo, multichannel, or adaptive because the API does not expose a reliable pre-mutation lane-disable contract. Placement with two non-negative indices remains supported; source-aware storePlacedItemsIn verification permits a genuinely video-only or audio-only source to produce only the component it actually contains.
  • The block never implements video-only/audio-only placement by overwriting first and deleting the unwanted destination item afterward.
  • 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 first reads the source Project Item's actual VIDEO/AUDIO capabilities, then stores freshly placed Track Item references only when exactly one matching item with the requested source range and requested enabled state exists for every media component the source contains. This permits a genuine video-only or audio-only Project Item to use non-negative paired target indices without falsely requiring the absent component, while every track of that absent kind is still scanned for unexpected placement. For explicit source ranges, a verified audio-only source uses the AUDIO In/Out domain even though both native track indices are non-negative; video-capable sources use VIDEO. A missing expected VIDEO or AUDIO component, an unexpected absent-media component, an enabled-state mismatch, or ambiguous identity is a verification failure. Timeline start uses a strict epsilon; frame tolerance applies only to source in/out verification.
  • Placement success and placed-item reference capture are separate results. If Premiere committed the placement but reference capture then fails, storeResultIn remains true; onError governs the capture failure and storePlacedItemsIn remains unset. The verifier does not attempt place-then-delete cleanup: an overwrite may already have displaced prior Timeline content, so deleting the new item would not be a rollback. Workflows that need post-placement verification must mutate a disposable or explicitly incomplete output sequence until verification succeeds.
  • 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 integers: 0 and above are 0-based target tracks; -1 is the reserved single-lane request and currently fails closed before mutation.
  • 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