AIR for TV application design considerations

Video encoding guidelines

Adobe recommends that you use the H.264 codec for video delivered to AIR for TV devices.

The StageVideo class

AIR for TV supports hardware decoding and presentation of H.264-encoded video. Use the StageVideo class to enable this feature.

See Using the StageVideo class for hardware accelerated presentation in the ActionScript 3.0 Developer’s Guide for details about:

To best support existing AIR applications that use the Video object for H.264-encoded video, AIR for TV internally uses a StageVideo object. Doing so means the video playback benefits from hardware decoding and presentation. However, the Video object is subject to the same restrictions as a StageVideo object. For example, if the application tries to rotate the video, no rotation occurs, since the hardware, not the runtime, is presenting the video.

However, when you write new applications, use the StageVideo object for H.264-encoded video.

For an example of using the StageVideo class, see Delivering video and content for the Flash Platform on TV.

Video delivery guidelines

On an AIR for TV device, the network’s available bandwidth can vary during video playback. These variations can occur, for example, when another user starts to use the same Internet connection.

Therefore, Adobe recommends that your video delivery system use adaptive bitrate capabilities. For example, on the server side, Flash Media Server supports adaptive bitrate capabilities. On the client side, you can use the Open Source Media Framework (OSMF).

For more information, see the following:

Using hardware graphics acceleration

AIR for TV devices provide hardware acceleration for 2D graphics operations. The device’s hardware graphics accelerators off-load the CPU to perform the following operations:

This hardware graphics acceleration means many graphics operations in an AIR for TV application can be high performing. Some of these operations include:

To get the performance benefits of hardware graphics acceleration for these types of operations, use one of the following techniques:

For more information about bitmap caching, see the following:

Managing graphics memory

To perform the accelerated graphics operations, hardware accelerators use special graphics memory. If your application uses all the graphics memory, the application runs more slowly because AIR for TV reverts to using software for the graphics operations.

To manage your application’s use of graphics memory:

• When you are done using an image or other bitmap data, release its associated graphics memory. To do so, call the dispose() method of the bitmapData property of the Bitmap object. For example:

  myBitmap.bitmapData.dispose();

  Note: Releasing the reference to the BitmapData object does not immediately free the graphics memory. The runtime’s garbage collector eventually frees the graphics memory, but calling dispose() gives your application more control.

• Use PerfMaster Deluxe, an AIR application that Adobe provides, to better understand hardware graphics acceleration on your target device. This application shows the frames per second to execute various operations. Use PerfMaster Deluxe to compare different implementations of the same operation. For example, compare moving a bitmap image versus moving a vector image. PerfMaster Deluxe is available at Flash Platform for TV.

Managing the display list

To make a display object invisible, set the object’s visible property to false. Then, the object is still on the display list, but AIR for TV does not render or display it. This technique is useful for objects that frequently come and go from view, because it incurs only a little processing overhead. However, setting the visible property to false does not release any of the object’s resources. Therefore, when you are done displaying an object, or at least done with it for a long time, remove the object from the display list. Also, set all references to the object to null. These actions allow the garbage collector to release the object’s resources.

Screen resolution

Currently, TV devices typically have one of these screen resolutions: 540p, 720p, and 1080p. These screen resolutions result in the following values in the ActionScript Capabilities class:

To write a full-screen AIR for TV application for a specific device, hard code Stage.stageWidth and Stage.stageHeight to the device’s screen resolution. However, to write a full-screen application that runs on multiple devices, use the Capabilities.screenResolutionX and Capabilities.screenResolutionY properties to set your Stage dimensions.

For example:

stage.stageWidth = Capabilities.screenResolutionX; 
stage.stageHeight = Capabilities.screenResolutionY;

The safe viewing area

The safe viewing area on a television is an area of the screen that is inset from the screen’s edges. This area is inset far enough that the end user can see the entire area, without the TV’s bezel obscuring any part of the area. Because the bezel, which is the physical frame around the screen, varies among manufacturers, the necessary inset varies. The safe viewing area attempts to guarantee the area of the screen that is visible. The safe viewing area is also known as the title safe area.

Overscan is the area of the screen that is not visible because it is behind the bezel.

Adobe recommends an inset of 7.5% on each edge of the screen. For example:

View full size graphic

Safe viewing area for a screen resolution of 1920 x 1080

Always consider the safe viewing area when designing a full-screen AIR for TV application:

The following table shows the dimensions of the safe viewing area for each of the typical screen resolutions, using an inset of 7.5%.

However, a best practice is to always dynamically calculate the safe viewing area. For example:

var horizontalInset, verticalInset, safeAreaWidth, safeAreaHeight:int; 
 
