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
```