@mks2508/yt-dl

YouTube music metadata and download library for Bun

A comprehensive TypeScript library for fetching YouTube metadata and downloading audio/video content with music metadata enrichment from MusicBrainz, iTunes, Spotify, and Last.fm.

Features

• Fast Metadata Fetching - Parallel fetching of oEmbed (fast) and yt-dlp JSON (complete)
• Music Metadata Enrichment - Automatic enrichment from MusicBrainz, iTunes, Spotify, Last.fm
• Format Selection - List and select from all available video/audio formats
• Download Management - Real-time progress tracking with callbacks
• Result Types - Functional error handling with Result types ({ success, data } | { success, error })
• Plugin System - Extensible architecture with hooks for customization
• Cross-Platform - Works on macOS, Linux, and Windows

Installation

bun add @mks2508/yt-dl

Requirements

• Bun >= 1.0.0
• yt-dlp installed in PATH

# macOS
brew install yt-dlp

# Linux
sudo curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o /usr/local/bin/yt-dlp
sudo chmod a+rx /usr/local/bin/yt-dlp

Quick Start

Get Music Metadata

import { YouTubeMusic } from '@mks2508/yt-dl'

const result = await YouTubeMusic.getMusicMetadata(
  'https://youtu.be/dQw4w9WgXcQ'
)

if (!result.success) {
  console.error('Error:', result.error)
  process.exit(1)
}

const { title, artist, album, artwork } = result.data
console.log(`♪ ${title} by ${artist}`)

Download Audio

const result = await YouTubeMusic.downloadBestAudio(
  'https://youtu.be/dQw4w9WgXcQ',
  './downloads',
  (p) => console.log(`${p.percent}% - ${p.speed}`)
)

if (result.success) {
  console.log('Downloaded:', result.data.filePath)
}

API Reference

YouTubeMusic (High-Level API)

import { YouTubeMusic } from '@mks2508/yt-dl'

// Video Info
await YouTubeMusic.getVideoInfo(url)           // Complete info (oEmbed + yt-dlp + thumbnails)
await YouTubeMusic.getQuickInfo(url)           // Fast oEmbed metadata only
await YouTubeMusic.getFullInfo(url)            // Complete yt-dlp JSON

// Music Metadata
await YouTubeMusic.getMusicMetadata(url)       // Enriched music metadata
await YouTubeMusic.search(title, artist)       // Search by title/artist

// Formats
await YouTubeMusic.getFormats(url)             // Categorized formats (video/audio/combined)
await YouTubeMusic.getBestAudioFormat(url)     // Best audio format
await YouTubeMusic.getBestVideoFormat(url)     // Best video format

// Downloads
await YouTubeMusic.download(options)           // Custom download
await YouTubeMusic.downloadBestAudio(url)      // Best quality audio
await YouTubeMusic.downloadBestVideo(url)      // Best quality video
await YouTubeMusic.downloadBestCombined(url)   // Best quality combined

Services

For advanced usage, you can use individual services:

import {
  videoInfoService,
  musicMetadataService,
  formatService,
  downloadService
} from '@mks2508/yt-dl'

// Video info service
const info = await videoInfoService.getCompleteInfo(url, {
  thumbnailAnsiEnabled: true,
  thumbnailHeight: 14,
  fullInfoEnabled: true
})

// Music metadata service
const metadata = await musicMetadataService.getMusicMetadata(url, ytInfo, {
  useProviders: true,
  providerConfig: {
    spotify: { enabled: true, clientId: 'xxx', clientSecret: 'yyy' }
  }
})

// Format service
const categories = formatService.categorize(formats)
const bestAudio = formatService.getBestAudio(formats)

// Download service
const result = await downloadService.download({
  url,
  format: 'bestaudio',
  outputPath: './downloads',
  onProgress: (p) => console.log(`${p.percent}% - ${p.speed}`)
})

Documentation

• Getting Started
• Metadata Fetching
• Downloads
• Format Selection
• Error Handling
• Configuration
• Examples

Result Type Pattern

All service methods return a Result<T, Error> type for explicit error handling:

type Result<T, E = Error> =
  | { success: true; data: T }
  | { success: false; error: E }

Usage:

import { YouTubeMusic } from '@mks2508/yt-dl'

const result = await YouTubeMusic.getMusicMetadata(url)

if (!result.success) {
  // Handle error
  console.error('Failed:', result.error.message)
  return
}

// Use data
const { title, artist } = result.data
console.log(`${title} by ${artist}`)

Configuration

Create a config file at ~/.config/ytdlp-tui/config.json:

{
  "mp3Metadata": {
    "providers": {
      "musicbrainz": { "enabled": true },
      "itunes": { "enabled": true },
      "spotify": { "enabled": false, "clientId": "", "clientSecret": "" },
      "lastfm": { "enabled": false, "apiKey": "" }
    }
  }
}

TUI Application

This package also includes a terminal UI application:

# Interactive mode
bun yt-tui https://youtu.be/dQw4w9WgXcQ

# Non-interactive download
bun yt-tui -a https://youtu.be/dQw4w9WgXcQ

# List formats
bun yt-tui -l https://youtu.be/dQw4w9WgXcQ

See TUI README for full CLI documentation.

License

MIT