Home

Awesome

 _                                 _    _____ 
(_)                               | |  / ____|
 _   _ __ ___    ___    ___       | | | (___  
| | | '_ ` _ \  / __|  / __|  _   | |  \___ \ 
| | | | | | | | \__ \ | (__  | |__| |  ____) |
|_| |_| |_| |_| |___/  \___|  \____/  |_____/ 
                                              
                              
                              

INTRODUCTION

imscJS is a JavaScript library for rendering IMSC 1.0.1 and IMSC 1.1 documents to HTML5. IMSC is a profile of TTML 2 designed for subtitle and caption delivery worldwide.

A sample web app that uses imscJS is available at https://www.sandflow.com/imsc1_1/index.html.

Documentation is available on MDN.

KNOWN ISSUES AND LIMITATIONS

imscJS is primarily developed on Firefox. Latest versions of Chrome, Safari, and Microsoft Edge are intended to be supported nevertheless, albeit with potentially reduced capabilities. In particular, advanced ruby layout is currently only supported by Firefox.

imscJS is intended to reflect the most recent published versions of IMSC 1.0.1 and IMSC 1.1. These publications are routinely clarified by proposed resolutions to issues captured in their respective bug trackers.

imscJS bugs are tracked at https://github.com/sandflow/imscJS/issues.

RUNTIME DEPENDENCIES

(required) sax-js 1.2.1

Rendering to HTML5 requires a browser environment, but parsing an IMSC document and transforming it into ISDs does not.

DEVELOPMENT DEPENDENCIES

(required) node.js (see package.json for a complete list of dependencies)

(recommended) git

QUICK START

    <script src="libs/sax.js"></script>
    <script src="libs/imsc.js"></script>

See BUILD ARTIFACTS for a full list of build artifacts, and TESTS AND SAMPLES for a list of samples and tests available.

ARCHITECTURE

API

imscJS renders an IMSC document in three distinct steps:

In each step, the caller can provide an errorHandler to be notified of events during processing. The errorHandler may define four methods: info, warn, error and fatal. Each is called with a string argument describing the event, and will cause processing to terminate if it returns true.

Inline documentation provides additional information.

MODULES

imscJS consists of the following modules, which can be used in a node environment using the require functionality, or standalone, in which case each module hosts its definitions under a global name (the token between parantheses):

BUILD

imscJS is built using the build:release or build:debug Grunt tasks -- the build task is an alias of build:debug.

The dist directory contains the following build artifacts:

The build/public_html/libs/imsc.js files is identical to:

RELEASES

imscJS is released as an NPM package under imsc. The dev distribution tag indicates pre-releases.

Builds/dist are available on the unpkg CDN under the dist directory.

To access the latest builds, please consult the release page.

TESTS AND SAMPLES

W3C Test Suite

imscJS imports the IMSC test suite as a submodule at src/test/resources/imsc-tests. The gen-renders.html web app can be used to generate PNG renderings as as well intermediary files from these tests.

Unit tests

Unit tests run using QUnit are split between:

NOTABLE DIRECTORIES AND FILES