https://github.com/alexandercerutti/sub37
A set of libraries to parse, serve and show subtitles in video medias
https://github.com/alexandercerutti/sub37
captions subtitles subtitles-files subtitles-parsing ttml vtt vtt-subtitles webvtt webvtt-parser
Last synced: about 1 year ago
JSON representation
A set of libraries to parse, serve and show subtitles in video medias
- Host: GitHub
- URL: https://github.com/alexandercerutti/sub37
- Owner: alexandercerutti
- Created: 2021-12-23T19:45:32.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2025-04-02T22:54:59.000Z (about 1 year ago)
- Last Synced: 2025-04-12T07:52:08.638Z (about 1 year ago)
- Topics: captions, subtitles, subtitles-files, subtitles-parsing, ttml, vtt, vtt-subtitles, webvtt, webvtt-parser
- Language: TypeScript
- Homepage: https://sub37.vercel.app/
- Size: 2.37 MB
- Stars: 27
- Watchers: 4
- Forks: 2
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
## Introduction
sub37 is set of client-side _dependency-free_ libraries that aims to provide a consistent and customizable media contents captions experience across browsers by leaving developers, at the same time, the freedom to choose which caption format to support (like WebVTT, TTML, ...) and how to style them.
## Architecture overview
sub37 architecture is made of three components:
- A [Renderer](packages/captions-renderer/) (`@sub37/captions-renderer`), a WebComponent that handles all the aspects of captions rendering (styles, colors, positioning, etc.);
- A [Server](packages/server/) (`@sub37/server`), a client library that handles timed serving of cues and centralizes all the shared aspects (formats, communication);
- An [Adapter](packages/webvtt-adapter/) (e.g. `@sub37/webvtt-adapter`), a library that knows how to parse a specific captions format and knows how to convert it to the core format provided by the server;
Of the three components, both Renderer and Adapter are replaceable: they only need to provide the correct support to the interface that server expects to use to communicate with them (see the wiki).
> At this early stage, sub37 provides only the webvtt-adapter to be used. Further formats will be implemented and evaluated over the time.
Here a schema of how the flow works:
## Installation
Once chosen the adapters suitable for your use case, proceed to install all the packages needed.
```sh
$ npm install @sub37/server @sub37/captions-renderer @sub37/webvtt-adapter
```
## API Documentation Reference
Each component has its own README and Wiki Page that provides more details on how they should be used and which features they support.
More details about usage and architecture can be found in the wiki (_coming soon_).
## Usage example
In your HTML, include the `captions-renderer`. This element is studied to be put over `HTMLVideoElement`s.
```html
```
In your Javascript, load the caption-renderer by importing it as a side-effect. This will load it into your window's customElements Registry.
Create an instance of the server and pass it the Renderers you want to import. The renderers will be available as long as you keep your Server instance.
Attach `caption-renderer` to server instance event system. Then create a session and pass it a set of tracks. Each track represents a content to be associated and parsed through your adapters.
As parsing is a synchronous activity, once it is completed, you'll be able to call `.start` to start serving the content.
```javascript
import "@sub37/captions-renderer";
import { Server, Events } from "@sub37/server";
import { WebVTTAdapter } from "@sub37/webvtt-adapter";
const videoElement = document.getElementsByTagName("video")[0];
const rendererElement = document.getElementsByTagName("captions-renderer")[0];
/**
* Create the server instance.
* One for your whole runtime is fine.
* Renderers will be maintained across sessions.
* You'll need at least an Adapter per server...
*/
const captionServer = new Server(WebVTTAdapter);
/**
* ... or you may pass multiple adapters to a single server instance,
* as many as formats you plan to support, custom renderers included
*/
const captionServer = new Server(WebVTTAdapter, MyCustomAdapter, ...);
captionServer.addEventListener(Events.CUE_START, rendererElement.setCue);
captionServer.addEventListener(Events.CUE_STOP, rendererElement.setCue);
captionServer.addEventListener(Events.CUE_ERROR, (/** @type {Error} */ error) => {
console.error(error);
});
/**
* Create the session. A new one for each video content.
*/
captionServer.createSession([
{
lang: "ita",
content: "WEBVTT ...",
mimeType: `text/vtt`,
active: true,
},
]);
captionServer.start(() => {
return videoElement.currentTime;
});
videoElement.play();
videoElement.addEventListener("seeking", () => {
/**
* Seeking on native controls, might fire this event
* a lot of times. We want to keep our subtitles updated
* based on position if we are in pause. Otherwise
* the server will automatically update them.
*/
if (videoElement.paused && !captionServer.isRunning) {
captionServer.updateTime(videoElement.currentTime);
}
});
videoElement.addEventListener("pause", () => {
/**
* It might be useless to keep having an interval
* running if our content is paused. We can safely
* update the captions when seeking.
*/
captionServer.suspend();
});
videoElement.addEventListener("playing", () => {
if (!captionServer.isRunning) {
captionServer.resume();
}
});
```
## Other
This project was born by a personal need while working on the on-demand video player of a big Italian 🇮🇹 television broadcaster. It took over a year to become ready.
Its name is a reference to an Italian television teletext service, called "televideo". It was common to hear, before the beginning of programs, a voice telling "subtitles available at 777 of televideo". From there, `sub37`.