Control closed-caption styling

You can provide styling information for closed-caption tracks using the TextFormat 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, TextFormatBuilder, 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 media player to be in at least the PREPARED state.

2. Create a TextFormatBuilder instance.

   You can provide all the closed-caption styling parameters now or set them later.

   TVSDK encapsulates closed-caption styling information in the TextFormat interface. The TextFormatBuilder class creates objects that implement this interface.

   public TextFormatBuilder(
      Font font,
      Size size,
      FontEdge fontEdge,
      Color fontColor,
      Color backgroundColor,
      Color fillColor,
      Color edgeColor,
      int fontOpacity,
      int backgroundOpacity,
      int fillOpacity)
   

3. To obtain a reference to an object that implements the TextFormat interface, call the TextFormatBuilder.toTextFormat public method.

   This returns a TextFormat object that can be applied to the media player.

   public TextFormat toTextFormat()
   

4. Optionally get the current closed-caption style settings by doing one of the following:

   • Get all the style settings with MediaPlayer.getCCStyle.

     The return value is an instance of the TextFormat interface.

     /**
     * @return the current closed captioning style.
     * If no style was previously set, it returns a TextFormat object
     * with default values for each attribute.
     * @throws IllegalStateException if media player was already released.
     */
     public TextFormat getCCStyle() throws IllegalStateException;
     

   • Get the settings one at a time through the TextFormat interface getter methods.

     public Color getFontColor();
     public Color getBackgroundColor();
     public Color getFillColor(); // retrieve the font fill color
     public Color getEdgeColor(); // retrieve the font edge color
     public Size getSize(); // retrieve the font size
     public FontEdge getFontEdge(); // retrieve the font edge type
     public Font getFont(); // retrieve the font type
     public int getFontOpacity();
     public int getBackgroundOpacity();
     

5. To change the style settings, do one of the following:

   NOTE

   You cannot change the size for WebVTT captions.

   • Use the setter method MediaPlayer.setCCStyle, passing an instance of the TextFormat interface:

     /**
     * Sets the closed captioning style. Used to control the closed captioning font,
     * size, color, edge and opacity.
     *
     * This method is safe to use even if the current media stream doesn't have closed
     * captions.
     *
     * @param textFormat
     * @throws IllegalStateException
     */
     public void setCCStyle(TextFormat textFormat) throws IllegalStateException;
     

   • Use the TextFormatBuilder class, which defines individual setter methods.

     The TextFormat interface defines an immutable object so there are only getter methods and no setters. You can set the closed-caption styling parameters only with the TextFormatBuilder class:

     // set font type
     public void setFont(Font font)
     public void setBackgroundColor(Color backgroundColor)
     public void setFillColor(Color fillColor)
     // set the font-edge color
     public void setEdgeColor(Color edgeColor)
     // set the font size
     public void setSize(Size size)
     // set the font edge type
     public void setFontEdge(FontEdge fontEdge)
     public void setFontOpacity(int fontOpacity)
     public void setBackgroundOpacity(int backgroundOpacity)
     // set the font-fill opacity level
     public void setFillOpacity(int fillOpacity)
     public void setFontColor(Color fontColor)
     

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 specify several caption styling options, and these options override the style options in the original captions

public TextFormatBuilder(
 Font font,
 Size size,
 FontEdge fontEdge,
 Color fontColor,
 Color backgroundColor,
 Color fillColor,
 Color edgeColor,
 int fontOpacity,
 int backgroundOpacity,
 int fillOpacity,
 String bottomInset)

Caption formatting examples

You can specify closed-caption formatting.

Example 1: Specify format values explicitly

private final MediaPlayer.PlaybackEventListener
  _playbackEventListener = new MediaPlayer.PlaybackEventListener() {
    @Override
    public void onPrepared() {
        // Set CC style.
        TextFormat tf = new TextFormatBuilder(TextFormat.Font.DEFAULT,
        TextFormat.Size.DEFAULT,
        TextFormat.FontEdge.DEFAULT,
        TextFormat.Color.DEFAULT,
        TextFormat.Color.DEFAULT,
        TextFormat.Color.DEFAULT,
        TextFormat.Color.DEFAULT,
        TextFormat.DEFAULT_OPACITY,
        TextFormat.DEFAULT_OPACITY,
        TextFormat.DEFAULT_OPACITY).toTextFormat();
        mediaPlayer.setCCStyle(tf);
        ...
    }
}

Example 2: Specify format values in parameters

/**
* Constructor using parameters to initialize a TextFormat.
*
* @param font
* The desired font.
* @param size
* 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 TextFormatBuilder(
    Font font, Size size, FontEdge fontEdge,
    Color fontColor, Color backgroundColor,
    Color fillColor, Color edgeColor,
    int fontOpacity, int backgroundOpacity,
    int fillOpacity);

/**
* Creates a TextFormat with the parameters supplied to this builder.
*/
public TextFormat toTextFormat();

/**
* Sets the text font.
* @param font The desired font
* @return This builder object to allow chaining calls
*/
public TextFormatBuilder setFont(Font font);
...