3. Turbine Media Markup Language

This chapter describes the very powerful Turbine MML language that allows you to create a variety of multimedia elements. A good number of examples is included while the reference for all tags available on the MML Reference section.

• Turbine MML
• Placing Elements on the Screen
• Placing Elements Across Frames
• Moving and Removing Elements
• The <Place> Common Attributes
• The <Media> Tag
• Using Text
• Shapes
• The <Image> Tag
• Movie Clips
• Buttons
• Video
• Audio
• The <Script> Tag
• AutoLayout

Turbine MML

Turbine Media Markup Language is an XML language that models all the possible multimedia elements inside Turbine, from text, images and shapes to audio and video, as well as complex commands like charts and automedia. MML is pervasive across Turbine, it can be used both from text MML templates as well as from inside Flash .swf template files. Turbine MML specifies where and when elements are placed, moved or removed. An example of MML that displays text, starts playing an MP3 and creates a movie clip with two images:

 
Being an XML language, common XML characteristics also apply - for example XML-style comments, XML entities, and the need for MML documents to be well-formed.
Here's a resume of the XML traits accepted by the Turbine MML parser:

In general, white space characters are ignored by the MML parser, except on places where they can be important, for example on text elements.

MML shares certain characteristics with HTML - for example, colors are specified in the traditional HTML form #RRGGBB or in the form #AARRGGBB, where AA is an extra alpha component.

Placing Elements on the Screen

Turbine MML is in part about describing where and when to display media elements, like text audio or video. Elements are placed in a screen with left-to-right X-axis values and top-to-bottom Y-axis values - horizontal coordinates increase to the right, vertical coordinates increase downwards, with all values in pixels:

For example to display an image at position 20,20 we can use the pos attribute, which is common to all visual tags:

 
What happens if a pos attribute is not specified? In this case, the behavior is ruled by the AutoLayout settings which basically tell whether the element should be placed below the latest one, to the right of last element or if the pos should default to the origin, that is to (0,0).

The coordinates origin, the point (0,0) is on the top-left corner of the media being generated. Certain elements like movie clips, buttons and shapes create their own coordinate spaces, which means that the location where those elements are placed represents the origin for any elements that are placed inside them (their 0,0) - this happens because those elements can contain other elements inside themselves. For example suppose this movie clip placed at position 100,100:

Inside this movie clip, an image is placed at position 20,20 - since the image is inside the movie clip and thus should use its coordinate system, the image is in fact placed at 100+20, 100+20 that is at global position 120,120. What happens is that elements placed inside the movie clip relate to the position where the movie clip is placed as being their origin, as their 0,0 point.

 
The Depth

Besides x and y coordinates, elements can be placed at different depth values, so that some elements are above or below other elements. The depth of an element is a numeric value, where higher values mean that the element was placed "higher", with respect to elements placed on lower depths. By default and if not specified, depth values continuously go up - that is an element placed after another element will be immediately above it.
On the next example, an image is placed at depth 10, another at depth 20 (above) and a third one in-between the two, on depth 15:

Elements should always be placed at separated depths, so that each element is on its own depth, to avoid confusions. Most of the time, automatic depth values are used, so this is not a problem.

But when numeric depth values need to be specified, and to make things easier, it's possible to use depth aliases for those numbers - a depth alias is a name that refer to a certain depth, instead of numeric values. On the next example the image and text elements will appear at the same depth:

The first time a non-numeric value is used in a depth attribute, it defines that depth as being that alias. Later the alias can be used to refer to that depth. Depth aliases are thus a convenience to structure element depths, avoiding the need to specify numeric depths.

 

Placing Elements Across Frames

On a multimedia environment such as Turbine, besides positioning elements spatially, it's also necessary to distribute them across time - to place them, remove them or change their position across the frames on a timeline. Each of these frames display for a certain duration of time, with all frames having the same duration - this duration is set by the frame rate at which the generated movie plays.

Besides the main timeline, each movie clip has its own timeline, with frames from all timelines displaying synchronized - that is having the same frame rate and displaying at the same instant. By default, successions of frames are displayed in a continuous loop, with the screen always starting in a cleared state (with no elements placed) on the first frame.

However, the "frame" and "frame rate" concepts apply in different ways to a PDF document. The "frame rate" concept is completely eliminated but the "frame" concept is translated to a PDF page. When outputting to PDF, one would end with a PDF document with as many pages as existing frames in the input media.

Some examples:

Moving and Removing Elements

Besides placing elements across frames, one must be able to move and remove them where necessary. This can be accomplished with the <Move> and <Remove> tags.

Move tags deal with depth values - you can move whatever element is at a specified depth. On the next example, an image, which is at depth 10, displays for two frames at position 100,100 and is then moved to a different position (200,200) for another two frames.

