This is a message.

Development environment

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 the following software in order to work on Flowplayer Flash plugins:

  • Flex 4.5 SDK

  • Java Development Kit (JDK)

  • Apache Ant

In addition to 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 Adobe Flash 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

Flex SDK Versions

The minimum Flex SDK version required is 4.5.1 which targets for Flash 10.1/10.2 and above with support for Stage Video features. For Flash 10.0 player targets, Flex 4.1 is required which provided support for Dynamic Switch Streaming features available in the Bitrate plugins and Streaming plugins. The newest version available is 4.6 for Flash 11 players.

You can download the Flex SDK from the following locations

To specifically target for Flash 9 and 10.0 players using the specified SDK, two ant properties are available to disable Flash 10.1 specific features like Stage Video and in the rtmp plugin for specific version features.

flash.use.10.1=false
flash.target.player=10.0.0

Text only

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 and on my Windows machine it's in E:\cygwin\home\Anssi\flexsdk. (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\flexsdk\bin
 
E:\cygwin\home\Anssi\flexsdk\bin> mxmlc
Adobe Flex Compiler (mxmlc)
Version 4.5.1 build 21328
Copyright (c) 2004-2011 Adobe Systems, Inc. All rights reserved.
 
mxmlc [options] [defaultVar]
Use 'mxmlc -help' for more information.

Text only

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.

Note: Flex SDK by default omits traceback output. To enable its trace() function change omit-trace-statements setting to true in the Flex configuration at %flex_sdk_home_folder%\frameworks\flex-config.xml:

<omit-trace-statements>false</omit-trace-statements>

XML

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\flexsdk\bin> javac -version
javac 1.6.0_13
javac: no source files
Usage: javac .... (rest of output omitted)

Text only

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 and final tool that we need is Apache Ant and also Ant Contrib. Download the Ant 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

Text only

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

To install Ant Contrib follow these instructions.

Compiling Flowplayer

Obtaining the source code

The sources that are available in our repository in Github. To checkout the latest sources, run the following at your command prompt.

> git clone https://github.com/flowplayer/flash.git

Text only

This will get you everyting that you need to start hacking: The player core, plugins, libraries and also the JavaScript plugins' source code.

Configuration

At this point, you should have a directory structure with core, devkit, plugins, lib and js-plugins located next to each other in the flash directory. It's time to configure the build.properties files to point to our Flex SDK installation. Open up core/build.properties or a global property file [userhome]/core.properties with your favorite editor. Edit the flexdir 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
flexdir=C:/path/to/your/flexsdk

Properties

As we are working on Windows, we need to also change the Flex executables to point to the Windows .exe files:

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

Properties

core/build.properties file contains references to different plugins so that it's possible to build all the various plugins into the player SWF. See this document for more information about building plugins and configuration into the player. Now we need to make sure that we don't reference any plugins that we don't have sources available in our workspace.

# this needs to point to the directory where we have the controlbar sources
controls-dir=../controls
 
# the most basic configuration required for included sources, add extra plugins here if building into the player or compiling all plugins at once.
plugin-classes=${plugins.dir}controls/src/actionscript ${plugins.dir}common/src/actionscript
 
# following specifies which plugins get compiled as part of the player build
plugin.buildfiles=controls/build.xml
 
# if you want to build the controls plugin and the content plugin as
# part of the core build, uncomment following
# plugin.buildfiles=controls/build.xml,content/build.xml
 
# the most basic configuration required for this build files property, it will come with all plugins included
allplugins.buildfiles=controls/build.xml

Properties

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

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

Properties

Specifying which plugins to build

The core/build.properties file contains a property plugin.buildfiles which plugins get compiled when you run ant in the core directory. Change this to suit your needs. Minimally you should have the controls plugin specified here as the player needs the controlbar to work properly.

# following specifies which plugins get compiled as part of the player build
plugin.buildfiles=controls/build.xml

Properties

Running the build

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

> ant
Buildfile: build.xml
 
check-uptodate:
[echo] main up-to-date: ${uptodate.main}
[echo] main up-to-date: ${uptodate.commercial}
[echo] lib up-to-date: ${uptodate.lib}
 
.....

Text only

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/frameworks/flex-config.xml
[exec] /Users/api/flowplayer/core/build/flowplayer.swf (105993 bytes)
[copy] Copying 1 file to /Users/api/flowplayer/core/build
[echo] building example
[copy] Copying 1 file to /Users/api/flowplayer/core/build/example-free
[copy] Copying 2 files to /Users/api/flowplayer/core/build/example-free
 
BUILD SUCCESSFUL
Total time: 31 seconds

Text only

If you see "BUILD SUCCESSFUL", the build was successful and you have a working player located at 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 core/build/flowplayer.commercial.swf.

Testing it out

The previous build also generates an example HTML file located at 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.

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 into the plugins folder. 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 (plugin-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:

DirectoryDescription

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.2.8" />
 
<!-- "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>

XML