Class: shaka.text.UITextDisplayer

Constructor

new UITextDisplayer(player)

Parameters:
Name Type Description
player shaka.Player
Implements:
Source:

Members

CustomRegion_ :shaka.util.Lazy<!shaka.text.CueRegion>

Type:
Source:

FONT_FAMILIES_ :Map<shaka.config.FontFamily, string>

The CSS font families of each font family of the configuration. Each one lists several fonts, so a similar one is found on every platform.
Type:
Source:

MIN_REFRESH_PERIOD_ :number

Shortest the update timer will ever wait, in seconds (~one frame at 60fps). Prevents a hot loop when cue boundaries are very close together, e.g. character-by-character CEA-608 reveals.
Type:
  • number
Source:

REGION_LINE_HEIGHT_ :number

The line height of the cues in a region sized in lines, relative to their font size. It matches the default line height of the text container.
Type:
  • number
Source:

SAFETY_REFRESH_PERIOD_ :number

Longest the update timer will ever wait, in seconds. Caption updates normally land exactly on the next cue boundary; this only bounds the wait so a missed event or a playback stall can never leave the captions stale indefinitely.
Type:
  • number
Source:

SCROLL_DURATION_MS_ :number

How long the lines of a region with scroll:up take to scroll, as in the WebVTT spec.
Type:
  • number
Source:

VISIBILITY_DEBOUNCE_ :number

Debounce applied before re-evaluating container visibility, in seconds.
Type:
  • number
Source:

applyVisibilityTimer_ :shaka.util.Timer

Type:
Source:

aspectRatio_ :number

Type:
  • number
Source:

captionsTimer_ :shaka.util.Timer

Drives caption updates. Rather than polling at a fixed rate, this fires once at the next moment a cue needs to change (see configureCaptionsTimer_), then reschedules itself.
Type:
Source:

config_ :shaka.extern.TextDisplayerConfiguration

Type:
Source:

cues_ :Array<!shaka.text.Cue>

Type:
Source:

currentCuesMap_ :Map<!shaka.text.Cue, !shaka.text.UITextDisplayer.CueRegistry_>

Maps cues to cue elements. Specifically points out the wrapper element of the cue (e.g. the HTML element to put nested cues inside).
Type:
Source:

eventManager_ :shaka.util.EventManager

Type:
Source:

isContainerActuallyVisible_ :boolean

Type:
  • boolean
Source:

isTextVisible_ :boolean

Type:
  • boolean
Source:

pendingResize_ :boolean

Type:
  • boolean
Source:

player_ :shaka.Player

Type:
Source:

previewConfig_ :shaka.extern.TextDisplayerConfiguration

Type:
Source:

previewCue_ :shaka.text.Cue

Type:
Source:

regionBackgrounds_ :Map<!HTMLElement, string>

The background colors of the region elements which have one.
Type:
  • Map<!HTMLElement, string>
Source:

regionElements_ :Map<string, !HTMLElement>

Type:
  • Map<string, !HTMLElement>
Source:

renderSuspended_ :boolean

Type:
  • boolean
Source:

resizeObserver_ :ResizeObserver

Type:
  • ResizeObserver
Source:

showingPreviewCue_ :boolean

Type:
  • boolean
Source:

textContainer_ :HTMLElement

Type:
  • HTMLElement
Source:

video_ :HTMLMediaElement

Type:
Source:

video_ :HTMLVideoElement

Type:
  • HTMLVideoElement
Source:

video_ :HTMLVideoElement

Type:
  • HTMLVideoElement
Source:

video_ :HTMLVideoElement

Type:
  • HTMLVideoElement
Source:

videoContainer_ :HTMLElement

Type:
  • HTMLElement
Source:

visibilityObserver_ :IntersectionObserver

Type:
  • IntersectionObserver
Source:

Methods

convertLengthValue_(lengthValue, cuenon-null, videoContainer, scaleFactoropt) → {string}

Converts length value to an absolute value in pixels. If lengthValue is already an absolute value it will not be modified. Relative lengthValue will be converted to an absolute value in pixels based on Computed Cell Size
Parameters:
Name Type Attributes Default Description
lengthValue string
cue shaka.text.Cue
videoContainer HTMLElement
scaleFactor number <optional>
 1
Source:
Returns:
Type
string

displayAlignToJustifyContent_(displayAlign) → {string}

