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).
<media-transcript>
attributes
Attribute | Description | Values |
---|---|---|
media |
an id reference (IDREF) that corresponds to the media element's id | Any valid string |
timestamp |
enable timestamps for all child <media-cue> elements |
boolean (i.e., <media-transcript timestamp> or <media-transcript timestamp="timestamp"> for proper conformance) |
role |
set a role to make the transcript interactive. |
|
aria-orientation |
Change keyboard behavior when an interactive mode is enabled |
|
<media-cue>
attributes
Attribute | Description | Values |
---|---|---|
start |
the cue's start time | decimal number string. Assumed to be 0 when omitted. |
end |
the cue's end time | decimal number string. |
timestamp |
enable the cue's built-in timestamp (set as a <time> element) |
boolean (i.e., <media-cue timestamp> or <media-cue timestamp="timestamp"> for proper conformance) |