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:

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:

ZERO_WIDTH_SPACE_ :string

The text of the empty bases and annotations which reserve space for ruby.
Type:
  • string
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:

outsideRubyElements_ :Array<!HTMLElement>

The new ruby elements whose annotations are outside the lines of their paragraph.
Type:
  • Array<!HTMLElement>
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:

rubyParagraphs_ :Array<{element: !HTMLElement, cue: !shaka.text.Cue}>

The new paragraphs with ruby, which are laid out once they are shown, as some of their ruby depends on the lines they are broken into.
Type:
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, or on the size of the video container for lengths relative to the root container.
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

getBaseRect_(elementnon-null) → {DOMRect}

Gets the rectangle of the bases of a ruby, without its annotations.
Parameters:
Name Type Description
element Element
Source:
Returns:
Type
DOMRect

getBaseTexts_(elementnon-null) → {Array<!Text>}

Gets the texts of an element which are laid out on its lines, which are not the ones of ruby annotations.
Parameters:
Name Type Description
element Element
Source:
Returns:
Type
Array<!Text>

getBlockInterval_(rectnon-null, writingMode) → {Array<number>}

Gets the interval of a rectangle along the block progression direction, which increases from the first line to the last one.
Parameters:
Name Type Description
rect DOMRect
writingMode shaka.text.Cue.writingMode
Source:
Returns:
Type
Array<number>

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' }

getLines_(elementnon-null, writingMode) → {Array<!Array<number>>}

Gets the lines a paragraph is broken into, as intervals along the block progression direction, in the order the lines are stacked.
Parameters:
Name Type Description
element HTMLElement
writingMode shaka.text.Cue.writingMode
Source:
Returns:
Type
Array<!Array<number>>

getLineStarts_(elementnon-null, getLine) → {Array<{node: !Node, offset: number, line: number}>}

Finds where each line of a paragraph starts: before the first ruby, or the first character which is not a space, of the line.
Parameters:
Name Type Description
element HTMLElement
getLine function(!DOMRect): number
Source:
Returns:
The node and the offset in its text of each line start, with the index of the line.
Type
Array<{node: !Node, offset: number, line: number}>

hasCollapsibleWhiteSpace_(text) → {boolean}

Checks whether 'white-space: pre-line' would collapse or remove any of the white space in |text|, compared to 'pre-wrap'. That is the case for tabs and other white space characters besides spaces and line breaks, for runs of spaces, and for spaces at the start or end of a line.
Parameters:
Name Type Description
text string
Source:
Returns:
Type
boolean

hasRuby_(cuenon-null) → {boolean}

Finds whether a cue contains ruby.
Parameters:
Name Type Description
cue shaka.text.Cue
Source:
Returns:
Type
boolean

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:

setRubyPosition_(elementnon-null, isBefore, writingMode)

Places the annotations of a ruby before or after the line, in the block progression direction.
Parameters:
Name Type Description
element HTMLElement
isBefore boolean
writingMode shaka.text.Cue.writingMode
Source:

setWritingMode_(stylenon-null, writingMode)

Parameters:
Name Type Description
style CSSStyleDeclaration
writingMode shaka.text.Cue.writingMode
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

layOutRuby_()

Lays out the ruby of the new paragraphs which depends on the lines they are broken into: the annotations which are outside the lines, and the space reserved for annotations on each line. See https://www.w3.org/TR/ttml2/#style-attribute-rubyPosition and https://www.w3.org/TR/ttml2/#style-attribute-rubyReserve
Source:

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:

paintWindow_(cueElementnon-null, wrappernon-null, cuenon-null, parentsnon-null)

Paints the window of the configuration, a box behind all the lines of a block of text, which are the top-level cues and the cues laid out as separate lines by their container. The backgrounds of the text are painted over it.
Parameters:
Name Type Description
cueElement HTMLElement
wrapper HTMLElement
cue shaka.text.Cue
parents Array<!shaka.text.Cue> The parents of the cue, and the cue itself.
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: