youtubei.js
Advanced tools
A full-featured wrapper around the InnerTube API, which is what YouTube itself uses.
Scrape Google and other search engines from a fast, easy and complete API. |
InnerTube is an API used across all YouTube clients, it was created to simplify1 the internal structure of the platform in a way that updates, tweaks, and experiments can be easily made. This library handles all the low-level communication with InnerTube, providing a simple, fast, and efficient way to interact with YouTube programmatically.
If you have any questions or need help, feel free to contact us on our chat server 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
TODO: Deno install instructions (esm.sh possibly?)
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.
// Pre-bundled version for the web
import { Innertube } from 'youtubei.js/bundle/browser';
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';
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);
Our browser example in examples/browser/web provides a fully working example.
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()
});
// 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 or YTMUSIC |
<info>#like()
<info>#dislike()
<info>#removeLike()
<info>#getLiveChat()
<info>#chooseFormat(options)
<info>#toDash(url_transformer)
<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 or YTMUSIC |
Searches the given query on YouTube.
Returns: Promise.<Search>
| 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.<FilterableFeed>
Retrieves the account's library.
Returns: Promise.<Library>
<library>#history<library>#watch_later<library>#liked_videos<library>#playlists<library>#clips<library>#page
Retrieves watch history.
Returns: Promise.<History>
<history>#getContinuation()
Retrieves trending content.
Returns: Promise.<TabbedFeed>
Retrieves subscriptions feed.
Returns: Promise.<Feed>
Retrieves contents for a given channel.
Returns: Promise.<Channel>
| Param | Type | Description |
|---|---|---|
| id | string | Channel id |
<channel>#getVideos()<channel>#getPlaylists()<channel>#getHome()<channel>#getCommunity()<channel>#getChannels()<channel>#getAbout()See ./examples/channel for examples.
Retrieves notifications.
Returns: Promise.<NotificationsMenu>
<notifications>#getContinuation()
Retrieves unseen notifications count.
Returns: Promise.<number>
Retrieves playlist contents.
Returns: Promise.<Playlist>
| Param | Type | Description |
|---|---|---|
| id | string | Playlist id |
<playlist>#items
Returns deciphered streaming data.
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.
Utility to call navigation endpoints.
Returns: Promise.<ActionsResponse | ParsedResponse>
| Param | Type | Description |
|---|---|---|
| endpoint | NavigationEndpoint | The target endpoint |
| args? | object | Additional payload arguments |
Something cool about YouTube.js is that it is completely modular and easy to tinker with. 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, you may want to call an endpoint directly, that can be achieved with the Actions class:
// ...
const payload = {
videoId: 'jLTOuvBTLxA',
client: 'YTMUSIC', // InnerTube client, can be ANDROID, YTMUSIC, WEB
parse: true // tells YouTube.js to parse the response, this is not sent to InnerTube.
};
const response = await yt.actions.execute('/player', payload);
console.info(response);
Or maybe there's an interesting NavigationEndpoint in a parsed response and we want to call it to see what happens:
// ...
const artist = await yt.music.getArtist('UC52ZqHVQz5OoGhvbWiRal6g');
const albums = artist.sections[1].as(MusicCarouselShelf);
// Say we have a button and want to “click” it
const button = albums.as(MusicCarouselShelf).header?.more_content;
if (button) {
// To do that, we can call its navigation endpoint:
const page = await button.endpoint.call(yt.actions, 'YTMUSIC', true);
console.info(page);
}
If you're working on an extension for the library or just want to have nicely typed and sanitized InnerTube responses for a project then have a look at our powerful parser!
// See ./examples/parser
import { Parser } from 'youtubei.js';
import SectionList from 'youtubei.js/dist/src/parser/classes/SectionList';
import SingleColumnBrowseResults from 'youtubei.js/dist/src/parser/classes/SingleColumnBrowseResults';
import MusicVisualHeader from 'youtubei.js/dist/src/parser/classes/MusicVisualHeader';
import MusicImmersiveHeader from 'youtubei.js/dist/src/parser/classes/MusicImmersiveHeader';
import MusicCarouselShelf from 'youtubei.js/dist/src/parser/classes/MusicCarouselShelf';
import MusicDescriptionShelf from 'youtubei.js/dist/src/parser/classes/MusicDescriptionShelf';
import MusicShelf from 'youtubei.js/dist/src/parser/classes/MusicShelf';
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(MusicImmersiveHeader, 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(SingleColumnBrowseResults).tabs.get({ selected: false });
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(SectionList).contents.array().as(MusicCarouselShelf, MusicDescriptionShelf, MusicShelf);
console.info('Sections:', sections);
Detailed documentation 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.
LuanRT - @lrt_nooneknows - 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.
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.