Maps a cue's displayAlign to the equivalent CSS justify-content value.
Parameters:
Name Type Description
displayAlign shaka.text.Cue.displayAlign
Source:
Returns:
Type
string

getAbsoluteLengthInPixels_(value, cuenon-null, videoContainer) → {string}

Returns computed absolute length value in pixels based on cell and a video container size
Parameters:
Name Type Description
value number
cue shaka.text.Cue
videoContainer HTMLElement
Source:
Returns:
Type
string

getBackgroundColor_(inheritedColor, hasText, confignullable) → {string}

Gets the background color of a cue element, applying the background color and the background opacity of the configuration.
Parameters:
Name Type Attributes Description
inheritedColor string The background color of the cue, or of its nearest parent that has one.
hasText boolean
config shaka.extern.TextDisplayerConfiguration <nullable>
Source:
Returns:
Type
string

getLengthValueInfo_(lengthValuenullable) → {?{value: number, unit: string}}

Returns info about provided lengthValue
Parameters:
Name Type Attributes Description
lengthValue string <nullable>
Source:
Returns:
Type
?{value: number, unit: string}
Example
100px => { value: 100, unit: 'px' }

inheritProperty_(parentsnon-null, cb) → {T}

Inherits a property from the parent Cue elements. If the value is falsy, it is assumed to be inherited from the parent. This returns null if the value isn't found.
Parameters:
Name Type Description
parents Array<!shaka.text.Cue>
cb function(!shaka.text.Cue): ?T
Source:
Returns:
Type
T

isBackgroundCustomized_(confignullable) → {boolean}

Parameters:
Name Type Attributes Description
config shaka.extern.TextDisplayerConfiguration <nullable>
Source:
Returns:
Type
boolean

scrollUpRegion_(regionElementnon-null, newCueElementsnon-null)

Scrolls up the lines of a region with scroll:up when new cues are added to it, the way the WebVTT spec transitions the region from the old to the new position of its lines. See https://www.w3.org/TR/webvtt1/#processing-model
Parameters:
Name Type Description
regionElement HTMLElement
newCueElements Array<!HTMLElement>
Source:

append(cuesnon-null)

Append given text cues to the list of cues to be displayed.
Parameters:
Name Type Description
cues Array<!shaka.text.Cue> Text cues to be appended.
Implements:
Source:

applyVisibility_()

Source:

clearTextStylePreview()

Clears temporary text style preview settings.
Source:

computeCuePositionAlignment_(cuenon-null) → {shaka.text.Cue.positionAlign}

Compute cue position alignment See https://www.w3.org/TR/webvtt1/#webvtt-cue-position-alignment
Parameters:
Name Type Description
cue shaka.text.Cue
Source:
Returns:
Type
shaka.text.Cue.positionAlign

configure(config)

Sets the TextDisplayer configuration.
Parameters:
Name Type Description
config shaka.extern.TextDisplayerConfiguration
Implements:
Source:

configureCaptionsTimer_()

Schedules the next caption update to land exactly when the displayed text next needs to change (a cue or nested-cue start/end boundary), instead of polling at a fixed rate. This makes character-by-character reveals (CEA-608 paint-on / roll-up) land on time and avoids waking up while nothing is changing. A safety period bounds the wait so a missed event or a stall can never freeze the captions.
Source:

convertTtmlLengths_(value, cuenon-null) → {string}

Converts the lengths in cells or relative to the size of the video, like "1c" or "10rh", to pixels.
Parameters:
Name Type Description
value string
cue shaka.text.Cue
Source:
Returns:
Type
string

createCue_(cuenon-null, parentsnon-null)

Creates the object for a cue.
Parameters:
Name Type Description
cue shaka.text.Cue
parents Array<!shaka.text.Cue>
Source:

findCueRegistry_(cuenon-null, confignullable) → {{key: !shaka.text.Cue, registry: ?shaka.text.UITextDisplayer.CueRegistry_}}

Looks up the cue registry for a cue. When a custom positionArea is configured the cue list is cloned, so the cue may not be a key by reference; in that case we fall back to an equality-based search.
Parameters:
Name Type Attributes Description
cue shaka.text.Cue
config shaka.extern.TextDisplayerConfiguration <nullable>
Source:
Returns:
Type
{key: !shaka.text.Cue, registry: ?shaka.text.UITextDisplayer.CueRegistry_}

generateRegionId_(region)

Compute a unique internal id: Regions can reuse the id but have different dimensions, we need to consider those differences
Parameters:
Name Type Description
region shaka.text.CueRegion
Source:

