YouTube - Talos

@talosjs/youtube provides a Youtube class that fetches a video’s transcript — segmented text with timestamps — along with its title, author, and thumbnail, via the transcriptapi.com service. It also re-exports the option and format types from ytdlp-nodejs (YoutubeArgsOptionsType, YoutubeFormatOptionsType, YoutubeQualityOptionsType, YoutubeVideoFormatType, YoutubeVideoProgressType) for typing video download workflows built on ytdlp-nodejs directly.

Installation

Add the package with Bun.

bun add @talosjs/youtube

Configuration

Youtube needs a transcript API key, either passed to the constructor or read from the YOUTUBE_TRANSCRIPT_API_KEY environment variable. The constructor throws YoutubeException (API_KEY_REQUIRED) if neither is set.

YOUTUBE_TRANSCRIPT_API_KEY=your-api-key

import { Youtube } from "@talosjs/youtube";

// Reads YOUTUBE_TRANSCRIPT_API_KEY when no key is passed
const youtube = new Youtube();

// Or pass a key explicitly
const explicit = new Youtube("your-api-key");

Usage

transcript(videoId) returns the transcript segments plus video metadata for a given YouTube video id.

import { Youtube } from "@talosjs/youtube";

const youtube = new Youtube();

const result = await youtube.transcript("dQw4w9WgXcQ");

result.lang;                 // e.g. "en"
result.transcript;           // [{ text, start, duration }, ...]
result.metadata.title;       // video title
result.metadata.author.name; // channel name
result.metadata.thumbnail;   // thumbnail URL

Types

Type	Purpose
`IYoutube`	Interface implemented by `Youtube` — a single `transcript(videoId)` method.
`YoutubeTranscriptResponseType`	Shape returned by `transcript()`: `id`, `lang`, `transcript`, `metadata`.
`YoutubeTranscriptSegmentType`	A single transcript line: `text`, `start`, `duration`.
`YoutubeTranscriptMetadataType`	Video `title`, `author`, and `thumbnail`.
`YoutubeVideoQualityType`	Named video quality strings (`"1080p"`, `"highest"`, etc.), for pairing with `ytdlp-nodejs`.
`YoutubeAudioQualityType`	`"highest" \| "lowest"`, for pairing with `ytdlp-nodejs`.
`YoutubeArgsOptionsType`, `YoutubeFormatOptionsType`, `YoutubeQualityOptionsType`, `YoutubeVideoFormatType`, `YoutubeVideoProgressType`	Re-exported `ytdlp-nodejs` types for typing download/format code that uses `ytdlp-nodejs` directly.

Exceptions

YoutubeException (extending Exception, mapped to InternalServerError) is thrown with a machine-readable key.

Key	When
`API_KEY_REQUIRED`	`Youtube` is constructed without an API key and `YOUTUBE_TRANSCRIPT_API_KEY` is unset.
`TRANSCRIPT_FAILED`	The transcript API responds with a non-OK status; `data` carries the `videoId` and HTTP `status`.

import { Youtube, YoutubeException } from "@talosjs/youtube";

try {
  const result = await youtube.transcript(videoId);
} catch (error) {
  if (error instanceof YoutubeException) {
    logger.error(`YouTube error [${error.key}]`, error.data);
  } else {
    throw error;
  }
}

​Installation

​Configuration

​Usage

​Types

​Exceptions

Installation

Configuration

Usage

Types

Exceptions