1 | _ _ _____
|
2 | (_) | | / ____|
|
3 | _ _ __ ___ ___ ___ | | | (___
|
4 | | | | '_ ` _ \ / __| / __| _ | | \___ \
|
5 | | | | | | | | | \__ \ | (__ | |__| | ____) |
|
6 | |_| |_| |_| |_| |___/ \___| \____/ |_____/
|
7 |
|
8 |
|
9 | INTRODUCTION
|
10 | ============
|
11 |
|
12 | imscJS is a JavaScript library for rendering IMSC1 Text and Image Profile
|
13 | documents [1] to HTML5. IMSC1 is a profile of TTML [2] designed for subtitle and
|
14 | caption delivery worldwide.
|
15 |
|
16 | [1] https://www.w3.org/TR/ttml-imsc1/
|
17 | [2] https://www.w3.org/TR/ttml1/
|
18 |
|
19 | A live sample web app using imscJS is available at [3].
|
20 |
|
21 | [3] http://sandflow.com/imsc1proc/index.html
|
22 |
|
23 |
|
24 |
|
25 | KNOWN ISSUES AND LIMITATIONS
|
26 | ============================
|
27 |
|
28 | imscJS is primarily developed on Chrome. Latest versions of Firefox, Safari,
|
29 | Microsoft Internet Explorer 11 and Microsoft Edge are intended to be supported
|
30 | nevertheless.
|
31 |
|
32 | imscJS is intended to reflect the most recent published versions of TTML1 and
|
33 | IMSC1, as clarified by proposed resolutions to issues captured in their
|
34 | respective bug trackers [1-2].
|
35 |
|
36 | [1] https://github.com/w3c/ttml1/issues
|
37 | [2] https://github.com/w3c/imsc/issues
|
38 |
|
39 | imscJS bugs are tracked at [3]
|
40 |
|
41 | [3] https://github.com/sandflow/imscJS/issues
|
42 |
|
43 |
|
44 |
|
45 | RUNTIME DEPENDENCIES
|
46 | ====================
|
47 |
|
48 | (required) sax-js (1.2.1) [https://www.npmjs.com/package/sax]
|
49 |
|
50 | imscJS defines an NPM package (see DEVELOPMENT DEPENDENCIES and PACKAGE below) to simplify development,
|
51 | track dependencies and manage versions, but has no runtime dependency on node.js. Rendering to HTML5 requires a
|
52 | browser environment but parsing an IMSC1 document and tranforming it into ISDs does not.
|
53 |
|
54 |
|
55 |
|
56 | DEVELOPMENT DEPENDENCIES
|
57 | ========================
|
58 |
|
59 | (required) node.js (see package.json for a complete list of dependencies)
|
60 |
|
61 | (recommended) git
|
62 |
|
63 | (recommended) Netbeans 8.2
|
64 |
|
65 | imscJS consists of a collection of modules (see MODULES below), which can be used in a node
|
66 | environment using the 'require' functionality, or standalone, in which case each module hosts its
|
67 | definitions under a global name. The modules can be combined into a single file using Browserify [1]
|
68 | to simplify use in web apps (see Gruntfile.js for an example).
|
69 |
|
70 |
|
71 |
|
72 | QUICK START
|
73 | ===========
|
74 |
|
75 | * build the 'build' target defined in Gruntfile.js using grunt [1]. This will build the library and the tests into the
|
76 | build/public_html directory, which can be served by popular web server.
|
77 |
|
78 | [1] http://gruntjs.com/
|
79 |
|
80 | * the resulting imsc.js and sax.js files at build/public_html/libs are, respectively, the
|
81 | imscJS library and its sax-js dependency. Both are included in a web page using the following:
|
82 |
|
83 | <script src="libs/sax.js"></script>
|
84 | <script src="libs/imsc.js"></script>
|
85 |
|
86 | See TESTS AND SAMPLES below for a list of samples available.
|
87 |
|
88 |
|
89 |
|
90 | ARCHITECTURE
|
91 | ============
|
92 |
|
93 | imscJS renders an IMSC1 document in three distinct steps:
|
94 |
|
95 | * `fromXML(xmlstring, errorHandler, metadataHandler)` parses the document and returns a TT object. The latter contains opaque
|
96 | representation of the document and exposes the method `getMediaTimeEvents()` that returns a list of time offsets (in seconds) of the
|
97 | ISD, i.e. the points in time where the visual representation of the document change.
|
98 |
|
99 | * `generateISD(tt, offset, errorHandler)` creates a canonical representation of the document (provided as a TT object generated by `fromXML()`)
|
100 | at a point in time (`offset` parameter). This point in time does not have to be one of the values returned by `getMediaTimeEvents()`. For
|
101 | example, given an ISOBMFF sample covering the interval `[a, b[`, `generateISD(tt, offset, errorHandler)` would be called first with `offset = a`,
|
102 | then in turn with offset set to each value of `getMediaTimeEvents()` that fall in the interval `]a, b[`.
|
103 |
|
104 | * `renderHTML(isd, element, imgResolver, eheight, ewidth, displayForcedOnlyMode, errorHandler, previousISDState, enableRollUp)`
|
105 | renders an `isd` object returned by `generateISD()`
|
106 | into a newly-created `div` element that is appended to the `element`. The `element` must be attached to the DOM.
|
107 | The height and width of the child `div` element are equal to `eheight` and `ewidth` if not null, or `clientWidth` and `clientHeight` of the
|
108 | parent `element` otherwise. Images URIs specified in `smpte:background` attributes are mapped to image resource URLs by the `imgResolver`
|
109 | function. The latter takes the value of the `smpte:background` attribute URI and an `img` DOM element as input and is expected to
|
110 | set the `src` attribute of the `img` DOM element to the absolute URI of the image. `displayForcedOnlyMode` sets the (boolean) value
|
111 | of the IMSC1 displayForcedOnlyMode parameter. `enableRollUp` enables roll-up as specified in CEA 708. `previousISDState` maintains states across
|
112 | calls, e.g. for roll-up processing.
|
113 |
|
114 | In each step, the caller can provide an `errorHandler` to be notified of events during processing. The `errorHandler` may define four methods:
|
115 | `info`, `warn`, `error` and `fatal`. Each is called with a string argument describing the event, and will cause processing to terminate if it
|
116 | returns `true`.
|
117 |
|
118 | See inline documentation for additional documentation.
|
119 |
|
120 |
|
121 |
|
122 | MODULES
|
123 | =======
|
124 |
|
125 | The imscJS codebase is arranged in the following modules (the token between parantheses is the global name
|
126 | used if 'require' is not used to load modules):
|
127 |
|
128 | * doc.js (imscDoc): parses an IMSC1 document into an in-memory TT object
|
129 | * isd.js (imscISD): generates an ISD object from a TT object
|
130 | * html.js (imscHTML): generates an HTML fragment from an ISD object
|
131 | * names.js (imscNames): common constants
|
132 | * styles.js (imscStyles): defines TTML styling attributes processing
|
133 | * utils.js (imscUtils): common utility functions
|
134 |
|
135 |
|
136 |
|
137 | TESTS AND SAMPLES
|
138 | =================
|
139 |
|
140 | W3C Test Suite
|
141 | **************
|
142 |
|
143 | imscJS imports the IMSC1 test suite [1] managed by the W3C as submodule at [2].
|
144 | The gen-renders.html web app can be used to generate PNG renderings as as well intermediary files from these
|
145 | tests. For regression testing, a copy of these intermediary files are committed at [3].
|
146 |
|
147 | [1] https://github.com/w3c/imsc-tests
|
148 | [2] src/test/resources/imsc-tests
|
149 | [3] src/test/resources/generated
|
150 |
|
151 | Unit tests
|
152 | **********
|
153 |
|
154 | Unit tests are located at [1] and run as a webapp [2] using QUnit [3].
|
155 |
|
156 | [1] src/test/webapp/js/unit-tests.js
|
157 | [2] src/test/webapp/unit_tests.html
|
158 | [3] https://qunitjs.com/
|
159 |
|
160 | NPM PACKAGE
|
161 | ===========
|
162 |
|
163 | imscJS is released as an NPM package under the name "imsc".
|
164 |
|
165 |
|
166 |
|
167 | NOTABLE DIRECTORIES AND FILES
|
168 | =============================
|
169 |
|
170 | /package.json NPM package definition
|
171 |
|
172 | /Gruntfile.js Grunt build script
|
173 |
|
174 | /properties.json General project properties
|
175 |
|
176 | /README This file
|
177 |
|
178 | /LICENSE License under which imscJS is made available
|
179 |
|
180 | /src/main/js JavaScript modules
|
181 |
|
182 | /src/test/resources Test files
|
183 |
|
184 | /src/test/webapp Test web applications
|
185 |
|
186 | /build Build output
|