WebAssembly.Exception constructor - WebAssembly

WebAssembly.Exception constructor
=================================

The **`WebAssembly.Exception()`** constructor is used to create a new `WebAssembly.Exception`.

 The constructor accepts a `Tag` argument and a `payload` array of data fields.
 The data types of each of the payload elements must match the corresponding data type specified in the `Tag`.

 The constructor may also take an `options` object.
 The `options.traceStack` property can be set `true` (by default it is `false`) to indicate that a Wasm stack trace may be attached to the exception's `stack` property.

Syntax
------

```js
new Exception(tag, payload)
new Exception(tag, payload, options)
```

### Parameters

`tag`

An `WebAssembly.Tag` defining the data types expected for each of the values in the `payload`.

`payload`

 An array of one or more data fields comprising the payload of the exception.
 The elements must match the data types of the corresponding elements in the `tag`.
 If the number of data fields in the payload and their types don't match, a `TypeError` exception is thrown.

`options` Optional
Non-standard

An object with the following optional fields:

`traceStack` Optional
Non-standard

`true` if the `Exception` may have a stack trace attached to its `stack` property, otherwise `false`.
 This is `false` by default (if `options` or `options.traceStack` are not provided).

### Exceptions

`TypeError`

The `payload` and `tag` sequences do not have the same number of elements and/or the elements are not of matching types.

Examples
--------

This example shows the creation of an exception using a simple tag.

```js
// Create tag and use it to create an exception
const tag = new WebAssembly.Tag({ parameters: ["i32", "f32"] });
const exception = new WebAssembly.Exception(tag, [42, 42.3]);
```

The `stack` example shows the creation of an exception that uses the `options` parameter.

Specifications
--------------

| Specification |
| --- |
| WebAssembly JavaScript Interface: Exception Handling # dom-exception-exception |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* WebAssembly overview
* WebAssembly concepts
* Using the WebAssembly JavaScript API


WebAssembly.Exception.prototype.getArg() - WebAssembly

WebAssembly.Exception.prototype.getArg()
========================================

The **`getArg()`** prototype method of the `Exception` object can be used to get the value of a specified item in the exception's data arguments.

 The method passes a `WebAssembly.Tag` and will only succeed if the thrown `Exception` was created using the same tag, otherwise it will throw a `TypeError`.
 This ensures that the exception can only be read if the calling code has access to the tag.
 Tags that are neither imported into or exported from the WebAssembly code are internal, and their associated `WebAssembly.Exception` cannot be queried using this method!

**Note:** It is not enough that the tag has an identical sequence of data types — it must have the same *identity* (be the same tag) as was used to create the exception.

Syntax
------

```js
getArg(exceptionTag, index)
```

### Parameters

`exceptionTag`

A `WebAssembly.Tag` that must match the tag associated with this exception.

`index`

The index of the value in the data arguments to return, 0-indexed.

### Return value

The value of the argument at `index`.

### Exceptions

`TypeError`

The tags don't match; the exception was not created with the tag passed to the method.

`RangeError`

The value of the `index` parameter is greater than or equal to the number of fields in the data.

Examples
--------

 In order to get the values of an exception, the tag must be "known" to the calling code;
 it may be either imported into or exported from the calling code.

### Getting exception value from imported tag

 Consider the following WebAssembly code, which is assumed to be compiled to a file "example.wasm".
 This imports a tag, which it refers to internally as `$tagname`, and exports a method `run` that can be called by external code to throw an exception using the tag.

```wasm
(module
  ;; import tag that will be referred to here as $tagname
  (import "extmod" "exttag" (tag $tagname (param i32)))

  ;; $throwException function throws i32 param as a $tagname exception
  (func $throwException (param i32)
    local.get 0
    throw $tagname
  )

  ;; Exported function "run" that calls $throwException
  (func (export "run")
    i32.const 1
    call $throwException
  )
)
```

 The code below calls `WebAssembly.instantiateStreaming` to import the "example.wasm" file, passing in an "import object" (`importObject`) that includes a new `WebAssembly.Tag` named `tagToImport`.
 The import object defines an object with properties that match the `import` statement in the WebAssembly code.

Once the file is instantiated, the code calls the exported WebAssembly `run()` method, which will immediately throw an exception.

```js
const tagToImport = new WebAssembly.Tag({ parameters: ["i32"] });

// Note: the import object properties match the import statement in WebAssembly code!
const importObject = {
  extmod: {
    exttag: tagToImport,
  },
};

WebAssembly.instantiateStreaming(fetch("example.wasm"), importObject)
  .then((obj) => {
    console.log(obj.instance.exports.run());
  })
  .catch((e) => {
    console.error(e);
    console.log(`getArg 0 : ${e.getArg(tagToImport, 0)}`);
  });

/\* Log output
example.js:40 WebAssembly.Exception: wasm exception
example.js:41 getArg 0 : 1
\*/
```

 The code catches the exception and uses `getArg()` to print the value at the first index.
 In this case, it is just "1".

### Getting exception value from an exported tag

 The process for using an exported tag is very similar to that shown in the previous section.
 Here is the same WebAssembly module, simply replacing the import with an export.

```wasm
(module
  ;; Export tag giving it external name: "exptag"
  (tag $tagname (export "exptag") (param i32))

  (func $throwException (param i32)
    local.get 0
    throw $tagname
  )

  (func (export "run")
    i32.const 1
    call $throwException
  )
)
```

 The JavaScript is similar too. In this case, we have no imports, but instead we get the exported tag and use that to get the argument.
 To make it a little more "safe", here we also test that we have the right tag using the `is()` method.

```js
let tagExportedFromWasm;

WebAssembly.instantiateStreaming(fetch("example.wasm"))
  .then((obj) => {
    // Import the tag using its name from the WebAssembly module
    tagExportedFromWasm = obj.instance.exports.exptag;
    console.log(obj.instance.exports.run());
  })
  .catch((e) => {
    console.error(e);
    // If the tag is correct, get the value
    if (e.is(tagExportedFromWasm)) {
      console.log(`getArg 0 : ${e.getArg(tagExportedFromWasm, 0)}`);
    }
  });
```

Specifications
--------------

| Specification |
| --- |
| WebAssembly JavaScript Interface: Exception Handling # dom-exception-getarg |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* WebAssembly overview page
* WebAssembly concepts
* Using the WebAssembly JavaScript API


IMSC: subtitles and captioning for the Web - Web-related technologies

IMSC: subtitles and captioning for the Web
==========================================

IMSC (TTML Profiles for Internet Media Subtitles and Captions) is a file format for representing subtitles and captions. It uses XML to describe content, timing, layout, and styling. IMSC is very similar to HTML and CSS in concept — in fact, most IMSC styles have a direct equivalent in CSS.

Concepts and usage
------------------

IMSC is standardized by the W3C, and used around the world by content producers (e.g. 20th Century Fox), online services (e.g. Netflix), and traditional broadcasters (e.g. the BBC). Many platforms and players support it, e.g. iOS devices and the dashJS player.

IMSC supports a wide range of world languages and scripts, and rich styling. In addition to text-based subtitles, IMSC also supports PNG subtitles.

Each IMSC document is self-contained and combines content, timing, layout and styling information. The content of the document is structured using tags similar to those used in HTML such as `<body>`, `<div>`, `<p>`, `<span>`, and `<br>`. Timing and styling are expressed using attributes such as `begin`, `end`, `color`, `tts:backgroundColor`, `tts:fontSize`, `tts:fontFamily` — these are mostly familiar concepts to anyone familiar with CSS.

### Differences between IMSC, HTML, and CSS

IMSC differs from HTML in a number of ways:

* IMSC uses namespaces, so that `tts:fontSize` is not the same as `fontSize`, and namespace declarations are required, like
 `<tt xmlns="http://www.w3.org/ns/ttml" xmlns:tts="http://www.w3.org/ns/ttml#styling" …>`
* IMSC has stricter rules, for instance `<p>` elements can only be present within `<div>` elements, and cannot be direct children of `<body>` elements.

While attributes names and syntax are similar, styling differs from CSS in a couple of ways:

* Whereas CSS properties use hyphens, like `font-size`, IMSC uses camel case, like `tts:fontSize`.
* IMSC does not use external stylesheets.
### Differences between IMSC and WebVTT

IMSC is unrelated to WebVTT, which is another way of making subtitles and captions for the Web.

WebVTT is supported natively to some extent by browsers, while IMSC is not.

There is however an IMSC polyfill, called imscJS, which is used to render all the examples in this documentation. From a developer's perspective, imscJS allows a consistent experience across browsers.

IMSC also supports styles, like `tts:linePadding` and `tts:fillLineGap`, and features, such as support for HDR and stereoscopic 3D, that are useful for subtitle and captions, but not available in WebVTT.

Below is an example that uses `tts:fillLineGap`:

```xml
<tt xmlns="http://www.w3.org/ns/ttml"
 xmlns:tts="http://www.w3.org/ns/ttml#styling"
 xmlns:itts="http://www.w3.org/ns/ttml/profile/imsc1#styling"
 xml:lang="en">
    <head>
      <styling>
       <style xml:id="defaultStyle"
 tts:fontSize="125%"
 tts:lineHeight="120%"/>
       <style xml:id="spanStyle"
 tts:backgroundColor="black"
 tts:color="white"/>
       <style xml:id="fillGap"
 itts:fillLineGap="true"/>
      </styling>
     <layout>
     <region xml:id="top"
 tts:origin="5% 5%"
 tts:extent="90% 40%"
 tts:textAlign="center"
 tts:displayAlign="before"/>
     <region xml:id="bottom"
 tts:origin="5% 55%"
 tts:extent="90% 40%"
 tts:textAlign="center"
 tts:displayAlign="after"/>
    </layout>
  </head>
 <body style="defaultStyle">
  <div>
    <p region="top">
      <span style="spanStyle">Without itts:fillLineGap<br/>
      Gaps between lines appear.</span>
    </p>
    <p region="bottom" style="fillGap">
      <span style="spanStyle">With itts:fillLineGap<br/>
      Gaps between lines are "filled".<br/></span>
    </p>
    </div>
 </body>
</tt>
```

… and an example that uses `ebutts:linePadding`:

Last but not least, IMSC is compatible with SMPTE-TT and EBU-TT-D, which are widely used in the USA and in Europe. IMSC is also actively used in the authoring of TV and movie content. Implementing IMSC support therefore removes the need for conversion to WebVTT.

In contrast to IMSC, which uses markup, WebVTT uses a combination of CSS and plaintext.

Tutorials
---------

IMSC basics

This takes you through what you need to get started with IMSC, including basic document structure, and the basics of how to style, time, and position subtitles. These topics will be expanded on later in their own tutorials.

Using the imscJS polyfill

You currently need a polyfill to render IMSC on the web. imscJS is a good choice as it is actively maintained and has almost complete coverage of the IMSC features. This article hows you how to make use of imscJS and how to integrate it on your own website.

Styling IMSC documents

IMSC offers many options for styling documents, and most of the IMSC styling properties have direct CSS equivalents, making them familiar to web developers. In this guide you'll learn a bit more about IMSC styling including the difference between inline and referential styling, and efficient styling using inheritance and region styling.

Subtitle placement in IMSC

IMSC allows the author to precisely control the position of subtitles, such that the text is positioned next to the speaker or to avoid obscuring an important content in your video. Learn how to define a subtitle region and how to define its width and height.

Namespaces in IMSC

This article covers the subject of XML namespaces, giving you enough information to recognize their usage in IMSC, and be able to use it effectively.

Timing in IMSC

When building an IMSC document, each defined piece of text must include timing information to specify when it should appear. There are multiple ways to describe when a subtitle should start and stop displaying, with pros and cons to each method.

Mapping video time codes to IMSC

Mapping the time or time code value that is seen within a video track or video editor timeline to an IMSC document can be a little tricky. There are a few different issues that you'll need to be aware of, which we'll cover in this article.

IMSC and other standards

IMSC is the result of an international effort to bring together popular profiles of TTML, like EBU-TT-D and SMPTE-TT. This article provides an overview how IMSC is related to these other subtitle standards, and explains the differences between the versions of IMSC.

Reference
---------

* TTML Profiles for Internet Media Subtitles and Captions
Tools
-----

imscJS polyfill

IMSC documents can be rendered in browsers using the imscJS polyfill.

dash.js

The reference player of the DASH Industry Forum with IMSC support.

Specifications
--------------

* TTML Profiles for Internet Media Subtitles and Captions 1.2
Browser compatibility
---------------------

IMSC does not have native support in browsers at this current moment, but it can be used to effectively render timed text in web documents via the imscJS polyfill.

See also
--------

Timed Text Working Group

The IMSC standard is developed by the W3C Timed Text Group, which you are encouraged to join if you wish to contribute directly to the standard.

IMSC standards repository

At the IMSC GitHub repository you can provide feedback on the specifications and file issues

Web Video Text Tracks Format (WebVTT)

WebVTT is another mechanism for implementing captions and subtitles on the web, which has some native support in browsers and some useful features.

Docs project team
-----------------

Team:

* Dave Kneeland
* Pierre-Anthony Lemieux
* Andreas Tai

If you want to get involved with documenting IMSC, please contact Andreas Tai.


Namespaces in IMSC - Web-related technologies

Namespaces in IMSC
==================

This article covers the subject of XML namespaces, giving you enough information to recognize their usage in IMSC, and be able to use it effectively.

What are XML namespaces?
------------------------

Namespaces are basically the mechanism that you use in XML to differentiate different families of markup (which may have features with the same name), and allow them to be used in the same document.

To help you understand what we mean by this, let's use a real-world example — human family names. There are many people in the world called Mary. One way to tell them apart is by their full names — there can be a Mary Smith and a Mary Jones.

In XML you can also give elements and attributes a "family name", which is their namespace. Namespaces define what family an XML vocabulary belongs to, and generally consist of an identifying string of characters. The `<p>` element is available in both HTML and IMSC, so perhaps you could use the namespace `html` to specify HTML's `<p>`, and `imsc` to specify IMSC's `<p>`?

As with many things, it's not that simple. There might be another XML vocabulary named IMSC and it may not be related to subtitles. This is the same with Mary Smith — There are many Mary Smiths in the world, so more information is needed to tell them apart — their birthdays, hair color, address, etc.

So normally you use longer strings as namespace names. A URL is a very popular form of namespace. It is easy to remember and can also point to further information about that XML vocabulary.

* The W3C standard IMSC uses the URL `http://www.w3.org/ns/ttml` as the namespace for the `<p>` element.
* For the `<p>` in HTML the namespace is `http://www.w3.org/1999/xhtml`.

If you use the namespace `http://www.w3.org/ns/ttml` it is quite safe to assume that you are referring to elements from the IMSC vocabulary.

Setting namespaces in documents
-------------------------------

So how do you express in an IMSC document that the `<p>` element belongs to the namespace `http://www.w3.org/ns/ttml`? You need to include the namespace in the document. The simple way to do this could be to include it in each element and attribute that comes from that namespace. You set the namespace of an element by specifying the namespace identifier inside its `xmlns` attribute:

```xml
<tt xmlns="http://www.w3.org/ns/ttml" xml:lang="en">
  <body xmlns="http://www.w3.org/ns/ttml">
    <div xmlns="http://www.w3.org/ns/ttml">
      <p xmlns="http://www.w3.org/ns/ttml">Hello world</p>
    </div>
  </body>
</tt>
```

But this is not very efficient. Imagine a document with hundreds of subtitles. This would be very verbose.

### Default namespaces

Fortunately, you don't need to do the above — instead you can just use a default namespace. If you set the attribute `xmlns` on the document's root element to the value `http://www.w3.org/ns/ttml`, all elements nested inside the root will inherit this namespace — they will all have that namespace too.

```xml
<tt xmlns="http://www.w3.org/ns/ttml" xml:lang="en">
  <body>
    <div>
      <p>Hello world</p>
    </div>
  </body>
</tt>
```

In this example the elements `<tt>`, `<body>`, `<div>` and `<p>` have all the namespace `http://www.w3.org/ns/ttml`.

Because nearly all XML elements you need in an IMSC document are in the namespace `http://www.w3.org/ns/ttml`, this makes life a lot easier. If you want to use an element from another vocabulary inside an IMSC document, you can still overwrite the default namespace.

```xml
<tt xmlns="http://www.w3.org/ns/ttml" xml:lang="en">
  <head>
   <metadata>
     <documentPublisher xmlns="urn:ebu:tt:metadata">MDN</documentPublisher>
   </metadata>
  </head>
  <body>
    <div>
      <p>Hello world</p>
    </div>
  </body>
</tt>
```

The element `<documentPublisher>` comes from the EBU Part M metadata vocabulary. The elements in this vocabulary have the namespace `urn:ebu:tt:metadata`. By setting the `xmlns` attribute on the element `<documentPublisher>` to `urn:ebu:tt:metadata`, the namespace `http://www.w3.org/ns/ttml` gets overwritten. Now the `<documentPublisher>` element and all its descendants have the namespace `urn:ebu:tt:metadata`.

A better way to overwrite a default namespace is by using prefixes.

```xml
<tt xmlns="http://www.w3.org/ns/ttml" xml:lang="en"
 xmlns:ebuttm="urn:ebu:tt:metadata">
  <head>
   <metadata>
     <ebuttm:documentPublisher>MDN</ebuttm:documentPublisher>
   </metadata>
  </head>
  <body>
    <div>
      <p>Hello world</p>
    </div>
  </body>
</tt>
```

We explain in the following section how XML namespace prefixes work.

Namespaced attributes
---------------------

We've looked at elements, but how can we specify the namespace of IMSC attributes, and without being too verbose? Contrary to XML elements there is no default namespace for attributes.

In addition, IMSC attributes are contained in more than one namespace. Let's explain further — in IMSC there are different categories of attributes, styling attributes for example. The different categories have different namespaces. For example, all styling attributes have the namespace `http://www.w3.org/ns/ttml#styling`.

As for XML elements, it would be too verbose to always write the complete namespace for each attribute, e.g. `color_http://www.w3.org/ns/ttml#styling="yellow"`.

Luckily XML has the concept of prefixes. A prefix can be thought of as a "shortcut" for a namespace. For example, we can define an attribute namespace on the root element:

```xml
<tt xmlns="http://www.w3.org/ns/ttml" xml:lang="en"
 xmlns:tts="http://www.w3.org/ns/ttml#styling"/>
```

By defining `xmlns:tts="http://www.w3.org/ns/ttml#styling` on the `<tt>` element you "bind" the prefix `tts` to the styling namespace. Subsequently, whenever you prefix an attribute (or element) with `tts` (plus a colon) it is given the namespace `http://www.w3.org/ns/ttml#styling`. This way you can write the prefix throughout your document, not the whole namespace each time.

```xml
<tt xmlns="http://www.w3.org/ns/ttml" xml:lang="en"
 xmlns:tts="http://www.w3.org/ns/ttml#styling" >
  <body>
    <div>
      <p tts:color="yellow" tts:fontSize="120%">
        Hello world
      </p>
     <p tts:color="white" tts:fontSize="120%">
        Hi!
     </p>
    </div>
  </body>
</tt>
```

Much more readable, isn't it?

**Note:** The namespace/prefix match is only a document-wide agreement. Theoretically you can use another prefix than `tts` to bind the styling namespace. It is completely legal to define `xmlns:foo="http://www.w3.org/ns/ttml#styling"` and then write `<p foo:color="yellow">`. But it makes your IMSC document much more readable if you use the official prefixes listed in namespace section of the IMSC standard.


IMSC basics - Web-related technologies

IMSC basics
===========

IMSC allows you to add subtitles or captions to your online video. In this article we'll take you through what you need to get started, including basic document structure, and the basics of how to style, time, and position subtitles.

**Note:** IMSC can be used for any kind of timed text you might want to include on a web document, not just for subtitles and captions. But because subtitles and captions represent the most common use cases for IMSC, we will focus on those. For readability we only use the term subtitles. In the technical context we describe, the term "subtitles" is interchangeable with "captions".

So what is IMSC?
----------------

IMSC is a markup language you can use to define timed text for adding subtitles to digital media. It defines the structure of your subtitle content in an XML document. It consists of a series of elements, which you can use to enclose, or wrap, different parts of your subtitle content to make it appear in a certain way or appear at a certain time. Many of these are similar or the same as HTML features.

If you are not already familiar with XML or HTML, read up on them first and then come back here:

* XML Introduction
* HTML Basics

**Note:** If you want to know what you can do with IMSC in real-world scenarios have a look at the expanded example at the end of this tutorial.

Minimal IMSC document
---------------------

IMSC is always specified as a complete XML document. As a file it should have the extension "*ttml*".

**Note:** IMSC does not have native support in browsers at this current moment, but the imscJS polyfill can be used to bridge this gap. All the examples below are rendered by using imscJS. It creates dynamically HTML and CSS from an IMSC XML document.

Let's look at a minimal IMSC document and how it is rendered:

The most important features are as follows:

* `<tt></tt>` — You always start an IMSC document with the root element `<tt>`. You should also specify the default namespace of the document by using the `xmlns` attribute. Don't worry for now about namespaces. We will come to that in a separate guide.
* `xml:lang` — You must specify the language of your content with the `xml:lang` attribute. Note that the `lang` attribute must have the prefix `xml:`, unlike HTML. In IMSC `<tt lang="en">` is not correct — you always have to write `<tt xml:lang="en">`.
* `<body></body>` — As in HTML, the `<body>` element contains all content that you want to show. For IMSC this is typically subtitle content that you want to show at certain time intervals during the playback of a video.
* `<div></div>` — The `<div>` element is used as a container for subtitle content; you always need to have at least one of these. The `<p>` elements that contain the actual subtitle content always have a `<div>` element as their parent.
* `<p></p>` — Text content for subtitles must always be wrapped in a `<p>` element. The element describes a paragraph of text, in a similar fashion to HTML. The main difference is that it can be timed.
Timing
------

The minimal IMSC document from the previous example had no timing. That means that the subtitle content will be shown during the complete duration of the video. Usually this is not what you want. Instead you want subtitles to show up at a certain time and then disappear. You can use a combination of the timing attributes `begin`, `end`, and `dur` to make this happen.

Consider the following editable example:

This includes the following new attributes:

* `begin` — specifies when the subtitle shall start to show (in this case 1s after the video started).
* `end` — specifies when the subtitle shall disappear (in this case 2s after the video started).

Play around with the second values in the code sample and push the reload button when you are ready.

**Note:** The end times in IMSC are not "inclusive". The subtitle "Hello, I am Mork from Ork." is not shown anymore when it reaches the second value in time.

You can also use the `dur` attribute for timing:

This attribute can be used as an alternative to the `end` attribute. It defines "how long" the subtitle is shown after the `begin` time has elapsed. In the example the second paragraph shall be displayed for 2s. As it starts at second 2 it shall disappear at second 4.

Note what has changed at second 2 compared to the previous example.

Colors
------

Often subtitles are shown on an opaque or semi-opaque background to improve readability. You can use the `backgroundColor` and `color` attributes to change the colors, as demonstrated in this editable example:

Here we've introduced the following:

* `tts:backgroundColor` — This attribute sets the background color on the element it is applied to. In this case it is applied to the `<p>` element, or more correctly to the area that is generated by the `<p>`
 element. The default background color is `transparent`.
* `tts:color` — This attribute sets the text color on the element it is applied to. The default text color is `white`.

Try setting some other colors for the text and background colors:

* Try other named colors like `lime` or `aqua`.
* Use hexadecimal values like `#00ff00` or `#00ffff`.
* You can use other color schemes like `rgb(0 255 255)`.
* Finally, try semi-transparent variations, like `rgb(0 0 0 / 80%)`.

**Note:** Don't worry for now about namespaces. We will explain the meaning of `xmlns:tts` and `tts:backgroundColor` in a separate guide.

As explained in the IMSC Styling guide, it is possible to define a collection of styling properties that can be used any number of times. The style `s1` below is applied three times:

```xml
<tt xmlns="http://www.w3.org/ns/ttml"
 xmlns:tts="http://www.w3.org/ns/ttml#styling"
 xml:lang="en">
  <head>
   <styling>
     <style xml:id="s1" tts:color="yellow" tts:fontStyle="italic"/>
   </styling>
  </head>
  <body>
    <div>
      <p>
        Hello, I am <span style="s1">Mork</span> from <span style="s1">Ork</span>.<br/>
        I come from another <span style="s1">planet</span>.
      </p>
    </div>
  </body>
  </tt>
```

Position, width, and length
---------------------------

If you do not specify a position explicitly, the subtitle shows up by default in the top-left-hand corner of the video. Commonly however you will want to position your subtitle somewhere else, like the bottom center of the video. You need to specify a region to position a subtitle.

See below for a minimal document that uses regions for positioning.

```xml
<tt xmlns="http://www.w3.org/ns/ttml"
 xmlns:tts="http://www.w3.org/ns/ttml#styling"
 xml:lang="en">
  <head>
    <layout>
      <region tts:origin="10% 80%"
 tts:extent="80% 20%"
 xml:id="bottom"/>
      <region tts:origin="10% 10%"
 tts:extent="80% 20%"
 xml:id="top"/>
    </layout>
</head>
<body>
    <div>
      <p region="bottom"
 tts:backgroundColor="black">
          Hello, I am Mork from Ork.
      </p>
    </div>
  </body>
</tt>
```

This includes the following new features:

* `<head></head>` — As in HTML, the `<head>` element acts as a container for all the stuff you want to include in an IMSC document that isn't subtitle content, most commonly metadata about the content or document. You'll use it mostly to store positioning and styling information.
* `<layout></layout>` — This element acts as a wrapper for positioning information. It has `<region>` elements as its children.
* `<region></region>` — this element can be used to define `region`s, rectangular areas you can place on top of your video. They have a defined position, width, and height, plus an `id` to uniquely identify them. You can think of it as being similar to a `<div>` element in HTML that is given an absolute position, width, and height via CSS. If subtitle content is "linked" to a region (by specifying the region's `id` in its `region` attribute), it will be shown inside the area generated by that region.
* `xml:id` - the `xml:id` attribute. The value of the `xml:id` attribute is a string that can be used to link subtitle content to a `region`.
* `tts:origin` — This attribute defines the position of the top-left corner of the region. It uses the % (percentage) metric. The first value defines how far the top left corner of the region is pushed to the right — in this case the value `10%` places the region 10% of the video's width to the right. The second value defines how far the top left corner of the region is placed towards the bottom of the video — in this case the value `80%` pushes the top left corner of the region 80% of the video's height towards the bottom of the video.
* `tts:extent` — This attribute defines the width and height of the region. In this case `80%` sets the width to 80% of the video's width, and `20%` sets the height of the region to 20% of the video's height.
* `region` — setting this on some subtitle content and then giving it a region's `xml:id` as its value causes it to *reference* that region, meaning that at the specified time, it will appear in the area defined by that region. So here, the value `bottom` places the subtitle content represented by this `<p>` element in the region with an `xml:id` of `bottom`.

This sample will be rendered as shown below. Give it a try and play around with the code in the two boxes. You could for example set the `tts:origin` attribute to "*0% 0%*". Or see what happens when you change the value of the `region` attribute of the `<p>` element to "*top*".

Expanded example
----------------

The more expanded example below gives you an idea what you can do with IMSC after you worked through our tutorials.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<tt
 xmlns="http://www.w3.org/ns/ttml" xmlns:tts="http://www.w3.org/ns/ttml#styling"
 xmlns:ttp="http://www.w3.org/ns/ttml#parameter" xml:lang="en" ttp:timeBase="media">
  <head>
    <styling>
      <style xml:id="defaultStyle" tts:fontFamily="Verdana, Arial" tts:fontSize="100%"
 tts:textAlign="center"/>
      <style xml:id="alignStart" tts:textAlign="start"/>
      <style xml:id="alignCenter" tts:textAlign="center"/>
      <style xml:id="alignEnd" tts:textAlign="end"/>
      <style xml:id="textWhite" tts:color="#FFFFFF"/>
      <style xml:id="titleHeading" tts:fontSize="300%"/>
      <style xml:id="spanDefaultStyle" tts:backgroundColor="#000000" tts:color="#FFFFFF"/>
      <style xml:id="monoFont" tts:fontFamily="Lucida Console, Monaco, monospace"/>
      <style xml:id="sansserifFont" tts:fontFamily="Impact, Charcoal, sans-serif"/>
      <style xml:id="comicFont" tts:fontFamily="Comic Sans MS, cursive, sans-serif"/>
      <style xml:id="blueText" tts:color="#00FFFF" tts:backgroundColor="#000000"/>
      <style xml:id="limeText" tts:color="#00FF00" tts:backgroundColor="#000000"/>
      <style xml:id="fuchsiaText" tts:color="#FF00FF" tts:backgroundColor="#000000"/>
      <style xml:id="yellowText" tts:color="#FFFF00" tts:backgroundColor="#000000"/>
    </styling>
    <layout>
      <region xml:id="rTop" tts:origin="10% 10%" tts:extent="80% 80%" tts:displayAlign="before"/>
      <region xml:id="rCenter" tts:origin="10% 10%" tts:extent="80% 80%" tts:displayAlign="center"/>
      <region xml:id="rBottom" tts:origin="10% 10%" tts:extent="80% 80%" tts:displayAlign="after"/>
    </layout>
  </head>
  <body style="defaultStyle">
    <div>
      <p xml:id="p1" begin="00:00:01" end="00:00:03" region="rCenter" style="alignCenter">
        <span style="titleHeading">IMSC Demo</span>
      </p>
      <p xml:id="p2" begin="00:00:03" end="00:00:05" region="rBottom" style="alignCenter">
        <span style="spanDefaultStyle">You </span><span style="blueText">can</span><span
 style="yellowText"> apply</span><span style="fuchsiaText"> different</span><span
 style="limeText"> colors, </span>
      </p>
      <p xml:id="p3" begin="00:00:05" end="00:00:07" region="rBottom" style="alignCenter">
        <span style="monoFont">use</span><span style="sansserifFont"> different</span><span
 style="comicFont"> fonts,</span>
      </p>
      <p xml:id="p4" begin="00:00:07" end="00:00:09" region="rBottom" style="alignCenter">
        <span>set </span><span tts:fontSize="150%">the</span><span tts:fontSize="200%"> font
          size.</span>
      </p>
      <p xml:id="p5" begin="00:00:09" end="00:00:11" region="rBottom" style="alignStart">
        <span style="spanDefaultStyle">Align at the start, </span><br/>
      </p>
      <p xml:id="p6" begin="00:00:11" end="00:00:13" region="rBottom" style="alignCenter">
        <span style="spanDefaultStyle">center and</span>
      </p>
      <p xml:id="p7" begin="00:00:13" end="00:00:15" region="rBottom" style="alignEnd">
        <span style="spanDefaultStyle">end</span><br/>
      </p>
      <p xml:id="p8" begin="00:00:15" end="00:00:17" region="rTop" style="alignCenter">
        <span style="spanDefaultStyle">or vertically at the top, </span><br/>
      </p>
      <p xml:id="p9" begin="00:00:17" end="00:00:19" region="rCenter" style="alignCenter">
        <span style="spanDefaultStyle">center and </span>
      </p>
      <p xml:id="p10" begin="00:00:19" end="00:00:21" region="rBottom" style="alignCenter">
        <span style="spanDefaultStyle">bottom.</span>
      </p>
    </div>
  </body>
</tt>
```

Summary
-------

That's it for your crash course in IMSC code basics! We've only really scratched the surface here, and you'll go much deeper into the above topics in subsequent articles.


Styling IMSC documents - Web-related technologies

Styling IMSC documents
======================

IMSC offers many options for styling documents, and most of the IMSC styling properties have direct CSS equivalents, making them familiar to web developers. In this guide you'll learn a bit more about IMSC styling including the difference between inline and referential styling, and efficient styling using inheritance and region styling.

Inline styling
--------------

The simplest way of styling content elements like `<p>` or `<span>` is by specifying one or more style attributes, such as `tts:color`, on them. For instance, the following

```xml
<p tts:textAlign="center"
 tts:fontSize="64px"
 tts:color="red"
 tts:fontFamily="proportionalSansSerif"
 tts:fontStyle="italic">
 Hello, I am Mork from Ork
</p>
```

yields:

Referential styling
-------------------

Inline styling is usually avoided since it generates duplication.

Take for example the following two `<span>` elements, which have exactly the same style attributes:

```xml
<p>
  <span tts:color="yellow" tts:backgroundColor="black">
   Hello, I am Mork from Ork.
  </span>
</p>
<p>
  <span tts:color="yellow" tts:backgroundColor="black">
    I come from another planet.
  </span>
</p>
```

In referential styling, styles are defined once and reused throughout the document — in a similar way to how CSS rules can be declared once and then applied to multiple HTML elements via for example, element or class selectors. In IMSC this is achieved by defining a `<styling>` element inside the document `<head>`, inside which is placed one or more `<style>` elements — each one of which defines a set of styles that you can reuse elsewhere. This is illustrated below:

```xml
<tt xmlns="http://www.w3.org/ns/ttml"
 xmlns:tts="http://www.w3.org/ns/ttml#styling"
 xml:lang="en">
  <head>
   <styling>
     <style xml:id="s1" tts:color="yellow" tts:backgroundColor="black"/>
   </styling>
  </head>
  <body>
    <div>
      <p>
        <span style="s1">Hello, I am Mork from Ork.</span>
      </p>
      <p>
        <span style="s1">I come from another planet.</span>
      </p>
    </div>
  </body>
  </tt>
```

Each `<style>` element is given an `id` (`"s1"` in this example):

```xml
<style xml:id="s1" tts:color="yellow" tts:backgroundColor="black"/>
```

which can then be referred to later in the document:

```xml
<span style="s1">Hello, I am Mork from Ork.</span>
```

this is equivalent to:

```xml
<span tts:color="yellow" tts:backgroundColor="black">
  Hello, I am Mork from Ork
</span>
```

In other words, referencing a `<style>` element via its `id` and the `style` attribute is equivalent to copying the style properties of the `<style>` element onto the referencing element, as if the style properties had been specified using inline styling.

Style inheritance
-----------------

If a style property is inheritable, like `tts:color`, then the style property will apply to all the descendants of an element it is specified on — again, this is similar to CSS and HTML. In the following example, the color `"yellow"` is applied to the text of both `<p>` elements because they are descendants of the `<body>` element.

```xml
<body tts:color="yellow">
  <div>
    <p>Hello, I am Mork from Ork.</p>
    <p>I come from another planet.</p>
  </div>
</body>
```

Specifying a style on an element overrides any style specified on an ancestor, for example in the following snippet, the color of the second `<p>`'s text would be set to `"aqua"`:

```xml
<body tts:color="yellow">
  <div>
     <p>Hello, I am Mork from Ork.</p>
     <p tts:color="aqua">I come from another planet.</p>
  </div>
</body>
```

Region styling
--------------

Region styling plays a special role in IMSC since a style property specified on a region is inherited by all elements that are selected to the region, starting with the `<body>` element, as if the `<region>` element was the parent of the `<body>` element. For example, in the following example, the text "Hello, I am Mork from Ork" will appear in yellow.

```xml
<tt
 xmlns="http://www.w3.org/ns/ttml"
 xmlns:tts="http://www.w3.org/ns/ttml#styling"
 xml:lang="en">
  <head>
    <layout>
      <region xml:id="r1" tts:color="yellow" />
    </layout>
 </head>
 <body>
   <div>
     <p region="r1">Hello, I am Mork from Ork</p>
   </div>
 </body>
</tt>
```

Combining styles
----------------

Referential styling can be applied to style elements themselves:

```xml
<styling>
  <style xml:id="s1"
 tts:color="yellow"
 tts:backgroundColor="black"/>
  <style xml:id="s2"
 style="s1"
 tts:textAlign="left"/>
</styling>
```

Multiple styles can be also applied simultaneously on an element. For example, in the snippet below the style properties of both styles `s1` and `s2` are applied to the same `<p>` element.

```xml
<p style="s1 s2">Hello, I am Mork from Ork</p>
```


Timing in IMSC - Web-related technologies

Timing in IMSC
==============

When building an IMSC document, each defined piece of text must include timing information to specify when it should appear. There are multiple ways to describe when a subtitle should start and stop displaying, with pros and cons to each method. This article explains those different methods.

If you have not already read the IMSC document with timing section in the IMSC basics article, you should do so now and then return here — it contains an initial overview of how to describe timing events.

Different ways to describe timing
---------------------------------

There are three primary ways of describing the time expression values within an IMSC document.

* Seconds.fraction: Specifying simple second values. This is the simplest approach to take; we've already seen this used earlier in the article series.
* HH:MM:SS.fraction: Specifying more complex times in the format `HH:MM:SS`. This is similar to only using Seconds, and is one of the most common time expressions in IMSC files.
* Frames: Specifying start and end times in terms of numbers of frames rather than seconds. This is the other most common time expression used in IMSC files. The advantage to this approach is that the frame number directly corresponds to the frame number in the video file.
### Seconds.fraction

```xml
<p begin="1s" end="2s">Hello, I am Mork from Ork</p>
```

This method for describing the `begin` and `end` values in the IMSC document is very simple — you just include a number with "s" (seconds) appended. It does not require the user to declare the frame rate of the corresponding media. These values must be mapped to the video frame that the text is synchronized with. Fractional values will always round up to the nearest video frame.

### HH:MM:SS.fraction

```xml
<p begin="00:00:01.00" end="00:00:02.00">Hello, I am Mork from Ork</p>
```

This method for describing the begin and end values in the IMSC document is essentially the same as using seconds, except for the fact that you are expressing those values as hours, minutes, and seconds. This allows you to easily set longer, more precise times.

### Frames

```xml
<tt xmlns="http://www.w3.org/ns/ttml"
 xml:lang="en"
 ttp:frameRate="24"
 ttp:frameRateMultiplier="1000 1001">
  <body>
    <div>
      <p begin="24f" end="48f">Hello, I am Mork from Ork</p>
    </div>
  </body>
</tt>
```

This method requires that the `frameRate` and `frameRateMultiplier` attributes are declared in the root element of the IMSC document. The frame rate describes how many frames are in one second of the video. The multiplier is applied to the `frameRate` to declare how that one second of video is compared with one realtime second.

Let's explain this in little bit more detail.

The `frameRateMultiplier` stems from the problems associated with non-integer frame rates such as 23.98fps (as opposed to an integer frame rate such as 24fps). 24fps means that every second of video has 24 frames in it, and that second is the same as a realtime second. 23.98fps means that every second of video has 24 frames in it, and that second is slightly longer than a realtime second. The `frameRateMultiplier` defines the duration of each frame when compared to realtime.

Imagine that you had a stopwatch and timed yourself watching a movie. If that movie was playing back at a speed of 24fps, once your media player says you have watched exactly 1 hour of it, your stopwatch would say 01:00:00.00. Now if that movie was playing back at a speed of 23.98fps, once your media player says you have watched exactly 1 hour of it, your stopwatch would now say 01:00:03.6 (1 hour × (24/23.98)).

Make sense?

To describe a frame rate of 23.976fps, the following `frameRate` and `frameRateMultiplier` values would be used:

```xml
<tt xmlns="http://www.w3.org/ns/ttml"
 xml:lang="en"
 ttp:frameRate="24"
 ttp:frameRateMultiplier="1000 1001">
```

This is actually saying that each second of 24 frames should play back at a speed of (24 \* (1000/1001)), or 23.98fps.

Now that a frame rate of 23.98 is declared, you are able to describe time expressions in frames, or f.

```xml
<p begin="24f" end="48f">Hello, I am Mork from Ork</p>
```

The advantage of using this method is that the time expression frame number is the same as the frame number of the media asset. A value of 86400f is frame number 86400 in the video file.

**Note:** You can find an additional explanation of these values in Mapping video time codes to IMSC.


Mapping video time codes to IMSC - Web-related technologies

Mapping video time codes to IMSC
================================

Mapping the time or time code value that is seen within a video track or video editor timeline to an IMSC document can be a little tricky. There are a few different issues that you'll need to be aware of, which we'll cover in this article.

Considering time code start times
---------------------------------

For the sake of simplicity, we will be assuming that the time code tracks within our video assets start at 00:00:00:00. By default, values within an IMSC document start at 0 and auto increment from there.

If the time code in a video track does not begin at 00:00:00:00, you will have to take the first timestamp in the video track and perform a calculation on that value and all following values so that the initial value is 00:00:00:00. For example, if the first time code value in the video track is 00:59:50:00, then you will have to subtract 00:59:50:00 from all time code values in the video track in order to synchronize it to the IMSC document.

Frame rates
-----------

Mapping an IMSC document to a video asset is quite straightforward when you are working with integer frame rates, such as 24fps, 25fps, and 30fps. The value in your timeline will be the same as the value in the IMSC document. When you are working with fractional frame rates (such as 23.976fps or 29.97fps) however, this gets a bit more complicated.

A frame rate actually describes both the number of frames per second, and the velocity of those frames:

* 25fps describes that there are 25 frames per second (0-24), and those frames play at the same speed as a real time clock.
* 24fps describes that there are 24 frames per second (0-23), and those frames play at the same speed as a real time clock.
* 23.976fps is where things get weird. Like 24fps, it describes that there are 24 frames per second (0-23). Unlike 24fps, however, those 24 frames play at a slightly slower speed than a real time clock. As the frame rate number (23.976fps) implies, in one real time second you almost see 24 frames. It actually takes 1.001 seconds for 24 frames playing back at 23.976fps to display.

In a single second this is not a big deal. As you extend to a few minutes, however, 24fps and 23.976fps will already be a few frames different from one other. As you extend to an hour, they will differ by 3.6s. Here's some math to illustrate this:

01:00:00:00 @ 24fps

3600 (seconds in 1 hour) \* 1.000 (velocity) = 3600 real time seconds

01:00:00:00 @ 23.976fps

3600 (seconds in 1 hour) \* 1.001 (velocity) = 3603.6 real time seconds

This is especially important to understand with IMSC files, since all of the timings in the document represent real time values. For example, if you want to describe an event that synchronizes with 23.976fps video that begins at 01:00:00:00 time code in the video, and ends 1 second later, it would look like this:

`<p begin="3603.6s" end="3604.6s">Hello, I am Mork from Ork</p>`

The important takeaway from this is that if you are synchronizing a video with a fractional frame rate to an IMSC document, the timings will not match. The timings in the IMSC document will slowly get further and further away from the video timings.

Mitigating the issue
--------------------

That said, there is actually a different approach to describing the time expression values in the IMSC file, which addresses this problem. As discussed in the Timing in IMSC guide, using a time expression syntax of frames will give you a 1:1 correlation of the frame number in the IMSC file and the frame number in the media asset.

The two attributes that must be included to use the frames method are `frameRate` and `frameRateMultiplier`. The frame rate describes how many frames are in one second, and the multiplier is applied to the `frameRate` to describe the actual frame rate in real time seconds. To describe a frame rate of 23.976fps, the following values would be used:

```xml
<tt ttp:frameRate="24" ttp:frameRateMultiplier="1000 1001">
  …
</tt>
```

This is saying that there are 24 frames in a second, and those are playing back at a speed of 23.976 frames per real time second (24 \* (1000 / 1001)).

By describing this actual frame rate, you are now able to describe time expressions in frames, or f. This is the actual frame number that the event begins and ends. Here is the same example as above, where the event begins at 01:00:00:00, and ends one second later.


IMSC and other standards - Web-related technologies

IMSC and other standards
========================

IMSC is the result of an international effort to bring together popular profiles of TTML, like EBU-TT-D and SMPTE-TT. This article provides an overview how IMSC is related to these other subtitle standards, and explains the differences between the versions of IMSC.

IMSC spec genealogy
-------------------

TTML Profiles for Internet Media Subtitles and Captions (or IMSC) is a constrained version of the Timed Text Markup Language for worldwide subtitles and captions family of specifications.

IMSC was designed to be a practical application of SMPTE-TT (SMPTE ST 2052-1), which is designated as a safe-harbor format by the FCC. As a result, most SMPTE-TT documents should render correctly using IMSC renderers (see the limitations), and the conversion guidelines from CTA 608/708 to SMPTE-TT (SMPTE RP 2052-10 and SMPTE RP 2052-11) are also applicable to IMSC.

IMSC is also a syntactic superset of both SDP-US and EBU-TT-D, such that documents that conform to either of these two formats are valid IMSC documents and can be rendered by IMSC renderers — see Compatibility with other TTML-based specifications for more details.

IMSC traces its origins to the CFF-TT format, and CFF-TT documents can be converted to IMSC relatively easily.

IMSC is unrelated to WebVTT, and does not use the same syntax. Basic conversion guidelines exist.

Active IMSC versions
--------------------

Two versions of IMSC are in use today:

* IMSC 1.0.1
* IMSC 1.1

IMSC 1.1 was designed such that valid IMSC 1.0.1 documents are valid IMSC 1.1 documents and will render as intended on an IMSC 1.1 renderer. It does however add important features on top of IMSC 1.0.1:

* Japanese text layout features such as ruby.
* Support for author-controlled luminance when compositing onto absolute luminance High-Dynamic Range video.
* Support for stereoscopic 3D.

**Note:** IMSC 1.1 also deprecates, but does not prohibit, a limited number features that have no practical use or for which better alternatives exist.

In summary, authors are encouraged to create IMSC 1.0.1 documents if possible and for maximal compatibility, and implementers are encouraged to implement support for IMSC 1.1 for worldwide coverage.

Summary
-------

This document gives you all you need to know about IMSC and its relationship with other specifications.


Using the imscJS polyfill - Web-related technologies

Using the imscJS polyfill
=========================

You currently need a polyfill to render IMSC on the web. imscJS is a good choice as it is actively maintained and has almost complete coverage of the IMSC features. This article shows you how to make use of imscJS and how to integrate it on your own website.

Introducing imscJS
------------------

imscJS is a JavaScript library for rendering IMSC documents to HTML. Below we will first go through a simple example how to use imscJS, then we'll look at a more complex example that actually renders subtitles on top of video at appropriate times. You can find the source code of the first sample on GitHub.

Embedding imscJS
----------------

First you need to embed the imscJS library:

```html
<script src="https://unpkg.com/imsc@1.1.0-beta.2/build/umd/imsc.all.min.js">
```

Once the imscJS library is loaded, it can be used to render an IMSC document in three distinct steps, explained in the below sections.

Parsing the IMSC document
-------------------------

First of all, the IMSC document is parsed into an immutable JavaScript object (`doc`, in our case):

```js
const doc = imsc.fromXML(source);
```

This step needs to happen only once for every IMSC document. The `doc` object has a single method, `getMediaTimeEvents()`, which returns an array of time offsets (in seconds) indicating where the visual representation of the IMSC document changes.

```js
const t = doc.getMediaTimeEvents();
```

Generating an IMSC snapshot
---------------------------

In the second step, a snapshot of the IMSC document at a particular point in time (`isd`) is created using `imsc.generateISD()`.

```js
const isd = imsc.generateISD(doc, t[1]);
```

This point in time does not have to be one of the values returned by `getMediaTimeEvents()`, but it usually is. In the example above, the snapshot is created at the second point in time that the IMSC document changes (`t[1]`). In a typical scenario, an application would, prior to media playback and for every offset returned by `getMediaTimeEvents()`, create a snapshot and schedule its presentation at the specified offset.

Rendering an IMSC snapshot
--------------------------

In the third and final step, a snapshot is rendered into an HTML `<div>` using `imsc.renderHTML()`:

```js
const vdiv = document.getElementById("render-div");
imsc.renderHTML(isd, vdiv);
```

Building an IMSC player
-----------------------

Lets look at a more expanded example and show you how can render subtitles with imscJS on an embedded HTML video. As an example we use the below video with subtitles.

You can find the HTML markup and the JavaScript source code on the MDN repository for IMSC samples.

Accessing the DOM
-----------------

An IMSC subtitle is rendered by HTML markup with inline CSS. It represents the IMSC subtitles during a specific period on the timeline of the associated media element. As we saw in the Rendering an IMSC snapshot section above, the markup is inserted into a `<div>` element using the `renderHtml()` method. We can think of this `<div>` element as a container for the HTML that was generated from IMSC code. Later we pass the corresponding DOM element as a parameter to `renderHtml()` method.

For convenience we assign this DOM element to a variable.

```js
const renderDiv = document.getElementById("render-div");
```

We use HTML cues associated with HTML text tracks to throw events whenever an IMSC subtitle should appear or disappear. In this example we use a `<track>` element that we declared in the HTML markup, but we could also create a text track on the fly and add it to the `<video>`.

```js
const myVideo = document.getElementById("imscVideo");
const myTrack = myVideo.textTracks[0];
```

We use the `src` attribute of the `<track>` element as a pointer to the IMSC document that contains our subtitle:

```js
const ttmlUrl = myVideo.getElementsByTagName("track")[0].src;
```

Retrieving the IMSC file
------------------------

The browser will not retrieve the document automatically for us. In most browsers only WebVTT is implemented at the moment. Therefore, these browsers expect that the value of the `src` attribute points to a WebVTT file. If it doesn't, they don't use it, and we also have no direct access to the file the `src` attribute is pointing to. We use the `src` attribute therefore just to store the URL of the IMSC file. We need to do the work to retrieve the file and read it into a JavaScript string. In the example we use the `fetch()` API for this task:

```js
const response = await fetch(ttmlUrl);
initTrack(await response.text());
```

Setting the text track mode
---------------------------

There is one more side effect. Because browsers get no valid WebVTT file from the `src` attribute, they disable the track. The `mode` property of the text track is set to the value `disable`.

But this is not what we want. In disabled mode a cue does not throw events on its start and end times. Because we need these events for rendering the IMSC subtitles we change the mode of the text track to `hidden`. In this mode the browser will throw the events of the cues but will not render the value of the cue text property.

```js
myTrack.mode = "hidden";
```

After we have set up everything, we can concentrate on implementing the IMSC subtitle rendering.

Generating "subtitle states"
----------------------------

Above we explained that we need to generate IMSC snapshots. In the following section we go a bit deeper into what that means and why this is necessary.

As we learned in Parsing the IMSC document, the first step is to parse the IMSC document into an imscJS object.

```js
const imscDoc = imsc.fromXML(text);
```

We want to use cues for rendering the IMSC subtitles. Each cue has properties representing its start time and end time. The browser engine fires events whenever the timeline of the media hits the start and the end time of a cue. We can register function calls for these events. We use them to render the HTML generated from imscJS and remove it again when required.

But the mapping of IMSC subtitles to start and end times of cues is not as straightforward as you may think. Of course, you could just use `<p>` elements with `begin` and `end` attributes. This would map perfectly to the cue interface with their `start` and `end` properties.

But take the following IMSC code:

```html
<p>
  <span begin="1s" end="3s">Hello</span> <span begin="2s" end="3s">world!</span>
</p>
```

This can be taken as an example of an "accumulating" subtitle, where word after word is added to a line. In some countries this is common practice for live captioning.

What happens is the following:

* At second 0 there is no subtitle.
* At second 1 the text "Hello" must appear.
* At second 2 the text "Hello" must still stay "on screen" but the text "world!" needs to be added. So, from second 2 to 3 we have a subtitle representing the text "Hello world!".

To map this into HTML we need at least two cues: one that represents the text "Hello" from second 1-2 and the other representing the text "Hello world!" from second 2-3.

But this is a simplified easy scenario. Imagine that you have 5 more words accumulating. They may have all the same end time but different start times. Or imagine you have a subtitle in a different location (e.g. representing a different speaker). This subtitle is shown in parallel to the other subtitle but the accumulating words may have different start times and therefore different intervals.

Luckily in IMSC and imscJS this scenario is quite easy to cover, because IMSC has a mechanism of stateless subtitle rendering.

Let's have a closer look what that means.

In our HTML/CSS implementation we can think of IMSC subtitles as a rendering layer that is put on top of the video. At each point in time on the media timeline the rendering layer has one specific state. For these "states" IMSC has a conceptual model, the "intermediate synchronous document format", which represents what is eventually rendered in that layer. Each time the rendering needs to change, a new representation is created. What is created is called an **Intermediate Synchronous Document** or **ISD**. This ISD has no dependency on the ISD's that come before or after. It is completely stateless and has all information needed to render the subtitle.

So how can we get the times when the ISD changes?

This is easy: we just call the `getMediaTimeEvents()` method on the imscJS document object (see also Parsing the IMSC document):

```js
const timeEvents = imscDoc.getMediaTimeEvents(); // timeEvents = [0,1,2,3]
```

To get an ISD document that corresponds to a time event we need to call the imscJS method `generateISD()`. We explained this briefly in Generating an IMSC snapshot. So for the ISD at second 2 we need to do the following:

```js
imsc.generateISD(imscDoc, 2);
```

Creating text track cues
------------------------

With two methods we can now generate all necessary states of the IMSC rendering layer. We do this as follows:

* Iterate over the array we get back from `getMediaEvents()`
* For each time event:
    + Create a corresponding cue.
    + Use an `onenter` event to render the ISD.
    + Use an `onexit` event to remove the rendering layer again.

```js
for (let i = 0; i < timeEvents.length; i++) {
  const Cue = window.VTTCue || window.TextTrackCue;

  let myCue;
  if (i < timeEvents.length - 1) {
    myCue = new Cue(timeEvents[i], timeEvents[i + 1], "");
  } else {
    myCue = new Cue(timeEvents[i], myVideo.duration, "");
  }

  myCue.onenter = function () {
    clearSubFromScreen();
    const myIsd = imsc.generateISD(imscDoc, this.startTime);
    imsc.renderHTML(myIsd, renderDiv);
  };
  myCue.onexit = function () {
    clearSubFromScreen();
  };

  myTrack.addCue(myCue);
}
```

Let's look at it into more detail.

While we loop through the `timeEvents` we can take the value of the time event as the start time of the cue. We can then use the value of the next time event for the end time of the cue, because this indicates that the rendering layer needs to change:

```js
myCue = new Cue(timeEvents[i], timeEvents[i + 1], "");
```

**Note:** In most browsers text track cues are currently only implemented for the WebVTT format. So usually you create a cue with all WebVTT properties including the WebVTT text property. We never use these properties but it is important to remember that they are still there. In the constructor we also have to add the VTTCue text as a third parameter.

But how should we calculate the end time of the last time event? It does not have a "next" time event we can take the end time from.

If there is no further time event this actually means that the rendering layer is active until the end of the playtime of the media. So we can set the end time to the duration of the associated media:

```js
myCue = new Cue(timeEvents[i], myVideo.duration, "");
```

Once we construct the cue object we can register the function that is called "on entering" the cue:

```js
myCue.onenter = function () {
  clearSubFromScreen();
  const myIsd = imsc.generateISD(imscDoc, this.startTime);
  imsc.renderHTML(myIsd, renderDiv);
};
```

We generate the ISD that is associated with cue and then use the imscJS method `renderHTML()` to render its corresponding HTML in the "rendering container."

To be sure there is no remaining subtitle layer we first remove the subtitle layer if there is one. For this we define a function we can reuse later when the cue ends:

```js
function clearSubFromScreen() {
  const subtitleActive = renderDiv.getElementsByTagName("div")[0];
  if (subtitleActive) {
    renderDiv.removeChild(subtitleActive);
  }
}
```

We call this function again once the `onexit` event of the cue is thrown:

```js
myCue.onexit = function () {
  clearSubFromScreen();
};
```

At the end we just need to add the generated cue to the text track:

```js
myTrack.addCue(myCue);
```

Using native video player controls
----------------------------------

Usually you want to give the user some options to control the video playback. At least they should be able to play, pause, and seek. The easiest method would be to use the native video controls of the web browser, right? Yes, this is true, when you do not want any additional features.

Native video player controls are part of the browser and not the HTML markup. Although they react to DOM events and generate some of their own, you do not have direct access to them as a web developer.

This causes two problems when using imscJS:

1. The IMSC HTML overlay covers the complete video. It sits on top of the `<video>` element. Although you can see the player controls (because most of the overlay has a transparent background), pointer events like mouse clicks are not coming through to the controls. Because they can't be accessed by standard CSS you can also not change the z-index of the controls to solve this problem. So, if you always have a subtitle overlay, you will not able be able to stop the video once it has started. This would be a very bad user experience.
2. Usually the native video player controls have a caption user interface. You can select a text track or to switch off the rendering of subtitles. Unfortunately, the caption interface only controls the rendering of WebVTT subtitles. The browser does not know that we are rendering subtitles with imscJS, so these controls will have no effect.

For the first problem there is a straightforward CSS solution. We need to set the CSS property `pointer-events` to `none` (see the sample code on GitHub for the complete CSS).

```css
#render-div {
  pointer-events: none;
}
```

This has the effect that pointer events are going "through" the overlay (see reference documentation for point events for more details).

The caption user interface problem is a bit harder to solve. Although we can listen to events, activating a track using the caption user interface will also activate the rendering of corresponding WebVTT. As we are using VTTCues for IMSC rendering, this can course undesired presentation behavior. The text property of the VTTCue has always the empty string as value but in some browser this may lead nonetheless to the rendering of artefacts.

the best solution is to building your own custom controls. Find out how in our Creating a cross-browser video player tutorial.


Subtitle placement in IMSC - Web-related technologies

Subtitle placement in IMSC
==========================

IMSC allows for very explicit positioning of the text over the video content you are displaying it against. There are a few tricks and best practices that can be used in order to simplify the placement of the on-screen text.

Considering correct text placement
----------------------------------

Creating an IMSC document that has the proper text placement and flow is one of the most crucial things to get correct. Unlike some other subtitle formats, IMSC allows for very explicit placement of the text anywhere on the screen. With that said, the most common subtitle styles used today are bottom centered and top centered on the screen.

The <region> element
--------------------

The `<region>` element essentially creates a box on the screen for the text to appear inside. The on-screen text will never be displayed outside of this box. In addition to describing the size and position of the box in which the text can appear, the `<region>` element also defines the horizontal and vertical alignment of the text.

In the example below, we have defined two regions. Both region boxes are the same size, which is 80% of the image width and 80% of the image height. This box is centered on the screen.

The important items to consider here are:

* `tts:origin` — the upper left corner of the region box, specified as X Y coordinate values. This should be described in percentage values.
* `tts:extent` — describes how far to the right of the video the region box goes, then how far down.
* `tts:backgroundColor` — describes the color of the region box. This will most commonly be transparent, however you are welcome to fill it in with a color if that works for your design.
* `tts:showBackground` — should be set to `whenActive`. The other allowable value is `always`, which tells the IMSC decoder to display all region boxes with the value of `always` at the same time. This is very unlikely to be something you want to do.
* `tts:textAlign` — the horizontal text justification. Like a word processor, this can be set to `left`, `center`, or `right`. `center` is the most common text justification for subtitles.
* `tts:displayAlign` — the vertical alignment of the text. This can be set to `before`, `center`, or `after`. `before` means that the text will start from the very top of the region box, and flow downwards. `center` means the text will be vertically centered within the region box. After means that the text will start from the very bottom of the region box, and flow upwards.


OpenSearch description format

OpenSearch description format
=============================

The **OpenSearch description format** can be used to describe the web interface of a search engine. This allows a website to describe a search engine for itself, so that a browser or other client application can use that search engine. OpenSearch is supported by (at least) Firefox, Edge, Safari, and Chrome. (See Reference Material for links to other browsers' documentation.)

Firefox also supports additional features not in the OpenSearch standard, such as search suggestions and the `<SearchForm>` element. This article focuses on creating OpenSearch-compatible search plugins that support these additional Firefox features.

OpenSearch description files can be advertised as described in Autodiscovery of search plugins.

**Warning:** OpenSearch plugins can't be uploaded anymore on addons.mozilla.org (AMO). Search engine feature must use WebExtension API with chrome settings in `manifest.json` file.

OpenSearch description file
---------------------------

The XML file that describes a search engine follows the basic template below. Sections in *[square brackets]* should be customized for the specific plugin you're writing.

```xml
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/"
 xmlns:moz="http://www.mozilla.org/2006/browser/search/">
  <ShortName>[SNK]</ShortName>
  <Description>[Search engine full name and summary]</Description>
  <InputEncoding>[UTF-8]</InputEncoding>
  <Image width="16" height="16" type="image/x-icon">[https://example.com/favicon.ico]</Image>
  <Url type="text/html" template="[searchURL]"/>
  <Url type="application/x-suggestions+json" template="[suggestionURL]"/>
  <moz:SearchForm>[https://example.com/search]</moz:SearchForm>
</OpenSearchDescription>
```

ShortName

A short name for the search engine. It must be **16 or fewer character**s of plain text, with no HTML or other markup.

Description

A brief description of the search engine. It must be **1024 or fewer characters** of plain text, with no HTML or other markup.

InputEncoding

The character encoding to use when submitting input to the search engine.

Image

URL of an icon for the search engine. When possible, include a 16×16 image of type `image/x-icon` (such as `/favicon.ico`) and a 64×64 image of type `image/jpeg` or `image/png`.

The URL may also use the `data:` URL scheme. (You can generate a `data:` URL from an icon file at The `data:` URL kitchen.)

```xml
<Image height="16" width="16" type="image/x-icon">https://example.com/favicon.ico</Image>
  <!-- or -->
<Image height="16" width="16">data:image/x-icon;base64,AAABAAEAEBAAA … DAAA=</Image>
```

Firefox caches the icon as a base64 `data:` URL (search plug-ins are stored in the profile's `searchplugins/` folder). `http:` and `https:` URLs are converted to `data:` URLs when this is done.

**Note:** For icons loaded remotely (that is, from `https://` URLs as opposed to `data:` URLs), Firefox will reject icons larger than **10 kilobytes**.

![Search suggestions from Google displayed in Firefox's search box](/en-US/docs/Web/OpenSearch/searchsuggestionsample.png)

Url

Describes the URL or URLs to use for the search. The `template` attribute indicates the base URL for the search query.

Firefox supports three URL types:

* `type="text/html"` specifies the URL for the actual search query.
* `type="application/x-suggestions+json"` specifies the URL for fetching search suggestions. In Firefox 63 onwards, `type="application/json"` is accepted as an alias of this.
* `type="application/x-moz-keywordsearch"` specifies the URL used when a keyword search is entered in the location bar. This is supported only in Firefox.

For these URL types, you can use `{searchTerms}` to substitute the search terms entered by the user in the search bar or location bar. Other supported dynamic search parameters are described in OpenSearch 1.1 parameters.

For search suggestions, the `application/x-suggestions+json` URL template is used to fetch a suggestion list in JSON format.

Autodiscovery of search plugins
-------------------------------

Websites with search plugins can advertise them so Firefox users can easily install the plugins.

To support autodiscovery, add a `<link>` element for each plugin to the `<head>` of your web page:

```html
<link
 rel="search"
 type="application/opensearchdescription+xml"
 title="searchTitle"
 href="pluginURL" />
```

Replace the bolded items as explained below:

searchTitle

The name of the search to perform, such as "Search MDC" or "Yahoo! Search". This must match your plugin file's `<ShortName>`.

pluginURL

The URL to the XML search plugin, so the browser can download it.

If your site offers multiple search plugins, you can support autodiscovery for them all. For example:

```html
<link
 rel="search"
 type="application/opensearchdescription+xml"
 title="MySite: By Author"
 href="http://example.com/mysiteauthor.xml" />

<link
 rel="search"
 type="application/opensearchdescription+xml"
 title="MySite: By Title"
 href="http://example.com/mysitetitle.xml" />
```

This way, your site can offer plugins to search by author, or by title.

**Note:** In Firefox, an icon change in the search box indicates there's a provided search plugin. (See image, the green plus sign.) Thus if a search box is not shown in the user's UI, they will receive *no* indication. *In general, behavior varies among browsers*.

Supporting automatic updates for OpenSearch plugins
---------------------------------------------------

OpenSearch plugins can automatically update. To support this, include an extra `Url` element with `type="application/opensearchdescription+xml"` and `rel="self"`. The `template` attribute should be the URL of the OpenSearch document to automatically update to.

For example:

```xml
<Url type="application/opensearchdescription+xml"
 rel="self"
 template="https://example.com/mysearchdescription.xml" />
```

**Note:** At this time, addons.mozilla.org (AMO) doesn't support automatic updating of OpenSearch plugins. If you want to put your search plugin on AMO, remove the auto-updating feature before submitting it.

Troubleshooting Tips
--------------------

If there is a mistake in your Search Plugin XML, you could run into errors when adding a discovered plugin. If the error message isn't be helpful, the following tips could help you find the problem.

* Your server should serve OpenSearch plugins using `Content-Type: application/opensearchdescription+xml`.
* Be sure that your Search Plugin XML is well formed. You can check by loading the file directly into Firefox. Ampersands (&) in the `template` URL must be escaped as `&`, and tags must be closed with a trailing slash or matching end tag.
* The `xmlns` attribute is important — without it you could get the error message "Firefox could not download the search plugin".
* You **must** include a `text/html` URL — search plugins including only Atom or RSS URL types (which is valid, but Firefox doesn't support) will also generate the "could not download the search plugin" error.
* Remotely fetched favicons must not be larger than 10KB (see Firefox bug 361923).

In addition, the search plugin service provides a logging mechanism that may be useful to plugin developers. Use `about:config` to set the pref '`browser.search.log`' to `true`. Then, logging information will appear in Firefox's Browser Console(Tools ➤ Browser Tools ➤ Browser Console) when search plugins are added.

Reference Material
------------------

* OpenSearch Documentation
* Safari 8.0 Release Notes: Quick Website Search
* Microsoft Edge Dev Guide: Search provider discovery
* The Chromium Projects: Tab to Search
* imdb.com has a working `osd.xml`
* Ready2Search - create OpenSearch plugins. Customized Search through Ready2Search