API

Spyter provides a modern and consistent API. It allows you to easily search on YouTube and retrieve information about videos and playlists.

Videos

isVideoUrl(url)

Checks whether a URL matches the format of a video URL on YouTube.

Parameter	Type	Optional	Default	Description
url	unknown	❌		Video URL.

Returns:

boolean

getVideoMeta(url, [options])

Gets the metadata of a video.

Parameter	Type	Optional	Default	Description
url	string	❌		Video URL.
options	VideoOptions	✔️	See VideoOptions.	Video retrieval options.

Returns:

Promise<VideoMeta>

getVideoFormats(url, [options])

Gets the audio formats of a video.

Parameter	Type	Optional	Default	Description
url	string	❌		Video URL.
options	VideoOptions	✔️	See VideoOptions.	Video retrieval options.

Returns:

Promise<Format[]>

getVideo(url, [options])

Gets the metadata and audio formats of a video.

Parameter	Type	Optional	Default	Description
url	string	❌		Video URL.
options	VideoOptions	✔️	See VideoOptions.	Video retrieval options.

Returns:

Promise<Video>

Playlists

isPlaylistUrl(url)

Checks whether a URL matches the format of a playlist URL on YouTube.

Parameter	Type	Optional	Default	Description
url	unknown	❌		Playlist URL.

Returns:

boolean

getPlaylist(url, [options])

Retrieves information about a playlist on YouTube.

Parameter	Type	Optional	Default	Description
url	string	❌		Playlist URL.
options	PlaylistOptions	✔️	See PlaylistOptions.	Playlist retrieval options.

Returns:

Promise<Playlist>

Search

search(query, [options])

Performs a search on YouTube.

Parameter	Type	Optional	Default	Description
query	string	❌		Query.
options	SearchOptions	✔️	See SearchOptions.	Search options.

Returns:

Promise<VideoMeta[]>

Types

VideoOptions

Video retrieval options.

Property	Type	Default	Description
language?	string	en	ISO 639-1 language code (e.g., en, de).
region?	string	US	ISO 3166-2 region code (e.g., US, DE).

PlaylistOptions

Playlist retrieval options.

Property	Type	Default	Description
maxPages?	number	1	Maximum number of pages to retrieve.
maxVideos?	number	100	Maximum number of videos to retrieve.
language?	string	en	ISO 639-1 language code (e.g., en, de).
region?	string	US	ISO 3166-2 region code (e.g., US, DE).

SearchOptions

Search options.

Property	Type	Default	Description
maxVideos?	number	1	Maximum number of videos to retrieve.
language?	string	en	ISO 639-1 language code (e.g., en, de).
region?	string	US	ISO 3166-2 region code (e.g., US, DE).

Video

Video.

Property	Type	Description
id	string	Video ID.
url	string	Video URL.
title	string	Video title.
channelUrl	string	Channel URL.
channelName	string	Channel name.
thumbnails	Thumbnail[]	List of available thumbnails.
duration	number	Duration in seconds. If the video is live, duration will be Infinity.
isLive	boolean	Whether a video is a livestream or not.
formats	Format[]	List of available audio formats.

VideoMeta

See Video, except without formats.

Playlist

Playlist.

Property	Type	Description
id	string	Playlist ID.
url	string	Playlist URL.
title	string	Playlist title.
channelUrl	string	Channel URL of the playlist owner.
channelName	string	Channel name of the playlist owner.
thumbnails	Thumbnail[]	List of available thumbnails.
videos	VideoMeta[]	List of videos from the playlist.

Format

Audio format.

Property	Type	Description
url	string	Audio format URL.
itag	number	Format code. See this gist for more information.
mimeType	string	MIME type.
codec	string	Audio codec.
bitrate	number	Audio bitrate.
isLive?	boolean	Whether the format is a live format or not.

⚠️ Note: Livestreams can only be played via formats that have the isLive property, otherwise you will only get a small portion of the audio.

Thumbnail

Video thumbnail.

Property	Type	Description
url	string	Thumbnail URL.
width	number	Width in px.
height	number	Height in px.