Lyra SDK

A powerful TypeScript SDK for working with YouTube data. Fetch videos, channels, playlists, comments, and transcripts — all with full type safety and zero dependencies.

🌐 Website · 📚 Docs

Installation

npm install lyra-sdk

Requires Node.js 22+ and a YouTube Data API v3 key.

Quick Start

import { yt } from 'lyra-sdk'

const client = yt(process.env.YOUTUBE_API_KEY!)

// Fetch a video
const video = await client.video(videoUrl)
console.log(video.title, video.viewsFmt)

// Fetch a channel by handle
const channelHandle = '@MrBeast'
const channel = await client.channel(channelHandle)
console.log(channel.name, channel.subscribersFmt)

// Fetch a full playlist
const playlist = await client.playlist(playlistUrl)
console.log(playlist.title, playlist.videoCount)

Fetch Video Transcript (No API Key)

import { transcribeVideo, toPlainText } from 'lyra-sdk/transcript'

const videoUrl = 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'
const lines = await transcribeVideo(videoUrl)
console.log(toPlainText(lines)) // Full transcript as plain text

The transcript module uses YouTube's internal Innertube API — no quota consumption, no API key.

Production Deployments & Proxy Support

YouTube may block requests from datacenter or serverless IPs (Vercel, Cloudflare Workers, AWS Lambda, etc.) when fetching transcripts. Route requests through a residential proxy using the customFetch option.

Node.js (https-proxy-agent):

import { transcribeVideo } from 'lyra-sdk/transcript'
import { HttpsProxyAgent } from 'https-proxy-agent'

const agent = new HttpsProxyAgent('http://user:pass@proxy.webshare.io:8080')
const lines = await transcribeVideo(videoUrl, {
  customFetch: (url, init) => fetch(url, { ...init, agent }),
})

Node.js 20+ (undici — no extra deps):

import { transcribeVideo } from 'lyra-sdk/transcript'
import { ProxyAgent } from 'undici'

const agent = new ProxyAgent('http://user:pass@proxy.webshare.io:8080')
const lines = await transcribeVideo(videoUrl, {
  customFetch: (url, init) => fetch(url, { ...init, dispatcher: agent }),
})

Works with providers like Webshare, Bright Data, Oxylabs, Smartproxy, and any HTTP/HTTPS proxy.

Transcribe Playlist (Batch)

import { transcribePlaylist, InMemoryCache } from 'lyra-sdk'

const result = await transcribePlaylist(playlistUrl, {
  apiKey: process.env.YOUTUBE_API_KEY!,
  concurrency: 5,
  cache: new InMemoryCache(),
  onProgress(done, total, videoId, status) {
    console.log(`[${status}] ${done}/${total} — ${videoId}`)
  },
})

console.log(`Succeeded: ${result.succeeded}, Failed: ${result.failed}`)

Features: concurrency control, smart caching, partial failure handling, range filtering.

Comments & Comment Threads

// Fetch all comment threads
const threads = await client.comments(videoUrl)

// Top comments by relevance
const top5 = await client.topComments(videoUrl, 5)

// All replies to a specific comment
const replies = await client.commentReplies(commentId)

// Search comments by keyword
const results = await client.searchComments(videoUrl, 'great song')

// Compute aggregate stats
const stats = client.commentStats(videoUrl, threads)
console.log(`Unique authors: ${stats.uniqueAuthors}`)

Playlist Query Builder

const result = await client
  .playlistQuery(playlistUrl)
  .filterByDuration({ min: 300 })
  .filterByViews({ min: 100_000 })
  .sortBy('views', 'desc')
  .between(1, 10)
  .execute()

URL Utilities & Formatting (No API Key)

import { parseURL, extractVideoId } from 'lyra-sdk/url'
import { formatNumber, formatDurationClock } from 'lyra-sdk/fmt'

parseURL(videoUrl)
formatNumber(1_763_613_349) // '1.8B'
formatDurationClock(214)    // '3:34'

Error Handling

import { NotFoundError, QuotaError } from 'lyra-sdk'

try {
  const video = await client.video('invalid-id')
} catch (err) {
  if (err instanceof NotFoundError) console.log('Video not found')
  if (err instanceof QuotaError) console.log('API quota exceeded')
}

Packages

Package	Description
`lyra-sdk`	Core SDK
`lyra-sdk/url`	Standalone URL utilities (no API key)
`lyra-sdk/fmt`	Standalone formatters (no API key)
`lyra-sdk/transcript`	Transcript fetching (no API key for single videos)
`lyra-sdk/ai-tools`	Pre-built AI tools for Vercel AI SDK and agent workflows

Agent Skills

Add Lyra SDK agent skills to your project:

npx skills add abhisek-1221/lyra-skills

Works with Claude Code, Codex, OpenCode etc.

Vercel AI SDK

Use Lyra SDK with the Vercel AI SDK for agent-powered YouTube research:

import { createAITools } from 'lyra-sdk/ai-tools'
import { generateText, tool } from 'ai'
import { openai } from '@ai-sdk/openai'

const ai = createAITools({ apiKey: process.env.YOUTUBE_API_KEY! })

const result = await generateText({
  model: openai('gpt-4o-mini'),
  tools: {
    getVideo:    tool(ai.getVideo),
    getChannel:  tool(ai.getChannel),
    transcribeVideo: tool(ai.transcribeVideo),
    getComments: tool(ai.getComments),
  },
  prompt: 'How many subscribers does @MrBeast have, and what is the title of his latest video?',
})

console.log(result.text)

Also integrates with all Vercel AI SDK providers — Google Gemini, Anthropic Claude, Groq, Mistral, and more.

Documentation

Full docs, API reference, and examples: docs.uselyra.xyz

License

MIT

If you find Lyra useful, please consider giving it a ⭐ on GitHub!