Getting Started

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

# Deno
deno add npm:youtubei.js@latest

Deno (deprecated):

import { Innertube } from 'https://deno.land/x/youtubei/deno.ts';

Basic Usage

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

Configuration Options

lang (string)

  • Description: Language for the session.
  • Default: en

location (string)

  • Description: Geolocation setting.
  • Default: US

user_agent (string)

  • Description: User agent for InnerTube requests.
  • Default: undefined

account_index (number)

  • Description: The account index to use. This is useful if you have multiple accounts logged in. Works only with cookies.
  • Default: 0

on_behalf_of_user (string)

  • Description: Page ID of the YouTube profile/channel to use, if the logged-in account has multiple profiles.
  • Default: undefined

visitor_data (string)

  • Description: A persistent visitor data string that allows YouTube to provide tailored content even when not logged in.
  • Default: undefined

po_token (string)

  • Description: Session-bound Proof of Origin Token (attestation token) used to confirm the request is from a real client.
  • Default: undefined

player_id (string)

  • Description: Player ID override. Can be used to work around temporary issues when YouTube introduces breaking changes by forcing an older player.
  • Default: undefined

retrieve_player (boolean)

  • Description: Specifies whether to retrieve the JS player. Disabling this will make session creation faster, but deciphering formats will not be possible.
  • Default: true

enable_safety_mode (boolean)

  • Description: Enables YouTube's safety mode, which prevents potentially unsafe content from being loaded.
  • Default: false

retrieve_innertube_config (boolean)

  • Description: Specifies whether to retrieve the InnerTube config. Useful for "onesie" requests.
  • Default: true

generate_session_locally (boolean)

  • Description: Generates session data locally instead of retrieving it from YouTube for better performance. This is ignored if a session is already cached.
  • Default: false

enable_session_cache (boolean)

  • Description: Caches session data for future use.
  • Default: true

device_category (string)

  • Description: Platform type for session (DESKTOP, MOBILE, etc.).
  • Default: DESKTOP

client_type (string)

  • Description: InnerTube client type (WEB, ANDROID, etc.).
  • Default: WEB

timezone (string)

  • Description: Time zone for the session.
  • Default: *

cache (ICache)

  • Description: Cache implementation.
  • Default: undefined
  • Description: Cookies for authenticated sessions.
  • Default: undefined

fetch (FetchFunction)

  • Description: Custom fetch implementation.
  • Default: fetch

Providing a Custom JavaScript Interpreter

Some features, such as deciphering streaming URLs, require executing YouTube's obfuscated JavaScript code. YouTube.js does not include a built-in interpreter for this purpose, so you must provide your own.

Below is an example using JavaScript's Function constructor:

import { Innertube, Platform, Types } from 'youtubei.js/web';

Platform.shim.eval = async (data: Types.BuildScriptResult, env: Record<string, Types.VMPrimative>) => {
  const properties = [];

  if(env.n) {
    properties.push(`n: exportedVars.nFunction("${env.n}")`)
  }

  if (env.sig) {
    properties.push(`sig: exportedVars.sigFunction("${env.sig}")`)
  }

  const code = `${data.output}\nreturn { ${properties.join(', ')} }`;

  return new Function(code)();
}

const innertube = await Innertube.create(/* options */);
// ...