Fork me on GitHub

Videojs-caption

Most flexible way to display captions for videojs. Support displaying multiple captions at once, with different positions and alignments as well as roll-up and pop-on mode.

Features How is it useful?

Videojs already support displaying text on the video using webVTT standard. But there isn't a good way to display captions with higher flexibility. Videojs-caption is designed for fully customize your captions and be friendly to Asian characters.

Demo let's see it in action!

Display 2 captions

Display Chinese and English subtitles simultaneously, one on the bottom and the other on top. Note the demo uses videojs-youtube to load youtube videos and gets subtitles from TED.

Show code 
<video id="demo" controls class="video-js vjs-default-skin">
</video>

<script>
var captionJson = [
   {
      "alignment": "C", 
      "data": "So I want to start by offering you a free", 
      "endTime": 18505, 
      "position": "HB", 
      "startTime": 15707
    }, 
    {
      "alignment": "C", 
      "data": "\u9996\u5148\u6211\u8981\u63d0\u4f9b\u4f60\u5011\u4e00\u500b\u514d\u8cbb\u7684", 
      "endTime": 18505, 
      "position": "HT", 
      "startTime": 15707
    }, 
    {
      "alignment": "C", 
      "data": "no-tech life hack,", 
      "endTime": 21129, 
      "position": "HB", 
      "startTime": 18505
    }, 
    {
      "alignment": "C", 
      "data": "\u4e0d\u6d89\u79d1\u6280\u7684\u751f\u6d3b\u5c0f\u6487\u6b65", 
      "endTime": 21129, 
      "position": "HT", 
      "startTime": 18505
    }
    ...
]
var demo = videojs('demo', { "techOrder": ["youtube"], "src": "https://www.youtube.com/watch?v=Ks-_Mh1QhMc" });
      
demo.caption({
   data: captionJson, 
   setting:{
      captionSize: 2,
   } 
});
</script>

Roll-up caption

Showing caption in roll-up fashion, commonly used in live broadcast videos.

Show code 
<video id="demo" controls class="video-js vjs-default-skin">
   <source src="http://vjs.zencdn.net/v/oceans.mp4" type="video/mp4">
   <source src="http://vjs.zencdn.net/v/oceans.webm" type="video/webm">
</video>

<script>
var demo = videojs('demo');
var captionJson = [
   {
      "data": "This is a roll up example.", 
      "startTime": 0,
      "endTime": 1000
   },
   {
      "data": "As you can see,", 
      "startTime": 1000,
      "endTime": 2000
   },
   {
      "data": "the caption is being pushed up.", 
      "startTime": 2000,
      "endTime": 3000
   }
   ...
];

demo.caption({
   data: captionJson, 
   setting:{
      captionType: 'roll-up',
   } 
});
</script>

Advanced usage

Display Japanese lyric caption where Kanji is annotated with hiragana. Chinese subtitle is shown vertically on the right. Also allow dynamically updating the caption time and font size.

  • Showing captions:
Show code 
<video id="demo" controls class="video-js vjs-default-skin">
</video>

<script>
var demo = videojs('advancedDemo', { "techOrder": ["youtube"], "src": "https://www.youtube.com/watch?v=_Q5-4yMi-xg" });
demo.caption({
   data: firstLoveJson, 
   setting : {
      onCaptionChange: function(id){
         if (id < firstLoveJson.length) {
            $('.advanced-demo-captions').append('
  • Caption reached: '+ 
               getTimeFormat(firstLoveJson[id].startTime / 1000) + ", " + firstLoveJson[id].data + '
    • ');
         }
      }
   }
});

$(".advanced-demo-bigger").click(function(){
   demo.caption.increaseFontSize();
})
$(".advanced-demo-smaller").click(function(){
   demo.caption.decreaseFontSize();
})
$(".advanced-demo-forward").click(function(){
   for (var i = 0; i < firstLoveJson.length; i++) {
      firstLoveJson[i].startTime += 500;
      firstLoveJson[i].endTime += 500;
   }
   demo.caption.updateCaption();
})
$(".advanced-demo-backward").click(function(){
   for (var i = 0; i < firstLoveJson.length; i++){
      firstLoveJson[i].startTime -= 500;
      firstLoveJson[i].endTime -= 500;
   }
   demo.caption.updateCaption();
})
</script>

    The How-to It's simple!

    Add the dependencies

    Include jquery.min.js, video-js.css and video.js:

    <link href="http://vjs.zencdn.net/4.3/video-js.css" rel="stylesheet">
<link href="src/to/videojs.caption.css" rel="stylesheet">
...
<script src="http://code.jquery.com/jquery-2.0.3.min.js"> </script>
<script src="http://vjs.zencdn.net/4.3/video.js"></script>
<script src='src/to/videojs.caption.js'></script>

    Setup the caption plugin:

    // initialize video.js
var player = videojs('video-id');

//load the caption plugin
player.caption({
   data: captionData
});

    Options Let's get deeper

    Caption Settings

    Name Type Description
    captionSize Integer

    The font size of the caption from 0 to 8. The default is 3
    captionStyle Object

    The style to be applied to the caption overlay. Default is 

    {
   'background-color': "rgba(255,0,0,0.8)",
   'color':  'white',
   'padding': "3px"
},
    onCaptionChange Function

    The callback function that gets triggered whenever the new caption is displayed. The function takes in a parameter of the id of the displayed caption. If there are multiple captions with the same start time, this function would only be triggered once and receives the id of the last caption.

     function(id){
   console.log("I'm the id of the caption: " + id);
},
    captionType String

    There are 2 caption types: "roll-up" and "pop-on". It is important to note that roll-up mode only supports horizontal bottom positions and no captions should have the same start time.

    Caption Object

    Name Description
    startTime

    Start time of the caption in milliseconds.
    endTime

    End time of the caption in milliseconds
    data

    The caption data.
    Inline styling tags

    Along with setting the styles of the caption overlay as a whole, you can also specify inline styles for text. For example: 

    <b>I</b> am <i>italic text</i>. <u>Cool</u>!
    Inline Ruby tags

    For annotating East Asian typography, you can use <R></R>ruby tags to show the pronunciation of East Asian characters (hiragana for Japanese kanji, pinyin and zhuyin for Chinese characters).

    <R value='ㄋㄧˇ'>你</R><R value='ㄏㄠˇ'>好</R>
    Inline Group tags

    When displaying text vertically, numbers (e.g. 123) are displayed vertically as well like this:

    這是123什麼

    To "group" them together and display the numbers horizontally, use the <G></G> tag:

    這是<G>123</G>什麼

    The text will be displayed as follows:

    這是123什麼
    position

    The position for displaying the caption. There are 4 different positions: HB, HT, VR, and VL, corresponding to horizontal bottom, horizontal top, vertical right, and vertical left, respectively.
    alignment

    The alignment of the caption. Currently there are only 2 types of alignments: C (center) and L (left), both of which only applies to horizontal positons.

    API Methods

    Name Description
    updateCaption

    This function should be called whenever the original caption data array has been modified, either change in text or time. It would re-render the current caption.
    loadNewCaption

    Load new caption data array. This function would also pause the video and seek to the beginning.
    getRowCursorID

    Get the ID of the currently displayed row.
    getCaptionData

    Get the entire caption array.
    increaseFontSize

    Increase the font size. There are a total of 9 levels.
    decreaseFontSize

    Decrease font size.
    changeToRollUp

    Make the necessary internal state changes to change to Roll-up mode. It is probably unecessary to change the mode within the same video so this function is designed for dynamic videos
    changeToPopOn

    Change to PopOn mode.