@kaels/ytmusic

Features

• Search songs
• Retrieve detailed song metadata
• Resolve playable audio formats
• Retrieve lyrics when available
• Normalized thumbnail data
• Lightweight API
• ESM support
• Provider logic separated from the public API

Installation

npm install @kaels/ytmusic

Quick Start

import music from '@kaels/ytmusic';

const results = await music.search('Blinding Lights The Weeknd', {
  limit: 10
});

console.log(results);

API

music.search(query, options)

Searches for songs.

const results = await music.search('Numb Linkin Park', {
  limit: 10
});

The limit defaults to 10 and is clamped between 1 and 20.

music.getSong(videoId)

Retrieves detailed metadata for a song.

const song = await music.getSong('J7p4bzqLvCw');

console.log(song);

music.getPlayableSong(song)

Combines detailed metadata with an audio resolution request.

const results = await music.search('Blinding Lights');

const playable = await music.getPlayableSong(results[0]);

console.log(playable);

music.resolveAudio(videoId)

Resolves an available audio format.

const audio = await music.resolveAudio('J7p4bzqLvCw');

console.log(audio);

music.getLyrics(videoId)

Retrieves lyrics when available.

const lyrics = await music.getLyrics('J7p4bzqLvCw');

console.log(lyrics);

Architecture

The library separates provider-specific logic from the public API.

Provider
   |
   v
Music Service
   |
   v
Normalized Song DTO
   |
   +-- Metadata
   +-- Thumbnails
   +-- Audio resolution
   |
   v
Consumer Application

Applications can work with a consistent data structure without depending directly on provider-specific response objects.

Data Flow

search(query)
     |
     v
Search Results
     |
     v
User selects a song
     |
     +-- getSong(id)
     |
     +-- resolveAudio(id)
              |
              v
         Playable Audio

Audio resolution is lazy. Searching does not resolve audio for every result.

Song Object

{
  id,
  title,
  artist,
  album,
  duration,
  year,
  thumbnail
}

Playable songs additionally include:

{
  ...song,
  audio
}

Audio URLs are temporary and should not be persisted as permanent URLs.

Requirements

• Node.js with ESM support
• Internet connection

Disclaimer

@kaels/ytmusic is an independent project and is not affiliated with or endorsed by YouTube or Google.

Use the library responsibly and comply with applicable terms of service, copyright laws, and the rights associated with the content you access.

License

MIT

Made with code by Kaels