A simple system for adding captions and an interactive transcript to online videos. EasyCaptions uses progressive enhancement, providing the best possible experience for all visitors. Background information

Documentation

EasyCaptions API

Options:

  • enableTranscript (boolean; default is true)
    • If set to false, EasyCaptions will NOT make the transcript clickable.
  • enableCaptions (boolean; default is true)
    • If set to false, EasyCaptions will NOT dynamically generate the caption <div>
  • transcriptElementID (string or HTML DOM element)
    • Required. The HTML element containing the transcript. The transcript must be marked up with <span> elements using the custom data-begin attribute (data-end is optional).
  • videoElementID (string or HTML DOM element)
    • The HTML5 video element. If this element is not supplied the fallback will still function (assuming it is configured properly).
  • transcriptEnabledClass (string, default is “EasyCaptions-enabled”)
    • The class to append to the transcript text container. If no custom class name is provided by the user, the default “EasyCaptions-enabled” will be used
  • captionID (string, default is “EasyCaptions-caption”)
    • The ID to append to the generated caption area. If no custom ID is provided by the user, the default “EasyCaptions-caption” will be used

Returns: object with the following properties and methods

  • video_element (HTML DOM element)
    • The video element specified by the videoElementID option
  • transcript_element (HTML DOM element)
    • The transcript element specified by the transcriptElementID option
  • caption_element (HTML DOM element)
    • The caption element generated by EasyCaptions
  • html5_supported (boolean)
    • Indicates whether HTML5 video is supported in the user’s browser. Important note: This detection ONLY checks support for mime types specified in the markup. For example, if you only specify <source src="myvideo.mp4" type="video/mp4" />, the detection script will only check for video/mp4 support and will NOT check for any other mime types.
  • updateCaption(timecode) (function)
    • A utility that allows you to display the caption for a specific timecode. This is useful if you need to manually control caption timing. Pass the specified timecode (number representing seconds) as the argument.
  • enableFallback(obj) (function)
    • A utility that allows you to specify your own custom fallback mechanism (normally a Flash-based fallback, but other technologies such as Silverlight could be used as well). Accepts a single object argument, with the following properties:
      • elementID (string or HTML DOM element)
        • The element containing your fallback video (such as the <object> that loads the Flash-based JW Media Player)
      • captionHandler (function)
        • The hook for your fallback’s caption handling.
      • transcriptHandler (function)
        • The hook for your fallback’s transcript/onclick handling.

Code examples

Simplest example (no fallback):

<div id="transcript">
    <p>
        <span data-begin="0">My first phrase,</span> 
        <span data-begin="14">then a second.</span> 
        <span data-begin="16">A third comes shortly after.</span> 
    </p>
</div>

<video id="myVideoID" width="420" height="240" controls>
    <source src="myvideo.mp4" type="video/mp4" />
    <source src="myvideo.ogv" type="video/ogg" />
        <!-- fallback content here -->        
</video>
Code language: HTML, XML (xml)
var easy = new EasyCaptions({
    videoElementID: "myVideoID",
    transcriptElementID: "transcript"
});

alert(easy.html5_supported); //returns true in modern browsers
Code language: JavaScript (javascript)

With fallback:

<div id="transcript">
    <p>
        <span data-begin="0">My first phrase,</span> 
        <span data-begin="14">then a second.</span> 
        <span data-begin="16">A third comes shortly after.</span> 
    </p>
</div>

<video id="myVideoID" width="420" height="240" controls>
    <source src="myvideo.mp4" type="video/mp4" />
    <source src="myvideo.ogv" type="video/ogg" />
        
    <object id="video-swf" name="video-swf" data="player.swf" type="application/x-shockwave-flash" width="420" height="240">  
        <param value="player.swf" name="movie"/>  
        <param value="controlbar=over&file=myvideo.f4v" name="flashvars"/>
        
        <!-- fallback content here -->
        
    </object>    
        
</video>
Code language: HTML, XML (xml)
var easy = new EasyCaptions({
    videoElementID: "myVideoID",
    transcriptElementID: "transcript"
});

easy.addFallback({

    elementID: "video-swf",

    captionHandler: function (video, updateCaption){
        //Nothing needed here; we're using 
        //JW Media Player's "playerReady" function
    },

    transcriptHandler: function (video, position){
        video.sendEvent('SEEK', position);
    }

});

//The following code is specific to JW Media Player.
//You could replace with something else if you
//prefer other Flash video players.	
jw_timeupdateHandler = function (video){
    easy.updateCaption(parseInt(video.position, 10));
};
Code language: PHP (php)

Demonstrations

These demos have been successfully tested in the following browsers:

  • Firefox 3.0 (OSX 10.6.2, Windows XP)
  • Firefox 3.5 (OSX 10.6.2)
  • Firefox 3.6 (OSX 10.6.2, Windows 7)
  • Safari 4.0 (OSX 10.6.2)
  • Google Chrome 5.0 (OSX 10.6.2, Windows XP)
  • Opera 10.1, Opera 10.5 (OSX 10.6.2)
  • Internet Explorer 6 (Windows XP)
    • Issue: SWFObject demo doesn’t correctly remove fallback content
  • Internet Explorer 8 (Windows 7)
    • Issue: SWFObject demo doesn’t correctly remove fallback content

Download

Now hosted on GitHub