or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

format-selection.mdindex.mdurl-processing.mdvideo-downloading.mdvideo-information.md
tile.json

tessl/npm-ytdl-core

YouTube video downloader in pure JavaScript with streaming interface and comprehensive metadata extraction.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/ytdl-core@4.11.x

To install, run

npx @tessl/cli install tessl/npm-ytdl-core@4.11.0

index.mddocs/

ytdl-core

ytdl-core is a pure JavaScript YouTube video downloader that enables developers to programmatically download YouTube videos and extract comprehensive video metadata. It provides a streaming interface for efficient memory usage, supports various video formats and quality options, and includes TypeScript definitions for enhanced development experience.

Package Information

  • Package Name: ytdl-core
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install ytdl-core

Core Imports

const ytdl = require('ytdl-core');

For TypeScript:

import ytdl from 'ytdl-core'; // with --esModuleInterop
import * as ytdl from 'ytdl-core'; // with --allowSyntheticDefaultImports
import ytdl = require('ytdl-core'); // with neither of the above

Basic Usage

const fs = require('fs');
const ytdl = require('ytdl-core');

// Basic video download
ytdl('http://www.youtube.com/watch?v=aqz-KE-bpKQ')
  .pipe(fs.createWriteStream('video.mp4'));

// Get video information
const info = await ytdl.getInfo('http://www.youtube.com/watch?v=aqz-KE-bpKQ');
console.log(info.videoDetails.title);

// Choose specific format
const format = ytdl.chooseFormat(info.formats, { quality: 'highestaudio' });
const stream = ytdl.downloadFromInfo(info, { format });

Architecture

ytdl-core is built around several key components:

  • Streaming Interface: Main download function returns Node.js readable streams for efficient memory usage
  • Metadata Extraction: Comprehensive video information parsing including formats, thumbnails, and captions
  • Format Selection: Smart format choosing based on quality, container, and codec preferences
  • URL Processing: Robust YouTube URL parsing and video ID extraction
  • Signature Deciphering: Handles YouTube's dynamic signature algorithms for protected content
  • Caching System: Multiple cache layers for signatures, video info, and authentication tokens

Capabilities

Video Downloading

Core streaming download functionality for YouTube videos with extensive configuration options and progress tracking.

function ytdl(url, options);

interface downloadOptions {
  range?: { start?: number; end?: number };
  begin?: string | number | Date;
  liveBuffer?: number;
  highWaterMark?: number;
  IPv6Block?: string;
  dlChunkSize?: number;
  quality?: string | number | string[] | number[];
  filter?: string | function;
  format?: object;
  lang?: string;
  requestCallback?: function;
  requestOptions?: object;
}

Video Downloading

Video Information

Comprehensive metadata extraction including video details, available formats, thumbnails, captions, and related videos.

function getInfo(url, options);
function getBasicInfo(url, options);

interface getInfoOptions {
  lang?: string;
  requestCallback?: function;
  requestOptions?: object;
}

interface videoInfo {
  videoDetails: VideoDetails;
  formats: videoFormat[];
  player_response: object;
  related_videos: relatedVideo[];
}

Video Information

Format Selection

Advanced format selection utilities for choosing optimal video and audio formats based on quality, codec, and container preferences.

function chooseFormat(formats, options);
function filterFormats(formats, filter);

interface chooseFormatOptions {
  quality?: string | number | string[] | number[];
  filter?: string | function;
  format?: object;
}

Format Selection

URL Processing

URL validation and video ID extraction supporting all YouTube URL formats including shortened URLs and embed links.

function validateID(id);
function validateURL(url);
function getURLVideoID(url);
function getVideoID(str);

URL Processing

Cache Access

Provides access to internal caches for advanced use cases and debugging.

ytdl.cache = {
  sig: object,    // Signature decryption cache
  info: object,   // Video info cache
  watch: object,  // Watch page cache
  cookie: object  // Authentication cookie cache
};

Caption/Subtitle Support

Access to video captions and subtitle tracks through the video info object.

// Captions are available in player_response.captions
interface CaptionData {
  playerCaptionsRenderer: {
    baseUrl: string;
    visibility: string;
  };
  playerCaptionsTracklistRenderer: {
    captionTracks: captionTrack[];
    audioTracks: audioTrack[];
    translationLanguages: translationLanguage[];
    defaultAudioTrackIndex: number;
  };
}

interface audioTrack {
  captionTrackIndices: number[];
}

interface translationLanguage {
  languageCode: string;
  languageName: { simpleText: string };
}

Version Information

Package version information.

ytdl.version: string;  // Package version from package.json

Types

interface videoFormat {
  itag: number;
  url: string;
  mimeType?: string;
  bitrate?: number;
  audioBitrate?: number;
  width?: number;
  height?: number;
  initRange?: { start: string; end: string };
  indexRange?: { start: string; end: string };
  lastModified: string;
  contentLength: string;
  quality: string;
  qualityLabel: string;
  projectionType?: string;
  fps?: number;
  averageBitrate?: number;
  audioQuality?: string;
  colorInfo?: {
    primaries: string;
    transferCharacteristics: string;
    matrixCoefficients: string;
  };
  highReplication?: boolean;
  approxDurationMs?: string;
  targetDurationSec?: number;
  maxDvrDurationSec?: number;
  audioSampleRate?: string;
  audioChannels?: number;
  
  // Added by ytdl-core
  container: string;
  hasVideo: boolean;
  hasAudio: boolean;
  codecs: string;
  videoCodec?: string;
  audioCodec?: string;
  isLive: boolean;
  isHLS: boolean;
  isDashMPD: boolean;
}

interface VideoDetails {
  videoId: string;
  title: string;
  shortDescription: string;
  lengthSeconds: string;
  keywords?: string[];
  channelId: string;
  isOwnerViewing: boolean;
  isCrawlable: boolean;
  thumbnails: thumbnail[];
  averageRating: number;
  allowRatings: boolean;
  viewCount: string;
  author: string;
  isPrivate: boolean;
  isUnpluggedCorpus: boolean;
  isLiveContent: boolean;
}

interface thumbnail {
  url: string;
  width: number;
  height: number;
}

interface Author {
  id: string;
  name: string;
  avatar: string;
  thumbnails?: thumbnail[];
  verified: boolean;
  user?: string;
  channel_url: string;
  external_channel_url?: string;
  user_url?: string;
  subscriber_count?: number;
}

interface Media {
  category: string;
  category_url: string;
  game?: string;
  game_url?: string;
  year?: number;
  song?: string;
  artist?: string;
  artist_url?: string;
  writers?: string;
  licensed_by?: string;
  thumbnails: thumbnail[];
}

interface captionTrack {
  baseUrl: string;
  name: { simpleText: string };
  vssId: string;
  languageCode: string;
  kind: string;
  rtl?: boolean;
  isTranslatable: boolean;
}

interface relatedVideo {
  id?: string;
  title?: string;
  published?: string;
  author: Author | string;
  short_view_count_text?: string;
  view_count?: string;
  length_seconds?: number;
  thumbnails: thumbnail[];
  richThumbnails: thumbnail[];
  isLive: boolean;
}