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
Constantsmodule has a few updates to available enumerations:- A missing
CARIBBEANvalue has been found and added for theProjectItemColorLabelenumeration. - A new enumeration for
ProjectItemTypehas been added to help make identifyingProjectItems easier.
- A missing
-
Two new classes have been added to introduce some initial support for After Effects-authored MoGRTs when working with
ComponentParams:MogrtCommentallows for reading comment text assocatiated with a component parameter.MogrtTextallows for reading and editing Source Text content, fonts, sizes, and styles.MogrtTextinstances 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!
-
TickTimenow has utility functionstimeToTimecodeandtimecodeToTimefor 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); -
TimeDisplaynow has a proper constructor to help when using with the above-added timecode utility functions. You can use the availableConstants.AudioDisplayFormatTypeandConstants.VideoDisplayFormatTypewith aTimeDisplay’stypeproperty.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
-
EventManager’sremoveEventListenerandremoveGlobalEventListenerfunctions now accept a third (optional) parameteruseCapturematching the equivalent parameter foraddEventListenerandaddGlobalEventListener. This helps make sure that adding an event listener on the capture phase can be correctly removed from the capture phase to avoid event listeners staying beyond their welcome. -
ComponentParam’screateKeyframe()andgetStartValue()functions have been updated to work with the newly addedMogrtCommentandMogrtTextclasses.
Bug Fixes
- Calling
Exporter.exportSequenceFramewill now correctly queue calls internally. This previously caused issues when callingexportSequenceFrameback-to-back for multiple frames. ComponentParam.getStartValueforColor-basedComponentParamshould no longer be lossy. Previously there were issues maintaining the blue channel that have been resolved.SourceMonitor.openFilePathwill correctly resolve withfalseif 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 andPointKeyframe’svalueproperty 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 withPointKeyframe.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, returningPromise<Sequence | null>rather than suggesting it always synchronously returns aSequenceinstance. -
ProjectItem.type,ClipProjectItem.type, andFolderItem.typemore specifically use the newly addedConstants.ProjectItemTypeenumeration to help identify what type values are present for each class rather than usingnumbermore generically. -
TrackItemSelection.createEmptySelection()better documents lifetime and scope limitations with the emptyTrackItemSelectionobject provided to the callback function. We’ve similarly added a new ESLint rule to the@adobe/eslint-plugin-premiereproplugin to help identify incorrect usage through static analysis checks. -
Transcript.transcribeClipProjectItem()'s options have been corrected to accept an optionallanguageproperty rather thanlanguageCode. How this works between transcription default settings and language auto-detection has been further clarified in the method’s description.