ytcog

YouTube innertube class library for node-js; session, searches, channels, playlists, videos and downloads.

Features

• Simple, efficient, fast, powerful.
• No Google developer key required.
• The innertube api is what the YouTube website itself uses to efficiently deliver search, channel and video information (json only).
• The downloader is a forked process allowing for concurrent non-blocking, high quality downloads.

Classes

• Session - manage your Youtube session/player - deciphering, encoding and hashing - enables seemless search, channel, playlist, video and download requests.
• Search - fetch videos, playlists and channels from specific search requests.
• Channel - fetch metadata, videos, playlists, associated channels or search specific channels.
• Playlist - fetch videos from specific playlists
• Video - fetch metadata and stream information deciphered/encoded to avoid throttling - ensure reliable and fast downloads.
• Download - a convenience object for easy once-off, sessionless, downloads.

See the wiki for greater detail.

Basic Usage

Easy downloader

const ytcog = require('ytcog');
await ytcog.dl(videoOptions[,cookie,userAgent]);

videoOptions (object) See the wiki for alll videoOptions.
cookie (string) is optional. With a cookie, everything will work. Without it, age-restricted video streams will not be retrieved and there might be some rate-limiting (although none reported so far)
userAgent (string) is optional. Since ytcog emulates a browser session, you can make all requests use your browser's user agent.

Session

const ytcog = require('ytcog');
const session = new ytcog.Session([cookie, userAgent]);
await session.fetch();

In order to obtain your youtube cookie and user agent: Log onto YouTube in your browser. Goto settings > ... > developer tools. Refresh the page. Goto network>headers. Find the "www.youtube.com" entry. In the request headers you will find "cookie" and "user-agent". Pass these string values in your ytcog sessions.

A session object is required to create searches, channels, playlists and videos.

Search

const search = new ytcog.Search(session, searchOptions);
await search.fetch();

session (Session) the session object
searchOptions (Object) See the wiki for all search options.

Search again with different options:

await search.fetch({items: 'videos', period:'year', order: 'views', features: 'hd', quantity: 500 });

Examine the results in an array of Video objects:

search.videos.forEach((video)=>{
    // do something with the results, like collect and display their streams
    await video.fetch();
    console.log(video.info());
    console.log(video.streamInfo);
});

Also search for playlists, channels and movies that match your search term

await search.fetch({items:'playlists'});
await search.fetch({items:'channels'});
await search.fetch({items:'movies'});

Iterate through the current results with:

search.results.forEach((item)=>{});

Or the accumulated results

search.playlists.forEach((playlist)=>{...});
search.channels.forEach((channel)=>{...});
search.videos.forEach((video)=>{...});

Channel

const channel = new ytcog.Channel(session, channelOptions);
await channel.fetch();

channelOptions See wiki for all channel options.

Get channel playlists

await channel.fetch({items: 'playlists', order: 'updated', quantity: 90});

Get associated channels

await channel.fetch({items: 'channels'});

Search a channel

await channel.fetch({items: 'search', query: 'vlogs'});

Iterate through the results with:

search.results.forEach((item)=>{});  //current
channel.videos.forEach((video)=>{...}); //accumulated
channel.playlists.forEach((playlist)=>{...}); //accumulated
channel.channels.forEach((chan)=>{...}); //accumulated

Playlist

const playlist = new ytcog.Playlist(session, playlistOptions);
await playlist.fetch();

playlistOptions See wiki for all playlist options.

Get 100 videos from a playlist

await playlist.fetch({quantity:100});

Get all the videos from a playlist

await playlist.fetch({quantity: playlist.videoCount});

Iterate through the results with:

playlist.results.forEach((video)=>{...}) //current
playlist.videos.forEach((video)=>{...}); //accumulated

Video

const video = new ytcog.Video(session, videoOptions);
await video.fetch();
if (video.status == 'OK') await video.download();

videoOptions See wiki for all video options.

Examples

Check the examples folder for more clarity on usage of Session, Search, Channel, Playlist and Video classes.

To tun the examples:

~ytcog$ node examples/session_test
~ytcog$ node examples/search_test [query]
~ytcog$ node examples/channel_test [id]
~ytcog$ node examples/playlist_test [id]
~ytcog$ node examples/video_test [id]
~ytcog$ node examples/dl_test [id]

Install

npm install ytcog

Disclaimer

YouTube can and will change how their innertube api works at any time. So potential disruptions are likely in the future. I will try to evolve and adapt this library asap, but without gaurantees.

Command Line Interface

Try out the command line interface (CLI) to this library:

• ytcog-dl

Acknowledgement

To the following node-js projects on which ytcog has a dependency:

• miniget (robust web requests)
• ffmpeg-static (muxing video and audio downloads; embedding metadata as necessary)
• sanitize-filename (as the name suggests)