YouTube.js

<!-- BADGE LINKS --> <!-- OTHER LINKS --> <div align="center"> <br/> <p> <a href="https://github.com/LuanRT/YouTube.js"><img src="https://luanrt.github.io/assets/img/ytjs.svg" title="youtube.js" alt="YouTube.js' Github Page" width="200" /></a> </p> <p align="center">A full-featured wrapper around the InnerTube API</p>

<h5> Sponsored by&nbsp;&nbsp;&nbsp;&nbsp;<a href="https://serpapi.com"><img src="https://luanrt.github.io/assets/img/serpapi.svg" alt="SerpApi - API to get search engine results with ease." height=35 valign="middle"></a> </h5> <br> </div>

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.

Table of Contents

<ol> <li><a href="#prerequisites">Prerequisites</a></li> <li><a href="#installation">Installation</a></li> <li> <a href="#usage">Usage</a> <ul> <li><a href="#browser-usage">Browser Usage</a></li> <li><a href="#caching">Caching</a></li> <li><a href="#api">API</a></li> <li><a href="#extending-the-library">Extending the library</a></li> </ul> </li> <li><a href="#contributing">Contributing</a></li> <li><a href="#contact">Contact</a></li> <li><a href="#disclaimer">Disclaimer</a></li> <li><a href="#license">License</a></li> </ol>

Prerequisites

YouTube.js runs on Node.js, Deno, and modern browsers.

It requires a runtime with the following features:

• fetch
  • On Node, we use undici's fetch implementation, which requires Node.js 16.8+. If you need to use an older version, you may provide your own fetch implementation. See providing your own fetch implementation for more information.
  • The 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 return a non-standard Readable object.)
• EventTarget and CustomEvent are required.

Installation

# 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';

Usage

Create an InnerTube instance:

// const { Innertube } = require('youtubei.js');
import { Innertube } from 'youtubei.js';
const youtube = await Innertube.create(/* options */);

Options

<details> <summary>Click to expand</summary>

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
po_token	string	Proof of Origin Token. This is an attestation token generated by BotGuard/DroidGuard. It is used to confirm that the request is coming from a genuine device. To obtain a valid token, please refer to Invidious' Trusted Session Generator.	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. NOTE: If you are using the cache option and a session has already been generated, this will be ignored. If you want to force a new session to be generated, you must clear the cache or disable session caching.	false
enable_session_cache	boolean	Specifies whether to cache the session data.	true
device_category	DeviceCategory	Platform to use for the session.	DESKTOP
client_type	ClientType	InnerTube client type. It is not recommended to change this unless you know what you are doing.	WEB
timezone	string	The time zone.	*
cache	ICache	Used to cache algorithms, session data, and OAuth2 tokens.	undefined
cookie	string	YouTube cookies.	undefined
fetch	FetchFunction	Fetch function to use.	fetch

</details>

Browser Usage

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);
  }
});

Streaming

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.

<a name="custom-fetch"></a>

Providing your own fetch implementation

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(
      /* ... */
    );
  }
});

<a name="caching"></a>

Caching

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' 
  )
});

API

• Innertube

  <details> <summary>Properties</summary> <p>
  • .session
  • .account
  • .interact
  • .playlist
  • .music
  • .studio
  • .kids
  </p> </details> <details> <summary>Methods</summary> <p>
  • .getInfo(target, client?)
  • .getBasicInfo(video_id, client?)
  • .search(query, filters?)
  • .getSearchSuggestions(query)
  • .getComments(video_id, sort_by?)
  • .getHomeFeed()
  • .getGuide()
  • .getLibrary()
  • .getHistory()
  • .getTrending()
  • .getSubscriptionsFeed()
  • .getChannel(id)
  • .getNotifications()
  • .getUnseenNotificationsCount()
  • .getPlaylist(id)
  • .getHashtag(hashtag)
  • .getStreamingData(video_id, options)
  • .download(video_id, options?)
  • .resolveURL(url)
  • .call(endpoint, args?)
  </p> </details>

<a name="getinfo"></a>

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	InnerTube client to use.

<details> <summary>Methods & Getters</summary> <p>

• <info>#like()

  • Likes the video.

• <info>#dislike()

  • Dislikes the video.

• <info>#removeRating()

  • Removes like/dislike.

• <info>#getLiveChat()

  • Returns a LiveChat instance.

• <info>#getTrailerInfo()

  • Returns trailer info in a new VideoInfo instance, or null if none. Typically available for non-purchased movies or films.

• <info>#chooseFormat(options)

  • Used to choose streaming data formats.

• <info>#toDash(url_transformer?, format_filter?)

  • Converts streaming data to an MPEG-DASH manifest.

• <info>#download(options)

  • Downloads the video. See download.

• <info>#getTranscript()

  • Retrieves the video's transcript.

• <info>#filters

  • Returns filters that can be applied to the watch next feed.

• <info>#selectFilter(name)

  • Applies the given filter to the watch next feed and returns a new instance of VideoInfo.

• <info>#getWatchNextContinuation()

  • Retrieves the next batch of items for the watch next feed.

• <info>#addToWatchHistory()

  • Adds the video to the watch history.

• <info>#autoplay_video_endpoint

  • Returns the endpoint of the video for Autoplay.

• <info>#has_trailer

  • Checks if trailer is available.

• <info>#page

  • Returns original InnerTube response (sanitized).

</p> </details>

<a name="getbasicinfo"></a>

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	InnerTube client to use.

<a name="search"></a>

search(query, filters?)

Searches the given query on YouTube.

Returns: Promise<Search>

Note Search extends the Feed class.

Param	Type	Description
query	string	The search query
filters?	SearchFilters	Search filters

<details> <summary>Search Filters</summary>

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 |