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. A single `-1` denotes a video-only (`audioTrackIndex=-1`) or audio-only (`videoTrackIndex=-1`) request, but currently fails before mutation. 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. Placement always reads native source channel availability through an internal UI-independent query; grant READ for the source item as well as WRITE for the destination. Unknown source channels fail before placement/source-range mutation, with the selected placement error policy. This does not depend on storePlacedItemsIn.
  • 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, or to the measured native Sequence end for a Sequence-like source.
  • If only sourceOutSeconds is set, placement runs from source-relative media start (0) to that time.
  • Explicit Sequence-like source ranges are bounded by [0, Sequence.getEndTime()], including Merged and Multicam. The already-read native extent supplies these placement bounds without calling unavailable Media START/DURATION; it does not redefine the public Media getters. A range such as 3–4 seconds on a 2-second Sequence is rejected before source-point or timeline mutation.
  • When explicit source-range inputs are used, the runtime temporarily sets project-item source in/out, reads the same VIDEO/AUDIO domain back, and performs placement only if both points match the requested interval within 1e-6 seconds (including the one-tick exclusive-out adjustment). Ignored or altered ranges fail before insertion; failed/nonfinite readback reports PROPERTY_DATA_UNAVAILABLE. This verification applies even without storePlacedItemsIn and also covers non-Sequence clips. It does not silently accept frame snapping beyond that tolerance.
  • Project Item source-point readback and the resulting Timeline clip range are separate: the Project Item readback passed the strict 1e-6-seconds source-point check in the tested non-frame-aligned placements, while Premiere quantized the Timeline clip's source In/Out to frames. At 25 fps in Premiere 26.3, requested 0.213456–1.234567 seconds produced Timeline source 0.2–1.2 seconds; both boundaries were rounded down, so the tail lost less than one frame. Transcription-based edits should inspect the resulting clips when word boundaries matter. This observation does not establish the rounding rule for other frame rates, media domains or versions.
  • Original finite source points must be readable before a temporary override. The runtime restores them on success, readback failure or native transaction failure; unset native sentinels are preserved. This requires write permission for the source project item as well as the target sequence. A restoration failure itself is reported; successful restoration is not guaranteed if Premiere rejects it.
  • 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). A single -1 denotes a video-only or audio-only request, but that request currently fails before mutation; values below -1, fractional indices, and -1 for both lanes are invalid.
  • 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 only while its locally captured timeline range still identifies the target; if that range changes, it reports the incomplete placement without risking removal of a different item. 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.
  • Sequence-like sources are checked using native ClipProjectItem.isSequence() → getSequence() → Sequence.getEndTime(), including Merged and Multicam sources. A measured end of exactly 0 is rejected with source context before this placement changes source In/Out or target tracks: zero-length Sequences cannot be nested, even with an explicit positive source range. Missing, failed or invalid native extent reads throw PROPERTY_DATA_UNAVAILABLE for END_TIME; they do not imply positive duration. HAS_VIDEO / HAS_AUDIO still describe output channels and can both be true for a zero-length Sequence.
  • Extent, explicit bounds and source-point readback rejections follow the normal error policy: STOP aborts; CONTINUE and RETURN_FALSE continue with storeResultIn=false and no storePlacedItemsIn. Earlier queued Actions are committed before fresh source wrappers and extent are read; the pre-mutation guarantee applies to this placement, not to earlier blocks. The shared native-placement helper also enforces the extent check for legacy Insert/Overwrite and disposable source-frame probe placement.
  • 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.
  • Before placement commits, a failed attempt clears a previously stored storeResultIn=true to false. This does not change the committed-placement/capture-failure distinction above.
  • 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.
  • storePlacedItemsIn stores positional Track Item refs, not durable identities. After later structural edits, determine the current positions of any clips you intend to keep targeting.
  • 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