Change Subtitles Positions

By default, subtitles (and close captioning) are displayed at the bottom of the video, unless a part of the platform interface overlaps with their position, in which case they are moved to a new, free position. These positions are referred to as subtitle display zones. This document outlines ways and use cases to change the position of subtitles.

Display zone availability (“in which position should the subtitles be displayed”) is ordered by first reverse number of locks, then priority. IE the currently available zone is the one with the highest priority from the non-locked zones, or if all zones are locked, the one with the least locks.

The name, priority and style of the default display zones:

Name Priority Position (mobile / desktop)
bottom1 1000 bottom: 20px / 30px
bottom2 900 bottom: 50px / 90px
bottom3 800 bottom: 90px / 150px
center 700 top: 50%
top1 600 top: 20px
top2 500 top: 40px
top3 400 top: 70px

You can get more information about the properties of these display zones by calling console.log(player.subtitles.position.getDisplayZone('all'))

Changing position from code using subtitles plugin API

The subtitles plugin offers functionality for adding, locking and retrieving information about display zones. All the other methods described on this page are effectively using said functionality under the hood. More information is available in the plugin documentation).

// example: lock/unlock a display zone
player.subtitles.position.lockDisplayZone('bottom1', 'lockedByBottomMenu')
player.subtitles.position.unlockDisplayZone('bottom1', 'lockedByBottomMenu')

Changing position permanently using player options

If your video content requires changing the location of the subtitles for the entirety of its duration, such as in the case where you have a piece of visual or interface that clashes with the default location of the subtitles, you can use custom player options to alter the position of the subtitles.
The subtitles plugin accepts two parameters as player options to affect the lock status and priority of display zones.
You can use this to either make it more likely for subtitles to appear in certain display zone (using priority), or less likely to appear in one (using locks) according to your specific need.

For example, these options will place a lock on the “bottom1” display zone, and override the “top1” display zone priority to be highest. It effectively means that subtitles will always be displayed at the “top1” zone, unless it is locked. It also means that “bottom1” is very unlikely be selected as a location to display subtitles. Click here to learn more about how the order of display zones is determined.

// playerOptions.json
    "plugins": {
         "subtitles": {
          "displayZoneLocks": ["bottom1"],
          "displayZonePriority": {
                "top1": 2000

Changing subtitle position per-node with metadata and custom code

If you wish to change position for only some of the nodes in your project, you can do so by supplying metadata for the nodes in question, which will then be read to set up the required locks when a node starts playing. For example:

// node metadata, which specifies locks to avoid subtitles appearing at the bottom of the frame
  "subtitleDisplayZoneLocks": {
    "bottom1": true,
    "bottom2": true,
    "bottom3": true,
    "center": true
// app.js
function onReady(player, ctx) {
        const setupLocks = node => {
            let metadata =;

            // when starting to play a new node unlock previously locked subtitle positions
                displayZoneId => player.subtitles.position.unlockDisplayZone(displayZoneId, 'nodeConfigLock')

            if (metadata.subtitleDisplayZoneLocks){
                // for each display zone specified in the node metadata, lock this display zone
                    lockedZoneId => player.subtitles.position.lockDisplayZone(lockedZoneId, 'nodeConfigLock')

        // finally, setup locks on the node that's already playing

        // take care of future nodes
        player.on("nodestart", setupLocks);

export default { onReady };
Rate this page: X
Tell us more!