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 DASH content. This allows for enhanced readability where required by the end user through a flexible set of characteristics.

HLS content on Safari browsers already have the ability for the natively managed subtitles to be customised by the Captions system settings on iOS/MacOS.

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 color / text edge effect

Each of the attributes defaults to a neutral state such that the characteristics specified in the DASH stream’s subtitle styling will be rendered.

API

An API entry point is defined to set these attributes: player.otvtoolkit().configureTextStyle().

A JSON object provides the ability to independently set or batch set values of the attributes, for example:

JS
player.otvtoolkit().configureTextStyle(
  {
      "textSizeScaleFactor":1.5,
      "textColor":"white",
      "backgroundColor":"rgba(0,0,0,80%)",
      "characterEdgeColor":"cyan",
      "characterEdgeEffect":"raised",
      "fontFamily":"monospace"
  })

Text scale factor

Default behaviour is for the stream to prescribe the font-size or the CONNECT Player SDK set this to 20px (or 4.4vmin for full screen). The textSizeScaleFactor attribute allows that value to be scaled by the provided factor.

Examples:

  • a value of 2 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 (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

Furthermore 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.

Font family

Default behaviour is for the stream to prescribe the font-family or the CONNECT Player SDK set this to 'sans-serif'. The fontFamily attribute allows any legal font-family string or comma separated priority list - see https://developer.mozilla.org/en-US/docs/Web/CSS/font-family .

Examples:

fontFamily value

Rendered outcome

'serif'

image-20250320-105558.png

'sans-serif' or ''

image-20250320-105615.png

'monospace'

image-20250320-105657.png

'cursive'

image-20250320-105637.png

'fantasy'

image-20250320-105729.png

Device font support will vary.

Text color

Default behaviour is for the stream to prescribe the text’s color or the CONNECT Player SDK set this to white. The textColor attribute allows any legal CSS color string - see https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_colors/Color_values . This supports the ability to style text with opacity.

Opacity cannot be overriden without also overriding the color.

Examples:

  • ”white” solid white

  • ”red” solid red

  • ”rgb(255,255,170)” a solid yellow

  • ”rgba(255,255,255,0.5)” semi-transparent white

  • ”” (default) empty string reverts to the default behaviour

If the stream contains different colored text for different speakers, these will not be differentiable if a value is set with the textColor attribute.

Background color

Default behaviour is for the stream to prescribe the background-color or the CONNECT Player SDK set this to black with some transparency (rgba(0,0,0,0.8)). The backgroundColor attribute allows any legal CSS color string - see https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_colors/Color_values . This supports the ability to style the background with opacity.

Opacity cannot be overriden without also overriding the color.

Examples:

  • ”black” solid black

  • ”rgba(255,255,0, 0.5)” a semi-transparent yellow

  • ”” (default) empty string reverts to the default behaviour

Character Edge Effect & Color

Default behaviour is for the stream to prescribe the text-shadow or the CONNECT Player SDK omit this attribute. The characterEdgeEffect and characterEdgeColor attributes work together to achieve a text-shadow effect from a set of standardised basic effects. The SDK translates these standard effects into shadow effects with x, y offsets, blue radius and the specified color.

The characterEdgeEffect can even support some advanced multi-shadow effects with any valid comma separated shadow parameters. These may not enhanced readability but can allow for rich effects.

See https://developer.mozilla.org/en-US/docs/Web/CSS/text-shadow .

Edge color cannot be overriden without also overriding the edge effect.

Examples:

characterEdgeEffect value

characterEdgeColor value

Rendered outcome

”raised”

”green”

image-20250320-102731.png

”depressed”

”magenta”

image-20250320-102758.png

”dropShadowed”

”cyan”

image-20250320-104005.png

”uniform”

”red”

image-20250320-104039.png

"0 0 7px #fff,0 0 10px #fff,0 0 21px #fff,0 0 42px #0fa,0 0 82px #0fa,0 0 92px #0fa,0 0 102px #0fa,0 0 151px #0fa"

(ignored)

image-20250320-104152.png

””

(ignored)

image-20250320-105117.png

The standard effects are case insensitive.

JavaScript errors detected

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

If this problem persists, please contact our support.