You will recieve your password to this address. Address is not made public.

Your preferred username that is used when logging in.

Setting up your Flash development environment for Flowplayer development

Introduction

In this tutorial we will set up a Flowplayer Flash development environment. Flowplayer uses some "exotic" development tools that many Flash developers are not familiar with. For example, it uses Apache Ant for compilation and other build tasks. Here we will explain how to install all these tools and how to configure the build process. After reading this tutorial you should have all the required tools and libraries installed so that you can compile Flowplayer's plugins, and also compile the player itself.

Required software

We need to install following software in order to work on Flowplayer Flash plugins:

In addition to the these you will need a text editor or an IDE for editing ActionScript. Flowplayer does not force you to use any particular editor or IDE, you can choose your favorite. You can also use the Adobe Flash CS4 application for editing ActionScript, but that is not required. In fact, you will not find the typical .FLA files in any of the Flowplayer source packages because the compilation is done using the Flex SDK and Ant. Flash CS4 is not so good at editing ActionScript, but it's good when authoring animation and Flash graphics, and we recommend it for those tasks.

One popular editor for ActionScript 3 is the Flex Builder. It has rich ActionScript editing features and does a much better job at it when compared to Flash CS4. It is a commercial product, but free evaluation versions are available. Other good IDEs are FDT and Intellij IDEA that both have support for Flex/Flash.

Note that Flowplayer is not a Flex application. The Flex compiler is used in compilation, but none of the Flex components or Flex classes are used in Flowplayer. Flowplayer is a Flash application implemented in ActionScript 3.

We'll next install the required software packages starting with the Adobe Flex SDK. The Flex SDK is a free Flex and Flash development kit and it contains the compilers that are used to compile the player and plugins.

Flex SDK

