FCP 5.1.2 for Script Kiddies

As the administrator of quite a few FCP seats for a few years now, I’ve been hanging out for some kind of way to automate FCP for most of that time.The XML introduced with version 4 promised all sorts of streamlining (and I put it to good use), but it still requires human intervention to start/stop/save anything. Closer, but no cigar.We have workflows here which just require humans to click the same buttons again and again, and (until recently) I had one script which used UI scripting to pretend to be a human clicking “Save as …”, filename, click OK, etc etc etc. (To generate a pile of FCP projects ready for use derived form an excel sheet of jobs with code numbers, duration etc). Could be better! (suffice to say it didn’t always work!)I even got me an audience with some senior FCP people at Apple and asked them directly. And they’re obviously listening. Slightly. One of the improvements brought in with FCP 5.1.2 is support for AppleEvents. I say “slightly” for two reasons:

  1. They’re Apple Events not AppleScript. There’s some example Objective-C code, which maybe I could have made something of in a few months, but nothing simple
  2. What they do seems a little odd. Or non-obvious anyway.

Once I got over my initial disappointment, I set to thinking. First, I worked out where Apple were coming from with how you were supposed to use these things. Then (with help from a page Google can no longer find, or I’d credit it) I managed to get my head around using Raw AppleEvents within AppleScript.

My findings

The basic workflow is: you can add arbitrary XML to an existing project (or extract it, change it and put it back). You can’t just create a new blank project, so my scripts do this:

  1. Duplicate a base template project, giving it the right name you want and putting it in the right place(via standard AS or Shell script)
  2. Open that Project in FCP (via routines below)
  3. Insert my custom-generated XML into this project (via routines below)
  4. Save and close the FCP project (via routines below)

You still can’t create a new project from scratch, export a movie of anything or do an automatic print-to-video or Edit-to-tape. So there are a lot of possibilities which … aren’t actually possible. But hopefully what we have here will help someone somehow! It has helped me to retire my UI scripting monster, with a faster and more reliable successor.And here are the routines I cooked up. I generally use POSIX paths (my scripts are total unapologetic bastard hybrids of shell and AppleScript. My motto is “quick-and-dirty is totally safe for a script under 2 screens long”) so these routines expect those. If you’re more of a purist, omit the word “POSIX” in front of “file”.Also, If you’re doing heavier work, you really don’t want to use these subroutines, with their repeated tell .. end tells, you want to just use what I have as a guide to the syntax.And lastly, I’ve only used three of the possible events. If you’ve actually read this far and want to know more, head on over to Apple’s Developer pages for the full information (the whole API is in FCP_AppleEvents.h). The basic raw syntax below can be applied to all of the events.

Sample Code

My basic code is:

-----------------Routines to talk to FCP via new v. 5.1.2 AppleEvents ------------------------
--From FCP_AppleEvents.h
property kFCPSaveAndCloseProject : 0
property kFCPDiscardAndCloseProject : 1
--We always refer to projects via their files. I'm always using POSIX file paths,
--if you don't, delete the word "POSIX" form each routine

--get FCP to open a file
on FCPOpen(aFile)
	tell application "Final Cut Pro"
		«event KeyGofcP» given «class fcpP»:POSIX file aFile
	end tell
end FCPOpen

--get FCP to insert XML into a project (you refer to the project as a file)
on FCPInsertXML(aFile, someXML)
	tell application "Final Cut Pro"
		«event KeyGiXML» given «class fcpP»:POSIX file aFile, «class xmlD»:someXML
	end tell
end FCPInsertXML

--get FCP to Close (and optionally save as per the flags)
on FCPSaveandClose(aFile, saveFlags)
	tell application "Final Cut Pro"
		«event KeyGcfcP» given «class fcpP»:POSIX file aFile, «class fcCF»:saveFlags
	end tell
end FCPSaveandClose
    • dwalker
    • January 22nd, 2008

    great article. helped me out a bunch. thank you!

    btw: any idea how to retrieve the xml from a fcp document?

    i’ve tried:

    <> given <>:POSIX file aFile, <>:someXML

    but i don’t end up with anything in someXML. am i missing something on the call to retrieve information?

    • pdaddy
    • January 22nd, 2008

    Hi dwalker,

    Wow, I helped someone. I should have mentioned in the article, and will ammend it, the actual header file at apple which lists each and every command. The one you want, I think, is ‘eXML’.

    From FCP_AppleEvents.h:

    @defined kFCPGetDocumentXML
    @discussion Allows an application to request the XML representation of an FCP Project. If the project is not open then it is first opened.
    The project is always brought to the foreground inside of FCP. If no project file is supplied, then no XML will be returned.
    @param kFCPProjectFileKey Which project file to operate on.
    @param kFCPXMLDataVersion An optional value controlling which version of the XML spec to use. The default is the current version.
    @result kFCPXMLDataKey The XML data, represented as a UTF-8 string.
    #define kFCPGetDocumentXML 'eXML' // the XML Export command
    #define kKGAEGetDocumentXML kFCPGetDocumentXML //deprecated name

    so in AS, something like:
    «class xmlD»:someXML = «event KeyGiXML» given «class fcpP»:POSIX file aFile

    .. I think .. the old memory’s a tad hazy.

    • Jasper
    • February 17th, 2009

    Are the AS routines still available?

    • Jasper
    • February 21st, 2009

    Okay, I’ve found the routines in the source of the website.
    I also need the XML data but I can’t figure it out.

    The «class xmlD»:someXML = «event KeyGiXML» given «class fcpP»:POSIX file aFile doesn’t work and I really don’t know how else to get the data stream.
    Could you please help me out?

  1. Jasper, I’m not sure what WP has done to my code, it seems to have eaten some line feeds.

    I’ll have to dig out my original scripts in a few days and see if I can make sense of it: this is FCP 5.x code so I’m not even sure if it will work in 6 unmodified.

  2. OK, just tried it and it works: are you using POSIX paths? If not, remove the word POSIX.

    I made an empty project in FCP, saved that. Made a sequence with 1 slug in it – exported just the seq as XML and deleted it from my project, then I just got some code to load the XML into a variable (“myXML”) and ran this and the sequence appeared in my FCP Proj again:

    FCPInsertXML(“/tmp/anfcpproj.fcp”, myXML)

    So, it works with FCP 6 for me, at least at a very basic level. HTH

  3. Also, to extract is eXML – I did mistype in my comment above. It would be:

    «class xmlD»:someXML = «event KeyGeXML» given «class fcpP»:POSIX file aFile

      • Dave
      • August 6th, 2009

      Hi, I tried that, it did not create the xml, it says,«event KeyGeXML» given «class fcpP»:POSIX file aFile does not return any data.

        • pdaddy
        • August 6th, 2009

        OK … have you opened a document first with FCPOpen()? Is there data in that document?

        The variable “aFile” needs to contain the POSIX path to an open FCP Project

        • Dave
        • August 13th, 2009

        Yes, it opens the final cut project. just can’t export the xml.

        i have:

        tell application “Final Cut Pro”«class xmlD»:/Users/chen/Public/test.xml = «event KeyGeXML» given «class fcpP»:POSIX file “/Users/chen/Public/test.fcp”

    • Brian
    • July 18th, 2009

    Is there a way to get a list of open projects?

  1. January 3rd, 2007

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: