Captioneer

A powerful TypeScript library for fetching YouTube video transcripts with ease.

Features

• 🎯 Fetch transcripts from any YouTube video
• 🔌 Configurable HTTP clients (Fetch, Axios, Got, etc.)
• 🌍 Support for multiple languages
• 💪 Type-safe with full TypeScript support
• ⚡ Modern ESM and CommonJS support
• 🛡️ Robust error handling
• 🧪 Well-tested and reliable

Installation

npm install captioneer
# or
yarn add captioneer
# or
pnpm add captioneer

Usage

Basic Example

import { Captioneer } from 'captioneer';

const captioneer = new Captioneer();

// Fetch captions for a video
const captions = await captioneer.fetchCaptions('dQw4w9WgXcQ');
console.log(captions);

With Language Selection

const captions = await captioneer.fetchCaptions('dQw4w9WgXcQ', {
  lang: 'es' // Fetch Spanish captions
});

HTTP Clients

Captioneer provides flexibility in how you make HTTP requests through its HTTP client system.

Using the Default HTTP Client

The library comes with a built-in HTTP client using the Fetch API:

import { Captioneer } from 'captioneer';

// Uses default HTTP client
const captioneer = new Captioneer();
const captions = await captioneer.fetchCaptions('dQw4w9WgXcQ');

Using Custom HTTP Clients

You can provide your own HTTP client implementation. Here's an example using Axios:

import { Captioneer, CaptioneerHttpClient } from 'captioneer';
import axios from 'axios';

const axiosClient: CaptioneerHttpClient = {
  async get(url, options) {
    const response = await axios.get(url, options);
    return {
      ok: response.status >= 200 && response.status < 300,
      text: async () => response.data
    };
  }
};

const captioneer = new Captioneer(axiosClient);
const captions = await captioneer.fetchCaptions('dQw4w9WgXcQ');

Advanced HTTP Client Configuration

Custom HTTP clients support additional configurations like proxies or custom headers:

const configuredClient: CaptioneerHttpClient = {
  async get(url, options) {
    const response = await axios.get(url, {
      ...options,
      proxy: {
        host: 'proxy-server',
        port: 8080,
      },
      headers: {
        ...options?.headers,
        'Custom-Header': 'value',
      },
    });

    return {
      ok: response.status >= 200 && response.status < 300,
      text: async () => response.data,
    };
  },
};

The HTTP client interface ensures compatibility while giving you full control over the request implementation.

Error Handling

import { Captioneer, isCaptioneerError, ErrorCode } from 'captioneer';

try {
  const captions = await captioneer.fetchCaptions('VIDEO_ID');
} catch (error) {
  if (isCaptioneerError(error)) {
    switch (error.code) {
      case ErrorCode.LANGUAGE_NOT_AVAILABLE:
        console.log('Language not available:', error.details.availableLanguages);
        break;
      case ErrorCode.VIDEO_UNAVAILABLE:
        console.log('Video is not available');
        break;
      // Handle other specific errors
    }
  }
}

API Reference

Captioneer

Main class for interacting with YouTube transcripts.

Methods

fetchCaptions(videoId: string, config?: CaptioneerConfig): Promise<CaptionEntry[]>

Fetches captions for a YouTube video.

• videoId: YouTube video ID or URL
• config: Optional configuration object
  • lang: Language code (e.g., 'en', 'es')

Returns an array of caption entries.

Types

interface CaptionEntry {
  text: string;
  duration: number;
  offset: number;
  lang: string;
}

interface CaptioneerConfig {
  lang?: string;
}

Error Handling

The library provides specific error types for different scenarios:

• TooManyRequestsError: Rate limiting detected
• VideoUnavailableError: Video not accessible
• CaptionsDisabledError: Captions are disabled
• LanguageNotAvailableError: Requested language not available
• InvalidVideoIdError: Invalid video ID format
• NetworkError: Network-related issues
• ParseError: Response parsing failed

Development

# Install dependencies
pnpm install

# Run tests
pnpm test

# Build the library
pnpm build

# Run linting
pnpm lint

Contributing

Contributions are welcome! We follow a structured branching strategy and conventional commits.

Quick Start

1. Fork the repository
2. Create your feature branch from develop (git checkout -b feature/amazing-feature)
3. Write meaningful commit messages following conventional commits (feat: add amazing feature)
4. Push to your branch (git push origin feature/amazing-feature)
5. Open a Pull Request to develop

Detailed Guidelines

• See CONTRIBUTING.md for detailed contribution guidelines
• Check .github/BRANCH_STRATEGY.md for branch workflows
• Follow our Code of Conduct

Your contributions help make Captioneer better for everyone!

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

Created by ItsCurstin