Skip to main content
Skip table of contents

Customization of Subtitle styling

In response to the European Accessibility Act 2025 (EAA), the CONNECT Player SDK provides the ability for customisation of the appearance of text subtitles for HLS content. This allows for enhanced readability where required by the end user through a flexible set of characteristics.

Text of the following subtitle types can be customized:

  • SRT

  • SMPTE

  • WebVTT

Limitation: Closed Captions customization is not supported.

Customization works in conjunction with the iOS/tvOS system settings under the Accessibility settings' “Subtitles & Captioning” controls. There are a set of predefined standard styling combinations, plus the ability for the user to define their own combinations.

Screenshot 2025-05-12 at 09.36.01.png

“Subtitles & Captioning” controls

This feature’s configuration options can further refine individual settings. Care should be taken that system settings permit the Video Override for each attribute, for example:

Screenshot 2025-05-12 at 09.36.39.png

Video Override allowed

Customisation of the following styling properties is supported:

  1. font size scaling

  2. font family

  3. text color / text opacity

  4. background color / background opacity

  5. text edge effect

Each of the attributes are defined Optional so can be isolated individually or combined as required.

API

An API entry point is defined to set these attributes via method call on the player passing an instance of the class OTVTextStyle in which each of the the attributes can be set, for example:

SWIFT
let txtStyle = OTVTextStyle()
txtStyle.textSizeScaleFactor = 2.0
txtStyle.fontFamily = "Times New Roman"
txtStyle.textColor = UIColor.yellow
txtStyle.backgroundColor = UIColor.blue.withAlphaComponent(0.75)
txtStyle.characterEdgeEffect = OTVTextStyleCharacterEdge.uniform

player.configureTextStyle(styling: txtStyle)

Text scale factor

Default behaviour is for 24 pt text to be shown. The textSizeScaleFactor attribute allows that value to be scaled by the provided factor.

Examples:

  • a value of 2.0 will double the rendered size

  • a value of 0.5 will half the size

  • a value of 1.5 will increase by 50%

  • a value of 1.0 (default) will have no effect

It is recommended to integrators that a small set of values are defined and mapped to meaningful labels, for example:

  • small: 0.75

  • medium: 1.0

  • large: 1.5

  • extra large: 2.0

Futhermore it is not recommended going beyond 2.0 as the layout of the rendered subtitles may be greatly affected and readability will likely be affected.

Bear in mind that 24 pt reflects the default and mid point of the iOS System Accessibility Settings' “Display & Text Size” control.

Screenshot 2025-05-12 at 09.25.38.png

iOS System Accessibility Settings' “Display & Text Size”

Both the system scaling and textSizeScaleFactor will affect the displayed size. When “Larger Accessibility Sizes” is toggled on the range of options increases further.

Font family

Default behaviour is for the system settings selected font to be used. The fontFamily attribute allows any string font name to be passed.

It is the application integrator’s responsibility to ensure the font is available.

Text color / opacity

Default behaviour is for the system settings selected text color and opacity to be used.

Opacity takes a value from 0.0 (transparent) to 1.0 (opaque).

Opacity cannot be overridden without also overriding the color.

Examples:

  • txtStyle.textColor = UIColor.white

  • txtStyle.textColor = UIColor.yellow

  • txtStyle.textColor = UIColor.white.withAlphaComponent(0.8)

Background color / opacity

Default behaviour is for the system settings selected background color and opacity to be used.

Opacity takes a value from 0.0 (transparent) to 1.0 (opaque).

Opacity cannot be overridden without also overriding the color.

Examples:

  • txtStyle.backgroundColor = UIColor.black

  • txtStyle.backgroundColor = UIColor.blue

  • txtStyle.backgroundColor = UIColor.black.withAlphaComponent(0.8)

Character Edge Effect

Default behaviour is for the system settings selected edge style to be used. The set of valid values are defined in the enumeration:

SWIFT
public enum OTVTextStyleCharacterEdge: String, Codable {
    case none
    case dropShadowed
    case uniform
    case raised
    case depressed
}

Examples:

  • txtStyle.characterEdgeEffect = .dropShadowed

  • txtStyle.characterEdgeEffect = .depressed

Unlike other platforms there is no native support for character edge color customisation.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.