ytmusic-api-proxy
Version:
YouTube Music API
128 lines (95 loc) • 4.94 kB
Markdown
# YTMusic API
    
YouTube Music API (Unofficial) is a YouTube Music data scraper. It comes with TypeScript support API for return types. The package is published to [NPM](https://www.npmjs.com/package/ytmusic-api-proxy).
## Motivation
I used to use [youtube-music-api](https://npmjs.com/package/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
- Lyrics
- Upcoming Songs
## Installation
```bash
npm install ytmusic-api-proxy
```
## Usage
### Basic Usage
**ES Modules (import):**
```js
import YTMusic from "ytmusic-api-proxy"
const ytmusic = new YTMusic()
await ytmusic.initialize(/* Optional: Custom cookies */)
ytmusic.search("Never gonna give you up").then(songs => {
console.log(songs)
})
```
**CommonJS (require):**
```js
const YTMusic = require("ytmusic-api-proxy").default
const ytmusic = new YTMusic()
await ytmusic.initialize(/* Optional: Custom cookies */)
ytmusic.search("Never gonna give you up").then(songs => {
console.log(songs)
})
```
### Using with HTTP Proxy
```js
import YTMusic from "ytmusic-api-proxy"
// Option 1: Pass proxy config in constructor
const ytmusic = new YTMusic({
protocol: "http", // or "https", "socks4", "socks5"
host: "proxy.example.com",
port: 8080,
auth: { // Optional authentication
username: "your_username",
password: "your_password"
}
})
await ytmusic.initialize()
// Option 2: Pass proxy config in initialize method
const ytmusic2 = new YTMusic()
await ytmusic2.initialize({
proxy: {
protocol: "http",
host: "proxy.example.com",
port: 8080
}
})
ytmusic.search("Never gonna give you up").then(songs => {
console.log(songs)
})
```
### Proxy Configuration
The proxy configuration supports:
- **HTTP/HTTPS proxies**: Use `protocol: "http"` or `protocol: "https"`
- **SOCKS proxies**: Use `protocol: "socks4"` or `protocol: "socks5"`
- **Authentication**: Optional `auth` object with `username` and `password`
- **Flexible setup**: Configure proxy in constructor or initialize method
## Credits
A lot of the credit should go to [youtube-music-api](https://npmjs.com/package/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 Bun Test. To run the tests, run the command
```
$ bun test
```
## Built with
- NodeJS
- TypeScript
- [](https://npmjs.com/package/@types/tough-cookie/v/4.0.5)
- [](https://npmjs.com/package/bun-types/v/1.1.18)
- [](https://npmjs.com/package/tsup/v/8.1.0)
- [](https://npmjs.com/package/typescript/v/5.1)
- Miscellaneous
- [](https://npmjs.com/package/@biomejs/biome/v/1.8.3)
- [](https://npmjs.com/package/axios/v/1.7.2)
- [](https://npmjs.com/package/tough-cookie/v/4.1.4)
- [](https://npmjs.com/package/zod/v/3.23.8)
- [](https://npmjs.com/package/zod-to-json-schema/v/3.23.1)