README

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

npm install media-transcript

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" src="path/to/media.mp3"></audio>
<media-transcript media="my-media"></media-transcript>

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, provided by microbundle. All bundles ship with both the <media-transcript> and <media-cue> custom elements.

UMD

The UMD bundle includes MediaCue & MediaTranscript and will work in all browsers.

<script src="media-transcript.umd.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="media-transcript.module.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).