> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talosjs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# YouTube

> Fetch YouTube video transcripts with metadata through a typed, container-friendly client.

`@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](https://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.

```bash theme={null}
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.

```bash theme={null}
YOUTUBE_TRANSCRIPT_API_KEY=your-api-key
```

```typescript theme={null}
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.

```typescript theme={null}
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`. |

```typescript theme={null}
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;
  }
}
```