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. | listbox: treat the transcript as a listbox widget, automatically enhancing the <media-cue> elements with [role="option"], managed roving focus, and proper aria-selected values.Other roles will be added | | aria-orientation | Change keyboard behavior when an interactive mode is enabled | vertical: only up/down arrow keys control focushorizontal: only left/right arrow keys control focusunset (default): all arrow keys control focus |

<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) |