Registry / http-networking / ytmusic-api

ytmusic-api

library5.3.1jsnpmunverified

ytmusic-api is an unofficial JavaScript/TypeScript library designed to scrape and interact with YouTube Music data. It provides a robust API for accessing information such as songs, videos, artists, albums, playlists, lyrics, and search suggestions directly from YouTube Music. The library ships with comprehensive TypeScript type definitions, aiming for 95% data type consistency despite the inherent variability of scraped data. Currently at version 5.3.1, the project demonstrates an active release cadence with frequent updates addressing bug fixes, stability improvements, and new features. Its primary differentiator is its strong TypeScript support and a refactored codebase built for understandability and testability, distinguishing it from older, less-typed alternatives.

http-networking data

npm install ytmusic-api

github ↗package ↗

INSTALL

IMPORT

SIG · YTMUSIC-API

ytmusic-api

http-networkingjavascriptv5.3.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

YTMusic

✓ import YTMusic from 'ytmusic-api'

✗ import { YTMusic } from 'ytmusic-api'

YTMusic is exported as a default export from the package.

YTMusic

✓ const YTMusic = require('ytmusic-api')

✗ import YTMusic from 'ytmusic-api'

While v5.0.2 fixed CJS issues, using 'require' in an ESM project will cause errors. Use the ES Module import if your project is type: 'module'.

SearchResult

✓ import type { SearchResult } from 'ytmusic-api'

✗ import { SearchResult } from 'ytmusic-api'

Importing types like `SearchResult` should use the `import type` syntax for better tree-shaking and explicit type-only imports.

Demonstrates initializing the YTMusic API and performing a song search, then logging the results.

import YTMusic from 'ytmusic-api' async function runSearch() { const ytmusic = new YTMusic() // Initialize with optional custom cookies, e.g., from an authenticated session // For anonymous access, no cookies are needed. await ytmusic.initialize() try { const songs = await ytmusic.search('Never gonna give you up', 'songs') console.log(`Found ${songs.length} songs for 'Never gonna give you up':`) songs.slice(0, 3).forEach((song, index) => { console.log(` ${index + 1}. Title: ${song.title}, Artist: ${song.artist?.name || 'Unknown'}`) }) } catch (error) { console.error('Error during search:', error) } } runSearch()

Debug

Known issues

gotchaAs an unofficial scraping library, ytmusic-api relies on the internal structure of YouTube Music's website and API. Google/YouTube can change these structures at any time, potentially causing breaking changes or unexpected behavior in the library.

fix

Always pin to a specific patch version and thoroughly test after updates to avoid unexpected regressions. Monitor the package's GitHub repository for critical updates and issues.

affects: >=1.0.0

breakingVersion 5.0.0 introduced 'better stability and more error reporting when data within strings is considered invalid'. This can lead to previously ignored malformed data now causing errors, which might break existing code that implicitly handled or ignored such inconsistencies.

fix

Review error handling in your application, especially around data processing from API responses. Ensure your code gracefully handles potential errors or `null`/`undefined` values for inconsistent data fields.

affects: >=5.0.0

gotchaThe library explicitly states that 'Data from YouTube can be inconsistent but YTMusic API has been tested and the data matches the TypeScript types 95% of the time'. This means there is a 5% chance of type mismatches or unexpected `undefined` values for specific fields.

fix

Implement defensive programming practices, such as optional chaining (`?.`) and nullish coalescing (`??`), when accessing properties of API response objects. Always validate critical data fields at runtime.

affects: >=1.0.0

breakingVersions 5.0.0 and 5.0.1 had issues with CommonJS (CJS) builds, specifically `noEmit blocking dist from generating` and a `CJS broken issue`. While fixed in v5.0.2, users on older v5.x.x versions might experience import failures in CJS environments.

fix

Ensure you are using `ytmusic-api@5.0.2` or later if your project relies on CommonJS modules. For new projects, prefer using ES Modules if possible.

affects: >=5.0.0 <5.0.2

Errors

Common errors & fixes

TypeError: ytmusic.initialize is not a function

The `ytmusic` instance was not properly initialized or `await` was missing before `ytmusic.initialize()` in an async context.

fix

Ensure `await ytmusic.initialize()` is called before making any API requests, typically within an `async` function.

ReferenceError: require is not defined in ES module scope

Attempting to use `require()` syntax in an ECMAScript Module (ESM) project context (e.g., `"type": "module"` in `package.json`).

fix

Change your import statement to `import YTMusic from 'ytmusic-api'`. If you must use CommonJS, ensure your project is configured as `"type": "commonjs"` or remove the `type` field from `package.json`.

TypeError: Cannot read properties of undefined (reading 'name') when accessing artist.name

YouTube Music data can be inconsistent; the `artist` property or its `name` might be `undefined` or `null` for certain results.

fix

Use optional chaining (`song.artist?.name`) and provide fallback values (e.g., `song.artist?.name || 'Unknown Artist'`) to safely access potentially missing properties.

Upgrade

Version history

5.3.1latest on npm

Audit

Dependencies

axiosrequiredFor making HTTP requests to YouTube Music endpoints.

tough-cookierequiredFor managing HTTP cookies, essential for session persistence and authenticated requests.

zodrequiredFor runtime schema validation and ensuring data integrity with TypeScript types.

Agent activity

36 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/zS1L3NT/ts-npm-ytmusic-api ↗

packagehttps://www.npmjs.com/package/ytmusic-api ↗