Premiere Reference Paths

Premiere reference paths are strings that identify objects inside the open Premiere project: project items, sequences, tracks, timeline clips and items, markers, effect components, and component parameters.

Most scripts do not need to type these paths by hand. Prefer blocks such as Pr Get Active Sequence Ref, Pr Get Track Ref, Pr Get Item Ref, Pr Get Marker Ref, Pr Get Component Ref, and list/loop blocks when the target depends on the current project. Use literal paths when you need a fixed, known target or when you store a reference returned by another block.

Reference paths are different from filesystem paths. Filesystem placeholders such as ::HOME:: and ::DESKTOP:: are for files and folders; Premiere reference paths use ::SEQ, ::TRACK, and similar typed tokens.

Basic Shape

A project item path is a backslash-separated path through the Premiere project panel:

MyProject.prproj\Footage\Intro.mov
MyProject.prproj\Sequences\Main Edit
MyProject.prproj\Bins\Same Name[1]

Current Automation Agent builds return a stable GUID-bearing project prefix while keeping the readable project name:

MyProject.prproj@58308490-12a1-41eb-a9b8-1de599c174ef\Sequences\Main Edit

If the first segment ends in .prproj, or contains .prproj@ followed by a GUID, it is treated as the project prefix. A name-only prefix must match exactly one currently open project resource. If two open resources have the same normalized name, Automation Agent fails with an ambiguity error instead of choosing the first one, including when copied files share a GUID. A GUID-bearing prefix continues to identify the same project after display-name changes while that GUID is unique. If the GUID collides, the readable name must select exactly one candidate; otherwise resolution fails closed. Automation Agent does not open a project just because its name appears in a reference path.

The remaining segments are project items or bins. A leading backslash marks an absolute project-panel path in the currently active project without naming the project:

\Footage\Intro.mov

Typed path sections are appended with ::TOKEN\selector:

MyProject.prproj\Sequences\Main Edit::SEQ::TRACK\VIDEO#0::ITEM\CLIP#2

The canonical paths returned by Automation Agent are GUID-qualified when Premiere exposes a valid project GUID, and typed. User-authored name-only paths remain convenient when project names are unique. Returned canonical refs are appropriate for the concrete currently open project, but a project GUID can be duplicated by copying a .prproj; do not treat the GUID portion alone as a portable template identity.

Portable Locators And Runtime Bindings

When a reference will be stored with a template, spreadsheet, Automation Document, or ABSCRIPT bundle, store a project-root-relative locator:

Sequences\Main Edit::SEQ::TRACK\VIDEO#0::ITEM\CLIP#2

Use Pr Make Project-Relative Ref to remove the project name and GUID through the Premiere reference parser. Do not use generic filesystem path* or text blocks for this conversion.

When the workflow runs:

1. Open or create the target project and set storeBindingIn. storeResultIn still contains the project GUID.
2. Pass the stored runtime binding and portable locator to Pr Bind Project-Relative Ref.
3. Store and reuse the returned bound reference for reads and writes.

The returned runtime ref has a form such as:

MyProject.prproj@58308490-12a1-41eb-a9b8-1de599c174ef~prbind_...\Sequences\Main Edit::SEQ

The prbind_... value distinguishes the exact open resource even when copied projects have the same name and GUID. It expires when the DSL run ends and must never be persisted. A bare GUID remains accepted by the bind expression only when it currently identifies one open resource; the bind expression then creates an exact run-scoped binding before returning the object ref.

Canonical refs returned by later operations also retain ~prbind_... when their input was bound. They are still runtime-only, not safe spreadsheet or document values. Pass them through Pr Make Project-Relative Ref before persisting them; calling that expression on an already project-relative ref is safe and returns the same parsed reference.

::SEQ\ACTIVE is not a portable locator. It deliberately follows the editor's current active sequence and is rejected by both portable conversion and binding expressions.

Sequences

A sequence can be referenced from its project item path:

MyProject.prproj\Sequences\Main Edit::SEQ

The active sequence has a special anchor:

::SEQ\ACTIVE

Use the active-sequence anchor only when the active timeline is intentionally part of the script. For deterministic scripts, store the result from Pr Get Active Sequence Ref or from sequence-creating blocks and pass that stored reference forward.

Tracks

Tracks belong to a sequence:

