FREEJ SCRIPT INTRODUCTION $Id: freej_scripting.txt 255 2004-11-26 17:44:42Z jaromil $ FreeJ is an asynchronous video rendering engine, it can be scripted using javascript syntax in an object oriented way, to control its operations thru a procedural list of commands and actions. This way we can start talking about "procedural video" as an evolution of the current non/linear paradigm widely spread in video production. Far from starting with such an high theoretical approach, this document aims to be a small and effective introduction to the first free software implementation of such a powerful functionality. It will not cover the programming syntax, but simply describe the objects that are made available to script FreeJ. Knowledge of generic object oriented programming syntax is suggested but not strictly necessary to make the first steps in the wonderful world of Procedural Video Scripting. Now let's get started! FreeJ scripting is completely object oriented, meaning that almost every operation is provided by objects that can be created: there are no global functions, but commands that are strictly related to a certain object. Layers and Effects are the object classes we can deal with. Once they exist, they will provide methods to control their operations. EXAMPLE: my_text_layer = new TxtLayer(); // create an new TxtLayer object (1) add_layer(my_text_layer); // make the new layer shown (2) my_text_layer.print("hello world!"); // print a message on the layer (3) In this example (1) we first create a new instance of the TxtLayer() class, which provides the Truetype rendering text layer; (2) then we add it to the list of layers processed by the engine; (3) at last we use the print() specific method to print something on the screen. Now try your first script by writing the three lines above in a file and then execute the file with 'freej -j myfile' there you are? then consider in *NIX systems you can use the interpreter header #!/usr/local/bin/freej -j at the beginning of your script, then by making it executable you'll have a self executing freej script! Generic and Specific methods: Every layer class inherits methods from the Layer superclass, providing generic methods common to all of them. Generic methods are available to change Layer attributes like: position, blit method, rotation, zoom, spin etc. Specific methods are found only on their layer, they can control special operations that a specific layer provides, like: printing a word on the text layer, appending a line to the scroll layer, skipping to a keyframe in a movie layer, etc. Here we go with a reference of all the methods made available by FreeJ: GENERIC METHODS common to all layers Layer.set_position(int x, int y) // coords of the upper left corner .set_blit("name") // must be an existing layer .set_blit_val(int val) // usually a value between 0 and 255 .rotate(double val) // usually between 0 and 360 .zoom(double x, double y) // floating point multiplier, // 1.0 means no zoom, 2.0 means double size .spin(double rotation, double zoom) // the layer will start rotating // and/or zooming (0 means stop) SPECIFIC LAYER TYPES: new CamLayer("/dev/video") new TextLayer("poetry.txt") (*) new MovieLayer("movie.avi") new ImageLayer("photo.png") new VScrollLayer("book.txt") (*) new ParticleLayer() // doesn't need a file (*) = the filename can be also omitted, the layer is then used with its own methods to feed the data to be processed. i.e. TxtLayer.print("string") or VScrollLayer.append("phrase") the constructor initialization consists of an open() on the file and it can return NULL in case of failure. In case the object returned is not NULL, it can be initialized using the init() call. ...to be continued... see the script example in doc/freejscript-example.js