youtube-captions

YouTube Captions

A simple utility to fetch YouTube video captions programmatically. This library retrieves captions in plain text or structured format for specified video IDs.

Features

• Fetch captions for any YouTube video with available subtitles.
• Supports multiple languages.
• Returns captions in both structured and plain text formats.

Installation

You can install the package via npm:

npm install youtube-captions

Or using Yarn:

yarn add youtube-captions

Or with pnpm:

pnpm add youtube-captions

Usage

Importing the Function

You can import the getVideoCaptions function in your project as follows:

import getVideoCaptions from 'youtube-captions';
// or for CommonJS
const getVideoCaptions = require('youtube-captions');

Fetching Captions

To fetch captions for a specific video, call the function with the video ID and optional configuration:

const videoId = 'jNQXAC9IVRw';
const captions = await getVideoCaptions(videoId, { lang: 'en' });

console.log(captions);

Caption Configuration Options

The getVideoCaptions function accepts the following optional parameters:

• lang (string): Specify the language of the captions (e.g., 'en' for English).
• plainText (boolean): If set to true, the captions will be returned in plain text format.

Example

const videoId = 'jNQXAC9IVRw';
const captions = await getVideoCaptions('jNQXAC9IVRw', { lang: 'en', plainText: true });

console.log(captions);

Error Handling

The getVideoCaptions function may throw errors for various reasons:

• Invalid Video ID: If the provided video ID is invalid.
• Captions Disabled: If captions are disabled for the video.
• No Captions Available: If there are no available captions for the video.
• Request Limit Exceeded: If YouTube is receiving too many requests from your IP.

Example Error Handling

try {
  await getVideoCaptions('invalid_id');
} catch (error) {
  console.error('Error fetching captions:', error.message);
}

Testing

This library includes tests using Vitest. To run the tests, execute:

npm test

Contributing

Contributions are welcome! Please feel free to submit a pull request or open an issue to discuss improvements or bugs.

License

This project is licensed under the MIT License.