ytmusic-api

YouTube Music API which comes with TypeScript support

Initialization

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

Class Methods

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