Web DevCenter
oreilly.comSafari Books Online.Conferences.
MySQL Conference and Expo April 14-17, 2008, Santa Clara, CA

Sponsored Developer Resources

Web Columns
Adobe GoLive
Essential JavaScript

Web Topics
All Articles
Scripting Languages

Atom 1.0 Feed RSS 1.0 Feed RSS 2.0 Feed

Learning Lab

PHP Powers FreeMovie API for Flash

by Jacek Artymiak

When Macromedia, Inc. released the specification of the Flash (SWF) file format to the public, it opened the way for independent developers to create tools that supplement the Macromedia Flash authoring application and the (now-discontinued) Macromedia Generator.

The FreeMovie project attempts to create a high-level Application Programming Interface (API) to the Macromedia Flash (SWF) file format. Unlike other libraries, FreeMovie is not written in C or C++. Instead, the first implementation of FreeMovie, called FreeMovie/PHP, was written in PHP, with sister implementations in Java, Perl, Python, Ruby, and Tcl to follow in the near future.

Although writing such a library in C or C++ and compiling it as a dynamically loaded library (DLL) would no doubt result in faster code, it also complicates matters for programmers who cannot quickly "take their tools with them" when they move their applications from one operating system to another.

Web application developers who rely on classic compiled DLLs have lots of work to do when they move their work environment to another operating system (or even a different machine). They must often recompile the Web server, the DLLs, and the APIs that make it possible to use DLLs in the scripting language of their choice. This is a serious disadvantage to anyone who's looking for rapid development tools that allow easy integration with the existing environment, quick migration, and portability.

FreeMovie/PHP attempts to solve these problems. It's written entirely in PHP, which makes the library extremely portable and autonomous (it does not depend on any other libraries beyond the standard operating system libraries).

Design Principles

When we speak of the principles that govern the design of FreeMovie, autonomy is among the most important. Autonomy is understood as independence from external libraries other than standard operating system libraries, and a maximum reliance on the features provided by the default configuration of the interpreter in which a particular implementation of FreeMovie is written.

How successful such attempts are depends only on the richness of the set of features available in the default configuration of the interpreter. Practice shows that popular scripting languages like Perl, PHP, Python, REBOL, Ruby, and Tcl are more than up to the given task.

The second important design principle is portability. It's easily achieved using popular scripting languages, such as PHP, Perl, or Python, because interpreters of these languages have been ported to virtually all modern operating systems. This makes it very easy to move FreeMovie and the scripts that use it from one system to another.

The third design principle was ease of use. After all, what is the point of going to so much trouble to ensure autonomy and portability, if the code is difficult to use? Ease of use of FreeMovie is achieved by wrapping intelligent code around raw functionality provided by the SWF file format. It’s only after you’ve tried to hand-code SWF generator software that you can understand how much effort has gone into the design of the Flash-authoring applications sold by Macromedia, Adobe, and others. The complexity of the SWF file format is the price that has to be paid for its low bandwidth requirements.

The internal design of FreeMovie is also very simple and facilitates creation of custom versions of the original code base. The library consists of four modules:

  • FreeMovieCompiler -- implements SWF data types, structures, tags, and utilities used in converting bitmap images and TrueType fonts into the SWF format.
  • FreeMovieCompilerToolbox -- provides a high-level API to FreeMovieCompiler.
  • FreeMovieParser -- implements low-level functionality for parsing, disassembling, converting, and splicing SWF files.
  • FreeMovieParserToolbox -- provides a high-level API to FreeMovieParser.

Version 1.1 of FreeMovie/PHP implements only the first two modules: FreeMovieCompiler and FreeMovieCompilerToolbox. In the current state these modules provide adequate functionality for creating complex vector graphics and animations using all three types of fills (solid, gradient, and bitmap) in the SWF file format.

Such files can be generated dynamically by the PHP interpreter module, integrated with the Apache Web server. The SWF streams can be viewed using the free Macromedia Flash Player plug-in available for major operating systems as well as a number of pocket devices.

FreeMovie/PHP version 2.0 will introduce APIs for creating SWF files with sound and a TrueType-to-SWF font converter. Version 3.0 planned for release near the end of 2002 should include support for native ActionScript compilation (version 2.0 will let the developer create ActionScript via PHP calls).


