commit 52b74004421cafc50081bc1ef970d0cfa4e887c1 Author: LuanRT Date: Fri Feb 17 04:23:49 2023 +0000 chore: v3.0.0 release diff --git a/LICENSE b/LICENSE new file mode 100644 index 00000000..3659f9e0 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2021 LuanRT + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 00000000..cd6db460 --- /dev/null +++ b/README.md @@ -0,0 +1,759 @@ + +[npm]: https://www.npmjs.com/package/youtubei.js +[versions]: https://www.npmjs.com/package/youtubei.js?activeTab=versions +[codefactor]: https://www.codefactor.io/repository/github/luanrt/youtube.js +[actions]: https://github.com/LuanRT/YouTube.js/actions +[say-thanks]: https://saythanks.io/to/LuanRT +[github-sponsors]:https://github.com/sponsors/LuanRT + + +[project]: https://github.com/LuanRT/YouTube.js +[twitter]: https://twitter.com/thesciencephile +[discord]: https://discord.gg/syDu7Yks54 +[nodejs]: https://nodejs.org + +

YouTube.js

+ +

A full-featured wrapper around the InnerTube API

+ +

+ + [![CI](https://github.com/LuanRT/YouTube.js/actions/workflows/test.yml/badge.svg)][actions] + [![NPM Version](https://img.shields.io/npm/v/youtubei.js?color=%2335C757)][versions] + [![Codefactor](https://www.codefactor.io/repository/github/luanrt/youtube.js/badge)][codefactor] + [![Downloads](https://img.shields.io/npm/dt/youtubei.js)][npm] + [![Discord](https://img.shields.io/badge/discord-online-brightgreen.svg)][discord] + [![Say thanks](https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg)][say-thanks] +
+ [![Donate](https://img.shields.io/badge/donate-30363D?style=for-the-badge&logo=GitHub-Sponsors&logoColor=#white)][github-sponsors] + +

+ +

+ _{Special thanks to:} +

+ + + + + + + +

+ + SerpApi

+
+ + _{+ Scrape Google and other search engines from a fast, easy and complete API.
+} + + +

+ +___ + +

Table of Contents

+ About +
+ Getting Started +
- Prerequisites
- Installation
+
+ Usage +
- Browser Usage
- Caching
- API
+
Extending the library
Contributing
Contact
Disclaimer
License

+ +## Description + +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 handles all the low-level communication with InnerTube, providing a simple, and efficient way to interact with YouTube programmatically. It is designed to emulate an actual client as closely as possible, including how API responses are parsed. + +If you have any questions or need help, feel free to reach out to us on our [Discord server][discord] or open an issue [here](https://github.com/LuanRT/YouTube.js/issues). + +## Getting Started + +### Prerequisites +YouTube.js runs on Node.js, Deno, and modern browsers. + +It requires a runtime with the following features: +- [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) + - On Node we use [undici]()'s fetch implementation which requires Node.js 16.8+. You may provide your fetch implementation if you need to use an older version. See [providing your own fetch implementation](#custom-fetch) 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`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget) and [`CustomEvent`](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) are required. + +### Installation + +```bash +# 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 (deno.land) + +## Usage +Create an InnerTube instance: +```ts +// 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`](https://github.com/LuanRT/YouTube.js/tree/main/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`](https://github.com/LuanRT/YouTube.js/tree/main/examples/browser/web) for a simple example using [Vite](https://vitejs.dev/). + +```ts +// 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 an MPEG-DASH manifest. + +The example below uses [`dash.js`](https://github.com/Dash-Industry-Forum/dash.js) to play the video. + +```ts +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); +``` + +A fully working example can be found in [`examples/browser/web`](https://github.com/LuanRT/YouTube.js/blob/main/examples/browser/web). Alternatively, you can view it live at [ytjsexample.pages.dev](https://ytjsexample.pages.dev/). + + + +## 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). +```ts +// 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. + +```ts +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` + +

Objects

+ + * [.session](https://github.com/LuanRT/YouTube.js/blob/main/docs/API/session.md) + * [.account](https://github.com/LuanRT/YouTube.js/blob/main/docs/API/account.md) + * [.interact](https://github.com/LuanRT/YouTube.js/blob/main/docs/API/interaction-manager.md) + * [.playlist](https://github.com/LuanRT/YouTube.js/blob/main/docs/API/playlist.md) + * [.music](https://github.com/LuanRT/YouTube.js/blob/main/docs/API/music.md) + * [.studio](https://github.com/LuanRT/YouTube.js/blob/main/docs/API/studio.md) + * [.kids](https://github.com/LuanRT/YouTube.js/blob/main/docs/API/kids.md) + +

+ + +

Methods

+ + * [.getInfo(video_id, client?)](#getinfo) + * [.getBasicInfo(video_id, client?)](#getbasicinfo) + * [.search(query, filters?)](#search) + * [.getSearchSuggestions(query)](#getsearchsuggestions) + * [.getComments(video_id, sort_by?)](#getcomments) + * [.getHomeFeed()](#gethomefeed) + * [.getLibrary()](#getlibrary) + * [.getHistory()](#gethistory) + * [.getTrending()](#gettrending) + * [.getSubscriptionsFeed()](#getsubscriptionsfeed) + * [.getChannel(id)](#getchannel) + * [.getNotifications()](#getnotifications) + * [.getUnseenNotificationsCount()](#getunseennotificationscount) + * [.getPlaylist(id)](#getplaylist) + * [.getHashtag(hashtag)](#gethashtag) + * [.getStreamingData(video_id, options)](#getstreamingdata) + * [.download(video_id, options?)](#download) + * [.resolveURL(url)](#resolveurl) + * [.call(endpoint, args?)](#call) + +

+ + +### getInfo(video_id, client?) + +Retrieves video info, including playback data and even layout elements such as menus, buttons, etc — all nicely parsed. + +**Returns**: `Promise` + +| Param | Type | Description | +| --- | --- | --- | +| video_id | `string` | The id of the video | +| client? | `InnerTubeClient` | `WEB`, `ANDROID`, `YTMUSIC`, `YTMUSIC_ANDROID` or `TV_EMBEDDED` | + +

Methods & Getters

+ +- `#like()` + - Likes the video. + +- `#dislike()` + - Dislikes the video. + +- `#removeRating()` + - Removes like/dislike. + +- `#getLiveChat()` + - Returns a LiveChat instance. + +- `#chooseFormat(options)` + - Used to choose streaming data formats. + +- `#toDash(url_transformer?, format_filter?)` + - Converts streaming data to an MPEG-DASH manifest. + +- `#download(options)` + - Downloads the video. See [download](#download). + +- `#filters` + - Returns filters that can be applied to the watch next feed. + +- `#selectFilter(name)` + - Applies the given filter to the watch next feed and returns a new instance of [`VideoInfo`](https://github.com/LuanRT/YouTube.js/blob/main/src/parser/youtube/VideoInfo.ts). + +- `#getWatchNextContinuation()` + - Retrieves the next batch of items for the watch next feed. + +- `#addToWatchHistory()` + - Adds the video to the watch history. + +- `#page` + - Returns original InnerTube response (sanitized). + +

+ + +### getBasicInfo(video_id, client?) + +Suitable for cases where you only need basic video metadata. Also, it is faster than [`getInfo()`](#getinfo). + +**Returns**: `Promise` + +| 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` + +> **Note** +> `Search` extends the [`Feed`](https://github.com/LuanRT/YouTube.js/blob/main/docs/API/feed.md) class. + +| Param | Type | Description | +| --- | --- | --- | +| query | `string` | The search query | +| filters? | `SearchFilters` | Search filters | + +

Methods & Getters

+ +- `

#selectRefinementCard(SearchRefinementCard | string)` + - Applies given refinement card and returns a new Search instance. + +- `#refinement_card_queries` + - Returns available refinement cards, this is a simplified version of the `refinement_cards` object. + +- `#getContinuation()` + - Retrieves next batch of results. + +

+ + +### getSearchSuggestions(query) +Retrieves search suggestions for given query. + +**Returns**: `Promise` + +| Param | Type | Description | +| --- | --- | --- | +| query | `string` | The search query | + + +### getComments(video_id, sort_by?) +Retrieves comments for given video. + +**Returns**: `Promise` + +| Param | Type | Description | +| --- | --- | --- | +| video_id | `string` | The video id | +| sort_by | `string` | Can be: `TOP_COMMENTS` or `NEWEST_FIRST` | + +See [`./examples/comments`](https://github.com/LuanRT/YouTube.js/blob/main/examples/comments) for examples. + + +### getHomeFeed() +Retrieves YouTube's home feed. + +**Returns**: `Promise` + +> **Note** +> `HomeFeed` extends the [`FilterableFeed`](https://github.com/LuanRT/YouTube.js/blob/main/docs/API/filterable-feed.md) class. + +

Methods & Getters

+ +- `#videos` + - Returns all videos in the home feed. + +- `#posts` + - Returns all posts in the home feed. + +- `#shelves` + - Returns all shelves in the home feed. + +- `#filters` + - Returns available filters. + +- `#applyFilter(name | ChipCloudChip)` + - Applies given filter and returns a new HomeFeed instance. + +- `#getContinuation()` + - Retrieves feed continuation. + +

+ + +### getLibrary() +Retrieves the account's library. + +**Returns**: `Promise` + +> **Note** +> `Library` extends the [`Feed`](https://github.com/LuanRT/YouTube.js/blob/main/docs/API/feed.md) class. + +

Methods & Getters

+ +- `#history` +- `#watch_later` +- `#liked_videos` +- `#playlists_section` +- `#clips` + +

+ + +### getHistory() +Retrieves watch history. + +**Returns**: `Promise` + +> **Note** +> `History` extends the [`Feed`](https://github.com/LuanRT/YouTube.js/blob/main/docs/API/feed.md) class. + +

Methods & Getters

+ +- `#getContinuation()` + - Retrieves next batch of contents. + +

+ + +### getTrending() +Retrieves trending content. + +**Returns**: `Promise>` + + +### getSubscriptionsFeed() +Retrieves the subscriptions feed. + +**Returns**: `Promise>` + + +### getChannel(id) +Retrieves contents for a given channel. + +**Returns**: `Promise` + +> **Note** +> `Channel` extends the [`TabbedFeed`](https://github.com/LuanRT/YouTube.js/blob/main/docs/API/tabbed-feed.md) class. + +| Param | Type | Description | +| --- | --- | --- | +| id | `string` | Channel id | + +

Methods & Getters

+ +- `#getVideos()` +- `#getShorts()` +- `#getLiveStreams()` +- `#getPlaylists()` +- `#getHome()` +- `#getCommunity()` +- `#getChannels()` +- `#getAbout()` +- `#search(query)` +- `#applyFilter(filter)` +- `#applyContentTypeFilter(content_type_filter)` +- `#applySort(sort)` +- `#getContinuation()` +- `#filters` +- `#content_type_filters` +- `#sort_filters` +- `#page` + +

+ +See [`./examples/channel`](https://github.com/LuanRT/YouTube.js/blob/main/examples/channel) for examples. + + +### getNotifications() +Retrieves notifications. + +**Returns**: `Promise` + +

Methods & Getter

+ +- `#getContinuation()` + - Retrieves next batch of notifications. + +

+ + +### getUnseenNotificationsCount() +Retrieves unseen notifications count. + +**Returns**: `Promise` + + +### getPlaylist(id) +Retrieves playlist contents. + +**Returns**: `Promise` + +> **Note** +> `Playlist` extends the [`Feed`](https://github.com/LuanRT/YouTube.js/blob/main/docs/API/feed.md) class. + +| Param | Type | Description | +| --- | --- | --- | +| id | `string` | Playlist id | + +

Methods & Getter

+ +- `#items` + - Returns the items of the playlist. + +

+ + +### getHashtag(hashtag) +Retrieves a given hashtag's page. + +**Returns**: `Promise` + +> **Note** +> `HashtagFeed` extends the [`FilterableFeed`](https://github.com/LuanRT/YouTube.js/blob/main/docs/API/filterable-feed.md) class. + +| Param | Type | Description | +| --- | --- | --- | +| hashtag | `string` | The hashtag | + +

Methods & Getter

+ +- `#applyFilter(filter)` + - Applies given filter and returns a new `HashtagFeed` instance. +- `#getContinuation()` + - Retrieves next batch of contents. + +

+ + +### getStreamingData(video_id, options) +Returns deciphered streaming data. + +> **Note** +> This will be deprecated in the future. It is recommended to retrieve streaming data from a `VideoInfo`/`TrackInfo` object instead if you want to select formats manually, see the example below. + +```ts +const info = await yt.getBasicInfo('somevideoid'); +const url = info.streaming_data?.formats[0].decipher(yt.session.player); +console.info('Playback url:', url); +``` + +**Returns**: `Promise