The Socket object allows you to set up a TCP connection with a server and exchange data with this server. A Socket is pretty versatile. We can set up different services like FTP file transfer, SMTP email, and Web services via HTTP. Today we are going to demo a very bare-bones Web Service using HTTP. How bare bones? Well, for this demo we are simply going to prepopulate some sample values in a JSON string and serve it up from a web server. In our next demo, we’ll go about connecting this service to different databases.

After Effects 7 introduced some useful new UI controls including a ListBox and DropDownList. Both of these controls work really well for grabbing multiple values like a group of projects, scene list, lower thirds or slate info. The main difference between the two is that a ListBox displays all of the values available and let’s you select multiple items if you rig it correctly whereas the DropDownList only displays one value at a time. For this demo we’ll use a DropDownList.

Typically, you would create an array of string values in your script and those values would populate your list. Like so…

var projectArray =["Sample Project1", "Sample Project2", "Sample Project3"];
win.projectList = win.add ("dropdownlist", [20,25,230,120], projectArray);

But what happens if you don’t know what values you’ll need in your list when you write your script? You can dynamically populate your script at script runtime. Aditionally, After Effects 7 has a strong event model that let’s you update information based on user interaction. We’ll also cover updating our info in a later demo.

So we’ve covered our UI control, what about the Socket? It is pretty straight forward. We set up our Objects with a typical Javascript Constructor and set some variables with the location of our Web Service and use the open(), write(), read(), and close() methods of the Socket object to communicate with our Web Server over port 80. Like so…

       webConnect	= new Socket;
	  response	= new String;
	  lines		= new Array;
	  if(webConnect.open("your-web-server.com:80")) {

		webConnect.write('GET /path/to/your/sampleProject.json HTTP/1.0\n\n');
		response	=  webConnect.read();
		lines		= response.split(/\n/);
		projects	= lines[lines.length-1];

		webConnect.close();

		return projects.toString();

	}else{
		return  '{["unable to open webConnect via Socket"]}';

	}

There are a couple of lines of interest in the previous code. Notice how we use response.split(/\n/) and lines[lines.length-1] above? We do this because we really are communicating at a low level with the Socket object and response = webConnect.read() includes the response header including the server information, response type, etc. We know we have a simple one-line JSON file at the end of our web service so we can simply grab the last line. In a more complex service we'd need to be much more robust. We also wrap our Unable to connect message with a JSON wrapper, return '{["unable to open webConnect via Socket"]}'; so that we can use eval() on the string even in an error condition.

Our final demo script.

//grab our projects via a simple web service
var projectsString = getProjects();
//check for existence of Projects string and populate DropDown with error if we don't have one

if(projectsString){
    //the JSON eval to get an array of projects
    var projectArray = eval(projectsString);
}else{
	var projectArray = ['Unable to connect to Projects Server'];
}

//buid and show our UI
var win = new Window('palette', 'Project DropDown Demo',[100,100,352,165]);
var w = buildUI();
w.show();

//the getProjects method, notice the nested function. The nested (inner) function is private to its containing (outer) function. This gives us an opaque interface for getProjects() that let's us do validation and webConnect without revealing the details of the connect. More on this in later demos

function getProjects() {

           	//here is where we do internal validation before we return a valid webConnect
		//things like version check etc.

		return webConnect();

           //the Socket connection setup
		function webConnect (){

			webConnect	= new Socket;
			response	= new String;
			lines		= new Array;

                //open the connection, change the your-web-server.com obviously
			if(webConnect.open("your-web-server.com:80")) {
                      //Use GET to grab the JSON with the path to your web service
				webConnect.write('GET /path/to/your/sampleProject.json HTTP/1.0\n\n');
				//put the response in a variable
                      response	=  webConnect.read();
                      //grab the last line
				lines		= response.split(/\n/);
				projects	= lines[lines.length-1];
                      //close the connection
				webConnect.close();
                      //return a string value to the eval()
				return projects.toString();

			}else{
                       //return a JSON string with our problem
				return  '{["unable to open webConnect via Socket"]}';

			}
		}

	}

//build our UI
function buildUI(){

	 if (win != null) {

		win.projectList = win.add ("dropdownlist", [20,25,230,120], projectArray);
		win.projectList.selection = 0;

      }
         return win

	}