FreeMovie is licensed under the terms of the XFree (BSD–style) license. This gives all developers maximum freedom and allows commercial users to use FreeMovie in their own products.


FreeMovie/PHP is available from http://freemovie.sourceforge.net. There is a link on the project’s home page that leads directly to the download page. The source files are currently distributed in two formats: .tar.gz and .zip with .rpm, .deb, and *BSD packages planned for the near future. Users of AIX, HP-UX, IRIX, Solaris, and other operating systems are encouraged to help package FreeMovie/PHP (as well as other implementations) in other package formats.

The next step is unpacking the archive with either tar –zxvf freemovie-php-1.1.tar.gz or unzip freemovie-php-1.1.zip.

The package contains two important files: freemoviecompiler.php and freemoviecompilertoolbox.php. Copying these into one of the directories on the PHP access path will make them instantly visible to the PHP interpreter.

That’s it, the installation process is complete.

Developing With FreeMovie

Writing scripts with FreeMovie/PHP is a simple affair -- if the developer obeys a few simple rules, that is. First of all, every script must start with a call to the header() function, as shown in the code listing below. No other comments, calls, and output should appear before that call, or the Flash Player plug-in will not start. It’s also a good idea to add the application/x-shockwave-flash MIME type to the server configuration file. For Apache, that file is called mime.types.

header("Content-Type: application/x-shockwave-flash");

// the header() function must _always_ be called first //

// import the FreeMovieCompilerTollbox


// initialize new SWF object.

$swf = new FreeMovieCompilerToolbox;

// set the global parameters of your movie
// frame size is in twips (1 twip = 20 pixels)

$swf->SetFrameSize(16000, 12000); // = 800 x 20, 600 x 20
$swf->SetBackgroundColor(255, 255, 255);

// lights! camera! action!


// frame # 00000

$CharacterInfo = $swf->DefineStraightLine(2000, 8000, 4000, 10000, 300, false, 0, 0, 0, 0);
$CharacterDepth = $swf->EasyPlaceObject($CharacterInfo["CharacterID"]);

// end frame # 00000


// That's it, Folks!


// send movie to the browser

print $swf->GetMovie();


Next, the script must import the freemoviecompilertoolbox.php module. When that is done, the script is ready to initialize the SWF object whose methods and properties are used to create the final SWF file.

Related Reading

Programming PHP
By Rasmus Lerdorf, Kevin Tatroe

Once the SWF object is ready, the script must set the initial parameters of the SWF file, such as the SWF format version number, frame size, frame rate, and the background color. When that’s done, the process or creating the movie begins with a call to the BeginMovie() function defined in the freemoviecompilertoolbox.php. Developers should remember that all coordinates and widths are expressed in twips (1 twip = 20 pixels).

This finishes the "header" section of the script and the developer is free to begin constructing the visual contents of each frame in the movie via calls to functions like DefineStraightLine(), DefineCircle(), and others defined in the freemoviecompilertoolbox.php.

However, developers should remember that the process of creating SWF files differs from the process of creating bitmap images with libraries like libtiff or gd.

Every character (geometric shape, movie sprite, or sound sample) in an SWF movie can be reused, therefore the SWF file format separates instructions that define characters (definition tags) from the instructions that tell the Flash Player to display or hide characters (control tags). Therefore, it is possible to define a character that doesn’t show up onscreen. To make it happen, the character ID number returned by one of the character definition calls should be passed to the character placement function, like in the example below:

$CharacterInfo = $swf->DefineStraightLine(2000, 8000, 4000, 10000, 300, false, 0, 0, 0, 0);
$CharacterDepth = $swf->EasyPlaceObject($CharacterInfo["CharacterID"]);

A call to the EasyPlaceObject() function puts the give character on the Display List, a list of characters that will be rendered onscreen after a call to the EndFrame() function, which creates a tag that marks the end of each frame in an SWF file. Characters placed on the Display List remain there until they are explicitly removed with a call to the RemoveObject() function.

The script ends with calls to EndMovie() and GetMovie(). The former creates the SWF file header and splices it with the raw SWF byte stream, and the latter returns the complete movie byte stream, which can be sent to the requesting client with a simple print statement or saved to a file (in which case, the initial call to the header() function is redundant).

Pages: 1, 2

Next Pagearrow