Choosing A Project Item Metadata Surface
Automation Agent exposes several project-item metadata surfaces because Premiere stores and presents different kinds of information in different places. Choose the surface that matches the workflow's meaning; do not treat them as interchangeable fallbacks.
Quick Decision
| What the workflow needs | Use |
|---|---|
| Mirror or export the columns currently shown in the Project Panel | Visible Metadata: prListProjectItemVisibleMetadataColumns, prGetProjectItemVisibleMetadataColumnValue, or prForEachProjectItemVisibleMetadataColumn |
| Read an intrinsic, typed clip or project-item fact | prGetProjectItemProperty |
| Read or maintain a project-local value independently of panel visibility | prListProjectItemProjectMetadataProperties and prGetProjectItemProjectMetadataProperty (plus the matching write/delete blocks when needed) |
| Read embedded or imported media metadata | prListProjectItemXmpProperties, prGetProjectItemXmpProperty, or the keyword, camera, and location helpers |
For durable reusable workflows, check for a typed property first. If none matches, choose complete Project Metadata for project-local state or XMP for media metadata.
Visible Means Enabled In Metadata Display
Visible Metadata is a view of the current Project Panel configuration. A row is available only when that column is enabled under Metadata Display in the editor's current workspace/configuration. Different users and workspaces can therefore expose different rows, even for the same project item.
prGetProjectItemVisibleMetadataColumnValue is not a "read any metadata by
Column ID" expression. It throws when the requested column is not in the
current visible set. Do not assume that a standard column such as Name, Comment,
or Frame Rate is enabled everywhere, and do not use a fixed Column.* lookup
when the workflow needs that value reliably. A fixed lookup is safe only after
the workflow has established that the column is currently visible and the
visible Project Panel value is the intended result.
Visible display values can be localized or formatted. That makes this surface appropriate for exporting, reproducing, or auditing what the editor currently sees in the Project Panel.
Project Metadata Is Project-Local
Complete Project Metadata is independent of Project Panel visibility. Use it for project-local tags, workflow status, review notes, descriptions, or other properties that should remain addressable when a column is hidden.
These values are not promised to be raw source-file values. Premiere may still
format or localize some project metadata. Discover the packet and use the
literal propertyId that belongs to that domain.
XMP Is Media Metadata
XMP helpers read metadata embedded in or imported from media, including common keyword, camera, and location fields when Premiere exposes them. XMP is distinct from project-local metadata and from the current Project Panel display. Missing XMP fields are normal for many media formats, and the public helpers are read-only.
Never silently retry a Project Metadata read as XMP, or a Visible Metadata read as Project Metadata. If a workflow intentionally supports multiple domains, make that policy explicit and preserve the meaning of each result.