Control closed-caption styling

You can provide styling information for closed-caption tracks using the ClosedCaptionStyles class. This sets the style for any closed captions that are displayed by your player.

This class encapsulates closed-caption styling information such as the font type, size, color, and background opacity. An associated helper class, ClosedCaptionStylesBuilder, facilitates working with closed-caption style settings.

Set closed-caption styles

You can style the closed-caption text with TVSDK methods.

  1. Wait for the MediaPlayer to have at least the PREPARED status (see Wait for a valid state).

  2. To change the styling settings, do one of the following:

    • Use the ClosedCaptionStylesBuilder helper class (operates on ClosedCaptionStyles behind the scenes).
    • Use the ClosedCaptionStyles class directly.
NOTE

Setting the closed-caption style is an asynchronous operation so it might take up to a few seconds for the changes to appear on the screen.

Closed caption styling options

You can provide styling information for closed-caption tracks using the ClosedCaptionStyles class. This sets the style for any closed captions that are displayed by your player.

public function TextFormat(
   font:String = default,
   size:String = default,
   fontEdge:String = default,
   fontColor:String = default,
   backgroundColor:String = default,
   fillColor:String = default,
   edgeColor:String = default,
   fontOpacity:int,
   backgroundOpacity:int,
   fillOpacity:int)
TIP

In options that define default values (for example, DEFAULT), that value refers to what the setting was when the caption was originally specified.

Format Description
Font

The font type.

Can be set only to a value that is defined by the ClosedCaptionStyles.FONT array and represents, for example, monospaced with or without serifs. public static const FONT :Array = [  AVCaptionStyle.DEFAULT,  AVCaptionStyle.MONOSPACE_WITH_SERIFS,  AVCaptionStyle.MONOSPACED_WITHOUT_SERIFS,  AVCaptionStyle.PROPORTIONAL_WITH_SERIFS,  AVCaptionStyle.PROPORTIONAL_WITHOUT_SERIFS,  AVCaptionStyle.CASUAL,  AVCaptionStyle.CURSIVE,  AVCaptionStyle.SMALL_CAPITALS  ];

Tip: The actual fonts that are available on a device might vary, and substitutions are used when necessary. Monospace with serifs is typically used as a substitute, although this substitution can be system specific.

Size

The caption's size.

Can be set only to a value defined by the ClosedCaptionStyles.FONT_SIZE array:

  • MEDIUM - The standard size
  • LARGE - Approximately 30% larger than medium
  • SMALL - Approximately 30% smaller than medium
  • DEFAULT - The default size for the caption; the same as medium

Tip: You can change the font size of WebVTT captions by changing the size parameter for the DefaultMediaPlayer.ccStyles setter function.

Font edge

The effect used for the font edge, such as raised or none.

Can be set only to a value that is defined by the ClosedCaptionStyles.FONT_EDGE array. public static const FONT_EDGE :Array = [     AVCaptionStyle.DEFAULT,     AVCaptionStyle.NONE,     AVCaptionStyle.RAISED,     AVCaptionStyle.DEPRESSED,     AVCaptionStyle.UNIFORM,     AVCaptionStyle.LEFT_DROP_SHADOW,     AVCaptionStyle.RIGHT_DROP_SHADOW  ];

Font color

The font color.

Can be set only to a value defined by the ClosedCaptionStyles.COLOR array. public static const COLOR :Array = [     AVCaptionStyle.DEFAULT,     AVCaptionStyle.BLACK,     AVCaptionStyle.GRAY,     AVCaptionStyle.WHITE,     AVCaptionStyle.BRIGHT_WHITE,     AVCaptionStyle.RED,     AVCaptionStyle.DARK_RED,     AVCaptionStyle.BRIGHT_RED,     AVCaptionStyle.GREEN,     AVCaptionStyle.DARK_GREEN,     AVCaptionStyle.BRIGHT_GREEN,     AVCaptionStyle.BLUE,     AVCaptionStyle.DARK_BLUE,     AVCaptionStyle.BRIGHT_BLUE,     AVCaptionStyle.YELLOW,     AVCaptionStyle.DARK_YELLOW,     AVCaptionStyle.BRIGHT_YELLOW,     AVCaptionStyle.MAGENTA,     AVCaptionStyle.DARK_MAGENTA,     AVCaptionStyle.BRIGHT_MAGENTA,     AVCaptionStyle.CYAN,     AVCaptionStyle.DARK_CYAN,     AVCaptionStyle.BRIGHT_CYAN   ];

Edge color

The color of the edge effect.

Can be set to any of the values that are available for the font color.

Background color

The background character cell color.

Can be set only to values that are available for the font color.

Fill color

The color of the background of the window in which the text is located.

Can be set to any of the values that are available for the font color.

Important: This does not apply to WebVTT captions, because WebVTT does not use this feature.

Font opacity

The opacity of the text.

Expressed as a percentage from 0 (fully transparent) to 100 (fully opaque). DEFAULT_OPACITY for the font is 100.

Background opacity

The opacity of the background character cell.

Expressed as a percentage from 0 (fully transparent) to 100 (fully opaque). DEFAULT_OPACITY for the background is 100.

Fill opacity

The opacity of the background of the caption window.

Expressed as a percentage from 0 (fully transparent) to 100 (fully opaque). DEFAULT_OPACITY for fill is 0.

Examples: Caption formatting

You can specify closed-caption formatting.

Example 1: Specify format values explicitly

private function onStatusChanged(event:MediaPlayerStatusChangeEvent):void {
    var formatBuilder:TextFormatBuilder = new TextFormatBuilder();
    formatBuilder.font = Font.DEFAULT,
    formatBuilder.fontSize = FontSize.DEFAULT,
    formatBuilder.fontEdge = FontEdge.DEFAULT,
    formatBuilder.fontColor = Color.DEFAULT,
    formatBuilder.backgroundColor = Color.DEFAULT,
    formatBuilder.fillColor = Color.DEFAULT,
    formatBuilder.edgeColor = Color.DEFAULT,
    formatBuilder.fontOpacity = .DEFAULT_OPACITY,
    formatBuilder.backgroundOpacity = Font.DEFAULT_OPACITY,
    formatBuilder.fillOpacity = TextFormat.DEFAULT_OPACITY
    mediaPlayer.set CCStyle(formatBuilder.toTextFormat());
}

Example 2: Specify format values in parameters

/**
* Constructor using parameters to initialize a TextFormat.
*
* @param font
* The desired font.
* @param fontSize
* The desired text size.
* @param fontEdge
* The desired font edge.
* @param fontColor
* The desired font color.
* @param backgroundColor
* The desired background color.
* @param fillColor
* The desired fill color.
* @param edgeColor
* The desired color to draw the text edges.
* @param fontOpacity
* The desired font opacity.
* @param backgroundOpacity
* The desired background opacity.
* @param fillOpacity
* The desired fill opacity.
*/
public function TextFormatBuilder(font:Font, fontSize:FontSize, fontEdge:FontEdge,
                                  fontColor:Color, backgroundColor:Color,
                                  fillColor:Color, edgeColor:Color, fontOpacity:int,
                                  backgroundOpacity:int, fillOpacity:int);
/**
* Creates a TextFormat with the parameters supplied to this builder.
*/
public function toTextFormat():TextFormat;
...

On this page