Premiere 27.0 API Updates

Hi all,

This major release of Premiere 27.0 comes with a breaking change, added features, bug fixes, and general documentation updates. As always you can also read this on the Premiere Changelog page and our updated API doc pages.

UXP Updates

As part of this release Premiere has upgraded to UXP 9.4. For more details on what this includes check out the UXP 9.4 Changelog at the UXP Developer Hub.

Breaking Changes

The Application class

We’ve decided to remove the Application class from the exposed set of classes available from the premierepro module, and the version asynchronous instance property it had documented.

const ppro = require("premierepro");
console.log(typeof ppro.Application);  // "undefined"

The version property didn’t have a great way to be accessed at runtime: since there isn’t a way to properly instantiate an Application object to even access the version property, this didn’t make sense to have available in the first place. Current version information is better served through the UXP host object which includes synchronous properties about the current Premiere version details instead, and is more consistent with other Adobe applications which support UXP plugins.

The documented Application class and its TypeScript declaration in @adobe/premierepro still remains, however, as the class is used with some EventManager event listener functions. We’re planning on improving our documentation generally around events and where the Application class does fit in here. Stay tuned!

New APIs

A number of new classes and APIs have been added in this release. More details on each can be seen in each class’s documentation page. If you’d like to see more examples of using all of these new APIs in action, check out the premiere-api sample panel in the UXP Premiere Pro Samples repository.

  • The Constants module has a few updates to available enumerations:

    • A missing CARIBBEAN value has been found and added for the ProjectItemColorLabel enumeration.
    • A new enumeration for ProjectItemType has been added to help make identifying ProjectItems easier.
  • Two new classes have been added to introduce some initial support for After Effects-authored MoGRTs when working with ComponentParams:

    • MogrtComment allows for reading comment text assocatiated with a component parameter.
    • MogrtText allows for reading and editing Source Text content, fonts, sizes, and styles. MogrtText instances respect author-defined editing restrictions. Currently these only work with single-run text.

    We’ll continue adding more support for MoGRT capabilities in the future!

  • TickTime now has utility functions timeToTimecode and timecodeToTime for converting to and from timecode strings.

    const ppro = require("premierepro");
    const project = await ppro.Project.getActiveProject();
    const sequence = await project.getActiveSequence();
    
    const tickTime = await sequence.getPlayerPosition();
    const frameRate = (await sequence.getSettings()).getVideoFrameRate();
    const timeDisplay = await sequence.getSequenceVideoTimeDisplayFormat();
    
    const timecode = ppro.TickTime.timeToTimecode(tickTime, frameRate, timeDisplay);
    
    // Converting back into a TickTime
    const originalTickTime = ppro.TickTime.timecodeToTime(timecode, frameRate, timeDisplay);
    
  • TimeDisplay now has a proper constructor to help when using with the above-added timecode utility functions. You can use the available Constants.AudioDisplayFormatType and Constants.VideoDisplayFormatType with a TimeDisplay’s type property.

    const format = new ppro.TimeDisplay();
    format.type = ppro.Constants.VideoDisplayFormatType.FPS_29_97;
    

UXP Host Additions

A new property buildNumber has been added to the UXP host object. This can be particularly useful for helping report any issues as of a particular version + build of Premiere.

const uxp = require("uxp");
console.log(uxp.host.version);      // "27.0.0"
console.log(uxp.host.buildNumber);  // "42"

API Updates

Bug Fixes

  • Calling Exporter.exportSequenceFrame will now correctly queue calls internally. This previously caused issues when calling exportSequenceFrame back-to-back for multiple frames.
  • ComponentParam.getStartValue for Color-based ComponentParam should no longer be lossy. Previously there were issues maintaining the blue channel that have been resolved.
  • SourceMonitor.openFilePath will correctly resolve with false if the given file cannot be previewed in the Source Monitor.

Documentation Updates

Outside of the above core changes, we’ve also updated our documentation and @adobe/premierepro TypeScript declarations package to address some inconsistencies or improve and clarify how to use various classes and APIs. We’ll continue reviewing these and working to make sure these are as accurate as possible.

  • ComponentParam.getValueAtTime()'s return value has been better clarified as to its actual runtime values/types. In particular Point (PointF)-related values are actually returned as an [x, y] array “tuple”. Other supported values are returned as scalars (number, boolean, string).

  • Keyframe’s and PointKeyframe’s value property has been better qualified in terms of its expected values/types. In particular the TypeScript declaration has been further split into getter and setter accessor declarations to highlight the difference in getting values from each Keyframe class and setting values. You can see this most clearly with PointKeyframe.

    const point = new ppro.PointF(0.5, 0.5);
    const pointKeyframe = componentParam.createKeyframe(point);
    
    // Getting the keyframe's value returns an object containing a tuple
    // of the PointF's [x, y] coordinates.
    console.log(pointKeyframe.value);  // { value: [0.5, 0.5] }
    
    // Setting the keyframe's value uses a PointF
    pointKeyframe.value = new ppro.PointF(0.75, 0.75);
    
  • Project.getSequence() is now correctly documented as being an asynchronous function, returning Promise<Sequence | null> rather than suggesting it always synchronously returns a Sequence instance.

  • ProjectItem.type, ClipProjectItem.type, and FolderItem.type more specifically use the newly added Constants.ProjectItemType enumeration to help identify what type values are present for each class rather than using number more generically.

  • TrackItemSelection.createEmptySelection() better documents lifetime and scope limitations with the empty TrackItemSelection object provided to the callback function. We’ve similarly added a new ESLint rule to the @adobe/eslint-plugin-premierepro plugin to help identify incorrect usage through static analysis checks.

  • Transcript.transcribeClipProjectItem()'s options have been corrected to accept an optional language property rather than languageCode. How this works between transcription default settings and language auto-detection has been further clarified in the method’s description.