@np-dev/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
Special thanks to:
API to get search engine results with ease.
InnerTube is an API used by all YouTube clients. It was created to simplify the deployment of new features and experiments across the platform 1. This library manages all low-level communication with InnerTube, providing a simple and efficient way to interact with YouTube programmatically. Its design aims to closely emulate an actual client, including the parsing of API responses.
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(/* options */);
| Option | Type | Description | Default |
|---|---|---|---|
lang | string | Language. | en |
location | string | Geolocation. | US |
account_index | number | The account index to use. This is useful if you have multiple accounts logged in. NOTE: Only works if you are signed in with cookies. | 0 |
visitor_data | string | Setting this to a valid and persistent visitor data string will allow YouTube to give this session tailored content even when not logged in. A good way to get a valid one is by either grabbing it from a browser or calling InnerTube's /visitor_id endpoint. | undefined |
retrieve_player | boolean | Specifies whether to retrieve the JS player. Disabling this will make session creation faster. NOTE: Deciphering formats is not possible without the JS player. | true |
enable_safety_mode | boolean | Specifies whether to enable safety mode. This will prevent the session from loading any potentially unsafe content. | false |
generate_session_locally | boolean | Specifies whether to generate the session data locally or retrieve it from YouTube. This can be useful if you need more performance. | false |
device_category | DeviceCategory | Platform to use for the session. | DESKTOP |
client_type | ClientType | InnerTube client type. | WEB |
timezone | string | The time zone. | * |
cache | ICache | Used to cache the deciphering functions from the JS player. | undefined |
cookie | string | YouTube cookies. | undefined |
fetch | FetchFunction | Fetch function to use. | fetch |
To use YouTube.js in the browser, you must proxy requests through your own server. You can see our simple reference implementation in Deno at examples/browser/proxy/deno.ts.
You may provide your own fetch implementation to be used by YouTube.js, which we will use to modify and send the requests through a proxy. See examples/browser/web for a simple example using Vite.
// Multiple exports are available 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 = await 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.
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(
/* ... */
);
}
});
Caching the transformed player instance can greatly improve the performance. Our UniversalCache implementation uses different caching methods depending on the environment.
In Node.js, we use the node:fs module, Deno.writeFile() in Deno, and indexedDB in browsers.
By default, the cache stores data in the operating system's temporary directory (or indexedDB in browsers). You can make this cache persistent by specifying the path to the cache directory, which will be created if it doesn't exist.
import { Innertube, UniversalCache } from 'youtubei.js';
// Create a cache that stores files in the OS temp directory (or indexedDB in browsers) by default.
const yt = await Innertube.create({
cache: new UniversalCache(false)
});
// You may want to create a persistent cache instead (on Node and Deno).
const yt = await Innertube.create({
cache: new UniversalCache(
// Enables persistent caching
true,
// Path to the cache directory. The directory will be created if it doesn't exist
'./.cache'
)
});
Innertube
getInfo(target, client?)Retrieves video info.
Returns: Promise<VideoInfo>
| Param | Type | Description |
|---|---|---|
| target | string | NavigationEndpoint | If string, the id of the video. If NavigationEndpoint, the endpoint of watchable elements such as Video, Mix and Playlist. To clarify, valid endpoints have payloads containing at least videoId and optionally playlistId, params and index. |
| client? | InnerTubeClient | WEB, ANDROID, YTMUSIC, YTMUSIC_ANDROID or TV_EMBEDDED |
<info>#like()
<info>#dislike()
<info>#removeRating()
<info>#getLiveChat()
<info>#getTrailerInfo()
VideoInfo instance, or null if none. Typically available for non-purchased movies or films.<info>#chooseFormat(options)
<info>#toDash(url_transformer?, format_filter?)
<info>#download(options)
<info>#getTranscript()
<info>#filters
<info>#selectFilter(name)
VideoInfo.<info>#getWatchNextContinuation()
<info>#addToWatchHistory()
<info>#autoplay_video_endpoint
<info>#has_trailer
<info>#page
getBasicInfo(video_id, client?)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 |
search(query, filters?)Searches the given query on YouTube.
Returns: Promise<Search>
Note
Searchextends theFeedclass.
| Param | Type | Description |
|---|---|---|
| query | string | The search query |
| filters? | SearchFilters | Search filters |
| Filter | Type | Value | Description |
|---|---|---|---|
| upload_date | string | all | hour | today | week | month | year | Filter by upload date |
| type | string | all | video | channel | playlist | movie | Filter by type |
| duration | string | all | short | medium | long | Filter by duration |
| sort_by | string | relevance | rating | upload_date | view_count | Sort by |
| features | string[] | hd | subtitles | creative_commons | 3d | live | purchased | 4k | 360 | location | hdr | vr180 | Filter by features |
<search>#selectRefinementCard(SearchRefinementCard | string)
<search>#refinement_card_queries
refinement_cards object.<search>#getContinuation()
getSearchSuggestions(query)Retrieves search suggestions for given query.
Returns: Promise<string[]>
| Param | Type | Description |
|---|---|---|
| query | string | The search query |
getComments(video_id, sort_by?)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.
getHomeFeed()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()
getGuide()Retrieves YouTube's content guide.
Returns: Promise<Guide>
getLibrary()Retrieves the account's library.
Returns: Promise<Library>
Note
Libraryextends theFeedclass.
<library>#history<library>#watch_later<library>#liked_videos<library>#playlists_section<library>#clipsgetHistory()Retrieves watch history.
Returns: Promise<History>
Note
Historyextends theFeedclass.
<history>#getContinuation()
getTrending()Retrieves trending content.
Returns: Promise<TabbedFeed<IBrowseResponse>>
getSubscriptionsFeed()Retrieves the subscriptions feed.
Returns: Promise<Feed<IBrowseResponse>>
getChannel(id)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>#getReleases()<channel>#getPodcasts()<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.
getNotifications()Retrieves notifications.
Returns: Promise<NotificationsMenu>
<notifications>#getContinuation()
getUnseenNotificationsCount()Retrieves unseen notifications count.
Returns: Promise<number>
getPlaylist(id)Retrieves playlist contents.
Returns: Promise<Playlist>
Note
Playlistextends theFeedclass.
| Param | Type | Description |
|---|---|---|
| id | string | Playlist id |
<playlist>#items
getHashtag(hashtag)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()
getStreamingData(video_id, options)Returns deciphered streaming data.
Note This method will be deprecated in the future. We recommend retrieving streaming data from a
VideoInfoorTrackInfoobject instead if you want to select formats manually. Please refer to the following example:
const info = await yt.getBasicInfo('somevideoid');
const url = info.streaming_data?.formats[0].decipher(yt.session.player);
console.info('Playback url:', url);
// or:
const format = info.chooseFormat({ type: 'audio', quality: 'best' });
const url = format?.decipher(yt.session.player);
console.info('Playback url:', url);
Returns: Promise<object>
| Param | Type | Description |
|---|---|---|
| video_id | string | Video id |
| options | FormatOptions | Format options |
download(video_id, 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.
resolveURL(url)Resolves a given url.
Returns: Promise<NavigationEndpoint>
| Param | Type | Description |
|---|---|---|
| url | string | Url to resolve |
call(endpoint, args?)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 modular and easy to extend. Most of the 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. 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', {
// You can add any additional payloads here, and they'll merge with the default payload sent to InnerTube.
videoId,
client: 'YTMUSIC', // InnerTube client options: ANDROID, YTMUSIC, YTMUSIC_ANDROID, WEB, or TV_EMBEDDED.
parse: true // tells YouTube.js to parse the response (not sent to InnerTube).
});
return videoInfo;
}
const videoInfo = await getVideoInfo('jLTOuvBTLxA');
console.info(videoInfo);
})();
Alternatively, suppose we locate a NavigationEndpoint in a parsed response and want to see what happens when we call it:
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);
// Let's imagine that we wish to click on the “More” button:
const button = albums.as(YTNodes.MusicCarouselShelf).header?.more_content;
if (button) {
// Having ensured that it exists, we can then call its navigation endpoint using the following code:
const page = await button.endpoint.call(yt.actions, { parse: true });
console.info(page);
}
})();
YouTube.js' parser enables you to parse InnerTube responses and convert their nodes into strongly-typed objects that are simple to manipulate. Additionally, it provides numerous utility methods that make working with InnerTube a breeze.
Here's an example of its usage:
// See ./examples/parser
import { Parser, YTNodes } from 'youtubei.js';
import { readFileSync } from 'fs';
// YouTube Music's artist page response
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 uses a proxy object to add type safety and utility methods for working with InnerTube's data arrays:
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.
We welcome all contributions, issues and feature requests, whether small or large. If you want to contribute, feel free to check out our issues page and our guidelines.
We are immensely grateful to all the wonderful people who have contributed to this project. A special shoutout to all our contributors! 🎉
LuanRT - @thesciencephile - luanrt@thatsciencephile.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 used in this project are the property of their respective owners and are used solely to describe the services provided.
As such, any usage of trademarks to refer to such services is considered nominative use. If you have any questions or concerns, please contact me directly via email.
Distributed under the MIT License.
8.0.0 (2023-12-01)
getChannels() method and has_channels getter from the YT.Channel class, as they are no longer useful. The featured channels are now shown on the channel home tab. To get them you can use the channels getter on the home tab of the channel. Please note that some channel owners might not have added that section to their home page yet, so you won't be able to get the featured channels for those channels. The home tab is the default tab that is returned when you call InnerTube#getChannel(), you can also access that tab by calling getHome() on a YT.Channel object.FeedNudge (#533) (e021395)VideoAttributeView (#531) (ff4ab16)ChannelOwnerEmptyState (#541) (b60930a)ClipSection (#532) (9007b65)contentType to audio and video adaption sets (#539) (4806fc6)overrides instead of --legacy-peer-deps (#529) (db7f620)getChannels() and has_channels, as YouTube removed the tab (#542) (6a5a579)ReelShelf to list of possible nodes (f74ed5a)image and overflow_menu_on_tap props (5ae15be)FAQs
A wrapper around YouTube's private API. Supports YouTube, YouTube Music, YouTube Kids and YouTube Studio (WIP).
The npm package @np-dev/youtubei-js receives a total of 139 weekly downloads. As such, @np-dev/youtubei-js popularity was classified as not popular.
We found that @np-dev/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.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.