Timbra.js

Add live captions from CaptionHub's Timbra to your video player. Plugins are included for Video.js 7 and 8 (including Brightcove), HLS.js, Mux Player and OptiView Player (THEOplayer 8.6+). The upcoming Video.js 10 rewrite is not yet supported.

👉 Full documentation · Upgrading from the 1.x hosted plugins

Installation

npm install @captionhub/timbra.js

or

yarn add @captionhub/timbra.js

No bundler? Versioned static bundles are hosted on timbra.com — they expose the same API on window.Timbra:

<script src="https://timbra.com/@2.0.0.js"></script>

Quick start

Get the captions URL for your stream from the CaptionHub UI or API, then construct the plugin for your player and start captions:

import { Timbra } from '@captionhub/timbra.js';

const player = videojs('my-video');

const timbra = new Timbra.VideoJSPlugin({
  video: player,
  captionsURL: 'https://…', // from the CaptionHub UI or API
});

timbra.startCaptions();

The same pattern works for the other players: Timbra.HLSJSPlugin ({ video, hls, captionsURL }), Timbra.MuxPlugin ({ video } — the captions URL is derived from the player's playback ID) and Timbra.OptiViewPlugin ({ player, captionsURL }).

Content Security Policy

If your site sets a CSP, the plugins need:

• script-src https://timbra.com — when using the hosted script tag (not needed for the NPM package).
• connect-src https://cdn.captionhub.com wss://ws-eu.pusher.com https://sockjs-eu.pusher.com — caption delivery (HTTPS polling and WebSocket) and playback metrics. Use the host of your captions URL if it differs.
• media-src data: — OptiView Player only: the player backs its custom text tracks with data:text/vtt URLs.

Troubleshooting

Captions not appearing? Check, in order:

1. The stream is live in CaptionHub and the player is actually playing — captions only start with playback.
2. The captions URL responds: open it in a browser; it should return JSON. Mistyped or stale URLs are the most common cause (the plugin throws immediately if a required option is missing entirely).
3. The caption track is selected: the plugin adds a subtitle track to the player's CC menu; viewers still need to turn it on (the stream's default language track enables itself).
4. Turn on logging: pass loglevel: 'debug' and watch the browser console — every fetch, track and caption placement is logged with a [Timbra#…] prefix. Include these logs in support tickets.
5. CSP errors in the console? See the Content Security Policy section above.

Support and feedback

Raise a support ticket at CaptionHub Support.

License

CaptionHub user terms and license