Besides changing the position, the <Move> tag can in fact change any other attributes of an element - known as the common <place> attributes.

The Remove tag, removes an element placed at a certain depth. For example on the next example, an image displays for three frames at depth 10 and is then removed from the screen:

As in the <Move> tag, the elements to remove must be referenced by their depth values.

A special case of the <Remove> tag is when it is used without a depth attribute - on this case all the visible elements (elements previously placed) are removed from the screen. On the next example, two text blocks display for two frames are then removed and substituted by a new text block:

The <Place> Common Attributes

So far we've seen examples of element placing, with the pos and depth attributes - these two attributes are part of a family of attributes that are common to all visual tags, to tags that can be placed on the screen. The most interesting of these common attributes are:

These attributes are very important for element composition, because they can express a variety of effects: size changes, rotations, transparency and many others.

 
The id Common Attribute

The id attribute can be used on any element to specify that the element can later be used, for example to be placed several times into different positions or frames, through the <Place> tag. The id attribute works as the unique identity for the element, allowing for reuse of the element on multiple situations. On the next example, the logo-image.tiff image is loaded on the <Image> tag, displayed and assigned to the id "logo"; later it is placed three more times on distinct positions by the <Place> tags, by using the "logo" id attribute:

What if we wanted to define the image on the <Image> tag, but did not want to display it at that time? This can be accomplished by adding a flags attribute set to "define".

An interesting side-efect of the id attribute is that in Flash it exports the element into Action Script, making it available for later manipulation at player-time. This is equivalent to enabling the "Linkage Properties" on the Macromedia Flash editor, to be used with methods like MovieClip.AttachMovie or Sound.AttachSound.
 

The Instance Common Attribute

While the id attribute is a server-side identifier of the element that allows placement of multiple copies of such element, the instance attribute is instead a Flash player-time identification of element instances. In the Flash player, a Turbine element with the instance attribute set, can be referenced from Flash Action Script as a regular instance.
On the next example the instance name for an image is defined, and a script block later sets its _x and _y properties to 100,100:

Through the instance attribute, elements can be composed inside Turbine and then made available for direct Action Script manipulation on the Flash player.

.
 
 

The <Media> Tag

The <Media> tag is an optional top-level tag that can specify properties of the media being generated - properties like the frame rate, native size, background color or compression settings. The next example shows a <Media> tag specifying a native size of 400 x 300 against a blue background:

Most of the attributes available on the <Media> tag map into the {Media.*} special variables.
 

Using Text

Turbine includes sophisticated text layout capabilities accessible through a very simple HTML 1.0-like interface. There are two types of text elements:

• Static text through the <Text> tag, which allows extensive formatting and always displays with high-fidelity across different systems.
• Dynamic through the <TextField> tag which although not so controllable as static text, is available at player-time.

Static text is thus best fitted for non-changing code that complex layout/formatting, while dynamic text can be used for more "dynamic" purposes.
In both tags, Unicode characters and fonts can be used.
Let's see more about the two available text tags.

Text Tag

The <Text> tag creates static text blocks with the several options, most of which can be defined for the whole text block or down to paragraphs and individual characters:

• font faces, styles and sizes
• text color
• paragraph alignment
• line vertical leading
• character spacing
• definable text flow areas

Most of these characteristics can either be specified for the whole block as attributes of the <Text> tag:

- Or they can be specified inside the <Text> tag, as HTML-like formatting tags, allowing for fine granularity:

For the tags possible inside a <Text> tag, please see the Text Tags section on the MML reference.

By using the bounds attribute, a number of rectangular areas can be specified, across which the text will flow. The general rule is that text will always flow from the top to the bottom, trying to fit the next available flow area. For example, the following text displays first across a rectangular area, and then down across a thin right-side rectangle (of 100 pixels, between left=500 and right=600):

 
The <Text> tag can also be used with an src attribute, to load its contents from an external file or remote HTTP location:

 
TextField Tag

The <TextField> tag can display a dynamic or editable text block - the following options can be used when outputting to Flash:

• font faces, styles and sizes
• text color
• paragraph alignment
• line vertical leading and horizontal indent and margins
• a maximum length for editable text
• multiline text wrapping
• whether the text field is selectable and/or editable
• the text field can display * characters, as a password field
• the text field can display HTML-like tags
• a border and background can be displayed around the text field
• an Action Script variable can be mapped to the text field contents

When outputting to PDF, there are some limitations associated with text fields:

• the font used in the PDF text field is always Times-Roman
• the PDF text field font style is always regular
• the alignment is applied globally to the text field
• there are no line vertical leading and horizontal indent and margins
• there is no text wrapping
• the text field can't display HTML-like tags
• the text will be encoded using Windows Code Page 1252, often called the “Windows ANSI” encoding. This is the standard encoding for Latin text in Western writing systems

Because of the above limitations, when outputting text to PDF, it is generally advisable to use static text instead of text fields whenever possible, because of its extra flexibility.

An example of the <TextField> tag is:

As in the <Text> tag, <TextField> can also be used with an src attribute, to load its contents from an external file or remote HTTP location:

Shapes

The <Shape> tag and its inner tags allow the drawing of shape elements, from a set of commands to select line and fill styles, draw lines and curves, or draw graphic elements like rectangles or circles. Next is an example of a circle shape with a radius of 50 pixels, centered at 100,100 and filled with a semi-transparent red:

The next sections describe the capabilities of the different Shape tags. The reference for all the <Shape> tags is available here.
 

Fill and Line Style Shape Tags

Shapes can be rendered using a Line Style describing the thickness and color to use, and a Fill Color that basically tells the type of paint to use for the enclosed areas of a shape. For example, to draw a blue line with a thickness of 5 pixels, a Line Style command must be issued prior to this Line command - afterwards all commands that need to draw lines will use the last defined Line Style command; the same applies for Fill Style definitions.
There are three types of Fill Styles:

• Solid color fills, with the <FillColor> tag.
• Bitmap fills, with the <FillBitmap> tag, supports the same image formats from the <Image> tag.
• Gradient fills, with the <FillGradient> tag.

Line and Curve Shape Tags

Two types of lines are possible - straight and curved lines:

• Straight lines can be specified by their endpoints, with the <Line> or <LineTo> tags.
• Curved lines can be specified as quadratic (three points) or bezier (four points) with the <Curve> or <CurveTo> tags.

Graphic Shape Tags

Besides simple lines, tags are available to display other common graphic shapes like:

• Rectangles, with the <Rect> tag.
• Circles and Ellipses with the <Circle> and <Ellipse> tags.
• Ellipse/circle arcs with the <Arc> and <ArcTo> tags.
• Slices, (arcs connected to their center position) with the <Slice> tag.

The <Image> Tag

Through the <Image> tag, Turbine can load external images from local files or remote HTTP locations in the following formats:

• PNG
• GIF
• JPEG
• BMP
• TIFF

Displaying an image at a size of 200x160 pixels, through the size attribute is very simple:

A number of interesting things can be done with images, through the attributes of this tag:

Turbine will always try to reuse multiple equal images to optimize the generated file size.
 

Movie Clips

Created with the <MovieClip> tag, movie clips are the basic unit of time organization, allowing elements to be sequenced across time. Movie clips provide a base where a succession of frames (through the <Frame> tag) are displayed - on these frames elements can be placed, changed or removed as needed. Frames always have the same duration, which is specified by the global frameRate setting (available on the {Media.FrameRate} variable or through the Interface).
Besides being directly defined, movie clips can be loaded from external sources, either Flash .swf movies or other MML, by using the src attribute - the following example creates a movie clip with the contents of an external Flash .swf movie:

Please see the above 'Placing Elements Across Frames' section for an overview and examples of movie clips.

Buttons

Button elements created with the <Button> tag, can be used to create clickable hot-spots for anything from normal buttons to dragging areas and a lot more. A simple example of a button displaying an image with a text above it; when clicked, a URL is requested; when the mouse enters the button area, a wash.wav audio file is played:

On the example we can see button states expressed through the <State> tag; as well as button events, signaled on the event attribute of the <Script> and <Audio> tags.

Button States

Button states describe how the button will appear on the four possible states:

• Up state is the normal, default button state.
• Over state is when the mouse is floating over the button hit area (the Hit state).
• Down state happens when the user clicks the button.
• Hit state or hit area defines what is the sensible area of the button used to determine whether the mouse is floating over the button or whether it was clicked.

A button state is specified by the <State> tag, which can express one or more of these states. All the elements placed inside a <State> will appear as the representation of that button state.

The button tag can include a type attribute that can be set to "push" or "menu", specifying how the button behaves:

• With "push" type the mouse is captured, all events are sent to the button, for example clicking on a push button and dragging outside will still affect the button.
• With "menu" type, as soon as the mouse cursor leaves the button area it is ignored by the button, which returns to its normal state.

Button Events

If the button states specify the looks, the events specify what to do when a button changes state - two types of actions can be specified: scripting to execute or audio to play. The following events are possible, depending on the mouse interaction with the button:

Buttons are outputted to PDF by showing only its "up" state. Associated audio and script are not exported

Video

The <Video> tag can integrate video from the following formats:

• Animated GIF format
• FLV format (except FlashComm-encoded Nelymoser 8 khz audio)
• AVI format (Windows version only)
• QuickTime format (Windows version only - the QuickTime runtime must be installed)

The next example displays a video loaded from a QuickTime movie, at a 200x160 size, in 12 frames per second:

Please have the following characteristics in mind when encoding videos, most of these are limitations derived from running on a web server environment:

• The required codecs for AVI or QuickTime must be installed on the machine where Turbine runs - when in doubt over this try to display the video on Media Player or QuickTime player. Note that AVI and QuickTime integration is only available on the Windows version of PHP Turbine.
• FLV movies are the fastest to be encoded, followed by Animated GIFs; AVI and QuickTime will consume larger system resources.
• AVI and QuickTime (Windows only) have a limitation of a maximum of 16000 frames. If this is problem, the frame rate at which the video is being integrated must be decreased.
• Due to QuickTime SDK limitations, QuickTime (Windows only) videos cannot be encoded in parallel, rather they are internally sequenced by Turbine.
• Video and audio encoding quality settings are available for all formats, except for FLV videos, which are not re-encoded.
• Encoding can be a resource-intensive process, with all the related consequences - for example if running from a web server, the default page timeout (which can be set to larger values) can be reached.

In general, encoding time and final file size can be improved by the following two factors:

• Selecting a lower frame rate (less frames are encoded)
• Selecting a lower resample size (less pixels are processed)
• Selecting lower quality settings will lower file size

 
The following encoding options and quality settings are available on the encode attribute:

Video (except loaded from FLV format) is exported to PDF as individual images, one per frame/page.

Audio

The <Audio> tag can integrate audio from the following formats:

• WAV files (uncompressed)
• MP3 files (with 11khz, 22khz and 44khz sampling rates)
• FLV format (except FlashComm-encoded Nelymoser 8 khz)
• AVI format (Windows only)
• QuickTime format (Windows only - the QuickTime runtime must be installed)

The next example plays an audio block encoded from a WAV file, with an high ADPCM encoding quality:

Please have the following characteristics or limitations in mind when encoding audio, most of them derived from running on a web server environment:

• The required audio codecs for AVI or QuickTime must be installed on the machine where Turbine runs - when in doubt over this try to play the video on Media Player or QuickTime player. Note that AVI and QuickTime integration is only available on the Windows version of PHP Turbine.
• MP3 and FLV movies are the fastest to be audio-encoded, followed by WAV files; AVI and QuickTime will consume larger system resources.
• Due to QuickTime SDK limitations, QuickTime (on Windows only) audio cannot be encoded in parallel, rather it is sequenced by Turbine.
• Audio encoding can be a resource-intensive process (although not as much as video encoding), with all the related consequences - for example if running from a web server, the default page timeout (which can be set) can be reached.

 
The following encoding options and quality settings are available on the encode attribute:

Audio is not exported to PDF.

The <Script> Tag

With the <Script> tag, Turbine supports ECMA-262 Script, also known as Action Script or JavaScript. The full ECMA Script specification is available at:

http://www.ecma-international.org/publications/standards/ECMA-262.HTM

Although the above standard specification covers the whole ECMA-262, we suggest instead using the Action Script reference included with the Macromedia Flash authoring tool help, which is also available online at the Macromedia.com website:

http://www.macromedia.com/support/flash/action_scripts/actionscript_dictionary

The subset of this standard supported by the Macromedia Flash MX authoring tool is also supported by Turbine with the following characteristics:

• Deprecated Flash functions, from Flash 4 and Flash 5, are not supported

On the next example, Action Script variables are set by the script tag:

All the usual object-oriented techniques are supported - on the next example, an onEnterFrame handler is set to _root:

Script blocks can interact with Turbine elements, by using the instance attribute - on the next example, the coordinates of an <Image> are manipulated from a script object, by setting them to the current mouse position:

  
When used with the Turbine Window (by setting {Media.Debug} to Yes or through the <Media> tag), debug messages can be issued from script block, for debugging purposes. This is done by calling the turbineDebug(msg) function, which is made available when the Turbine Window is included on the generated media. On the next example messages are logged by calling this function:

 
Scripting can also be loaded from an external file or HTTP location by using the src attribute:

 
Scripts are not exported to PDF. 

AutoLayout

What happens when the pos attribute of a visual object is not specified - where is it placed? The answer depends on the current AutoLayout settings defined by the <AutoLayout> tag, or by the default {System.AutoLayout} variable. Depending on the AutoLayout type, the behavior is:

When using Vertical or Horizontal AutoLayout types, we can align the elements column or elements row, with the align attribute, using the usual left, right or center alignments.