When I run our demo with this JSON

{["Sample Project1", "Sample Project2", "Sample Project3"]}

I get this in After Effects

Pretty nice. What's next? There isn't any security model so we'll either need to add authentication or run this service behind a firewall. We need to hook up our service to a database and develop methods for acquiring different sets of data. We're on our way.

The downloadable version of this script includes a link to a working demo that I'll try and keep running for a bit. It's pretty straight forward to set up on any working web server.

Downloadable version of this script and sample JSON file

I’ve posted a small application and tutorial at Final Cut Pro to After Effects Scripting without the hassle for those that find the scripting presented here a little daunting. The following article covers the steps and ideas encapsulated in the application if you’re more interested in the process for learning to script After Effects and Final Cut Pro yourself.

I work a lot in Final Cut Pro and After Effects. They are both really strong programs and more than once I’ve had reason to move projects, art, text, etc. between the two programs.

Until recently, the only option you had to do this kind of interchange was a product called Automatic Duck (which I highly recommend btw) and in previous versions you still had to use Avid’s interchange format and jump through a few hoops to move between the programs.

Now with Final Cut XML and more robust scripting available in After Effects you can finally flow between the two programs with relative ease. In this first installment, I’ll outline a simple workflow for getting clips in a FCP sequence into a AE project. In future posts I’ll go over text elements, filters, generator items etc., but all of these follow the same general development cycle and will just be elaborations on a theme.

THE WORKFLOW

Final Cut XML was introduced in Final Cut Pro 4 and has gone through one revision at the time of this article. It’s a pretty robust format, but today we are just going to pick out the items necessary to get our work done. After Effects scripting really started to open up at version 6.5 and it looks like Adobe is committed to opening up more and more of the program to outside developers with each revision. What we’re doing today should work fine with at least Final Cut Pro 4 XML and After Effects 6.5.

Final Cut Pro is exporting XML and After Effects is using Javascript for scripting, and luckily enough smart folks have developed an easy way for XML and Javascript to work together (thank you lazyWeb). The “special sauce” for what we’re doing is called JSON. JSON is an interchange format somewhat like xml, but the cool thing about it is that we can use the eval() command in Javascript and get nicely packaged Javascript objects after wrangling our xml.

So the first order of business is to grab the items of interest in a FCP-XML file and convert it to JSON.

(note) In these examples I’m using PHP for the xml wrangling, but just about any programming language with xml, xpath and xslt support that can output json will work fine. I chose PHP for this demo because of it’s ubiquity and relative straight-forwardness. I’m also using PHP 5 for it’s easier XML handling, so so-much for my ubiguity argument. You language zealots can go elsewhere for entertainment.

Step1: Export an FCP-XML file

We are going to export one sequence with a few clips on a timeline for demonstration purposes. I’ll edit one clip to show inpoint-outpoint translation.

1) I place a few clips in a FCP project window and place them in a sequence.

2) I use the export->xml file window and save as version 1 xml. (I’m not using any features of version 2 and I want compatiblity, this should still work with version 2)

Step2: Convert FCP-XML to JSON

1) I parse the FCP-XML file using the following script

include_once("json.php");
//hard coded FCP xml, use a dialog to drive to a file in production
$fcpXML = simplexml_load_file('fcpToJsonCut.xml');

//xpath match on project info
foreach($fcpXML->xpath('//sequence') as $projectInfo){
//if we don't typecast, we get a simplexml container
	$sequenceArray =
    array('sequence'=>array(
          'name'=>(string)$projectInfo->name,
         'duration'=>(int)$projectInfo->duration,
         'rate'=>(float)$projectInfo->rate->timebase,
         'height'=>(int)$projectInfo->media->video->format->samplecharacteristics->height,
         'width'=>(int)$projectInfo->media->video->format->samplecharacteristics->width));
}

