how to get started with premiere scripting?

[hyuvii]

Hi. I'm an experienced web developer who's working on a project which requires some scripting in Premiere Pro.

My needs aren't highly complicated, and at first I thought "well this looks fine" seeing the CEP samples on github. Never have I have ever seen such bad bad horrible job of creating an API since trying to work with Microsoft's Outlook. There seems to be no manual or proper documentation for Premiere, furthermore, most (if not all? I didn't check) of the links on the github page are dead. Worse, some of the links are supposed to point at a file within that project - upon finding that file (in a different place) it turns out that even the intended lines the link points to are out of date.The official ESTK install links on Adobe's website are dead too, I only finally got it through the Creative Cloud - after enabling "show older apps" of course, which hasn't been a whole lot of help because it's debugging system is so ridiculously out of date. Oh also, some of the examples on github don't even run *as is*. There's no proper guide or quick-start tool, there's not even something like a REPL system that'll allow you to mess around and learn through that.

I need to run some really simple operations. I'm not asking for help with figuring out how to do them - I can do that on my own, provided I have some system that allows me to actually understand and learn without banging my head against the wall. Frankly, this is embarrassing and unprofessional from a company this big, and I don't understand it, but maybe someone on this community can point me in the right direction? I just need a way to start messing with this so I can actually learn how to use it.

[Kevin-Monahan]

Hi Hyuvii,

What is it that you want to do? Create plug-ins? Create an HTML panel? Let me know and I'll try to steer you in the correct direction.

Thanks,
Kevin

[hyuvii]

I want to create several bins in a specific hierarchy, import files and create sequences from those files based on predetermined information. Again, I can figure it all out myself if there's any proper documentation that explains the basics, or even just a cheat sheet. But I need code samples I can actually work with.

[John T Smith]

The SDK forum is probably a better place to ask Premiere Pro SDK

[Bruce Bullis]

Sorry you've found it difficult to get started; yes, on-boarding could be simpler.

Premiere Pro has a thriving community of hundreds of panel developers and integration partners, all of whom have based their panel development on PProPanel.

PProPanel shows how to create bins, imports files, and creates sequences; what other questions do you have?

[hyuvii]

Well all of those things are "there" technically but not really as a tool to learn from.

There's a searchForBinWithName function - which does a deep-search, because really? That's the first method you bring? And a name-based search? What if I have multiple bins with the same name - something that's very common when you create a scene-shot-take hierarchy? There's also the searchBinForProjItemByName (what??) which is recursive for some reason and I have no idea what it does but it seems so convoluted and unreadable I'm at awe.

I can see a function called createBin being used at some points but where's a single comment explaining that function? Maybe it can take more arguments - like color maybe? Can you create multiple bins at once? Does it return anything (maybe itself or the name?) - can you chain functionalities? Also - when you want to create it within another bin, do you have to go from rootItem or is there any traversing system in place? Who knows. I'd test it but there's no REPL system that'll make that process easier to do, right? I have to write code and run it through the IDE, then do it again and again to test every single silly thing because there's no documentation to explain it, nor is there a readable sample that explains different usages and options.
 
The importFiles function is also badly written, relying on user input (why would I want that when creating automation? I am trying to actively avoid that) which *doesn't work well* as is (it sets up the filetype in the dialog badly so it doesn't recognize – wait for it – audio or video files. yep). There's also an ingestFiles function - why? I don't know. There's no GUI functionality for "ingesting", that's not part of the video editor's jargon. There's this cryptic comment halfway in which says "// We have an array of File objects; importFiles() takes an array of paths." – from which you'd think that – ok, so imortFiles takes paths and ingestFiles takes objects – only that isn't true! Because a few lines below that it actually opens a file dialog and extracts the files from a path just like importFiles. That is bonkers absolutely freaking ridiculous.

The ingest function also has a whole bunch of encoder-related-event binding at the top - why? what does it do? And they bind events to functions named the same way with the word proxy, which makes it so weird – not only because that defies DRY, but because that naming suggest those are general tools you call upon, but they're only used in this specific function. That is so odd!! - why? I don't know! There's no documentation available. Maybe this makes sure to conform the imported files – hence ingest, but, uh, that *always supposed to happen* when you import files, that's something you expect anyway, so why have this other function called ingest? I can't understand any of it.
 

This isn't me having trouble understanding complicated features, these are the very basic elements of your entire API. And they're completely mumbled in a confused mess of badly named, badly written functions with minimal comments or details available.

Look, If you don't have documentation, what you need to do is provide samples that are crystal clear, and do exactly one thing. saveProject function is a good example, so is exportCurrentFrameAsPNG and insertOrAppend. Just like the rest of that code they lack comments and are badly written, but at least they're readable, short, and have a correlating action in the GUI so you can sorta figure out how to use them.
 
On the other hand - look at onPlayWithKeyframes - what a mess. So many logical conditions one after the other. I have taught several courses of basic python and JS programming to groups of people with various technical backgrounds and even the ones with literally zero knowledge stop writing stuff that way after about a week. And the name of the function is so meaningless and weird. And inside it you actually have some constants that you wrote as is that is just oh my god really? COME ON.

