Video details

Use video() when you already know which video you want and need more detail than a search result provides.

IDs and URLs both work

const byId = await yt.video('jNQXAC9IVRw');
const byUrl = await yt.video(
  'https://www.youtube.com/watch?v=jNQXAC9IVRw',
);

byId.id; // 'jNQXAC9IVRw' — same video either way

Common watch, youtu.be, shorts, embed, and live URL forms are accepted. Internally, the SDK extracts the video ID before requesting metadata.

Read the result

const video = await yt.video('jNQXAC9IVRw');

video.title; // 'Me at the zoo'
video.channel.name; // 'jawed'
video.durationSeconds; // 19
video.viewCount; // 403522943
video.publishedAt; // '2005-04-23T20:31:52-07:00'
video.captions; // [{ languageCode: 'en', name: 'English', isAutoGenerated: false, … }, …]

Optional values are undefined when YouTube did not supply them. The SDK does not turn a missing like count into zero. Dates remain strings so their original meaning is preserved.

Choose full or basic mode

By default, the SDK enriches player metadata with another request. This can add likes, comments, channel subscribers, and the channel avatar.

When those values do not matter, basic mode skips the enrichment request:

const video = await yt.video('jNQXAC9IVRw', { basic: true });

Basic mode is useful for a quick lookup or a large job that only needs core fields. It trades completeness for less work; it does not change the object type.

Full mode can also add optional heatmap and chapters timeline data. See frame-level data for mapping those signals and transcript timestamps to storyboard preview frames.

Read several videos

const results = await yt.videos(videoIds, { concurrency: 2 });

results[0].value.title; // 'Me at the zoo'
results[1].value.title; // 'Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)'

Use the plural method when each target should succeed or fail independently. See concurrency before increasing the limit, and handling errors for reading each result.