Elevate multimedia interactivity with CueSync — a JavaScript library that simplifies the integration of interactive transcripts into your media projects.
Assuming you’ve added your media (audio or video) to your page, have the transcript ready, and have correctly included the required CueSync JavaScript file, you’re ready to use the component.
Simply add a <cue-sync> element with the transcript-path attribute set to the path of your transcript file,
and the media attribute set to a CSS selector that matches your media element (e.g. #videoId or .audio-player).
<!-- Video -->
<video id="natGeoVideo" controls style="width: 100%; max-width: 500px;">
<source src="/assets/videos/natgeo.mp4" type="video/mp4">
Your browser does not support HTML video.
</video>
<!-- Transcript -->
<cue-sync transcript-path="/assets/transcripts/natgeo.vtt"
media="#natGeoVideo"
style="height: 400px;"></cue-sync>
That’s it — your interactive transcript is ready to go!
Hit play and watch the transcript come to life, elegantly highlighting each phrase (Cue) as it’s spoken. Click on any Cue to jump to that moment in the media.
Video
Transcript
Before exploring the different options available with CueSync, it’s important to understand the supported transcript formats.
CueSync supports two common transcript file formats: VTT (WebVTT) and SRT (SubRip). These formats define
the timing and text of each spoken segment, allowing CueSync to sync them precisely with your media.
It is important to follow their structure strictly, or the transcript may not render correctly.
VTT is a flexible and modern format, commonly used for captions and interactive transcripts on the web.
Basic structure:
Language: English) is optionally supported by CueSync for language selection in
multilingual transcriptsWEBVTT
Language: Hindi
00:00:02 --> 00:00:03
कीट
00:00:03 --> 00:00:06
खुरदरे, गूदेदार
00:00:06 --> 00:00:09
ओह, वह मुलायम है
SRT is a simpler and widely used subtitle format, especially in video production and distribution.
Basic structure:
Language: line is included, CueSync will read it and enable language selection1
00:00:02 --> 00:00:03
bugs
2
00:00:03 --> 00:00:06
give me the scaly the squishy
3
00:00:06 --> 00:00:09
oh she's fluffy
CueSync offers two layout options for displaying the transcript: stacked and paragraph, with stacked being
the default.
Users can switch between these layouts at any time from the Settings panel.
As a developer, you can also set a default layout for your users using the layout attribute on the
<cue-sync> element. This attribute accepts the values 'stacked' or 'paragraph', respectively, to choose
the desired layout.
<!-- Video -->
<video id="natGeoVideo2" controls style="width: 100%; max-width: 500px;">
<source src="/assets/videos/natgeo.mp4" type="video/mp4">
Your browser does not support HTML video.
</video>
<!-- Transcript -->
<cue-sync transcript-path="/assets/transcripts/natgeo.vtt"
media="#natGeoVideo2"
layout="paragraph"
style="height: 400px;"></cue-sync>By default, CueSync displays timestamps for each segment of the transcript. Users can show or hide the timestamps at any time from the Settings panel.
As a developer, you can control the visibility of timestamps for your users by using the show-timestamp attribute
on the <cue-sync> element. This attribute accepts 'true' to show timestamps and 'false' to hide them.
<!-- Video -->
<video id="natGeoVideo3" controls style="width: 100%; max-width: 500px;">
<source src="/assets/videos/natgeo.mp4" type="video/mp4">
Your browser does not support HTML video.
</video>
<!-- Transcript -->
<cue-sync transcript-path="/assets/transcripts/natgeo.vtt"
media="#natGeoVideo3"
show-timestamp="false"
style="height: 400px;"></cue-sync>By default, CueSync enables auto-scroll, which automatically brings the currently spoken phrase (Cue) into view as the media plays. Users can turn this feature on or off at any time from the Settings panel.
As a developer, you can control the default behavior using the auto-scroll attribute on the <cue-sync>
element. This attribute accepts 'true' to enable auto-scroll and 'false' to disable it.
<!-- Video -->
<video id="natGeoVideo4" controls style="width: 100%; max-width: 500px;">
<source src="/assets/videos/natgeo.mp4" type="video/mp4">
Your browser does not support HTML video.
</video>
<!-- Transcript -->
<cue-sync transcript-path="/assets/transcripts/natgeo.vtt"
media="#natGeoVideo4"
auto-scroll="false"
style="height: 400px;"></cue-sync>CueSync offers three theme options: auto, light, and dark, with auto being the default.
The auto theme adapts to the user’s device settings, switching between light or dark mode accordingly.
Users can switch between these themes at any time from the Settings panel.
As a developer, you can set a default theme for your users using the theme attribute on the <cue-sync> element.
This attribute accepts the values 'auto', 'light', or 'dark'.
<!-- Video -->
<video id="natGeoVideo5" controls style="width: 100%; max-width: 500px;">
<source src="/assets/videos/natgeo.mp4" type="video/mp4">
Your browser does not support HTML video.
</video>
<!-- Transcript -->
<cue-sync transcript-path="/assets/transcripts/natgeo.vtt"
media="#natGeoVideo5"
theme="light"
style="height: 400px;"></cue-sync>The Settings feature is enabled by default in CueSync, allowing users to switch themes, toggle auto-scroll, change layouts, show or hide timestamps, and select transcript languages.
If you prefer not to offer these customization options, you can disable the Settings feature by using the
allow-settings attribute on the <cue-sync> element. This will prevent the settings button from appearing
in the toolbar.
This attribute accepts 'true' to enable settings and 'false' to disable it.
<!-- Video -->
<video id="natGeoVideo6" controls style="width: 100%; max-width: 500px;">
<source src="/assets/videos/natgeo.mp4" type="video/mp4">
Your browser does not support HTML video.
</video>
<!-- Transcript -->
<cue-sync transcript-path="/assets/transcripts/natgeo.vtt"
media="#natGeoVideo6"
allow-settings="false"
layout="paragraph"
show-timestamp="false"
style="height: 400px;"></cue-sync>If you have transcripts in multiple languages for a media element, you can provide the paths to each
transcript file (comma-separated) in the transcript-path attribute. The Settings panel will automatically
display an additional option, allowing users to select or hide any language they prefer.
CueSync determines the language name from the Language: metadata in each VTT or SRT file. If this metadata
is missing, the language selection may not appear in the Settings panel.
To ensure a smooth multilingual experience, always include the Language: field at the top of each VTT or SRT
file (e.g., Language: English, Language: Hindi, etc.).
<!-- Video -->
<video id="natGeoVideo7" controls style="width: 100%; max-width: 500px;">
<source src="/assets/videos/natgeo.mp4" type="video/mp4">
Your browser does not support HTML video.
</video>
<!-- Transcript -->
<cue-sync transcript-path="/assets/transcripts/natgeo.vtt, /assets/transcripts/natgeo_hindi.vtt"
media="#natGeoVideo7"
style="height: 400px;"></cue-sync>You can customize the appearance of CueSync by modifying the CSS custom properties listed here.
<style>
.custom-cuesync {
--cs-border-color: #aa076b;
--cs-border-radius: 20px;
--cs-toolbar-bg: #aa076b;
--cs-toolbar-color: #fff;
--cs-transcript-bg: #aa076b;
--cs-transcript-color: #fff;
--cs-cue-hover-bg: #e47aaf;
--cs-cue-hover-color: #000;
--cs-cue-active-bg: #ffd75e;
--cs-cue-active-color: #aa076b;
--cs-cue-highlight-color: #ffd75e;
--cs-timestamp-bg: #ffd75e;
--cs-timestamp-color: #aa076b;
--cs-timestamp-border-radius: 20px;
}
</style>
<!-- Video -->
<video id="natGeoVideo8" controls style="width: 100%; max-width: 500px;">
<source src="/assets/videos/natgeo.mp4" type="video/mp4">
Your browser does not support HTML video.
</video>
<!-- Transcript -->
<cue-sync class="custom-cuesync" transcript-path="/assets/transcripts/natgeo.vtt, /assets/transcripts/natgeo_hindi.vtt"
media="#natGeoVideo8"
style="height: 400px;"></cue-sync>The <cue-sync> web component is designed to work declaratively via HTML attributes, but it also exposes a
few useful ways to interact with it via JavaScript.
You can select the element using document.querySelector() (or any standard DOM method).
const cueSync = document.querySelector('cue-sync');
HTML attributes listed here can be updated via JavaScript using ‘setAttribute()’.
const cueSync = document.querySelector('cue-sync');
cueSync.setAttribute('layout', 'paragraph');
cueSync.setAttribute('theme', 'dark');
CueSync dispatches custom events listed here whenever key attributes change.
const cueSync = document.querySelector('cue-sync');
cueSync.addEventListener('layout-changed', e => {
console.log('Layout changed to:', e.detail.newValue);
});
Recalculates the width of the timestamp column. Useful if fonts or styles change.
const cueSync = document.querySelector('cue-sync');
cueSync.redrawTime();
mode: 'open'), so you can access cueSync.shadowRoot if absolutely necessary, though
this is not recommended.