yt-transcript-kit

Lightweight YouTube transcript extraction and YouTube search for apps that want video text and metadata first, then decide what to do with it. Built with TypeScript and zero runtime dependencies.

Install

node --version # requires Node.js 18+
npm install yt-transcript-kit

Use npx ytk --help for the CLI without installing globally.

Quick Start

import { fetchYouTubeTranscript, searchYouTube } from 'yt-transcript-kit';

const result = await fetchYouTubeTranscript('https://www.youtube.com/watch?v=dQw4w9WgXcQ');
console.log(result.title, result.fullText);

const videos = await searchYouTube({ query: 'typescript tutorial', maxResults: 5 });
console.log(videos[0].title, videos[0].url);

New APIs

YouTube Search

Search YouTube videos without a YouTube Data API key.

import { searchYouTube } from 'yt-transcript-kit';

const results = await searchYouTube({
  query: 'node.js streams',
  maxResults: 10,
  hl: 'en',
});

for (const video of results) {
  console.log(video.title);
  console.log(video.channelName, video.duration, video.viewCount);
  console.log(video.url);
}

Each result includes:

• videoId
• title
• channelName
• channelId
• publishedAt
• viewCount
• duration
• durationSeconds
• thumbnailUrl
• description
• url

Search With Transcripts

Fetch transcripts for search results in one call.

import { searchYouTubeWithTranscripts } from 'yt-transcript-kit';

const results = await searchYouTubeWithTranscripts({
  query: 'react server components',
  maxResults: 3,
  includeTranscripts: true,
  transcriptOptions: {
    languages: ['en'],
  },
});

for (const video of results) {
  if (video.transcript) {
    console.log(video.title, video.transcript.fullText.slice(0, 200));
  } else {
    console.warn(video.title, video.transcriptError);
  }
}

includeTranscripts: true makes one transcript request per search result, so keep maxResults modest for CLI tools and server routes.

Transcript Search

import { fetchYouTubeTranscript, searchTranscript } from 'yt-transcript-kit';

const transcript = await fetchYouTubeTranscript('videoId');
const matches = searchTranscript(transcript, 'keyword', {
  caseSensitive: false,
  maxResults: 20,
  contextChars: 24,
});

console.log(matches[0]);

Chunking for LLM pipelines

import { fetchYouTubeTranscript, chunkTranscript } from 'yt-transcript-kit';

const transcript = await fetchYouTubeTranscript('videoId');

const chunks = chunkTranscript(transcript, {
  maxChars: 4000,
  maxTokens: 1200,
  overlapSegments: 1,
  mergeAdjacentShortSegments: true,
});

console.log(chunks[0]);

Formatting modes

import { fetchYouTubeTranscript, formatTranscript } from 'yt-transcript-kit';

const transcript = await fetchYouTubeTranscript('videoId');

const plainText = formatTranscript(transcript, { mode: 'plainText' });
const markdown = formatTranscript(transcript, { mode: 'markdown', includeTimestamps: true });
const paragraphs = formatTranscript(transcript, { mode: 'paragraphs', paragraphMergeThresholdSec: 2 });
const segments = formatTranscript(transcript, { mode: 'segments' });

console.log(markdown);

Metadata helper

import { getTranscriptWithMetadata } from 'yt-transcript-kit';

const enriched = await getTranscriptWithMetadata('videoId');
console.log(enriched.channelName, enriched.duration, enriched.thumbnailUrls);

Optional cache support

import { fetchYouTubeTranscript, InMemoryTranscriptCache } from 'yt-transcript-kit';

const cache = new InMemoryTranscriptCache({ ttlMs: 60_000 });
const transcript = await fetchYouTubeTranscript('videoId', { cache });

console.log(transcript.videoId);

Batch fetching

import { fetchManyYouTubeTranscripts } from 'yt-transcript-kit';

const results = await fetchManyYouTubeTranscripts(['videoId1', 'videoId2'], { concurrency: 3 });

for (const item of results) {
  if (item.success) {
    console.log(item.result.videoId, item.result.languageCode);
  } else {
    console.error(item.input, item.error.code);
  }
}

Cleanup helpers

import {
  cleanTranscriptSegments,
  cleanTranscriptText,
  fetchYouTubeTranscript,
} from 'yt-transcript-kit';

const transcript = await fetchYouTubeTranscript('videoId');

const cleanedText = cleanTranscriptText(transcript, {
  stripBracketedMarkers: true,
  dedupeAdjacentLines: true,
});

const cleanedSegments = cleanTranscriptSegments(transcript.segments, {
  normalizeWhitespace: true,
});

console.log(cleanedText, cleanedSegments.length);

CLI

npx ytk <url>
npx ytk <url> --format txt
npx ytk <url> --format json
npx ytk <url> --format markdown
npx ytk <url> --languages de,en
npx ytk <url> --search "keyword"
npx ytk <url> --chunks --max-chars 4000
npx ytk batch urls.txt --format json
npx ytk batch urls.txt --concurrency 3
npx ytk search "typescript tutorial" --max-results 5
npx ytk search "typescript tutorial" --format json
npx ytk search "typescript tutorial" --transcripts --languages en
npx ytk channel @OpenAI --limit 10
npx ytk channel UCxxxxxxxxxxxxxxxxxxxxxx --order oldest --format json

Use npx ytk --help to print command help. ytk and yt-transcript-kit run the same CLI.

Typical CLI uses:

• --search prints matching transcript segments with their segment index.
• --chunks prints chunked transcript text, or structured JSON when combined with --format json.
• batch <file> --format json returns per-input success or failure records.
• search <query> prints video metadata and URLs from YouTube search results.
• search <query> --transcripts also attempts to fetch a transcript for each returned video.
• channel <channel-id-handle-or-url> prints videos from a channel videos page. Use --order newest|oldest and --limit <n>.

Error Codes

INVALID_VIDEO_ID, VIDEO_UNAVAILABLE, RATE_LIMITED, NO_TRANSCRIPT, LANGUAGE_NOT_AVAILABLE, REQUEST_FAILED, EMPTY_QUERY, SEARCH_FAILED.

Environment Notes

• Node.js 18+ is required.
• Standard browsers are not supported because YouTube transcript requests are blocked by CORS.
• Server runtimes, CLIs, browser extensions, and React Native are the intended environments.

Development

npm run build
npm run typecheck
npm run test