//xpath match on clipitem, in the interest of simplicity we ignore the audio
foreach($fcpXML->xpath('//video/track/clipitem') as $clipitem){

//if we don't typecast, we get a simplexml container
$itemArray[] = array(
     'clip'=>array('name'=>(string)$clipitem->name ,
     'path'=>(string)$clipitem->file->pathurl,
     'start'=>(int)$clipitem->start,
     'end'=>(int)$clipitem->end,
     'fcpin'=>(int)$clipitem->in,
     'fcpout'=>(int)$clipitem->out,
     'duration'=>(int)$clipitem->file->duration));
}
	//create an array to hold our FCP info
	$jsonArray = array();
	//push our arrays
	array_push($jsonArray, $sequenceArray);
	array_push($jsonArray, $itemArray);
	//encode in json
	$json = new json;
	$encoded = $json->encode($jsonArray);
	//echo the results, in production we would write to a file
	echo $encoded;

This is really the minimum information necessary to get our clips into AE. We use xpath to match the parts of interest, and in the interest of simplicity we ignore the audio clipitems, we’ll save that for a later exercise. We then add our values into two arrays. A sequence array which is all of our information about the project, and an array of video clipitems with information about the edit. Finally, we encode and output our JSON info.

(notes)
I’m using the json script available here UPDATE: 02-02-2007 It looks like Jack Sleight is doing some remodeling over at reallyshiny.com where the script I used was housed, I’m going to go ahead and post the version I used for this demo here, I’d go ahead and use the PEAR package since it’s a more thorough implementation but I’ll leave it here for completeness unless Jack asks me to remove it. There is a nice pear package, and even a c extension, but I’m using this class for portability. If you need a faster, more robust option check out the other two.

I’ve hard coded the xml file and the json output in the example, but you’ll want to write a file input and output for your production code, we’ll cover these in future installments.

One of the interesting things in the php code is the typecast from a simpleXml container to strings, ints and floats. If we don’t do this we end up with a container array and a numerically indexed value. You can keep that if you prefer, but it’s a bit cleaner if we typecast here.

Step 3: Import JSON and create elements in AE

Here is the .jsx script to convert the JSON to an AE project.

//I take the echoed JSON data and hard code the result, in a production environment,
//you'd use a dialog to read in the value, we'll cover that in another exercise

//JSON info
var encoded_data = [{"sequence":{"name":"fcpToJson","duration":2092,"rate":30,"height":486,"width":720}}
[{"clip":{"name":"Bottle_06_14_05_FINAL.mov",
"path":"file:\/\/localhost\/Volumes\/workDrive\/demoFiles\/Bottle_06_14_05_FINAL.mov",
"start":0,"end":900,"fcpin":0,"fcpout":900,"duration":900}},
{"clip":{"name":"IfWallsCouldTalk-open.mov",
"path":"file:\/\/localhost\/Volumes\/workDrive\/demoFiles\/IfWallsCouldTalk-open.mov",
"start":1144,"end":1445,"fcpin":0,"fcpout":301,"duration":301}},
{"clip":{"name":"No Taste Open.mov",
"path":"file:\/\/localhost\/Volumes\/workDrive\/demoFiles\/No%20Taste%20Open.mov",
"start":1871,"end":1993,"fcpin":110,"fcpout":232,"duration":331}}]];

//the magic JSON eval
var decoded_data = eval(encoded_data);

