JWCaptionStyle

@objcMembers
public final class JWCaptionStyle : NSObject
extension JWCaptionStyle: JWJSONCodable
extension JWCaptionStyle: DeepCopying

Configuration object used to customize the captions.

Note

Styles specified using this structure will only be applied if the user’s accessibility settings allow it, and only for SRT and WebVTT captions.

Warning

EIA-608 captions always default to the user’s accessibility settings.

Accessibility-related properties

  • Overrides the default font style and font size. Supports Dynamic Type.

    Note

    Styles specified using this property will only be applied if the user’s accessibility settings allow it, and only for SRT and WebVTT captions.

    Note

    While a UIFont has many properties, this generally corresponds to the “fontFamily” in JSON and the web API.

    Warning

    EIA-608 captions always default to the user’s accessibility settings.

    Declaration

    Swift

    public internal(set) var font: UIFont? { get }

  • Overrides the default font size of the captions.

    Note

    Styles specified using this property will only be applied if the user’s accessibility settings allow it, and only for SRT and WebVTT captions.

    Note

    Corresponds to the “fontSize” in JSON and the web API as well.

    Warning

    EIA-608 captions always default to the user’s accessibility settings.

    Declaration

    Swift

    public internal(set) var fontSize: CGFloat? { get }

  • Overrides the default font color of the captions.

    This controls the color only, not including its opacity.

    Seealso

    JWCaptionStyle.textOpacity

    Note

    Styles specified using this property will only be applied if the user’s accessibility settings allow it, and only for SRT and WebVTT captions.

    Note

    Corresponds to the “color” in JSON and the web API.

    Warning

    EIA-608 captions always default to the user’s accessibility settings.

    Declaration

    Swift

    public internal(set) var fontColor: UIColor? { get }

  • Changes the background color and the opacity of the overall window the captions reside in.

    Note

    Styles specified using this property will only be applied if the user’s accessibility settings allow it, and only for SRT and WebVTT captions.

    Note

    Corresponds to “windowColor” in JSON and the web API.

    Warning

    EIA-608 captions always default to the user’s accessibility settings.

    Important

    Keep in mind that while a UIColor is composed of both color space and opacity information, iOS’s default user accessibility settings only allow an app to set captions’ background color, but not opacity. If a UIColor class property is semantically dependant on opacity, you may have unexpected results. For example, UIColor.clear is a grayscale color object set to 0.0 (black) with an opacity of 0.0 (not visible). A device with the default user settings would accept the new color, but reject the opacity override, resulting in a black background with 50% opacity (the default) — not ‘clear’ at all.

    Declaration

    Swift

    public internal(set) var backgroundColor: UIColor? { get }

  • Overrides the default opacity of the captions’ overlay window.

    Note

    Styles specified using this property will only be applied if the user’s accessibility settings allow it, and only for SRT and WebVTT captions.

    Note

    Corresponds to “windowOpacity” in JSON and the web API.

    Warning

    EIA-608 captions always default to the user’s accessibility settings.

    Declaration

    Swift

    @ZeroToOneClamped
public internal(set) var backgroundOpacity: CGFloat? { get set }

  • Overrides the default opacity of the captions text.

    Note

    Styles specified using this property will only be applied if the user’s accessibility settings allow it, and only for SRT and WebVTT captions.

    Note

    Corresponds to “fontOpacity” in JSON and the web API.

    Warning

    EIA-608 captions always default to the user’s accessibility settings.

    Declaration

    Swift

    @ZeroToOneClamped
public internal(set) var textOpacity: CGFloat? { get set }

  • The edge style is an option to put emphasis around text. The available options are: none, dropshadow, raised, depressed, and uniform.

    Note

    Styles specified using this property will only be applied if the user’s accessibility settings allow it, and only for SRT and WebVTT captions.

    Note

    Corresponds to “edgeStyle” in JSON and the web API.

    Warning

    EIA-608 captions always default to the user’s accessibility settings.

    Declaration

    Swift

    public internal(set) var edgeStyle: JWCaptionEdgeStyle { get }

  • Changes the highlight color including highlight opacity of the text.

    Note

    Styles specified using this property will only be applied if the user’s accessibility settings allow it, and only for SRT and WebVTT captions.

    Note

    Corresponds to the “backgroundColor” (RGB component) and “backgroundOpacity” (alpha component) in JSON and the web API.

    Warning

    EIA-608 captions always default to the user’s accessibility settings.

    Declaration

    Swift

    public internal(set) var highlightColor: UIColor? { get }

Other properties

  • The default position of captions displayed in the player.

    This position is used if no position is specified by the caption itself, and this is only used with side-loaded captions. Because SRT captions contain no positional data, SRT captions will always be displayed using what is described by this property. For WebVTT captions, if no positional data is specified within the caption, the default position of the caption will be equal to what is described by this property.

    Declaration

    Swift

    public internal(set) var position: JWCaptionPosition? { get }

  • This property controls whether side-loaded captions will be enlarged for larger player sizes.

    If true, the side-loaded captions will be enlarged for large player sizes such as when the player is full screen. If false, the captions will retain their default assigned size, whether that is from the defined style by the developer or from the user’s accessibility settings.

    This property is true by default.

    Declaration

    Swift

    public internal(set) var allowScaling: Bool { get }

  • Indicates which strategy to use when applying the caption styling object to side-loaded captions.

    By default, as per the Human Interface Guidelines, the player assumes that captions are Accessibility aids to accomodate those with disabilities, and will only change the device’s caption styles if given user permission by toggling “Video Override” in the device settings.

    The default value is nil, which is treated as .videoOverrideOnly. You can set the player to ignore the device’s settings by changing this setting to .always.

    Declaration

    Swift

    public internal(set) var overrideStrategy: JWCaptionStyleOverrideStrategy? { get }

  • This initializer uses a JSON dictionary to initialize the style.

    This follows the JWP standard here: https://docs.jwplayer.com/players/reference/captions-config-ref With the addition of allowScaling, which is treated as a Boolean.

    Warning

    The Apple API and UI have different names for the various properties. This can get very confusing! Our SDK uses the UI terms for properties (from the SDH menu in iOS Settings App), so background is set by window, text by foreground, and text highlight by background.

    Seealso

    See the implementation, and SDK-11316 for details.

    Declaration

    Swift

    public init(from json: JSONObject)

  • Declaration

    Swift

    public func toJSONObject() -> JSONObject

  • Declaration

    Swift

    public func deepCopy() -> `Self`?