And this is all at odds with what I come to expect from Adobe in general. As a video editor I find the UI and software itself to be very thought-through and easy to work with, as well as your customer support  – when I had a problem I contacted someone through chat and it was quickly obvious he had actual technical knowledge and helped me through some playback issues (which is something to commemorate, really, when compared to customer support of so many other companies).

I'm astounded, really.

[Bruce Bullis]

> I'm astounded, really.

I'm sorry you don't like our API organization, design, or naming.

You are right; much could be done to improve the sample code, and documentation. Stepping through panel code in a debugger remains the best way to learn the interactions between PPro and panels.

The current panel sample has not been a barrier for hundreds of panel partners. We'd be happy to help you (directly, or here on the forums) with any specific development questions.

[hyuvii]

Ok. Sure. Here's what I'm trying to do:

1. Create a specific bin hierarchy

2. Import several files in, both audio and video.

3. Create sequences from those files with specific defined sync-points.

Resulting in something like this:

bin 1

      bin 1.1 -

            video1

            audio1

            sequence 1 - contains video 1 and all audio1 tracks synced according to given information

      bin 1.2

            etc.

The information for all of this is given by an external app I've already developed. I know I can't do any of that stuff externally, but I can probably create a JSON file to be read by a premiere script, or (hopefully) run a subprocess that'll call premiere to start and run my given script. Based on what I've seen I can probably do the first steps of creating bins and importing, but I'm not clear on the third part of creating a sequences, and I'm also unclear on how you can traverse within the source monitor files (do you have to loop from rootItem every time?). It'd be great if there was any REPL tool I could use to just mess around (similar to python's built in REPL system) and trial-and-error this.

[Bruce Bullis]

1. Create a specific bin hierarchy

2. Import several files in, both audio and video.

PProPanel's importFiles() lets the user choose some files, checks for an existing bin with [name], and creating one if it's not present. It then imports those files into the target bin.

  https://github.com/Adobe-CEP/Samples/blob/master/PProPanel/jsx/PPRO/Premiere.jsx#L206

To make a nested bin, you could add this after line 226:

  targetBin.createBin("nameOfNewNestedBin");

3. Create sequences from those files with specific defined sync-points.

PProPanel creates a new sequence, from preset:

  https://github.com/Adobe-CEP/Samples/blob/master/PProPanel/jsx/PPRO/Premiere.jsx#L381

PProPanel inserts media into sequences:

  https://github.com/Adobe-CEP/Samples/blob/master/PProPanel/jsx/PPRO/Premiere.jsx#L1364

Potentially simpler, than lots of sequence insert() calls: Can you obtain/create an FCP XML representation of that sequence?

There isn't much logging. CEP logs, mentioned in the PProPanel readme, will tell you something:

  https://github.com/Adobe-CEP/Samples/blob/master/PProPanel/ReadMe.md

Potentially helpful: Here's a video I made showing how to debug panels at both the JavaScript and ExtendScript levels. Probably better than alert boxes. [Download first, streaming playback is terrible.]

  https://www.dropbox.com/s/lwo8jg0klxkq91s/walkthru.mp4

Microsoft Visual Studio Code's integrated Chrome debugging is also awesome.

[hyuvii]

No. I need to import files without user input. consider this JSON file:

{

    "scenes": {

        "Scene 1": {

            "Shot 1": {

                "Take 1": ["path/to/video1-1-1", "path/to/audio1-1-1"],

                "Take 2": ["path/to/video1-1-2", "path/to/audio1-1-2"]

            },

            "Shot 2": {

                "Take 1": ["path/to/video1-2-1", "path/to/audio1-2-2"]

            }

        },

        "Scene 2": "etc."

}

The structure I can do like this:

for (var i in data) {

    var maindir = app.project.rootItem.createBin(i);

    for (var scene in data['scenes']) {

        var curScene = maindir.createBin(scene);

        for (var shot in data['scenes'][scene]) {

            var curShot = curScene.createBin(shot);

            for (var take in data['scenes'][scene][shot]) {

                curShot.createBin(take);

       }

    }

  }

}

It's not perfect, but it's decent enough. Now I need to import the list of paths for each take in, and create new sequences. I can probably figure out the import stuff (is there any way to just make a list of files to import and then batch-import them instead of doing it this loopy way? I rather not import them one at a time).

The createSequenceFromPreset function relies on a "presetPath" which I assume is a path to a file with information. What's that look like?

[hyuvii]

I actually found that video online from a different thread. I found it helpful but that process is still very limiting. You can't use the console at all, and you have to setup the break points through chrome so you can step in and then it points you to the function within ES? And it still doesn't let you console.log anyway, right? That's so convoluted. I don't know how I can use this, really.

[hyuvii]

Also, I thought about creating FCP XML file and just using that, but I can't find any decent documentation for that either - is there anything like that I can use? Like a basic template of how the structure should look like and what are my options. That'll be perfect

[Bruce Bullis]

> No. I need to import files without user input.

Ok, then leave out the file picker, and just import the media.

...is there any way to just make a list of files to import and then batch-import them instead of doing it this loopy way? I rather not import them one at a time.

importFiles() takes an array of file paths, so there's no need to import one at a time, but each call to importFiles() has just one destinationBin.

The createSequenceFromPreset function relies on a "presetPath" which I assume is a path to a file with information. What's that look like?

Here's where PProPanel finds path to its /payloads directory (using CEP calls), so it can pass an .sqpreset file into createSequenceFromPreset:

  https://github.com/Adobe-CEP/Samples/blob/master/PProPanel/index.html#L96

I thought about creating FCP XML file and just using that, but I can't find any decent documentation for that either.

https://documentation.apple.com/en/finalcutpro/usermanual/index.html#chapter=97%26section=3%26tasks=...

[hyuvii]

Ok, But what is an sqpreset? How does it look like?

[Bruce Bullis]

.sqpreset = sequence preset, generated from within PPro's New Sequence dialog (from the Settings tab). There's one such file in PProPanel's /payloads directory.

[hyuvii]

Ok, I found it, it's an XML file. Where's an explanation for the specifications and requirements of such a file / how its structure is built / how to give it information to link an audio and video file ?

Let's take a step back. I looked into the samples trying to make sense of 'em with your help. I can now import and create my hierarchy. Ok. What's left is the sequences - I found the function ​app.project.createNewSequence​ which gets two arguments: name & id. Testing it with ESTK revealed it automatically opens a prompt for user input (choosing which format). I want to avoid that. I don't want any input from the user. I need the details of that sequence to match those of the video, or a better way would be to create it from a specific video item and then adding the audio. Also, I can't see any way to create that sequence in a chosen directory (or even moving it? I don't know if that's possible).

By the way, that link you gave for the FCP XML - I already found it before, I always google before I ask - and it doesn't have anything, except for an overview and a link to some long lost documentation. Honestly I don't think there's anything about this thing, nor a library or tool that makes it easy to handle.

[Bruce Bullis · Accepted solution]

Where's an explanation for the specifications and requirements of such a file / how its structure is built

/ how to give it information to link an audio and video file ?

I don't understand why you'd every need to parse or (programmatically) create an .sqpreset file...? The only way to build a valid sequence preset is with PPro's Create Sequence dialog. Nothing outside of PPro should ever parse it. Perhaps you mean instead to provide a project, containing template sequences? Also doable.

I need the details of that sequence to match those of the video, or a better way would be to create it from a specific video item and then adding the audio.

There is no way to create a sequence from footage; you need to choose a specific preset.

Also, I can't see any way to create that sequence in a chosen directory (or even moving it? I don't know if that's possible).

Do you mean sequence in a bin, instead of directory? Every sequence is a projectItem, and you can change a projectItem's parent.

[hyuvii]

OK. Almost there. How do you change a projectItem's parent?

[hyuvii]

This doesn't work:

    seq = app.project.activeSequence;

    seq.moveBin(targetBin);

[hyuvii]

OH WOW IT'S ACTUALLY REALLY

     seq.projectItem.moveBin(targetBin)

That is currently the stupidest thing I've ever seen in programming. And I've worked with PHP in the past so that's saying something. I'm marking this as answered, but jeez, fix this entire mess, will ya? It is astonishingly bad.

[Bruce Bullis]

That is currently the stupidest thing I've ever seen in programming.

Noted.

As previously mentioned, hundreds of integration partners use these APIs every day, without complaint; we won't be changing things out from under them. The current API, warts and all, has been developed in direct conversation with our partners, and we improve it with every release. Sorry you find it so frustrating.

We're still happy to help with any specific technical questions.

[Thomas_Szabo]

Kudos to Bruce for being patient with this young padawan.

[hyuvii]

> hundreds of integration partners use these APIs every day, without complaint; we won't be changing things out from under them

I'm sure they won't complain even stronger if you fix this broken thing. Just... like, at the very least fix all the broken links on the GitHub page. That's something you can easily do right?

> Kudos to Bruce for being patient with this young padawan.

I appreciate his patience to my anger but I really think it's very justified, considering the quality of the code on PProPanel. Maybe aspiring sith lord is better?

[Bruce Bullis]

It seems that PProPanel, for all its faults, already demonstrated the functionality you need, above.

Yes, we'll fix those links with our forthcoming release.

[Thomas_Szabo]

hyuvii  wrote

I appreciate his patience to my anger but I really think it's very justified, considering the quality of the code on PProPanel. Maybe aspiring sith lord is better?

Anger is a part of your personality. You may put some intellectual logic behind it in order to justify it. You wouldn't even have to worry since this attitude is becoming popular nowadays. But remember, it is YOUR anger. Your anger is a result of how YOU perceive the world and what YOU make out of it.

My kudos go out to Bruce because he handles a young padawan who is yelling and telling people how — their work is but actually wants help from them - and he helps you although you're disrespecting him and his team.

But it is great that you came across the "astonishingly bad" code. You have the chance to make it better and send the Adobe guys some pull request of your refactor. It's your chance to be constructive and help.

Moderator note: Kindly do not use profanity in the forum. It is against community guidelines.