_ _ _____ (_) | | / ____| _ _ __ ___ ___ ___ | | | (___ | | | '_ ` _ \ / __| / __| _ | | \___ \ | | | | | | | | \__ \ | (__ | |__| | ____) | |_| |_| |_| |_| |___/ \___| \____/ |_____/
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.
(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.
(required) node.js (see package.json for a complete list of dependencies)
buildtarget defined in Gruntfile.js using grunt.
build/public_html/libsare, respectively, the imscJS library and its sax-js dependency. For example, both libraries can be included in a web page as follows:
<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.
imscJS renders an IMSC document in three distinct steps:
fromXML(xmlstring, errorHandler, metadataHandler)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.
generateISD(tt, offset, errorHandler)creates a canonical representation of the document (provided as a TT object generated by
fromXML()) at a point in time (
offsetparameter). 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
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
renderHTML(isd, element, imgResolver, eheight, ewidth, displayForcedOnlyMode, errorHandler, previousISDState, enableRollUp)renders an
isdobject returned by
generateISD()into a newly-created
divelement that is appended to the
elementmust be attached to the DOM. The height and width of the child
divelement are equal to
ewidthif not null, or
clientHeightof the parent
elementotherwise. Images URIs specified in
smpte:backgroundattributes are mapped to image resource URLs by the
imgResolverfunction. The latter takes the value of the
smpte:backgroundattribute URI and an
imgDOM element as input and is expected to set the
srcattribute of the
imgDOM element to the absolute URI of the image.
displayForcedOnlyModesets the (boolean) value of the IMSC displayForcedOnlyMode parameter.
enableRollUpenables roll-up as specified in CEA 708.
previousISDStatemaintains 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:
fatal. Each is called with a string argument describing the event, and will cause processing to terminate if it returns
Inline documentation provides additional information.
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):
imscDoc): parses an IMSC document into an in-memory TT object
imscISD): generates an ISD object from a TT object
imscHTML): generates an HTML fragment from an ISD object
imscNames): common constants
imscStyles): defines TTML styling attributes processing
imscUtils): common utility functions
imscJS is built using the
build:debug Grunt tasks -- the
build task is an alias of
dist directory contains the following build artifacts:
imsc.all.debug.js: Non-minified build that includes the sax-js dependency.
imsc.all.min.js: Minified build that includes the sax-js dependency.
imsc.debug.js: Non-minified build that does not include the sax-js dependency.
imsc.min.js: Minified build that does not include the sax-js dependency.
build/public_html/libs/imsc.js files is identical to:
imsc.debug.js, if the
build:debugtask is executed.
imsc.min.js, if the
build:releasetask is executed.
imscJS is released as an NPM package under imsc. The
dev distribution tag indicates pre-releases.
All builds are available on the unpkg CDN under the
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 run using QUnit are split between:
NOTABLE DIRECTORIES AND FILES
package.json: NPM package definition
Gruntfile.js: Grunt build script
properties.json: General project properties
LICENSE: License under which imscJS is made available
src/test: Test files
dist: Built libraries
build/public_html: Test web applications