horizontalInset = .075 * Capabilities.screenResolutionX; 
verticalInset = .075 * Capabilities.screenResolutionY; 
safeAreaWidth = Capabilities.screenResolutionX - (2 * horizontalInset); 
safeAreaHeight = Capabilities.screenResolutionY - (2 * verticalInset);

Stage scale mode

Set Stage.scaleMode to StageScaleMode.NO_SCALE, and listen for stage resize events.

stage.scaleMode = StageScaleMode.NO_SCALE; 
stage.addEventListener(Event.RESIZE, layoutHandler);

This setting makes stage coordinates the same as pixel coordinates. Along with FULL_SCREEN_INTERACTIVE display state and the TOP_LEFT stage alignment, this setting allows you to effectively use the safe viewing area.

Specifically, in full-screen applications, this scale mode means that the stageWidth and stageHeight properties of the Stage class correspond to the screenResolutionX and screenResolutionY properties of the Capabilities class.

Furthermore, when the application’s window changes size, the stage contents maintain their defined size. The runtime performs no automatic layout or scaling. Also, the runtime dispatches the Stage class’s resize event when the window changes size. Therefore, you have full control over how to adjust the application’s contents when the application begins and when the application window resizes.

Stage alignment

Set Stage.align to StageAlign.TOP_LEFT:

stage.align = StageAlign.TOP_LEFT; 

This alignment places the 0,0 coordinate in the upper-left corner of the screen, which is convenient for content placement using ActionScript.

Along with the NO_SCALE scale mode and the FULL_SCREEN_INTERACTIVE display state, this setting allows you to effectively use the safe viewing area.

Stage display state

Set Stage.displayState in a full-screen AIR for TV application to StageDisplayState.FULL_SCREEN_INTERACTIVE:

stage.displayState = StageDisplayState.FULL_SCREEN_INTERACTIVE; 

This value sets the AIR application to expand the stage over the entire screen, with user input allowed.

Adobe recommends that you use the FULL_SCREEN_INTERACTIVE setting. Along with the NO_SCALE scale mode and the TOP_LEFT stage alignment, this setting allows you to effectively use the safe viewing area.

Therefore, for full screen applications, in a handler for the ADDED_TO_STAGE event on the main document class, do the following:

private function onStage(evt:Event):void 
{ 
    stage.scaleMode = StageScaleMode.NO_SCALE; 
    stage.align = StageAlign.TOP_LEFT; 
    stage.addEventListener(Event.RESIZE, onResize); 
    stage.displayState = StageDisplayState.FULL_SCREEN_INTERACTIVE; 
}

Then, in the handler for the RESIZE event:

private function onResize(evt:Event):void 
{ 
    if ((Capabilities.screenResolutionX == stage.stageWidth) && 
        (Capabilities.screenResolutionY == stage.stageHeight)) 
    { 
         
        // Calculate and save safe viewing area dimensions. 
    } 
}

When the stage dimensions equal Capabilities.screenResolutionX and screenResolutionY, AIR for TV causes the hardware to deliver the best possible fidelity for your video and graphics.

Designing for multiple screen sizes

You can develop the same full-screen AIR for TV application to work and look good on multiple AIR for TV devices. Do the following:

1. Set the stage properties scaleMode, align, and displayState to the recommended values: StageScaleMode.NO_SCALE, StageAlign.TOP_LEFT, and StageDisplayState.FULL_SCREEN_INTERACTIVE, respectively.

2. Set up the safe viewing area based on Capabilities.screenResolutionX and Capabilities.screenResolutionY.

3. Adjust the size and layout of your content according to width and height of the safe viewing area.

   Although your content’s objects are large, especially compared to mobile device applications, concepts such as dynamic layout, relative positioning, and adaptive content are the same. For further information about ActionScript to support these concepts, see Authoring mobile Flash content for multiple screen sizes.

Stage quality

The Stage.quality property for an AIR for TV application is always StageQuality.High. You cannot change it.

This property specifies the rendering quality for all Stage objects.

Responsiveness

Use the following tips to make an AIR for TV application as responsive as possible.

Usability

Users of AIR for TV applications are in a “living room” environment. They are sitting across the room from the TV, some 10 feet away. The room is sometimes dark. They typically use a remote control device for input. More than one person can be using the application, sometimes together, sometimes serially.

Therefore, to design your user interface for usability on a TV, consider the following:

For more information about using the remote control, see Remote control input handling.

User’s personality and expectations

Consider that users of AIR for TV applications are typically seeking TV quality entertainment in a fun and relaxed environment. They are not necessarily knowledgeable about computers or technology.

Therefore, design AIR for TV applications with the following characteristics: