Mozilla Skin*/?>

CL2 Project Scripting

From ConduitWiki

Back to User's Guide contents


Conduit Live 2 has an extensive API for controlling node widgets. Some are explicitly scripting-oriented (like Script Widget); others have a scripting interface behind the scenes.

For example, the Movie/Image Source node widget can be controlled using scripts. There are two ways to accomplish this:

  • Use the command line to manipulate the node widget directly through scripts.
  • Write an onRender script for the node widget. This function will get called each time the node widget renders its output.

The Script Editor is the interface for both of these tasks. It's found in the Tools menu.

To control the Movie/Image Source widget directly, try the following simple test:

  • Load a video file in the default source node widget. (Its name should be "source"; if not, you can rename it by entering that name in its top-right corner text box.)
  • Play the project (Output menu > Play).
  • Open the Script Editor and type the following line.
stream.getNodeById('source').stop()


To create an onRender script, make sure "source" is selected in the pop-up menu at the top of the Script Editor, then enter the following in the Script text box and press Save:

this.onRender = function() {
   sys.trace("position: "+this.playPosition);
}

Now, as the node renders, it will write out its current position (in seconds) to the Trace output in the Script Editor.

Standard objects

The project scripting environment contains some standard objects. These are accessible everywhere.

stream

This is the primary "container" for accessing node widgets and project settings. (It's very much like the window object in web browser environment.) The following properties and methods are commonly used:
timeInStream
The current time (in seconds).
isTimelineMode
Tells whether the project is in Timeline or Free Run mode.
getNodeById( nodeName )
Gives access to a node widget by its name. The name can be found in the text box in the top-right corner of the node widget, in the Project view. (This function is very similar to getElementById() found in web browsers.)
enqueueRender()
Calling this function tells the application that values have changed and it should render. (Usually you only need to call this when responding to events from other node widgets which are not directly connected to the Display node.)

sys

This object contains methods that interface with the system. The following methods are available:
trace( aString )
Prints aString in the trace output text box in the Script Editor.
log( aString )
Prints aString in the operating system's console log. (On Mac OS X, it can be viewed with Console, available in Applications/Utilities.)
readLocalFile( path )
Reads a local file from the given path. This operation may be restricted in some contexts (for example, all system folders are forbidden). If successful, this call returns a ByteBuffer object (ByteBuffer reference).

app

This object contains values specific to Conduit Live 2 application plugins. This can be used to interface with e.g. the Stage Tools plugins.


Finding out object properties

An easy way to explore the JavaScript APIs within Conduit Live 2 is to use the Script Editor's command line. With the Object.keys() function, you can print out all the methods and properties available on any particular object.

Open the Script Editor (Tools menu > Show Project Script Editor), then enter the following on the command line, and press Enter:

Object.keys(stream)

The trace output view will display the result value of the keys call, which is an array and looks something like this:

["isTimelineMode","evalRefTime","startRefTime","currentRefTime",
"timeInStream","projectTimebase","projectRenderSize",
"getNodeByTag","enqueueRender","getNodeById"]

To find out whether a key is actually a property or a function that can be called, use the following:

Object.isFunction(stream.getNodeById)


Back to User's Guide contents