//check if there is a project, this is no longer technically necessary in AE7
//but it doesn't break anything so we leave it in, thanks Jeff
	if(!app.project){
	    var myProject = app.newProject();
	}else{
	    var myProject = app.project;
	}

 //here is where we iterate through our javascript object to grab important data

	for(x in decoded_data){

	//here is where we grab the sequence data

	if(decoded_data[x].sequence){
		var sequenceName = decoded_data[x].sequence.name;
		var sequenceHeight = decoded_data[x].sequence.height;
		var sequenceWidth = decoded_data[x].sequence.width;
		var sequenceRate = decoded_data[x].sequence.rate;
		var sequenceDuration = decoded_data[x].sequence.duration / sequenceRate;
//.9 = D1 comp, I've hard coded a float value rather than
// coerce NTSC-CCIR-601 as a pixelaspectratio element
		var myComp = myProject.items.addComp(sequenceName ,
           sequenceWidth, sequenceHeight, .9, sequenceDuration, sequenceRate);

		var layerCollection = myComp.layers;
	}

	//import footage

	for(y in decoded_data[x]){
		if(decoded_data[x][y].clip){

		var os = system.osName;

// we need the path sans localhost, etc,
// I'm still working on this part, Final Cut and AE use a a different path structure,
//Final Cut uses a fully qualified URI, i.e. File://localhost whereas
//AE's absoluteURI is based off the boot drive, so we work backwards from Volumes.
//Of course this breaks on the users folder which resolves to ~/,
//this case is not handled here and we don't even check for Windows,
//since your using a Mac for Fcp right?
//And if you move the project from the drive you created the XML, the hard path breaks.
//Geez! Lot's of work to do here. Luckily it's just a demo.
//Feel free to drop me a line if you've worked through this better than I have.

	if(os == 'MacOS'){
		var fileRef = decoded_data[x][y].clip.path;
		if(fileRef.indexOf('Volumes') != -1){
			//on full hd path
			var pathStart = 'Volumes';
		}
var fileSubstring = fileRef.substring(fileRef.indexOf(pathStart) + pathStart.length, fileRef.length);
}

//AE is a little weird here, you have to build an ImportOptions object so you can import the file.
	var my_io = new ImportOptions(new File(fileSubstring));
	var myItem = myProject.importFile(my_io);

  }

}

//We first have to import the footage before we can place it,
//this is because items is a numerically indexed object rather than named...
//or at least I think so, if you know how to address an item by name
//this next part might be unnecessary.	

//insert footage

	var items = myProject.items;
	var allFootage = new Array();

//run backwards to keep layer position
	for (var i = items.length; i > 0; i--){
   		if (items[i].typeName == "Footage"){         // Retrieve only footage items
        		allFootage[allFootage.length] = items[i];
		}
	}

    for(x in allFootage){
	    layerCollection.add(allFootage[x]);

	}

}
//finally we position the footage, making arrangements for inpoint/outpoint if there was a cut.
//position footage

    var layerIterator = 1;
		for(x in decoded_data){
			for(place in decoded_data[x]){
				if(decoded_data[x][place].clip){
					var start =  decoded_data[x][place].clip.start / sequenceRate ;
					var end =  decoded_data[x][place].clip.end / sequenceRate ;
					var duration = decoded_data[x][place].clip.duration;

	//check for a cut

	if((decoded_data[x][place].clip.end - decoded_data[x][place].clip.start) != duration){

		var fcpin = decoded_data[x][place].clip.fcpin;
		var fcpout = decoded_data[x][place].clip.fcpout;
		var cutStart = start - (duration - fcpin) / sequenceRate;
	     myComp.layer(layerIterator).startTime = cutStart;
	     myComp.layer(layerIterator).inPoint = cutStart + fcpin / sequenceRate;
		myComp.layer(layerIterator).outPoint = cutStart + fcpout / sequenceRate;
	}else{
		myComp.layer(layerIterator).startTime = start;
	}
		layerIterator++;
	}
  }
}

Place the .jsx script from the sample files in the .zip file below in the Applications/After Effects/scripts folder, and select file:run script. In the next dialog, select the json file you produced in the php step above.

That’s it in a nutshell. There is not much error catching and the info we extract from the xml is very task specific, but that is the beauty of a workflow hack. We get right to the meat of our problem in a very direct way so that we can concentrate on the task at hand. If you find yourself doing the same sort of thing over and over again, I encourage you to develop more robust routines and plan for where things might go awry (like our path problem above).

CONCLUSIONS

I wouldn’t forego your purchase of Automatic Duck if you’re moving lots of data between the programs on a regular basis. Think of Automatic Duck as the heavyweight solution for workflow when you need to move projects on a regular basis and FCP-XML to AE scripting as the more lightweight and hackable option when you need to munge data or develop your own solutions for a project.

I’ll be going over more examples in the coming weeks. We’ll flesh out our toolkit for moving between the two programs and do some cool hacks. As always, if you have any ideas or corrections to the above give me a shout at dale(at)creative-workflow-hacks(dot)com.

Here are the files used in this demo. I’ve enclosed the sample fcp.xml for demonstration purposes, but remember the path will fail because your drives and media won’t match mine. I encourage you to play with your own files, but be sure to take a look at the limited path support included in the script and adjust accordingly.

tip of the hat to Jeff Almasol at redefinery for the excellent scripting reference stuff.