You can download the Flex SDK from the Adobe's Flex site. The SDK is Open Source. After you have downloaded the zip file, unzip it to your desired location. You will later need to reference this installation location when you configure the Flowplayer build files. One good location for it is your home directory, on my Mac I have it installed in /users/api/flex_sdk_3 and on my Windows machine it's in E:\cygwin\home\Anssi\flex3sdk. (Note that in this tutorial I'm not working on Cygwin as the name of this Windows directory might suggest. I can however recommend Cygwin because it makes the command line experience in Windows much usable and efficient when compared to the standard Windows command prompt.)

Let's verify that we installed Flex correctly. Open the command prompt (or terminal) and execute the following commands. I'm typing this on my Windows machine and the following goes to the Command Prompt: 


E:\>cd E:\cygwin\home\Anssi\flex3sdk\bin

E:\cygwin\home\Anssi\flex3sdk\bin>mxmlc
Adobe Flex Compiler (mxmlc)
Version 3.3.0 build 4852
Copyright (c) 2004-2007 Adobe Systems, Inc. All rights reserved.

mxmlc [options] [defaultVar]
Use 'mxmlc -help' for more information.

I changed the working directory to the bin subfolder contained in the Flex installation folder. In that directory I ran the Flex compiler mxmlc. If you see similar output, you can be assured that the installation was OK.

Java Development Kit (JDK)

We need a working Java Development Kit installation. You might already have it installed, and to verify this, type the following at your command prompt: 


E:\cygwin\home\Anssi\flex3sdk\bin>javac -version
javac 1.6.0_13
javac: no source files
Usage: javac .... (rest of output omitted)

If you see similar output, the Java compiler has been found on your system. If not, you need to download and install it. The Java SE SDK is available here. Download the installation program and run it. After the installation is complete, verify the result by executing javac again at the command prompt. If javac is not found, you will need to add the JDK's bin folder to your Path (or PATH) environment variable. I have following included in my Path on Windows: E:\Program Files\Java\jre1.6.0_u13\bin.

Apache Ant

The third an final tool that we need is Apache Ant. Download the binary distribution and unzip it to your desired installation location. Next, add Ant to your Path (or PATH) environment variable, my Ant entry there reads E:\Program Files\apache-ant-1.7.1\bin. Next, verify the Ant installation by running: 


C:\Documents and Settings\Anssi>ant -version
Apache Ant version 1.7.1 compiled on June 27 2008

If you see similar output from Ant, you have it installed correctly. If not, follow the Ant installation instructions here.

Compiling Flowplayer

Obtaining the source code

First, we will compile the Flowplayer player SWF. We need the player compiled as a library when developing plugins for it because the plugins are compiled against the flowplayer.swc library. If you don't want to compile the player itself, you can download the flowplayer.devkit package and use the library contained in it. Note that having the player sources available is beneficial when developing plugins because you can then quickly lookup the player sources to see how it interacts with the plugin you are developing.

We're going to place the player sources and plugin sources all under one workspace directory. A good place is, for example, a folder called flowplayer located in your home directory. This workspace directory will hold sub-directories for the player and for all the plugins you will be developing or working with:

Next, you need to decide whether you want to work against the latest sources that are available in our Subversion repository. The other option is to download the source package and compile using the sources contained in it. To access the source repository, you will need a Subversion client installed on your machine. The IDEs mentioned above will include an integrated Subversion client. The player repository is hosted at Google code. To checkout the latest sources, run the following at your command prompt. Make sure you are in the flowplayer workspace directory when executing this: 


> svn checkout http://flowplayer-core.googlecode.com/svn/flowplayer/trunk/ flowplayer.core

This command will checkout the trunk (the branch containing the latest sources) from the repository into flowplayer/flowplayer.core. Next, we need to checkout the flowplayer.devkit module that contains supporting build scripts that are needed to compile the plugins. It will also hold the flowplayer.swc library that gets built from the sources contained in flowplayer-core. To fetch the devkit from the plugins repository, run the following. Again, make sure you are in the flowplayer workspace directory when executing this: 


> svn checkout http://flowplayer-plugins.googlecode.com/svn/flash/flowplayer.devkit/trunk/ flowplayer.devkit

Configuration

At this point, you should have a directory structure with flowplayer.core and flowplayer.devkit located next to each other in the flowplayer workskpace directory. It's time to configure the build.properties files to point to our Flex SDK installation. Open up flowplayer.core/build.properties with your favorite editor. Edit the flex3dir property that is found in the beginning of the file so that it points to the location where you installed Flex SDK: 


# you need to adjust the following to point to your Flex SDK
flex3dir=E:/cygwin/home/Anssi/flex3sdk

Next, check the devkit-dir property contained in the same file. Because we have the player and devkit directories both located in the same parent flowplayerdirectory, the default setting works and needs no modification. Also, the plugins.dir points to the parent directory where we are going to later place our plugin source code directories. As we are working on Windows, we need to also change the Flex executables to point to the Windows .exe files: 


devkit-dir=../flowplayer.devkit
plugins.dir=../

# change the following to point to the .exe files when running on Windows
mxmlc_bin= /mxmlc.exe
compc_bin= /compc.exe
asdoc_bin= /asdoc.exe

The final configuration is done to the flowplayer.devkit/plugin-build.properties file that is used when building plugins. Open it in your favorite editor and again change the flex3dir property to point to your Flex SDK directory and deploy_dir to point to the flowplayer.core directory: 


# you need to adjust the following to point to your Flex SDK
flex3dir=E:/cygwin/home/Anssi/flex3sdk

# where the compiled plugins will be deployed (copied) to
deploy_dir=../flowplayer.core

Building the player

Now that we have configured the player for compilation, it's time to test how the compilation works. CD (change directory) to the flowplayer.core and execute ant at the command prompt: 


> ant
Buildfile: build.xml

check-uptodate:
     [echo] main up-to-date: 
     [echo] main up-to-date: 
     [echo] lib up-to-date: 

.....

The compilation produces lots of output to the console, and when it finishes we should see the following:


compile:
     [echo] Building binary flowplayer.swf
     [exec] Loading configuration file /Users/api/flex_sdk_3/frameworks/flex-config.xml
     [exec] /Users/api/flowplayer/flowplayer.core/build/flowplayer.swf (105993 bytes)
     [copy] Copying 1 file to /Users/api/flowplayer/flowplayer.core/build
     [echo] building example
     [copy] Copying 1 file to /Users/api/flowplayer/flowplayer.core/build/example-free
     [copy] Copying 2 files to /Users/api/flowplayer/flowplayer.core/build/example-free

BUILD SUCCESSFUL
Total time: 31 seconds

If you see "BUILD SUCCESSFUL", the build was successful and you have a working player located at flowplayer.core/build/flowplayer.swf. If you get "BUILD FAILED", something went wrong. It's possible that the repository trunk contains a broken build and the compilation is failing because of that. In that case, please send an email to support [at] flowplayer.org.

To build the commercial version, run ant build-biz. This resulting player is flowplayer.core/build/flowplayer.commercial.swf.

The previous build also generates an example HTML file located at flowplayer.core/build/example-free/index.html. You can open up that file in your Web browser. It will load our freshly compiled flowplayer.swf and open it up in the page. Because the player by default tries to load the controlbar plugin you will get the error "300: Player initialization failed: Error: 301: Unable to load plugin: Unable to load plugin flowplayer.controls-3.1.1.swf". Looks like it's the time to build the controlbar plugin to get rid of this error!

Compiling plugins

We are going to build the controlbar plugin from the latest sources fetched from the version control repository. To checkout the sources, run the following at the command prompt. Make sure you are in the flowplayer workspace directory when executing this so that the plugin will be placed next to the player and devkit sources. 


> svn checkout http://flowplayer-plugins.googlecode.com/svn/flash/controls/trunk/ flowplayer.controls

We don't need to do any configuration for the controls plugin build since it reads the build properties from flowplayer.devkit/plugin-build.properties that we edited previously. The next step is to build the controlbar plugin: 


> cd flowplayer.controls
> ant
..
....
_deploy:
     [echo] deploying plugin to ../flowplayer.core
     [copy] Copying 1 file to /Users/api/flowplayer/flowplayer.core/build
     [copy] Copying 1 file to /Users/api/flowplayer/flowplayer.core/build
     [copy] Copying 1 file to /Users/api/flowplayer/flowplayer.core/dist

BUILD SUCCESSFUL
Total time: 0 seconds

As you can see from the last lines of Ant output, the build copied the flowplayer.controls.swf to flowplayer/flowplayer.core/build. This is where the example HTML file picks up the plugins and now we can again test by loading up flowplayer.core/build/example-free/index.html in the Web browser. This time you should see the player showing up correctly with the controlbar in its default location!

Developing your own plugin

The easiest approach for implementing your own plugins is to follow the same conventions and structure that is used by Flowplayer's "official" plugins, one of which is the controlbar plugin that we just compiled. These plugins all use the flowplayer.devkit/build.xml for compilation and other build tasks like building the distribution zip files. Your plugin can also include graphical assets that you design and create using the Adobe Flash CS application.

You should place your plugin in the same flowplayer workspace folder that already holds the flowplayer.core, flowplayer.devkit and flowplayer.controls folders that we have been working with in this tutorial. Let's take a look at the directory structure you should have in your plugin folder - this structure should be followed so that the devkit's Ant build file (build.xml) knows where to look for the different assets that are needed to build your plugin.

Directory structure

Here is the directory structure for plugins that use the flowplayer.devkit/build.xml for compilation and other build tasks:

directory description
src The root folder for different types of source files.
src/actionscript ActionScript source files.
src/flash Flash precompiled libraries to be included in the library path when compiling.

You can create the build.xml file for your plugin by taking the build.xml from the controlbar plugin and changing some of the property values defined in it. The properties that you need to change are all commented in the file shown below. Here are the relevant parts of the controlbar plugin's build.xml file: 

<project name="Flowplayer controlbar" default="deploy">

	<!-- The version number of our plugin, used in the zip and SWF file names -->
	<property name="version" value="3.1.1" />

	<!-- "basename" is the name of this plugin to be used in the SWF file name -->
	<property name="basename" value="flowplayer.controls" />

	<!-- The main class of our plugin. This is the main class provided to the mxmlc compiler -->
	<property name="plugin-main-class" value="org/flowplayer/controls/Controls.as" />

	<!--
		library-path should be defined if our plugin contains precompiled
		SWC files to be used in the compilation
	-->
	<property name="library-path" value="src/flash/default" />

	<!-- Location of the devkit -->
	<property name="devkit-dir" value="../flowplayer.devkit" />

	<!--
		Note that some properties and tasks that usually don't need any
		modification were left out from this example.
	 -->
</project>