We need Return Values for Actions within ExecuteTransactions for Undo Groups to make sense

Premiere Pro
, , , ,
1

Premiere UXP introduces the concept of creating actions and executing those actions in bulk in order to have more control over the undo history.

This is a great step forward from ExtendScript which did not have undo groups, however the implementation fails to make sense in it’s current state.

Currently all actions do not return any values as you would expect, so you’re only able to run bulk actions which are unrelated (e.g. delete a bunch of separate clips), while actions that are dependent on each other need to be in separate transactions. (e.g. create a sequence, rename the sequence, move it somewhere, add clips to it, etc)

Example

For instance, creating a new bin moving the active sequence to that bin and importing footage takes 4 steps in the code and creates 3 undo groups since they are all separate executeTransction() calls.

image
image301×145 6.03 KB

  const proj = await premierepro.Project.getActiveProject();
  const root = await proj.getRootItem();

  //* 1 Create Bin
  const parentBinName = "Parent Bin";
  proj.executeTransaction(async (compAction) => {
    compAction.addAction(root.createBinAction(parentBinName, false));
  }, "Create Parent Bin");

  //* 2 Find Bin
  const parentBin = (await root.getItems()).find(
    (item) => item.name === parentBinName,
  );

  if (parentBin) {
    //* 3 Move Current Sequence
    const seq = await proj.getActiveSequence();
    const seqProjItem = await seq.getProjectItem();
    proj.executeTransaction(async (compAction) => {
      compAction.addAction(
        root.createMoveItemAction(
          seqProjItem,
          premierepro.FolderItem.cast(parentBin),
        ),
      );
    }, "Move To Sequence");

    //* 4. Import Files to Bin
    await proj.importFiles(
      ["path/to/bolt-uxp.png", "path/to/typescript.png",],
      true,
      parentBin,
      false,
    );
  }

Problem:

  • We end up with 3 History items anyway because createBinAction() does not return a result to use with createMoveItemAction() and importFiles()
  • Also since createBinAction() doesn’t return a result, we have to attempt to find the bin we have already created by matching by names which can lead to errors since Premiere can have multiple items with the same name.

Solution

It would be much more straightforward and reliable if all create___Action() functions would return the result of that action for us to use in following actions or functions.

Then our code would be more straightforward and less error-proned:

const proj = await premierepro.Project.getActiveProject();
const root = await proj.getRootItem();
const seq = await proj.getActiveSequence();
const seqProjItem = await seq.getProjectItem();

const parentBinName = "Parent Bin";
// * Only One Undo Group
proj.executeTransaction(async (compAction) => {
  //* 1 Create Bin
  const parentBin = compAction.addAction(root.createBinAction(parentBinName, false));
  //* 2 Move Current Sequence
  compAction.addAction(
    root.createMoveItemAction(seqProjItem,premierepro.FolderItem.cast(parentBin))
  );
  //* 4. Import Files to Bin
  await proj.importFiles(
    ["path/to/bolt-uxp.png", "path/to/typescript.png"],
    true,
    parentBin,
    false,
  );
}, "Create, Move, and Import");

And all of these actions would be grouped into 1 undo group for easy reversal.

image
image296×206 4.96 KB

This is a simple example for demonstration purposes, but for complex tools creating dozens of sequences and importing and changing hundreds of clips / bins, these actions can quickly exceed the History stack meaning they are not only a nuisance to undo, they are impossible to undo in many cases depending on the user’s undo history settings.

Some More Examples of action functions that should return their result but currently return nothing:

  • createBinAction() (should return the created bin)

  • createSmartBinAction() (should return the created bin)

  • createCloneAction() (should return the cloned sequence)

  • createInsertComponentAction() (should return the created component)

  • createCloneAction() (should return the cloned sequence)

Thank you!

3 Likes