forked from sandflow/imscJS
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.txt
208 lines (127 loc) · 7.6 KB
/
README.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
_ _ _____
(_) | | / ____|
_ _ __ ___ ___ ___ | | | (___
| | | '_ ` _ \ / __| / __| _ | | \___ \
| | | | | | | | \__ \ | (__ | |__| | ____) |
|_| |_| |_| |_| |___/ \___| \____/ |_____/
INTRODUCTION
============
imscJS is a JavaScript library for rendering IMSC1 Text and Image Profile
documents [1] to HTML5. IMSC1 is a profile of TTML [2] designed for subtitle and
caption delivery worldwide.
[1] https://www.w3.org/TR/ttml-imsc1/
[2] https://www.w3.org/TR/ttaf1-dfxp
A live sample web app using imscJS is available at [3].
[3] http://sandflow.com/imsc1proc/index.html
KNOWN ISSUES AND LIMITATIONS
============================
imscJS is primarily developed on Chrome. Latest versions of Firefox, Safari,
Microsoft Internet Explorer 11 and Microsoft Edge are intended to be supported
nevertheless.
imscJS is intended to reflect the most recent published versions of TTML1 and
IMSC1, as clarified by proposed resolutions to issues captured in their
respective bug trackers [1-2].
[1] https://github.com/w3c/ttml1/issues
[2] https://github.com/w3c/imsc/issues
imscJS bugs are tracked at [3]
[3] https://github.com/sandflow/imscJS/issues
RUNTIME DEPENDENCIES
====================
(required) sax-js (1.2.1) [https://www.npmjs.com/package/sax]
imscJS defines an NPM package (see DEVELOPMENT DEPENDENCIES and PACKAGE below) to simplify development,
track dependencies and manage versions, but has no runtime dependency on node.js. Rendering to HTML5 requires a
browser environment but parsing an IMSC1 document and tranforming it into ISDs does not.
DEVELOPMENT DEPENDENCIES
========================
(required) node.js (see package.json for a complete list of dependencies)
(recommended) git
(recommended) Netbeans 8.2
imscJS consists of a collection of modules (see MODULES below), 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 modules can be combined into a single file using Browserify [1]
to simplify use in web apps (see Gruntfile.js for an example).
QUICK START
===========
* build the 'build' target defined in Gruntfile.js using grunt [1]. This will build the library and the tests into the
build/public_html directory, which can be served by popular web server.
[1] http://gruntjs.com/
* the resulting imsc.js and sax.js files at build/public_html/libs are, respectively, the
imscJS library and its sax-js dependency. Both are included in a web page using the following:
<script src="libs/sax.js"></script>
<script src="libs/imsc.js"></script>
See TESTS AND SAMPLES below for a list of samples available.
ARCHITECTURE
============
imscJS renders an IMSC1 document in three distinct steps:
* `fromXML(xmlstring, errorHandler)` 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 (`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)` 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 IMSC1 displayForcedOnlyMode parameter.
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`.
See inline documentation for additional documentation.
MODULES
=======
The imscJS codebase is arranged in the following modules (the token between parantheses is the global name
used if 'require' is not used to load modules):
* doc.js (imscDoc): parses an IMSC1 document into an in-memory TT object
* isd.js (imscISD): generates an ISD object from a TT object
* html.js (imscHTML): generates an HTML fragment from an ISD object
* names.js (imscNames): common constants
* styles.js (imscStyles): defines TTML styling attributes processing
* utils.js (imscUtils): common utility functions
TESTS AND SAMPLES
=================
W3C Test Suite
**************
imscJS imports the IMSC1 test suite [1] managed by the W3C as submodule at [2].
The gen-renders.html web app can be used to generate PNG renderings as as well intermediary files from these
tests. For regression testing, a copy of these intermediary files are committed at [3].
[1] https://github.com/w3c/imsc-tests
[2] src/test/resources/imsc-tests
[3] src/test/resources/generated
Unit tests
**********
Unit tests are located at [1] and run as a webapp [2] using QUnit [3].
[1] src/test/webapp/js/unit-tests.js
[2] src/test/webapp/unit_tests.html
[3] https://qunitjs.com/
IRT and W3C samples
*******************
Also included is the 'samples' webapp [1] that renders the samples listed at [2].
[1] src/test/webapp/samples.html
[2] src/test/resources/samples/samples.json
The samples.json provided with the distribution expects the following two directories to be added to [3]
* "irt" directory that contains the "ttml" and "png" directories at [4]. These are test vectors provided by the
Institut für Rundfunktechnik (IRT) [5].
* "ttml" directory that contains the directories at [6]. These are the formal TTML1 test vectors provided by the W3C.
Only tests that are compatible with IMSC1 are referenced.
[3] src/test/resources/samples/
[4] https://github.com/IRT-Open-Source/irt-ebu-tt-d-application-samples
[5] https://www.irt.de/en
[6] https://github.com/w3c/ttml1/tree/gh-pages/testsuite
NPM PACKAGE
===========
imscJS is released as an NPM package under the name "imsc".
NOTABLE DIRECTORIES AND FILES
=============================
/package.json NPM package definition
/Gruntfile.js Grunt build script
/properties.json General project properties
/README This file
/LICENSE License under which imscJS is made available
/src/main/js JavaScript modules
/src/test/resources Test files
/src/test/webapp Test web applications
/build Build output