YouTube.js/README_v2.0.0WIP.md

YouTube.js

A full-featured wrapper around the Innertube API, which is what YouTube itself uses.

Report Bug · Request Feature

---

WIP- Documentation for YouTube.js 2.0.0

Table of Contents

1. About The Project
   • Features
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Contributing
5. License
6. Contact
7. Disclaimer

About

Innertube is an API used across all YouTube clients, it was created to simplify¹ 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.

And huge thanks to @gatecrasher777 for his research on the workings of the Innertube API!

If you have any questions or need help, feel free to contact us on our chat server here.

Getting Started

Prerequisites

YouTube.js runs on Node.js, Deno and in 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+. You may provide your own fetch implementation if you need to use an older version. 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 returns a non-standard Readable object.)
• EventTarget and CustomEvent required.

Installation

• NPM:

npm install youtubei.js@latest

• Yarn:

yarn add youtubei.js@latest

• Git (bleeding-edge version):

npm install git+https://github.com/LuanRT/YouTube.js.git

TODO: Deno install instructions (esm.sh possibly?)

Usage

Create an Innertube instance (or session):

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

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 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 to through our proxy. See examples/browser/web for an 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);
  }
});

Streaming

YouTube.js supports streaming of videos in the browser by converting YouTube's streaming data into a 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 full working example.

Providing your own fetch implementation

You may provide your own fetch implementation to be used by YouTube.js. This may 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

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

API

Innertube : object

• Innertube : object
  • .getInfo(video_id) ⇒ function
  • .getBasicInfo(video_id) ⇒ function
  • .search(query, filters?) ⇒ function

getInfo(video_id)

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

Methods & Getters:

• <info>#like()

  • Likes the video.

• <info>#dislike()

  • Dislikes the video.

• <info>#removeLike()

  • Removes like/dislike.

• <info>#filters

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

• <info>#selectFilter(name)

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

• <info>#getWatchNextContinuation()

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

• <info>#page

  • Returns original InnerTube response (sanitized).

getBasicInfo(video_id)

Suitable for cases where you only need basic video metadata, much faster than getInfo().

Returns: Promise.<VideoInfo>

Param	Type	Description
video_id	string	The id of the video

search(query, filters?)

Searches the given query on YouTube.

Returns: Promise.<Search>

Param	Type	Description
query	string	The search query
filters	object	Search filters

Supported search filters:

• type: all | video | channel | playlist | movie
• upload_date: all | hour | today | week | month | year
• duration: all | short | medium | long
• sort_by: relevance | rating | upload_date | view_count

Methods & Getters:

• <search>#selectRefinementCard(SearchRefinementCard | string)

  • Applies given refinement card and returns a new Search instance.

• <search>#refinement_card_queries

  • Returns available refinement cards, this is a simplified version of the refinement cards object.

• <search>#getContinuation()

  • Retrieves next batch of results.

getHomeFeed()

Retrieves YouTube's home feed.

Returns: Promise.<FilterableFeed>

Contributing

Contributions, issues and feature requests are welcome. Feel free to check issues page if you want to contribute.

Contributors

Contact

LuanRT - @lrt_nooneknows - luan.lrt4@gmail.com

Project Link: https://github.com/LuanRT/YouTube.js

Disclaimer

This project is not affiliated with, endorsed, or sponsored by YouTube or any of their 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.

License

Distributed under the MIT License.

(back to top)

---

1. https://gizmodo.com/how-project-innertube-helped-pull-youtube-out-of-the-gu-1704946491 ↩︎