YTMusic API

YouTube Music API (Unofficial) is a YouTube Music data scraper. It comes with TypeScript support API for return types. The NPM Package can be found here

Motivation

I used to use youtube-music-api as my youtube music api data scraper. I liked looking into the source code of how it works but it never made sense to me. I also didn't like that there were no TypeScript annotations for the return types of methods. Because of this, I decided to build my own version of a youtube music api with TypeScript annotations, testing and written in a way I can understand.

Features

• TypeScript Support for data return types
  • Data from YouTube can be inconsistent but YTMusic API has been tested and the data matches the TypeScript types 95% of the time
• Scrape information directly from YouTube Music API
  • Search Suggestions
  • Songs
  • Videos
  • Artists
  • Albums
  • Playlists

Installation

With yarn

$ yarn add ytmusic-api

With npm

$ npm i ytmusic-api

Usage

Import YTMusic from the npm package

// TypeScript
import YTMusic from "ytmusic-api"

// JavaScript
const YTMusic = require("ytmusic-api")

Create an instance of the class YTMusic. Then, call the initialize() to initialize the API before using the API anywhere

const ytmusic = new YTMusic()
ytmusic.initialize().then(() => {
	// Use API here
})

Methods to fetch data

getSearchSuggestions

This function takes in the following parameters

Name	Data Type	Description
query	string	Search query you want suggestions for

The function returns a Promise<string[]> which are the suggestion results

ytmusic.getSearchSuggestions("Lilac").then(res => {
	console.log(res)
})

search

This function takes in the following parameters

Name	Data Type	Description
query	string	Search query
category	"SONG" | "VIDEO" | "ARTIST" | "ALBUM" | "PLAYLIST" | undefined	Type of results to search for. If not specified, returns all types of search result

The function when nothing is passed as the category returns a Promise<SearchResult[]> which are the search results of all categories

ytmusic.search("Lilac").then(results => {
	console.log(results)
})

search (category = "SONG")

When you pass in "SONG" as the category,

The function returns a Promise<SongDetailed[]> which are the song results

ytmusic.search("Lilac", "SONG").then(songs => {
	console.log(songs)
})

search (category = "VIDEO")

When you pass in "VIDEO" as the category,

The function returns a Promise<VideoDetailed[]> which are the video results

ytmusic.search("Lilac", "VIDEO").then(videos => {
	console.log(videos)
})

search (category = "ARTIST")

When you pass in "ARTIST" as the category

The function returns a Promise<ArtistDetailed[]> which are the artist results

ytmusic.search("Lilac", "ARTIST").then(artists => {
	console.log(artists)
})

search (category = "ALBUM")

When you pass in "ALBUM" as the category,

The function returns a Promise<AlbumDetailed[]> which are the album results

ytmusic.search("Lilac", "ALBUM").then(albums => {
	console.log(albums)
})

search (category = "PLAYLIST")

When you pass in "PLAYLIST" as the category,

The function returns a Promise<PlaylistFull[]> which are the playlist results

ytmusic.search("Lilac", "PLAYLIST").then(playlists => {
	console.log(playlists)
})

getSong

This function takes in the following parameters

Name	Data Type	Description
videoId	string	Video ID

The function returns a Promise<SongFull> which is the information about the song

ytmusic.getSong("v7bnOxV4jAc").then(song => {
	console.log(song)
})

getVideo

This function takes in the following parameters

Name	Data Type	Description
videoId	string	Video ID

The function returns a Promise<VideoFull> which is the information about the video

ytmusic.getVideo("v7bnOxV4jAc").then(video => {
	console.log(video)
})

getArtist

This function takes in the following parameters

Name	Data Type	Description
artistId	string	Artist ID

The function returns a Promise<ArtistFull> which is the information about the artist

ytmusic.getArtist("UCTUR0sVEkD8T5MlSHqgaI_Q").then(artist => {
	console.log(artist)
})

getArtistSongs

This function takes in the following parameters

Name	Data Type	Description
artistId	string	Artist ID

The function returns a Promise<SongDetailed[]> which is the information about all the artist's songs

ytmusic.getArtistSongs("UCTUR0sVEkD8T5MlSHqgaI_Q").then(artistSongs => {
	console.log(artistSongs)
})

getArtistAlbums

This function takes in the following parameters

Name	Data Type	Description
artistId	string	Artist ID

The function returns a Promise<AlbumDetailed[]> which is the information about all the artist's albums

ytmusic.getArtistAlbums("UCTUR0sVEkD8T5MlSHqgaI_Q").then(artistAlbums => {
	console.log(artistAlbums)
})

getAlbum

This function takes in the following parameters

Name	Data Type	Description
albumId	string	Album ID

The function returns a Promise<AlbumFull> which is the information about the album

ytmusic.getAlbum("MPREb_iG5q5DIdhdA").then(album => {
	console.log(album)
})

getPlaylist

This function takes in the following parameters

Name	Data Type	Description
playlistId	string	Playlist ID

The function returns a Promise<PlaylistFull> which is the information about the playlist (without the videos)

ytmusic.getPlaylist("OLAK5uy_nRb467jR73IXKybwzw22_rTYIJ808x4Yc").then(playlist => {
	console.log(playlist)
})

getPlaylistVideos

This function takes in the following parameters

Name	Data Type	Description
playlistId	string	Playlist ID

The function returns a Promise<Omit<VideoDetailed, "views">[]> which is the information about the videos without the view count

ytmusic.getPlaylistVideos("OLAK5uy_nRb467jR73IXKybwzw22_rTYIJ808x4Yc").then(playlistVideos => {
	console.log(playlistVideos)
})

Data Types

ThumbnailFull

Name	Data Type	Description
url	string	Link
width	number	Width of the image
height	number	Height of the image

SongDetailed

Name	Data Type	Description
type	"SONG"	Type of data
videoId	string | null	YouTube Video ID
name	string	Name
artists	ArtistBasic[]	Artists
album	AlbumBasic	Album
duration	number	Duration in seconds
thumbnails	ThumbnailFull[]	Thumbnails

SongFull

Name	Data Type	Description
type	"SONG"	Type of data
videoId	string | null	YouTube Video ID
name	string	Name
artists	ArtistBasic[]	Artists
duration	number	Duration in seconds
thumbnails	ThumbnailFull[]	Thumbnails
description	string	Description
formats	any[]	Video Formats
adaptiveFormats	any[]	Adaptive Video Formats

VideoDetailed

Name	Data Type	Description
type	"VIDEO"	Type of data
videoId	string | null	YouTube Video ID
name	string	Name
artists	ArtistBasic[]	Channels that created the video
views	number	View count
duration	number	Duration in seconds
thumbnails	ThumbnailFull[]	Thumbnails

VideoFull

Name	Data Type	Description
type	"VIDEO"	Type of data
videoId	string | null	YouTube Video ID
name	string	Name
artists	ArtistBasic[]	Channels that created the video
views	number	View count
duration	number	Duration in seconds
thumbnails	ThumbnailFull[]	Thumbnails
description	string	Description
unlisted	boolean	If the video is unlisted on YouTube
familySafe	boolean	If the video is family safe on YouTube
paid	boolean	If the video is paid on YouTube
tags	string[]	Tags

ArtistBasic

Name	Data Type	Description
artistId	string | null	Artist ID
name	string	Name

ArtistDetailed

Name	Data Type	Description
type	"ARTIST"	Type of data
artistId	string	Artist ID
name	string	Name
thumbnails	ThumbnailFull[]	Thumbnails

ArtistFull

Name	Data Type	Description
type	"ARTIST"	Type of data
artistId	string	Artist ID
name	string	Name
thumbnails	ThumbnailFull[]	Thumbnails
description	string | null	Description
subscribers	number	Number of subscribers the Artist has
topSongs	Omit<SongDetailed, "duration">[]	Top Songs from Artist
topAlbums	AlbumDetailed[]	Top Albums from Artist

AlbumBasic

Name	Data Type	Description
albumId	string	Album ID
name	string	Name

AlbumDetailed

Name	Data Type	Description
type	"ALBUM"	Type of data
albumId	string	Album ID
playlistId	string	Playlist ID for Album
name	string	Name
artists	ArtistBasic[]	Creators of the Album
year	number	Publication Year
thumbnails	ThumbnailFull[]	Thumbnails

AlbumFull

Name	Data Type	Description
type	"ALBUM"	Type of data
albumId	string	Album ID
playlistId	string	Playlist ID for Album
name	string	Name
artists	ArtistBasic[]	Creators of the Album
year	number	Publication Year
thumbnails	ThumbnailFull[]	Thumbnails
description	string | null	Description
songs	SongDetailed[]	Songs in the Album

PlaylistFull

Name	Data Type	Description
type	"PLAYLIST"	Type of data
playlistId	string	Playlist ID
name	string	Name
artist	ArtistBasic	Creator of the Playlist
videoCount	number	Number of videos in the Playlist
thumbnails	ThumbnailFull[]	Thumbnails

SearchResult

SongDetailed or VideoDetailed or ArtistDetailed or AlbumDetailed or PlaylistFull

Credits

A lot of the credit should go to youtube-music-api. I build this package as a refactored and tested version of youtube-music-api with TypeScript annotations

Testing

YTMusic API's data return types are tested with Jest. To run the tests, run the command

$ npm run test

Built with

• TypeScript
  • 
  • 
  • 
• Axios
  • 
• Tough Cookie
  • 
• Jest
  • 
  • 
  • 
  • 
  • 
• Miscellaneous
  •