::SEQ\ACTIVE::TRACK\VIDEO#0
::SEQ\ACTIVE::TRACK\AUDIO#0
::SEQ\ACTIVE::TRACK\CAPTION#0

Track indices are zero-based. VIDEO#0 means the first video track. Named track selectors are also supported:

::SEQ\ACTIVE::TRACK\VIDEO@V1
::SEQ\ACTIVE::TRACK\AUDIO@Dialogue[1]

Use [n] when there are duplicate names. [0] is the first matching duplicate.

Timeline Clips And Items

::CLIP targets clip items only:

::SEQ\ACTIVE::TRACK\VIDEO#0::CLIP\#3
::SEQ\ACTIVE::TRACK\AUDIO#0::CLIP\@Intro Music[0]

::ITEM targets generic timeline items by kind:

::SEQ\ACTIVE::TRACK\VIDEO#0::ITEM\CLIP#3
::SEQ\ACTIVE::TRACK\VIDEO#0::ITEM\TRANSITION#0
::SEQ\ACTIVE::TRACK\AUDIO#0::ITEM\GAP#2

Supported item kinds are CLIP, TRANSITION, GAP, PREVIEW, and FEEDBACK. Name selectors are only supported for CLIP items:

::SEQ\ACTIVE::TRACK\VIDEO#0::ITEM\CLIP@Intro[0]

Some timeline operations currently support clip items only. If a block requires a clip/item reference for trimming, moving, effects, or component parameters, use a CLIP item unless that block explicitly says it supports other item kinds.

Markers

Markers can belong to a project item, a sequence, or a timeline clip:

MyProject.prproj\Footage\Shot01.mov::MARKER\#0
MyProject.prproj\Sequences\Main Edit::SEQ::MARKER\@Chapter 1[0]
::SEQ\ACTIVE::TRACK\VIDEO#0::CLIP\#1::MARKER\~12.5s

Marker selectors can use:

• #0 for the first marker
• @Name[0] for the first marker with that name
• ~12.5s for a marker at a time in seconds

Markers are not supported directly on tracks, transitions, or gaps.

For permissions, ::MARKER can also be used without a selector as a marker namespace prefix:

::SEQ\ACTIVE::MARKER
MyProject.prproj\Footage\Shot01.mov::MARKER

This form means “the markers on this sequence or clip”. It is useful when a script should be allowed to create, edit, move, or delete markers without being allowed to otherwise modify the sequence or clip itself. A selector such as \#0 is still required when a block needs one specific marker reference.

Components And Parameters

Effect components belong to timeline clip items:

::SEQ\ACTIVE::TRACK\VIDEO#0::ITEM\CLIP#0::COMPONENT\#1
::SEQ\ACTIVE::TRACK\VIDEO#0::ITEM\CLIP#0::COMPONENT\@Motion[0]

Component parameters belong to components:

::SEQ\ACTIVE::TRACK\VIDEO#0::ITEM\CLIP#0::COMPONENT\#1::PARAM\#3
::SEQ\ACTIVE::TRACK\VIDEO#0::ITEM\CLIP#0::COMPONENT\@Motion[0]::PARAM\@Position[0]

Component and parameter selectors support index selectors (#n) and name selectors (@Name[n]). Component paths currently support clip items only.

Escaping Names

Backslash separates project-panel segments and typed selectors. Escape these characters when they are part of a literal name:

Literal character	Write as
\	\\
:	\:
[	\[
]	\]

Because unescaped :: starts a typed section, a project item named Seq::Name is written as:

Seq\:\:Name::SEQ

Choosing A Form

Use index selectors when the order is stable and the script owns the setup, for example after creating a sequence or placing items. Use name selectors for human-managed project structures, and add [n] when duplicates are possible.

For dynamic context, prefer resolver blocks over literal paths:

• Pr Get Active Sequence Ref for the current timeline
• Pr Get Track Ref, Pr Get Clip Ref, and Pr Get Item Ref for timeline navigation
• Pr List Track Items or Pr For Each Track Item when you need to process many clips
• Pr Get Marker Ref, Pr List Markers, or Pr For Each Marker for markers
• Pr Get Component Ref and Pr Get Component Param Ref for effects and parameters

Store returned references in variables when several later blocks should act on the same target. Do not strip the @<ProjectGuid> suffix from a returned reference. It is the part that prevents a later lookup from switching to another same-named open project.