getActiveConfig_() → {shaka.extern.TextDisplayerConfiguration}

Source:
Returns:
Type
shaka.extern.TextDisplayerConfiguration

getFontColor_(cuenon-null, isNested, confignullable) → {string}

Gets the font color of a cue element, applying the font color and the font opacity of the configuration.
Parameters:
Name Type Attributes Description
cue shaka.text.Cue
isNested boolean
config shaka.extern.TextDisplayerConfiguration <nullable>
Source:
Returns:
Type
string

getNextBoundary_(cuesnon-null, time) → {number}

Finds the earliest cue or nested-cue time boundary strictly after the given time. These are the only moments at which the rendered output can change, so the update timer wakes there.
Parameters:
Name Type Description
cues Array<!shaka.text.Cue>
time number
Source:
Returns:
The next boundary time, or null if there is none ahead.
Type
number

getRegionElement_(cuenon-null) → {HTMLElement}

Get or create a region element corresponding to the cue region. These are cached by ID.
Parameters:
Name Type Description
cue shaka.text.Cue
Source:
Returns:
Type
HTMLElement

getTextShadow_(cuenon-null, parentsnon-null) → {string}

Gets the text shadow of a cue, which also draws the text stroke around the text, since a CSS stroke would be drawn over the text. The text shadow of an element replaces the one of its parent, so it includes the text stroke and the text shadow inherited from the parents.
Parameters:
Name Type Description
cue shaka.text.Cue
parents Array<!shaka.text.Cue> The parents of the cue, and the cue itself.
Source:
Returns:
Type
string

hasCueAtTime_(cuesnon-null, currentTime) → {boolean}

Parameters:
Name Type Description
cues Array<!shaka.text.Cue>
currentTime number
Source:
Returns:
Type
boolean

hasCueContent_(cuenon-null) → {boolean}

Parameters:
Name Type Description
cue shaka.text.Cue
Source:
Returns:
Type
boolean

isElementUnderTextContainer_()

Source:

isTextVisible() → {boolean}

Returns true if text is currently visible.
Implements:
Source:
Returns:
Type
boolean

paintRegionBackgrounds_()

Paints the background of the regions while they show content. The region of a cue which only contains other cues is displayed with it, even when none of those cues is.
Source:

processCueStyle_()

Source:

remove(startTime, endTime) → {boolean}

Remove all cues that are fully contained by the given time range (relative to the presentation). endTime will be greater to equal to startTime. remove should only return false if the displayer has been destroyed. If the displayer has not been destroyed remove should return true.
Parameters:
Name Type Description
startTime number
endTime number
Implements:
Source:
Returns:
Type
boolean

setCaptionStyles_(cueElementnon-null, cuenon-null, parentsnon-null, hasWrapper)

Parameters:
Name Type Description
cueElement HTMLElement
cue shaka.text.Cue
parents Array<!shaka.text.Cue>
hasWrapper boolean
Source:

setCharacterEdgeStyle_(stylenon-null, confignullable)

Overrides the shadow and the outline of the subtitle with the character edge style of the configuration.
Parameters:
Name Type Attributes Description
style CSSStyleDeclaration
config shaka.extern.TextDisplayerConfiguration <nullable>
Source:

setTextLanguage(language)

Set the current language.
Parameters:
Name Type Description
language string
Implements:
Source:

setTextStylePreview(confignon-null, exampleText)

Temporarily previews text displayer style settings using the normal UI text rendering path.
Parameters:
Name Type Description
config shaka.extern.TextDisplayerConfiguration
exampleText string
Source:

setTextVisibility(on)

Set text visibility.
Parameters:
Name Type Description
on boolean
Implements:
Source:

updateCaptions_(forceUpdateopt)

Display the current captions.
Parameters:
Name Type Attributes Default Description
forceUpdate boolean <optional>
 false
Source:

updateCuesRecursive_(cuesnon-null, containernon-null, currentTime, parentsnon-null)

Parameters:
Name Type Description
cues Array<!shaka.text.Cue>
container HTMLElement
currentTime number
parents Array<!shaka.text.Cue>
Source:

Type Definitions

CueRegistry_

The DOM bookkeeping kept for each displayed cue. `wrapper` is the element into which nested cues are placed.
Type:
  • {cueElement: !HTMLElement, regionElement: HTMLElement, wrapper: !HTMLElement}
Source: