0
# Video Information
1

2
Comprehensive metadata extraction including video details, available formats, thumbnails, captions, and related videos. Provides both basic and full information retrieval with caching support.
3

4
## Capabilities
5

6
### Get Full Video Information
7

8
Retrieves complete video metadata including all formats with deciphered download URLs.
9

10
```javascript { .api }
11
/**
12
 * Gets complete video metadata including deciphered formats
13
 * @param {string} url - YouTube video URL or video ID
14
 * @param {getInfoOptions} options - Request options
15
 * @returns {Promise<videoInfo>} - Complete video information
16
 */
17
async function getInfo(url, options);
18

19
interface getInfoOptions {
20
  lang?: string;              // Language code for metadata (default: 'en')
21
  requestCallback?: function; // Callback for request streams
22
  requestOptions?: object;    // Options passed to miniget requests
23
}
24
```
25

26
**Usage Examples:**
27

28
```javascript
29
// Basic info retrieval
30
const info = await ytdl.getInfo('https://www.youtube.com/watch?v=aqz-KE-bpKQ');
31
console.log(info.videoDetails.title);
32
console.log(`Available formats: ${info.formats.length}`);
33

34
// With language preference
35
const info = await ytdl.getInfo(videoUrl, { lang: 'es' });
36

37
// With request options
38
const info = await ytdl.getInfo(videoUrl, {
39
  requestOptions: {
40
    headers: {
41
      'User-Agent': 'Custom User Agent'
42
    }
43
  }
44
});
45

46
// With request callback for monitoring
47
const info = await ytdl.getInfo(videoUrl, {
48
  requestCallback: (req) => {
49
    console.log(`Making request to: ${req.url}`);
50
  }
51
});
52
```
53

54
### Get Basic Video Information
55

56
Retrieves basic video metadata without deciphering format URLs (faster but limited).
57

58
```javascript { .api }
59
/**
60
 * Gets basic video metadata without deciphered URLs (faster)
61
 * @param {string} url - YouTube video URL or video ID
62
 * @param {getInfoOptions} options - Request options
63
 * @returns {Promise<videoInfo>} - Basic video information (full: false)
64
 */
65
async function getBasicInfo(url, options);
66
```
67

68
**Usage Examples:**
69

70
```javascript
71
// Quick metadata retrieval
72
const basicInfo = await ytdl.getBasicInfo(videoUrl);
73
console.log(basicInfo.videoDetails.title);
74
console.log(basicInfo.videoDetails.lengthSeconds);
75

76
// Note: Cannot use with downloadFromInfo()
77
// This will throw an error:
78
// ytdl.downloadFromInfo(basicInfo, options); // ERROR!
79
```
80

81
## Video Information Structure
82

83
### Main Video Info Object
84

85
```javascript { .api }
86
interface videoInfo {
87
  videoDetails: VideoDetails;        // Core video metadata
88
  formats: videoFormat[];           // Available download formats
89
  player_response: object;          // Raw YouTube player response
90
  related_videos: relatedVideo[];   // Related video suggestions
91
  full: boolean;                    // true for getInfo(), false for getBasicInfo()
92
  
93
  // Additional metadata from YouTube's response
94
  iv_load_policy?: string;
95
  iv_allow_in_place_switch?: string;
96
  fade_in_start_milliseconds?: string;
97
  fade_in_duration_milliseconds?: string;
98
  fade_out_start_milliseconds?: string;
99
  fade_out_duration_milliseconds?: string;
100
  // ... many more YouTube-specific fields
101
}
102
```
103

104
### Video Details
105

106
Core video metadata and information.
107

108
```javascript { .api }
109
interface VideoDetails {
110
  videoId: string;              // 11-character YouTube video ID
111
  title: string;                // Video title
112
  shortDescription: string;     // Video description
113
  lengthSeconds: string;        // Duration in seconds (as string)
114
  keywords?: string[];          // Video tags/keywords
115
  channelId: string;           // Channel ID
116
  isOwnerViewing: boolean;     // Whether owner is viewing
117
  isCrawlable: boolean;        // Whether video is crawlable
118
  thumbnails: thumbnail[];     // Video thumbnails
119
  averageRating: number;       // Average rating (deprecated by YouTube)
120
  allowRatings: boolean;       // Whether ratings are enabled
121
  viewCount: string;           // View count (as string)
122
  author: string;              // Channel name
123
  isPrivate: boolean;          // Whether video is private
124
  isUnpluggedCorpus: boolean;  // YouTube Premium content flag
125
  isLiveContent: boolean;      // Whether content is/was live
126
}
127
```
128

129
### Enhanced Video Details
130

131
Extended video information available in the info object.
132

133
```javascript { .api }
134
interface MoreVideoDetails {
135
  // Extends VideoDetails with additional fields
136
  published: number;           // Publication timestamp
137
  video_url: string;          // Full YouTube URL
138
  age_restricted: boolean;    // Age restriction status
139
  likes: number | null;       // Like count (may be null if hidden)
140
  dislikes: number | null;    // Dislike count (deprecated by YouTube)
141
  media: Media;               // Media/music information
142
  author: Author;             // Extended author information
143
  thumbnails: thumbnail[];    // Video thumbnails
144
  storyboards: storyboard[];  // Video preview thumbnails
145
  chapters: Chapter[];        // Video chapters
146
  description: string | null; // Full description
147
}
148

149
interface storyboard {
150
  templateUrl: string;
151
  thumbnailWidth: number;
152
  thumbnailHeight: number;
153
  thumbnailCount: number;
154
  interval: number;
155
  columns: number;
156
  rows: number;
157
  storyboardCount: number;
158
}
159

160
interface Chapter {
161
  title: string;
162
  start_time: number;
163
}
164
```
165

166
### Video Format Information
167

168
Detailed format specifications for each available download option.
169

170
```javascript { .api }
171
interface videoFormat {
172
  itag: number;                    // Format identifier
173
  url: string;                     // Download URL (deciphered in getInfo())
174
  mimeType?: string;               // MIME type (e.g., 'video/mp4; codecs="avc1.640028"')
175
  bitrate?: number;                // Video bitrate
176
  audioBitrate?: number;           // Audio bitrate
177
  width?: number;                  // Video width in pixels
178
  height?: number;                 // Video height in pixels
179
  initRange?: { start: string; end: string };  // Initialization range
180
  indexRange?: { start: string; end: string }; // Index range
181
  lastModified: string;            // Last modified timestamp
182
  contentLength: string;           // Content length in bytes
183
  quality: string;                 // Quality descriptor
184
  qualityLabel: string;            // Human-readable quality (e.g., '720p')
185
  projectionType?: string;         // Video projection type
186
  fps?: number;                    // Frames per second
187
  averageBitrate?: number;         // Average bitrate
188
  audioQuality?: string;           // Audio quality descriptor
189
  colorInfo?: object;              // Color space information
190
  approxDurationMs?: string;       // Approximate duration
191
  targetDurationSec?: number;      // Target duration for segments
192
  maxDvrDurationSec?: number;      // Max DVR duration for live
193
  audioSampleRate?: string;        // Audio sample rate
194
  audioChannels?: number;          // Number of audio channels
195
  
196
  // Added by ytdl-core
197
  container: string;               // Container format ('mp4', 'webm', etc.)
198
  hasVideo: boolean;               // Whether format includes video
199
  hasAudio: boolean;               // Whether format includes audio
200
  codecs: string;                  // Codec information
201
  videoCodec?: string;             // Video codec
202
  audioCodec?: string;             // Audio codec
203
  isLive: boolean;                 // Whether format is for live content
204
  isHLS: boolean;                  // Whether format uses HLS
205
  isDashMPD: boolean;              // Whether format uses DASH
206
}
207
```
208

209
### Thumbnails
210

211
Video thumbnail information in various sizes.
212

213
```javascript { .api }
214
interface thumbnail {
215
  url: string;    // Thumbnail image URL
216
  width: number;  // Width in pixels
217
  height: number; // Height in pixels
218
}
219
```
220

221
### Related Videos
222

223
Information about related/suggested videos.
224

225
```javascript { .api }
226
interface relatedVideo {
227
  id?: string;                    // Video ID
228
  title?: string;                 // Video title
229
  published?: string;             // Publication date
230
  author: Author | string;        // Channel information
231
  short_view_count_text?: string; // Abbreviated view count
232
  view_count?: string;            // Full view count
233
  length_seconds?: number;        // Duration in seconds
234
  thumbnails: thumbnail[];        // Video thumbnails
235
  richThumbnails: thumbnail[];    // Rich thumbnails
236
  isLive: boolean;               // Whether video is live
237
}
238
```
239

240
### Author/Channel Information
241

242
Extended channel/author metadata.
243

244
```javascript { .api }
245
interface Author {
246
  id: string;                    // Channel ID
247
  name: string;                  // Channel name
248
  avatar: string;                // Avatar URL (deprecated)
249
  thumbnails?: thumbnail[];      // Channel thumbnails
250
  verified: boolean;             // Verification status
251
  user?: string;                 // Username
252
  channel_url: string;           // Channel URL
253
  external_channel_url?: string; // External channel URL
254
  user_url?: string;             // User URL
255
  subscriber_count?: number;     // Subscriber count
256
}
257
```
258

259
### Caption/Subtitle Information
260

261
Available captions and subtitle tracks.
262

263
```javascript { .api }
264
interface captionTrack {
265
  baseUrl: string;                    // Caption file URL
266
  name: { simpleText: string };       // Language name
267
  vssId: string;                      // Voice search service ID
268
  languageCode: string;               // Language code (e.g., 'en', 'es')
269
  kind: string;                       // Caption kind
270
  rtl?: boolean;                      // Right-to-left text
271
  isTranslatable: boolean;            // Whether translatable
272
}
273
```
274

275
## Usage Patterns
276

277
### Examining Video Details
278

279
```javascript
280
const info = await ytdl.getInfo(videoUrl);
281

282
// Basic video information
283
console.log(`Title: ${info.videoDetails.title}`);
284
console.log(`Duration: ${info.videoDetails.lengthSeconds} seconds`);
285
console.log(`Views: ${info.videoDetails.viewCount}`);
286
console.log(`Author: ${info.videoDetails.author}`);
287

288
// Extended information
289
console.log(`Published: ${new Date(info.videoDetails.published * 1000)}`);
290
console.log(`Likes: ${info.videoDetails.likes}`);
291
console.log(`Age Restricted: ${info.videoDetails.age_restricted}`);
292
```
293

294
### Working with Formats
295

296
```javascript
297
const info = await ytdl.getInfo(videoUrl);
298

299
// List all available formats
300
info.formats.forEach(format => {
301
  console.log(`${format.itag}: ${format.qualityLabel} ${format.container} ` +
302
              `(${format.hasVideo ? 'V' : ''}${format.hasAudio ? 'A' : ''})`);
303
});
304

305
// Find best quality format with both audio and video
306
const bestFormat = info.formats
307
  .filter(f => f.hasVideo && f.hasAudio)
308
  .sort((a, b) => b.bitrate - a.bitrate)[0];
309
```
310

311
### Handling Captions
312

313
```javascript
314
const info = await ytdl.getInfo(videoUrl);
315

316
if (info.player_response.captions) {
317
  const captionTracks = info.player_response.captions.playerCaptionsTracklistRenderer.captionTracks;
318
  
319
  // List available caption languages
320
  captionTracks.forEach(track => {
321
    console.log(`${track.name.simpleText}: ${track.languageCode}`);
322
  });
323
  
324
  // Get English captions URL
325
  const englishTrack = captionTracks.find(track => track.languageCode === 'en');
326
  if (englishTrack) {
327
    console.log(`English captions: ${englishTrack.baseUrl}`);
328
  }
329
}
330
```
331

332
### Performance Considerations
333

334
```javascript
335
// Use getBasicInfo() when you only need metadata
336
const basicInfo = await ytdl.getBasicInfo(videoUrl);
337
if (basicInfo.videoDetails.isPrivate) {
338
  console.log('Video is private, cannot download');
339
  return;
340
}
341

342
// Only call getInfo() when you need formats or plan to download
343
const fullInfo = await ytdl.getInfo(videoUrl);
344
const stream = ytdl.downloadFromInfo(fullInfo, options);
345
```