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/ttaf1-dfxp
|
18 |
|
19 | A live sample web app using imscJS is available at [3].
|
20 |
|
21 | [3] http://sandflow.com/imsc1proc/index.html
|
22 |
|
23 | Renders of IRT and TTML test vectors are available at [4], respectively.
|
24 |
|
25 | [4] http://sandflow.com/imsc1proc/samples.html
|
26 |
|
27 |
|
28 |
|
29 | KNOWN ISSUES AND LIMITATIONS
|
30 | ============================
|
31 |
|
32 | imscJS is primarily developed on the latest released versions of Firefox and
|
33 | Chrome. Microsoft Internet Explorer is not supported at this point.
|
34 |
|
35 | imscJS is intended to reflect the most recent published versions of TTML1 and
|
36 | IMSC1, as clarified by proposed resolutions to issues captured in their
|
37 | respective bug trackers [1-2].
|
38 |
|
39 | [1] https://github.com/w3c/ttml1/issues
|
40 | [2] https://github.com/w3c/imsc/issues
|
41 |
|
42 | imscJS bugs are tracked at [3]
|
43 |
|
44 | [3] https://github.com/sandflow/regxmllib/issues
|
45 |
|
46 |
|
47 |
|
48 | RUNTIME DEPENDENCIES
|
49 | ====================
|
50 |
|
51 | (required) sax-js (1.2.1) [https://www.npmjs.com/package/sax]
|
52 |
|
53 | imscJS defines an NPM package (see DEVELOPMENT DEPENDENCIES and PACKAGE below) to simplify development,
|
54 | track dependencies and manage versions, but has no runtime dependency on node.js. Rendering to HTML5 requires a
|
55 | browser environment but parsing an IMSC1 document and tranforming it into ISDs does not.
|
56 |
|
57 |
|
58 |
|
59 | DEVELOPMENT DEPENDENCIES
|
60 | ========================
|
61 |
|
62 | (required) node.js (see package.json for a complete list of dependencies)
|
63 |
|
64 | (recommended) git
|
65 |
|
66 | (recommended) Netbeans 8.2
|
67 |
|
68 | imscJS consists of a collection of modules (see MODULES below), which can be used in a node
|
69 | environment using the 'require' functionality, or standalone, in which case each module hosts its
|
70 | definitions under a global name. The modules can be combined into a single file using Browserify [1]
|
71 | to simplify use in web apps (see Gruntfile.js for an example).
|
72 |
|
73 |
|
74 |
|
75 | QUICK START
|
76 | ===========
|
77 |
|
78 | * build the 'build' target defined in Gruntfile.js using grunt [1]. This will build the library and the tests into the
|
79 | build/public_html directory, which can be served by popular web server.
|
80 |
|
81 | [1] http://gruntjs.com/
|
82 |
|
83 | * the resulting imsc.js and sax.js files at build/public_html/libs are, respectively, the
|
84 | imscJS library and its sax-js dependency. Both are included in a web page using the following:
|
85 |
|
86 | ```
|
87 | <script src="libs/sax.js"></script>
|
88 | <script src="libs/imsc.js"></script>
|
89 | ```
|
90 |
|
91 | See TESTS AND SAMPLES below for a list of samples available.
|
92 |
|
93 |
|
94 |
|
95 | ARCHITECTURE
|
96 | ============
|
97 |
|
98 | imscJS renders an IMSC1 document in three distinct steps:
|
99 |
|
100 | * `fromXML(xmlstring, errorHandler)` parses the document and returns a TT object. The latter contains opaque representation of the document
|
101 | and exposes the method `getMediaTimeEvents()` that returns a list of time offsets (in seconds) of the ISD, i.e. the points in time
|
102 | where the visual representation of the document change.
|
103 |
|
104 | * `generateISD(tt, offset, errorHandler)` creates a canonical representation of the document (provided as a TT object generated by `fromXML()`)
|
105 | at a point in time (`offset` parameter). This point in time does not have to be one of the values returned by `getMediaTimeEvents()`.
|
106 |
|
107 | * `renderHTML(isd, div)` renders the object returned by `generateISD()` into a DOM "div" element.
|
108 |
|
109 |
|
110 | MODULES
|
111 | =======
|
112 |
|
113 | The imscJS codebase is arranged in the following modules (the token between parantheses is the global name
|
114 | used if 'require' is not used to load modules):
|
115 |
|
116 | * doc.js (imscDoc): parses an IMSC1 document into an in-memory TT object
|
117 | * isd.js (imscISD): generates an ISD object from a TT object
|
118 | * html.js (imscHTML): generates an HTML fragment from an ISD object
|
119 | * names.js (imscNames): common constants
|
120 | * styles.js (imscStyles): defines TTML styling attributes processing
|
121 | * utils.js (imscUtils): common utility functions
|
122 |
|
123 |
|
124 |
|
125 | TESTS AND SAMPLES
|
126 | =================
|
127 |
|
128 | Formal unit tests are located at [1] and run as a webapp [2] using QUnit [3].
|
129 |
|
130 | [1] src/test/webapp/js/unit-tests.js
|
131 | [2] src/test/webapp/unit_tests.html
|
132 | [3] https://qunitjs.com/
|
133 |
|
134 | Also included is the 'samples' webapp [4] that renders the samples listed at [5].
|
135 |
|
136 | [4] src/test/webapp/samples.html
|
137 | [5] src/test/resources/samples/samples.json
|
138 |
|
139 | The samples.json provided with the distribution expects the following two directories to be added to [6]
|
140 |
|
141 | * "irt" directory that contains the "ttml" and "png" directories at [7]. These are test vectors provided by the IRT.
|
142 | * "ttml" directory that contains the directories at [8]. These are the formal TTML1 test vectors provided by the W3C.
|
143 | Only tests that are compatible with IMSC1 are referenced.
|
144 |
|
145 | [6] src/test/resources/samples/
|
146 | [7] https://github.com/IRT-Open-Source/irt-ebu-tt-d-application-samples
|
147 | [8] https://github.com/w3c/ttml1/tree/gh-pages/testsuite
|
148 |
|
149 |
|
150 |
|
151 | NPM PACKAGE
|
152 | ===========
|
153 |
|
154 | imscJS is released as an NPM package under the name "imsc".
|
155 |
|
156 |
|
157 |
|
158 | NOTABLE DIRECTORIES AND FILES
|
159 | =============================
|
160 |
|
161 | /package.json NPM package definition
|
162 |
|
163 | /Gruntfile.js Grunt build script
|
164 |
|
165 | /properties.json General project properties
|
166 |
|
167 | /README This file
|
168 |
|
169 | /LICENSE License under which imscJS is made available
|
170 |
|
171 | /src/main/js JavaScript modules
|
172 |
|
173 | /src/test/resources Test files
|
174 |
|
175 | /src/test/webapp Test web applications
|
176 |
|
177 | /build Build output
|