Package com.jwplayer.pub.api.configuration

Class CaptionsConfig

java.lang.Object
com.jwplayer.pub.api.configuration.CaptionsConfig
public class CaptionsConfig extends Object
Configuration object used to customize the appearance of captions rendered by the player.

This is the Android analogue of the iOS SDK's JWCaptionStyle. It lets an integrator override caption font, size, colors, edge style, background window and position, and control how caption text scales for larger player sizes.

Styling applies to WebVTT, SRT, and TTML captions, for both in-manifest and side-loaded tracks, except where the caption track carries its own styling: a WebVTT STYLE block, ::cue rules, or TTML styling attributes take precedence under the default OVERRIDE_STRATEGY_VIDEO_OVERRIDE_ONLY. Use OVERRIDE_STRATEGY_ALWAYS to have these values win over embedded styling as well. CEA-608/708 captions carry their own styling and so continue to follow the device's accessibility settings, a constraint of the underlying renderer (matching iOS behavior).

Any property left unset falls back to the device's caption settings (CaptioningManager) when available, or the player default otherwise. Whether developer-provided values override the device settings is governed by getOverrideStrategy().

Two distinct backgrounds. Captions have two separate background layers, easily confused:

  • backgroundColor — the box rendered directly behind the text glyphs (the "highlight").
  • windowColor — the box rendered behind the whole caption region.

When backgroundColor is left unset, the highlight uses the platform default, which is an opaque black box behind the text (this mirrors Android's default caption rendering). To remove it, set a backgroundColor whose alpha is 0. Setting only windowColor does not affect this highlight.

  • Field Details

    • EDGE_STYLE_NONE

      public static final String EDGE_STYLE_NONE
      No edge decoration is drawn around the caption text.
      See Also:

    • EDGE_STYLE_DROP_SHADOW

      public static final String EDGE_STYLE_DROP_SHADOW
      A drop shadow is drawn behind the caption text.
      See Also:

    • EDGE_STYLE_RAISED

      public static final String EDGE_STYLE_RAISED
      The caption text is rendered as raised.
      See Also:

    • EDGE_STYLE_DEPRESSED

      public static final String EDGE_STYLE_DEPRESSED
      The caption text is rendered as depressed.
      See Also:

    • EDGE_STYLE_UNIFORM

      public static final String EDGE_STYLE_UNIFORM
      A uniform outline is drawn around the caption text.
      See Also:

    • OVERRIDE_STRATEGY_VIDEO_OVERRIDE_ONLY

      public static final String OVERRIDE_STRATEGY_VIDEO_OVERRIDE_ONLY
      For each property, the player honors the device's accessibility caption settings and only applies values from this object where the user has not explicitly chosen one. Styling embedded in the caption track itself is also honored ahead of this object. This is the default.

      Note this is decided per property and independently of whether the user has captioning switched on: on a device with no caption preferences set — the overwhelmingly common case — every value from this object applies.

      See Also:

    • OVERRIDE_STRATEGY_ALWAYS

      public static final String OVERRIDE_STRATEGY_ALWAYS
      The player ignores both the device's accessibility caption settings and any styling embedded in the caption track, and always prefers values from this object. Use with care: it overrides choices a low-vision user has made deliberately.
      See Also:

    • mFontSize

      public final Integer mFontSize

    • mFontFamily

      public final String mFontFamily

    • mColor

      public final Integer mColor

    • mBackgroundColor

      public final Integer mBackgroundColor

    • mWindowColor

      public final Integer mWindowColor

    • mEdgeStyle

      public final String mEdgeStyle

    • mPosition

      public final CaptionPosition mPosition

    • mOverrideStrategy

      public final String mOverrideStrategy

    • mAllowScaling

      public final boolean mAllowScaling

  • Method Details

    • getFontSize

      @Nullable public Integer getFontSize()
      Returns:
      The caption font size in Android scaled pixels (sp), or null to let the player determine a size automatically.

      The shared captions-config-ref JSON schema carries this value under fontSize for every platform, but the unit is platform-native: sp here, px on web and points on iOS. A config shared verbatim across platforms will therefore render at a similar but not pixel-identical size.

    • getFontFamily

      @Nullable public String getFontFamily()
      Returns:
      The caption font family (e.g. "sans-serif"), or null for the default.

    • getColor

      @Nullable @ColorInt public Integer getColor()
      Returns:
      The caption text color, including its opacity, or null for the default.

    • getBackgroundColor

      @Nullable @ColorInt public Integer getBackgroundColor()
      Returns:
      The color rendered directly behind the caption glyphs (the "highlight"), including its opacity, or null to use the default (an opaque black box). Distinct from getWindowColor().

    • getWindowColor

      @Nullable @ColorInt public Integer getWindowColor()
      Returns:
      The color of the window/box behind the whole caption region, including its opacity, or null for the default (transparent).

    • getEdgeStyle

      @Nullable public String getEdgeStyle()
      Returns:
      The edge style applied around caption text, one of the EDGE_STYLE_ constants, or null for the default.

    • getPosition

      @Nullable public CaptionPosition getPosition()
      Returns:
      The default position, width and text alignment of captions within the rendered video, or null to leave the player's positioning in place.

      This is a default for cues that carry no positioning of their own, and its coordinates are relative to the rendered video rather than to the player — see CaptionPosition.

    • getOverrideStrategy

      @NonNull public String getOverrideStrategy()
      Returns:
      The strategy governing whether developer-provided styles override the device's accessibility caption settings, one of the OVERRIDE_STRATEGY_ constants. Defaults to OVERRIDE_STRATEGY_VIDEO_OVERRIDE_ONLY when unset.

    • getAllowScaling

      public boolean getAllowScaling()
      Returns:
      Whether the device's accessibility caption/font scale is applied on top of the caption size. When false, the size comes from getFontSize() (or the player's automatic sizing) alone, ignoring that scale. Defaults to true.

      The automatic size stays proportional to the rendered video either way; this flag governs only the accessibility scale, not the player-size proportionality.