youtubei.js
Advanced tools
A wrapper around YouTube's private API. Supports YouTube, YouTube Music, YouTube Kids and YouTube Studio (WIP).
A full-featured wrapper around the InnerTube API
Scrape Google and other search engines from a fast, easy and complete API. |
InnerTube is an API used by all YouTube clients. It was created to simplify the deployment of new features and experiments across the platform1. This library handles all the low-level communication with InnerTube, providing a simple, and efficient way to interact with YouTube programmatically. It is designed to emulate an actual client as closely as possible, including how API responses are parsed.
If you have any questions or need help, feel free to reach out to us on our Discord server or open an issue here.
YouTube.js runs on Node.js, Deno, and modern browsers.
It requires a runtime with the following features:
fetch
Response object returned by fetch must thus be spec compliant and return a ReadableStream object if you want to use the VideoInfo#download method. (Implementations like node-fetch returns a non-standard Readable object.)EventTarget and CustomEvent are required.# NPM
npm install youtubei.js@latest
# Yarn
yarn add youtubei.js@latest
# Git (edge version)
npm install github:LuanRT/YouTube.js
When using Deno, you can import YouTube.js directly from deno.land:
import { Innertube } from 'https://deno.land/x/youtubei/deno.ts';
Create an InnerTube instance:
// const { Innertube } = require('youtubei.js');
import { Innertube } from 'youtubei.js';
const youtube = await Innertube.create();
To use YouTube.js in the browser you must proxy requests through your own server. You can see our simple reference implementation in Deno in examples/browser/proxy/deno.ts.
You may provide your own fetch implementation to be used by YouTube.js. Which we will use here to modify and send the requests through our proxy. See examples/browser/web for a simple example using Vite.
// We provide multiple exports for the web.
// Unbundled ESM version
import { Innertube } from 'youtubei.js/web';
// Bundled ESM version
// import { Innertube } from 'youtubei.js/web.bundle';
// Production Bundled ESM version
// import { Innertube } from 'youtubei.js/web.bundle.min';
await Innertube.create({
fetch: async (input: RequestInfo | URL, init?: RequestInit) => {
// Modify the request
// and send it to the proxy
// fetch the URL
return fetch(request, init);
}
});
YouTube.js supports streaming of videos in the browser by converting YouTube's streaming data into an MPEG-DASH manifest.
The example below uses dash.js to play the video.
import { Innertube } from 'youtubei.js/web';
import dashjs from 'dashjs';
const youtube = await Innertube.create({ /* setup - see above */ });
// get the video info
const videoInfo = await youtube.getInfo('videoId');
// now convert to a dash manifest
// again - to be able to stream the video in the browser - we must proxy the requests through our own server
// to do this, we provide a method to transform the URLs before writing them to the manifest
const manifest = videoInfo.toDash(url => {
// modify the url
// and return it
return url;
});
const uri = "data:application/dash+xml;charset=utf-8;base64," + btoa(manifest);
const videoElement = document.getElementById('video_player');
const player = dashjs.MediaPlayer().create();
player.initialize(videoElement, uri, true);
A fully working example can be found in examples/browser/web. Alternatively, you can view it live at ytjsexample.pages.dev.
You may provide your own fetch implementation to be used by YouTube.js. This can be useful in some cases to modify the requests before they are sent and transform the responses before they are returned (eg. for proxies).
// provide a fetch implementation
const yt = await Innertube.create({
fetch: async (input: RequestInfo | URL, init?: RequestInit) => {
// make the request with your own fetch implementation
// and return the response
return new Response(
/* ... */
);
}
});
To improve performance, you may wish to cache the transformed player instance which we use to decode the streaming urls.
Our cache uses the node:fs module in Node-like environments, Deno.writeFile in Deno, and indexedDB in browsers.
import { Innertube, UniversalCache } from 'youtubei.js';
// By default, cache stores files in the OS temp directory (or indexedDB in browsers).
const yt = await Innertube.create({
cache: new UniversalCache(false)
});
// You may wish to make the cache persistent (on Node and Deno)
const yt = await Innertube.create({
cache: new UniversalCache(
// Enables persistent caching
true,
// Path to the cache directory will create the directory if it doesn't exist
'./.cache'
)
});
Innertube
Retrieves video info, including playback data and even layout elements such as menus, buttons, etc — all nicely parsed.
Returns: Promise<VideoInfo>
| Param | Type | Description |
|---|---|---|
| video_id | string | The id of the video |
| client? | InnerTubeClient | WEB, ANDROID, YTMUSIC, YTMUSIC_ANDROID or TV_EMBEDDED |
<info>#like()
<info>#dislike()
<info>#removeRating()
<info>#getLiveChat()
<info>#chooseFormat(options)
<info>#toDash(url_transformer?, format_filter?)
<info>#download(options)
<info>#filters
<info>#selectFilter(name)
VideoInfo.<info>#getWatchNextContinuation()
<info>#addToWatchHistory()
<info>#page
Suitable for cases where you only need basic video metadata. Also, it is faster than getInfo().
Returns: Promise<VideoInfo>
| Param | Type | Description |
|---|---|---|
| video_id | string | The id of the video |
| client? | InnerTubeClient | WEB, ANDROID, YTMUSIC_ANDROID, YTMUSIC, TV_EMBEDDED |
Searches the given query on YouTube.
Returns: Promise<Search>
Note
Searchextends theFeedclass.
| Param | Type | Description |
|---|---|---|
| query | string | The search query |
| filters? | SearchFilters | Search filters |
<search>#selectRefinementCard(SearchRefinementCard | string)
<search>#refinement_card_queries
refinement_cards object.<search>#getContinuation()
Retrieves search suggestions for given query.
Returns: Promise<string[]>
| Param | Type | Description |
|---|---|---|
| query | string | The search query |
Retrieves comments for given video.
Returns: Promise<Comments>
| Param | Type | Description |
|---|---|---|
| video_id | string | The video id |
| sort_by | string | Can be: TOP_COMMENTS or NEWEST_FIRST |
See ./examples/comments for examples.
Retrieves YouTube's home feed.
Returns: Promise<HomeFeed>
Note
HomeFeedextends theFilterableFeedclass.
<home_feed>#videos
<home_feed>#posts
<home_feed>#shelves
<home_feed>#filters
<home_feed>#applyFilter(name | ChipCloudChip)
<home_feed>#getContinuation()
Retrieves YouTube's content guide.
Returns: Promise<Guide>
Retrieves the account's library.
Returns: Promise<Library>
Note
Libraryextends theFeedclass.
<library>#history<library>#watch_later<library>#liked_videos<library>#playlists_section<library>#clipsRetrieves watch history.
Returns: Promise<History>
Note
Historyextends theFeedclass.
<history>#getContinuation()
Retrieves trending content.
Returns: Promise<TabbedFeed<IBrowseResponse>>
Retrieves the subscriptions feed.
Returns: Promise<Feed<IBrowseResponse>>
Retrieves contents for a given channel.
Returns: Promise<Channel>
Note
Channelextends theTabbedFeedclass.
| Param | Type | Description |
|---|---|---|
| id | string | Channel id |
<channel>#getVideos()<channel>#getShorts()<channel>#getLiveStreams()<channel>#getPlaylists()<channel>#getHome()<channel>#getCommunity()<channel>#getChannels()<channel>#getAbout()<channel>#search(query)<channel>#applyFilter(filter)<channel>#applyContentTypeFilter(content_type_filter)<channel>#applySort(sort)<channel>#getContinuation()<channel>#filters<channel>#content_type_filters<channel>#sort_filters<channel>#pageSee ./examples/channel for examples.
Retrieves notifications.
Returns: Promise<NotificationsMenu>
<notifications>#getContinuation()
Retrieves unseen notifications count.
Returns: Promise<number>
Retrieves playlist contents.
Returns: Promise<Playlist>
Note
Playlistextends theFeedclass.
| Param | Type | Description |
|---|---|---|
| id | string | Playlist id |
<playlist>#items
Retrieves a given hashtag's page.
Returns: Promise<HashtagFeed>
Note
HashtagFeedextends theFilterableFeedclass.
| Param | Type | Description |
|---|---|---|
| hashtag | string | The hashtag |
<hashtag>#applyFilter(filter)
HashtagFeed instance.<hashtag>#getContinuation()
Returns deciphered streaming data.
Note This will be deprecated in the future. It is recommended to retrieve streaming data from a
VideoInfo/TrackInfoobject instead if you want to select formats manually, see the example below.
const info = await yt.getBasicInfo('somevideoid');
const url = info.streaming_data?.formats[0].decipher(yt.session.player);
console.info('Playback url:', url);
Returns: Promise<object>
| Param | Type | Description |
|---|---|---|
| video_id | string | Video id |
| options | FormatOptions | Format options |
Downloads a given video.
Returns: Promise<ReadableStream<Uint8Array>>
| Param | Type | Description |
|---|---|---|
| video_id | string | Video id |
| options | DownloadOptions | Download options |
See ./examples/download for examples.
Resolves a given url.
Returns: Promise<NavigationEndpoint>
| Param | Type | Description |
|---|---|---|
| url | string | Url to resolve |
Utility to call navigation endpoints.
Returns: Promise<T extends IParsedResponse | IParsedResponse | ApiResponse>
| Param | Type | Description |
|---|---|---|
| endpoint | NavigationEndpoint | The target endpoint |
| args? | object | Additional payload arguments |
YouTube.js is completely modular and easy to extend. Almost all methods, classes, and utilities used internally are exposed and can be used to implement your own extensions without having to modify the library's source code.
For example, let's say we want to implement a method to retrieve video info manually. We can do that by using an instance of the Actions class:
import { Innertube } from 'youtubei.js';
(async () => {
const yt = await Innertube.create();
async function getVideoInfo(videoId: string) {
const videoInfo = await yt.actions.execute('/player', {
// anything added here will be merged with the default payload and sent to InnerTube.
videoId,
client: 'YTMUSIC', // InnerTube client, can be ANDROID, YTMUSIC, YTMUSIC_ANDROID, WEB or TV_EMBEDDED
parse: true // tells YouTube.js to parse the response, this is not sent to InnerTube.
});
return videoInfo;
}
const videoInfo = await getVideoInfo('jLTOuvBTLxA');
console.info(videoInfo);
})();
Or perhaps there's a NavigationEndpoint in a parsed response and we want to call it to see what happens:
import { Innertube, YTNodes } from 'youtubei.js';
(async () => {
const yt = await Innertube.create();
const artist = await yt.music.getArtist('UC52ZqHVQz5OoGhvbWiRal6g');
const albums = artist.sections[1].as(YTNodes.MusicCarouselShelf);
// Say we want to click the “More” button:
const button = albums.as(YTNodes.MusicCarouselShelf).header?.more_content;
if (button) {
// After making sure it exists, we can call its navigation endpoint:
const page = await button.endpoint.call(yt.actions, { parse: true });
console.info(page);
}
})();
YouTube.js' parser allows you to parse InnerTube responses and turn their nodes into strongly typed objects that can be easily manipulated. It also provides a set of utility methods that make working with InnerTube much easier.
Example:
// See ./examples/parser
import { Parser, YTNodes } from 'youtubei.js';
import { readFileSync } from 'fs';
// Artist page response from YouTube Music
const data = readFileSync('./artist.json').toString();
const page = Parser.parseResponse(JSON.parse(data));
const header = page.header?.item().as(YTNodes.MusicImmersiveHeader, YTNodes.MusicVisualHeader);
console.info('Header:', header);
/**
* The parser encapsulates all arrays in a proxy object.
* A proxy intercepts access to the actual data, allowing
* the parser to add type safety and many utility methods
* that make working with InnerTube much easier.
*/
const tab = page.contents?.item().as(YTNodes.SingleColumnBrowseResults).tabs.firstOfType(YTNodes.Tab);
if (!tab)
throw new Error('Target tab not found');
if (!tab.content)
throw new Error('Target tab appears to be empty');
const sections = tab.content?.as(YTNodes.SectionList).contents.as(YTNodes.MusicCarouselShelf, YTNodes.MusicDescriptionShelf, YTNodes.MusicShelf);
console.info('Sections:', sections);
Documentation for the parser can be found here.
Contributions, issues, and feature requests are welcome. Feel free to check the issues page and our guidelines if you want to contribute.
Thank you to all the wonderful people who have contributed to this project:
LuanRT - @thesciencephile - luan.lrt4@gmail.com
Project Link: https://github.com/LuanRT/YouTube.js
This project is not affiliated with, endorsed, or sponsored by YouTube or any of its affiliates or subsidiaries. All trademarks, logos, and brand names are the property of their respective owners and are used only to directly describe the services being provided, as such, any usage of trademarks to refer to such services is considered nominative use.
Should you have any questions or concerns please contact me directly via email.
Distributed under the MIT License.
3.2.0 (2023-03-08)
FormatUtils' types (2d774e2)banner to PlaylistHeader (#337) (95033e7)game_info and category (#333) (214aa14)SearchSubMenu node (#340) (a511608)getGuide() (#335) (2cc7b8b)FAQs
A JavaScript client for YouTube's private API, known as InnerTube.
The npm package youtubei.js receives a total of 22,973 weekly downloads. As such, youtubei.js popularity was classified as popular.
We found that youtubei.js demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Ransomware negotiators share how modern cybercriminals operate like corporations, using specialized teams, negotiation tactics, and reputation management.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.