Formatters

Turn a fetched transcript into JSON, plain text, SRT, WebVTT, pretty-print or an article with a timestamp map.

Every formatter has the same two methods:

  • formatTranscript(transcript, options?) — one FetchedTranscript to a string.
  • formatTranscripts(transcripts, options?) — several, joined.
import { SRTFormatter, WebVTTFormatter, JSONFormatter, TextFormatter } from 'extract-youtube';

const transcript = await api.fetchTranscript('jNQXAC9IVRw');

const srt = new SRTFormatter().formatTranscript(transcript);
const vtt = new WebVTTFormatter().formatTranscript(transcript);
const json = new JSONFormatter().formatTranscript(transcript, { indent: 2 });
const text = new TextFormatter().formatTranscript(transcript);
FormatterOutput
JSONFormatterThe raw snippets as compact JSON. Accepts { indent }.
TextFormatterSnippet text only, one snippet per line, no timestamps.
SRTFormatterSubRip subtitles (00:00:01,000 --> 00:00:04,000).
WebVTTFormatterWebVTT subtitles for a <track> element.
PrettyPrintFormatterThe raw snippets as JSON indented by two spaces — readable in a terminal.
ArticleFormatterFull text plus a compressed character-to-timestamp map (below).

Subtitle formatters clip each cue's end time to the start of the next one, so overlapping auto-generated captions never show two lines at once.

Pick a formatter by name

FormatterLoader maps a string to a formatter — handy for a ?format= query parameter:

import { FormatterLoader } from 'extract-youtube';

const formatter = new FormatterLoader().load('srt'); // json | text | article | srt | webvtt | pretty
const body = formatter.formatTranscript(transcript);

An unknown name throws UnknownFormatterType. With no argument it returns the pretty-print formatter.

Article format and timestamp maps

ArticleFormatter joins the transcript into one paragraph of text and records where in that text each moment of the video falls, so you can link from any character back to a timestamp:

import { ArticleFormatter } from 'extract-youtube';

const article = JSON.parse(new ArticleFormatter().formatTranscript(transcript));
// {
//   "text": "Full transcript text...",
//   "timestamps": "10,15,20  100,200,300",
//   "wordCount": 1234,
//   "charCount": 5678
// }

For the same idea as a function, use the helpers in the main entry:

FunctionDescription
encodeTranscriptSpeeds(transcript, addPlayer?)Returns { html, word_count, speeds }: the joined text, a word count, and a run-length encoded speed string like 12x3,8x7. With addPlayer, html starts with a YouTube embed carrying data-timestamps.
decompressTimestampsArray(speeds)Expands 12x3,8x7 back to [12, 12, 12, 8, …].
getTimestampAtChar(transcript, charIndex)The video time, in seconds, at a character offset in the joined text.

The CLI exposes encodeTranscriptSpeeds as -f speeds.

On this page