mirror of
https://github.com/shaka-project/shaka-player.git
synced 2026-06-16 16:16:40 +03:00
Álvaro Velad Galván
133 lines
4.1 KiB
Markdown
133 lines
4.1 KiB
Markdown
# Configuring text displayer
|
|
|
|
### Default displayers
|
|
|
|
Shaka Player supports two implementations of {@link shaka.extern.TextDisplayer}
|
|
which can be used to render & style content subtitles.
|
|
|
|
#### NativeTextDisplayer
|
|
|
|
{@link shaka.text.NativeTextDisplayer} which uses browser's native cue
|
|
renderer. Shaka Player creates corresponding text tracks for text streams on
|
|
the video element and provides necessary data so video element can render it.
|
|
This is the default displayer when shaka UI is **not** used, we also use
|
|
NativeTextDisplayer when using PiP and Fullscreen API of the video element
|
|
itself.
|
|
|
|
#### UITextDisplayer
|
|
|
|
{@link shaka.text.UITextDisplayer} which renders subtitles inside of a DOM
|
|
container provided to shaka.
|
|
Container can be provided in 2 ways, by either a {@link shaka.Player}
|
|
constructor or a {@link shaka.Player#setVideoContainer} method. This call
|
|
is done automatically when using Shaka UI.
|
|
```js
|
|
// Take your custom video container element.
|
|
const container = document.getElementById('video_container');
|
|
// Attach container using player constructor.
|
|
const player = new shaka.Player(/* mediaElement= */ null, container);
|
|
// Alternatively, pass it using dedicated method.
|
|
player.setVideoContainer(container);
|
|
```
|
|
|
|
##### Font size scaling for readability
|
|
|
|
For improved readability the option to scale text size is provided via player
|
|
config.
|
|
|
|
```js
|
|
player.configure({
|
|
textDisplayer: {
|
|
fontScaleFactor: 1.5,
|
|
},
|
|
});
|
|
```
|
|
|
|
Note: Only supported on UITextDisplayer.
|
|
|
|
##### Subtitle timing offset
|
|
|
|
Shaka Player allows applications to manually adjust subtitle timing using the `textDisplayer.subtitleDelay` configuration option.
|
|
|
|
This is useful when subtitles are out of sync with the video.
|
|
|
|
```js
|
|
player.configure({
|
|
textDisplayer: {
|
|
subtitleDelay: 2, // Delay subtitles by 2 seconds
|
|
},
|
|
});
|
|
```
|
|
|
|
Behavior
|
|
- Positive values delay subtitles (they appear later than the video)
|
|
- Negative values advance subtitles (they appear earlier than the video)
|
|
- Default value is 0 (no offset)
|
|
|
|
Notes:
|
|
- With UITextDisplayer, the subtitle delay is applied dynamically.
|
|
- With NativeTextDisplayer, the delay is applied by modifying cue timings when they are added to the video element.
|
|
|
|
##### Overriding Subtitle Position
|
|
|
|
Shaka Player allows applications to override the default subtitle placement and render captions in predefined regions of the video viewport. This is useful when subtitles need to avoid UI overlays, follow accessibility guidelines, or provide a consistent layout across different content.
|
|
|
|
By setting the `textDisplayer.positionArea` configuration option, applications can:
|
|
|
|
- Explicitly control where subtitles are rendered on the screen
|
|
- Override the automatic or cue-defined positioning
|
|
- Update subtitle placement dynamically at runtime
|
|
|
|
The following enum defines the supported subtitle placement areas:
|
|
|
|
| Value | Screen Position |
|
|
|------|-----------------|
|
|
| `DEFAULT` | Default player behavior |
|
|
| `TOP_LEFT` | Top left |
|
|
| `TOP_CENTER` | Top center |
|
|
| `TOP_RIGHT` | Top right |
|
|
| `CENTER_LEFT` | Center left |
|
|
| `CENTER` | Center of the screen |
|
|
| `CENTER_RIGHT` | Center right |
|
|
| `BOTTOM_LEFT` | Bottom left |
|
|
| `BOTTOM_CENTER` | Bottom center |
|
|
| `BOTTOM_RIGHT` | Bottom right |
|
|
|
|
Example configuration:
|
|
|
|
```js
|
|
player.configure({
|
|
textDisplayer: {
|
|
positionArea: shaka.config.PositionArea.BOTTOM_CENTER,
|
|
},
|
|
});
|
|
```
|
|
|
|
Note: Only supported on UITextDisplayer.
|
|
|
|
### Text displayer configuration
|
|
|
|
Additional configuration for the text displayer can be passed by calling:
|
|
```js
|
|
player.configure({
|
|
textDisplayer: {/*...*/}
|
|
});
|
|
```
|
|
See {@link shaka.extern.TextDisplayerConfiguration} for more details.
|
|
|
|
### Custom text displayer
|
|
|
|
If none of displayers is suitable for your needs, you can prepare your own.
|
|
To do that you need to implement {@link shaka.extern.TextDisplayer} interface
|
|
and pass your custom displayer to shaka by calling:
|
|
```js
|
|
player.configure({
|
|
textDisplayFactory: (player) => new CustomTextDisplayer(player),
|
|
});
|
|
```
|
|
|
|
Keep in mind text displayers are used entirely for rendering subtitles related
|
|
directly to the content. If you wish to display other information, i.e. stream
|
|
metadata, you might consider using {@link shaka.ui.Overlay#setTextWatermark}
|
|
instead.
|