❓ Question: How to correctly get clip `id`, `name`, and `MediaType` in Premiere Pro API?

Premiere Pro
1

Code Example

I’m currently working with Premiere Pro’s scripting API and trying to collect information about selected track items:

const cliptItems = await Promise.all(
  trackItems.map(async (item: any) => {
    try {
      const [mediaType, trackIndex] = await Promise.all([
        item.getMediaType(),
        item.getTrackIndex(),
      ]);

      const videoTrack = await sequence.getVideoTrack(trackIndex);
      const videoTrackMediaType = await videoTrack.getMediaType();

      if (videoTrackMediaType.toString() === mediaType.toString()) {
        const label = await item.getMatchName();
        const projectItem = await item.getProjectItem();

        let projectItemName = await projectItem.name;
        return {
          id: '???', // How to get the real clip id?
          trackIndex,
          label: label || projectItemName,
        };
      }
      return null;
    } catch (error) {
      console.error('Failed to process trackItem:', error);
      return null;
    }
  })
);

My Problems

  1. Clip ID
  • I don’t know how to retrieve a unique identifier for the clip.
  • Is there any official API to get something like item.id or projectItem.nodeId?
  1. Clip Name
  • Right now I can only use item.getMatchName() or fallback to projectItem.name.
  • Sometimes this doesn’t reflect the actual displayed clip name on the timeline.
  • Is there a more reliable way to get the real clip name shown in the sequence?
  1. Media Type Handling
  • In my code I have to manually compare the string result of getMediaType().
  • According to ppro.d.ts, there is a clear enum definition:
export namespace Constants {
  export enum MediaType {
    ANY,
    DATA,
    VIDEO,
    AUDIO,
  }
}
  • But getMediaType(): Promise<Guid> returns a Guid instead of a mapped enum.
  • Why is this the case?
  • Is there a built-in helper or mapping table that converts the Guid into Constants.MediaType values, or do I need to maintain my own mapping?

Expected Behavior

  • A direct way to get:
    • clip.id (unique, stable across operations)
    • clip.name (the exact name as seen in the timeline)
    • clip.mediaType as a Constants.MediaType enum value (instead of Guid).

Actual Behavior

  • id is unknown / not available directly.
  • name is inconsistent (sometimes from getMatchName(), sometimes projectItem.name).
  • getMediaType() outputs a Guid instead of a type-safe enum.

Environment

  • API: Premiere Pro UXP API
  • Type Definitions: ppro.d.ts
  • Language: TypeScript

Question

  • How can I correctly retrieve the clip id and clip name?
  • Why does getMediaType() return a Guid instead of a Constants.MediaType enum, and what’s the best practice to map this to a usable type?
2

Media type is also coming, in our next pre-release SDK. :slight_smile: