Media Transcript

Create interactive transcripts for media elements

A dependency-free web component (custom element + shadow DOM) for creating interactive transcripts via the WebVTT API. Operates in two modes:

• Track to transcript: parse an existing <track> element to generate a transcript automatically.
• Transcript to track: parse an existing transcript to create a synthetic TextTrack for your media.

Install

Since this module isn't hosted on npm, you'll need to install directly from GitLab via SSH. Replace <tag> with the most recent tag (e.g., v2.0.0-alpha.2).

npm install git+ssh://git@gitlab.com:wwnorton/platform/media-transcript.git#<tag>

Modes

There are two modes for using the <media-transcript> element. Both start by binding a <media-transcript> to your media element (<audio> or <video>) via the [media] attribute.

<audio id="my-media" />
<media-transcript media="my-media" />

Track to transcript

If you already have captions for your media and just want to create a transcript from those captions, simply bind the media to the <media-transcript>.

When using this mode, the captions must be .vtt format. This is because <media-transcript> uses the native WebVTT and TextTrack APIs to parse the track. The .srt format does not implement these APIs.

<video id="my-video" poster="path/to/video.jpg" controls>
  <source src="/path/to/video.mp4" type="video/mp4" />
  <track src="path/to/video.vtt" kind="captions" label="English captions" srclang="en" />
</video>
<media-transcript media="my-video" />

View the track-to-transcript example

Transcript to Track

If your <media-transcript> has <media-cue> elements already set in the HTML, binding it to media will cause that media to display the transcript as captions. Note that user agents do not provide an interface for <audio> element TextTracks, so this mostly only makes sense for <video>.

<video id="my-video" poster="path/to/video.jpg" controls>
  <source src="/path/to/video.mp4" type="video/mp4" />
  <!-- no track necessary -->
</video>
<media-transcript media="my-video" kind="captions" label="English captions" srclang="la">
  <!-- cues can be nested in this mode -->
  <h2>
    <media-cue end="1">Chapter 1</media-cue>
  </h2>
  <p>
    <media-cue start="1.2" end="3">Lorem ipsum dolor sit amet consectetur adipisicing elit.</media-cue>
    <media-cue start="3.1" end="4">Est nesciunt incidunt,</media-cue>
    <media-cue start="4" end="6.2">deleniti doloremque natus ad id nam laborum amet facilis voluptatem odio?</media-cue>
    <media-cue start="6.7" end="8">Incidunt rerum sunt quo eaque sapiente sit sequi.</media-cue>
  </p>
</media-transcript>

Usage

Start by adding the custom elements to your page. Various builds are available to accomplish this. If you're not sure which one to use, use the UMD one.

UMD

The UMD bundle includes MediaCue & MediaTranscript and is the easiest, most compatible way to get started.

<script src="MediaTranscript.bundle.umd.min.js" defer></script>

Alternatively, you can add each custom element separately. Note that MediaCue must come before MediaTranscript in the DOM order.

<script src="MediaCue.umd.min.js" defer></script>
<script src="MediaTranscript.umd.min.js" defer></script>

ES Modules

If you're using a browser that supports ES modules, you can load the custom elements as modules. This can also be done via the bundle or as independent modules.

<script src="MediaTranscript.bundle.esm.min.js" type="module"></script>

<script src="MediaCue.esm.min.js" type="module"></script>
<script src="MediaTranscript.esm.min.js" type="module"></script>

CommonJS (Node.js)

If you're working in a Node.js environment, you can just import and use the JavaScript API.

import { MediaCue, MediaTranscript } from 'media-transcript';

const transcript = new MediaTranscript({ /* transcript options */ });
const cue = new MediaCue({ /* cue options */ });

transcript.appendChild(cue);
document.body.appendChild(transcript);

API

Since <media-transcript> and <media-cue> are custom elements, there is both a JavaScript API and an HTML API (attributes).

<media-transcript> attributes

<media-cue> attributes