0
# ytdl-core
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: ytdl-core
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install ytdl-core`
10

11
## Core Imports
12

13
```javascript
14
const ytdl = require('ytdl-core');
15
```
16

17
For TypeScript:
18

19
```typescript
20
import ytdl from 'ytdl-core'; // with --esModuleInterop
21
import * as ytdl from 'ytdl-core'; // with --allowSyntheticDefaultImports
22
import ytdl = require('ytdl-core'); // with neither of the above
23
```
24

25
## Basic Usage
26

27
```javascript
28
const fs = require('fs');
29
const ytdl = require('ytdl-core');
30

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

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

39
// Choose specific format
40
const format = ytdl.chooseFormat(info.formats, { quality: 'highestaudio' });
41
const stream = ytdl.downloadFromInfo(info, { format });
42
```
43

44
## Architecture
45

46
ytdl-core is built around several key components:
47

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

55
## Capabilities
56

57
### Video Downloading
58

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

61
```javascript { .api }
62
function ytdl(url, options);
63

64
interface downloadOptions {
65
  range?: { start?: number; end?: number };
66
  begin?: string | number | Date;
67
  liveBuffer?: number;
68
  highWaterMark?: number;
69
  IPv6Block?: string;
70
  dlChunkSize?: number;
71
  quality?: string | number | string[] | number[];
72
  filter?: string | function;
73
  format?: object;
74
  lang?: string;
75
  requestCallback?: function;
76
  requestOptions?: object;
77
}
78
```
79

80
[Video Downloading](./video-downloading.md)
81

82
### Video Information
83

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

86
```javascript { .api }
87
function getInfo(url, options);
88
function getBasicInfo(url, options);
89

90
interface getInfoOptions {
91
  lang?: string;
92
  requestCallback?: function;
93
  requestOptions?: object;
94
}
95

96
interface videoInfo {
97
  videoDetails: VideoDetails;
98
  formats: videoFormat[];
99
  player_response: object;
100
  related_videos: relatedVideo[];
101
}
102
```
103

104
[Video Information](./video-information.md)
105

106
### Format Selection
107

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

110
```javascript { .api }
111
function chooseFormat(formats, options);
112
function filterFormats(formats, filter);
113

114
interface chooseFormatOptions {
115
  quality?: string | number | string[] | number[];
116
  filter?: string | function;
117
  format?: object;
118
}
119
```
120

121
[Format Selection](./format-selection.md)
122

123
### URL Processing
124

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

127
```javascript { .api }
128
function validateID(id);
129
function validateURL(url);
130
function getURLVideoID(url);
131
function getVideoID(str);
132
```
133

134
[URL Processing](./url-processing.md)
135

136
### Cache Access
137

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

140
```javascript { .api }
141
ytdl.cache = {
142
  sig: object,    // Signature decryption cache
143
  info: object,   // Video info cache
144
  watch: object,  // Watch page cache
145
  cookie: object  // Authentication cookie cache
146
};
147
```
148

149
### Caption/Subtitle Support
150

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

153
```javascript { .api }
154
// Captions are available in player_response.captions
155
interface CaptionData {
156
  playerCaptionsRenderer: {
157
    baseUrl: string;
158
    visibility: string;
159
  };
160
  playerCaptionsTracklistRenderer: {
161
    captionTracks: captionTrack[];
162
    audioTracks: audioTrack[];
163
    translationLanguages: translationLanguage[];
164
    defaultAudioTrackIndex: number;
165
  };
166
}
167

168
interface audioTrack {
169
  captionTrackIndices: number[];
170
}
171

172
interface translationLanguage {
173
  languageCode: string;
174
  languageName: { simpleText: string };
175
}
176
```
177

178
### Version Information
179

180
Package version information.
181

182
```javascript { .api }
183
ytdl.version: string;  // Package version from package.json
184
```
185

186
## Types
187

188
```javascript { .api }
189
interface videoFormat {
190
  itag: number;
191
  url: string;
192
  mimeType?: string;
193
  bitrate?: number;
194
  audioBitrate?: number;
195
  width?: number;
196
  height?: number;
197
  initRange?: { start: string; end: string };
198
  indexRange?: { start: string; end: string };
199
  lastModified: string;
200
  contentLength: string;
201
  quality: string;
202
  qualityLabel: string;
203
  projectionType?: string;
204
  fps?: number;
205
  averageBitrate?: number;
206
  audioQuality?: string;
207
  colorInfo?: {
208
    primaries: string;
209
    transferCharacteristics: string;
210
    matrixCoefficients: string;
211
  };
212
  highReplication?: boolean;
213
  approxDurationMs?: string;
214
  targetDurationSec?: number;
215
  maxDvrDurationSec?: number;
216
  audioSampleRate?: string;
217
  audioChannels?: number;
218
  
219
  // Added by ytdl-core
220
  container: string;
221
  hasVideo: boolean;
222
  hasAudio: boolean;
223
  codecs: string;
224
  videoCodec?: string;
225
  audioCodec?: string;
226
  isLive: boolean;
227
  isHLS: boolean;
228
  isDashMPD: boolean;
229
}
230

231
interface VideoDetails {
232
  videoId: string;
233
  title: string;
234
  shortDescription: string;
235
  lengthSeconds: string;
236
  keywords?: string[];
237
  channelId: string;
238
  isOwnerViewing: boolean;
239
  isCrawlable: boolean;
240
  thumbnails: thumbnail[];
241
  averageRating: number;
242
  allowRatings: boolean;
243
  viewCount: string;
244
  author: string;
245
  isPrivate: boolean;
246
  isUnpluggedCorpus: boolean;
247
  isLiveContent: boolean;
248
}
249

250
interface thumbnail {
251
  url: string;
252
  width: number;
253
  height: number;
254
}
255

256
interface Author {
257
  id: string;
258
  name: string;
259
  avatar: string;
260
  thumbnails?: thumbnail[];
261
  verified: boolean;
262
  user?: string;
263
  channel_url: string;
264
  external_channel_url?: string;
265
  user_url?: string;
266
  subscriber_count?: number;
267
}
268

269
interface Media {
270
  category: string;
271
  category_url: string;
272
  game?: string;
273
  game_url?: string;
274
  year?: number;
275
  song?: string;
276
  artist?: string;
277
  artist_url?: string;
278
  writers?: string;
279
  licensed_by?: string;
280
  thumbnails: thumbnail[];
281
}
282

283
interface captionTrack {
284
  baseUrl: string;
285
  name: { simpleText: string };
286
  vssId: string;
287
  languageCode: string;
288
  kind: string;
289
  rtl?: boolean;
290
  isTranslatable: boolean;
291
}
292

293
interface relatedVideo {
294
  id?: string;
295
  title?: string;
296
  published?: string;
297
  author: Author | string;
298
  short_view_count_text?: string;
299
  view_count?: string;
300
  length_seconds?: number;
301
  thumbnails: thumbnail[];
302
  richThumbnails: thumbnail[];
303
  isLive: boolean;
304
}
305
```