imscJS

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

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.

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.

imscJS requires an XML parser. By default it uses the browser's native DOMParser, so no additional library is needed in a browser environment. In environments where DOMParser is not available, e.g. Node.js, the caller must provide fromXML() with a parser that implements the contract defined in src/main/js/parser.js, e.g. sax-js.

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

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

(recommended) git

• run npm run build.

• the resulting dist/imsc.debug.js (non-minified) or dist/imsc.min.js (minified) file is the imscJS library. For example, it can be included in a web page as follows:

    <script src="imsc.min.js"></script>

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

imscJS renders an IMSC document in three distinct steps:

• fromXML(xmlstring, errorHandler, metadataHandler, parser) parses the document and returns a TT object. The latter contains opaque representation of the document and exposes the method getMediaTimeEvents() that returns a list of time offsets (in seconds) of the ISD, i.e. the points in time where the visual representation of the document change. The optional parser argument allows the caller to provide an alternative XML parser, e.g. in environments where the browser's native DOMParser is not available.

• generateISD(tt, offset, errorHandler) creates a canonical representation of the document (provided as a TT object generated by fromXML()) at a point in time (offset parameter). This point in time does not have to be one of the values returned by getMediaTimeEvents(). For example, given an ISOBMFF sample covering the interval [a, b[, generateISD(tt, offset, errorHandler) would be called first with offset = a, then in turn with offset set to each value of getMediaTimeEvents() that fall in the interval ]a, b[.

• renderHTML(isd, element, imgResolver, eheight, ewidth, displayForcedOnlyMode, errorHandler, previousISDState, enableRollUp) renders an isd object returned by generateISD() into a newly-created div element that is appended to the element. The element must be attached to the DOM. The height and width of the child div element are equal to eheight and ewidth if not null, or clientWidth and clientHeight of the parent element otherwise. Images URIs specified in smpte:background attributes are mapped to image resource URLs by the imgResolver function. The latter takes the value of the smpte:background attribute URI and an img DOM element as input and is expected to set the src attribute of the img DOM element to the absolute URI of the image. displayForcedOnlyMode sets the (boolean) value of the IMSC displayForcedOnlyMode parameter. enableRollUp enables roll-up as specified in CEA 708. previousISDState maintains states across calls, e.g. for roll-up processing.

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.

imscJS consists of the following ES modules at src/main/js, which can be imported individually, or used together as the imsc global when loaded as a UMD bundle (see Build):

• main.js: public entry point; exposes fromXML(), renderHTML(), generateISD() and createSAXParserFromDOMParser()
• doc.js: parses an IMSC document into an in-memory TT object
• parser.js: defines the XML parser contract expected by doc.js
• dom_to_parser.js: implements the XML parser contract using the browser's DOMParser
• isd.js: generates an ISD object from a TT object
• html.js: generates an HTML fragment from an ISD object
• names.js: common constants
• styles.js: defines TTML styling attributes processing
• utils.js: common utility functions
• error.js: defines error handling utilities used across modules

imscJS is built using the build NPM script, which bundles the library.

The dist directory contains the following build artifacts:

• imsc.debug.js: Non-minified UMD build.
• imsc.min.js: Minified UMD build.
• main/: ES modules and TypeScript type declarations, used when the library is imported as an NPM package.

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.

The headless script src/test/script/gen-render-package.mjs can be used to generate PNG renderings as well as intermediary files (JSON document, ISD documents and HTML documents) from the W3C IMSC test suite.

npm run gen-imsc1
npm run gen-imsc1_1

src/test/script/compare_renders.py compares two such render outputs (unzipped), performing byte-level, JSON/HTML and pixel-level PNG diffs, and optionally generating an HTML comparison report.

pipenv install
pipenv run python3 src/test/script/compare_renders.py <unzipped renders-imsc1> <unzipped renders-imsc1_1>

Unit tests run using Node's built-in test runner and are located at src/test/js. They can be run with:

npm test

Some unit tests validate rendering output against the reference files at src/test/resources/reference-files. These reference files are generated from the W3C IMSC test suite by running:

npm run gen-reference-files

• package.json: NPM package definition

• eslint.config.js: ESLint configuration

• tsconfig.json: TypeScript configuration used to generate the type declarations in dist/main

• rollup.config.js: Rollup configuration used to bundle dist/main into the UMD builds at dist/imsc.debug.js and dist/imsc.min.js

• src/test/script/Pipfile: pipenv dependency declaration for compare_renders.py

• LICENSE: License under which imscJS is made available

• CONTRIBUTING: Certification required of contributions to imscJS

• src/main/js: JavaScript modules

• src/test: Test files

• dist: Built libraries