1 Correct answer
Confusing documentation removed.
Yes, it returns true; in the importFiles implementation, it's testing for whether an error was returned from internal calls; 'true' is the result of confirming that no errors were received, that were not passed on to the user. The import error was already passed on to the user, in the form of an import error dialog.
How to react to failure conditions = a common practice (by those who manage the metadata of imported items) is to count the items in the destination b
...
6
Replies
Bruce Bullis wrote
Regarding your "What are consumers of the API supposed to do" question...I'm not sure where you were presented with info that says 'Hey, something went wrong internally".
You just presented it to me in this thread:
... in the importFiles implementation, it's testing for whether an error was returned from internal calls; 'true' is the result of confirming that no errors were received, that were not passed on to the user.
So, if importFiles() returns false, something went wrong internally and Premiere couldn't (or didn't) inform the user. It would honestly be more useful to have such an API return one of the following:
- A Array<ProjectItem> object containing references to the successfully imported items. Then you could easily cross-check what was properly imported and what wasn't based on the return value.
- An enum value (integer, constant, etc.) with information about what happened. Something like: 0 = Success, 1 = Failure (User Notified), 2 = Failure (User Not Notified), etc.
I do understand that this will not change soon. I'm mentioning it here so that you can point to a customer request in the future when further such APIs are added and there's an internal argument about how to structure the calls.
Bruce Bullis wrote
With importFiles, it would seem that you'd have the obverse problem; "Something may or may not have worked, but you're not telling me". I suppose the broad answer is "Ask us", as we're pretty responsive.
I'm not sure what you mean about having the obverse problem with this: "Something may or may not have worked, but you're not telling me." Here's how I would expect this to work given the boolean result:
if (!app.project.importFiles(["file1.mov", "file2.wav"]))
{
// One or more of the files did not successfully import.
// Depending on my situation, I may check to see which
// one and notify the user or attempt to modify a file
// in some way and then re-attempt the importation.
}
/*else
{
// If importFiles returns true, then there was no error
// and all files were properly imported.
}*/
By simply looking at the API's footprint, I would assume that it works as above. More information on why something failed would be excellent, but at least I don't have to jump through extra hoops to figure out if there even was an issue to begin with.
Bruce Bullis wrote
I suppose the broad answer is "Ask us", as we're pretty responsive.
Yes, there are problems and shortcomings with the documentation, and sample code. Both are still works in progress. There are literally hundreds of PPro panels in use, today, that were created with zero docs, and rougher sample code. While getting started could certainly be easier, I don't think current docs/code are a barrier to entry; we're happy to help.
Yes, I understand that we are encouraged to ask about APIs and pour over sample code to figure stuff out. Technically that's what I'm (we're) doing right now! 
In this case, the documentation that does exist (and for which we are extremely grateful) simply has some issues that could use some clarification.
I understand that you guys are working on it and I seriously appreciate that. I was surprised at how quickly you jumped on the GitHub ticket I opened about the documentation issue and pushed some adjustments! Awesome.
What I was trying to point out to you in those last paragraphs is that what you consider "common practice" is not obvious for users unfamiliar and inexperienced with the Premiere Pro APIs. When using the APIs for the first time, one might write some script that looks exactly like what I wrote above. However, the contents of the if-block will rarely-if-ever be processed and a bug will ensue. It may even be one that takes a good deal of time to track down. The purpose for providing this information was to give you a better sense of where I as a "consumer of the API" is coming from such that future documentation efforts may better speak to your user-base.
Yes, you guys have literally hundreds of PPro Panels in use. That's fantastic. But the amount of time collectively burned for each developer trudging through the development may be a surprisingly high value. Which is not fantastic. As a user, the knowledge that there are hundreds of other developers who've figured it out before me isn't super useful and feels like more of an admonishment than a help. At the end of the day, we'll get there. It may simply be a slow, painful process.
AdChoices