Package com.jwplayer.pub.api.configuration

Class CaptionPosition

java.lang.Object
com.jwplayer.pub.api.configuration.CaptionPosition
public class CaptionPosition extends Object
Describes the default position, width and text alignment of a caption within the rendered video.

This is the Android analogue of the iOS SDK's JWCaptionPosition, and is attached to CaptionsConfig.getPosition().

Coordinates are relative to the rendered video, not to the player. In a letterboxed or pillarboxed layout the black bars are excluded, so linePercentage(100) is the bottom edge of the video image rather than the bottom edge of the player view. This matches iOS, which positions captions within the video rendering surface's videoRect. When the video fills the player there is no difference between the two.

This is a default, not an override. It applies only to caption cues that carry no positioning of their own, so the precedence is:

  1. positioning parsed from the caption track itself (WebVTT cue settings, TTML region attributes, CEA-608/708 row and column codes);
  2. this object;
  3. the player default — horizontally centered, near the bottom of the rendered video.

SRT carries no positional data at all, so SRT cues always take this position. Most WebVTT cues also carry no settings and so take it too, while CEA-608/708 cues are positioned by the broadcast data and are left alone.

A position set here is honored as given. Unpositioned captions are nudged up to clear the control bar while it is visible; a caption placed through this object is not, matching iOS. A caption placed low in the video can therefore sit behind the control bar while it is on screen.

  • Field Details

    • ALIGNMENT_LEFT

      public static final String ALIGNMENT_LEFT
      The caption text is flush with the leading edge of the caption box.
      See Also:

    • ALIGNMENT_CENTER

      public static final String ALIGNMENT_CENTER
      The caption text is centered within the caption box. This is the default.
      See Also:

    • ALIGNMENT_RIGHT

      public static final String ALIGNMENT_RIGHT
      The caption text is flush with the trailing edge of the caption box.
      See Also:

    • mWidth

      public final Integer mWidth

    • mAlignment

      public final String mAlignment

    • mHorizontalPosition

      public final Integer mHorizontalPosition

    • mLinePercentage

      public final Integer mLinePercentage

    • mLineIndex

      public final Integer mLineIndex

  • Method Details

    • getWidth

      @Nullable public Integer getWidth()
      Returns:
      The width of the caption box as a percentage of the rendered video width, in the range [0, 100], or null to size the box to fit the caption text.

    • getAlignment

      @Nullable public String getAlignment()
      Returns:
      The alignment of the caption text within the caption box, one of the ALIGNMENT_ constants, or null for the default (ALIGNMENT_CENTER).

      ALIGNMENT_LEFT and ALIGNMENT_RIGHT are resolved against the layout direction, so they read as leading and trailing in a right-to-left locale. This matches iOS.

    • getHorizontalPosition

      @Nullable public Integer getHorizontalPosition()
      Returns:
      The leading edge of the caption box as a percentage of the rendered video width, in the range [0, 100], or null to center the box.

    • getLinePercentage

      @Nullable public Integer getLinePercentage()
      Returns:
      The top edge of the caption box as a percentage of the rendered video height measured from the top, in the range [0, 100], or null to position by getLineIndex() instead.

    • getLineIndex

      @Nullable public Integer getLineIndex()
      Returns:
      The vertical position of the caption box as a line count, or null to position by getLinePercentage() instead. A non-negative value counts lines down from the top of the rendered video; a negative value counts lines up from the bottom, so -1 is the bottom line.

      At most one of this and getLinePercentage() is ever set.