Quickstart
Install Lyra SDK and make your first request
Prerequisites
- Node.js 18 or later
- A YouTube Data API v3 key from the Google Cloud Console
Installation
npm install lyra-sdkpnpm add lyra-sdkyarn add lyra-sdkbun add lyra-sdkSet up your API key
Create a .env file in your project root:
YOUTUBE_API_KEY=your_api_key_hereAPI Key Security
Never commit your API key to source control. Use environment variables or a secrets manager.
Make your first request
import { yt } from 'lyra-sdk'
const client = yt(process.env.YOUTUBE_API_KEY!)
// Fetch a single video
const video = await client.video('dQw4w9WgXcQ')
console.log(`${video.title} — ${video.viewsFmt} views`)Use URL utilities (no API key needed)
The lyra-sdk/url subpath exports standalone helpers that don't require an API key:
import { parseURL, isVideoURL, extractVideoId, formatDuration } from 'lyra-sdk/url'
const result = parseURL('https://youtu.be/dQw4w9WgXcQ')
// { isValid: true, type: 'video', videoId: 'dQw4w9WgXcQ' }
isVideoURL('https://youtube.com/watch?v=dQw4w9WgXcQ') // true
extractVideoId('https://youtu.be/dQw4w9WgXcQ') // 'dQw4w9WgXcQ'
formatDuration(9347) // '2h 35m 47s'Use formatters (no API key needed)
The lyra-sdk/fmt subpath exports formatting utilities:
import { formatNumber, formatDate, relativeTime, formatDurationClock } from 'lyra-sdk/fmt'
formatNumber(1763613349) // '1.8B'
formatDate('2009-10-25T06:57:33.000Z') // 'October 25, 2009'
relativeTime(new Date('2025-01-01')) // '3 months ago'
formatDurationClock(214) // '3:34'Fetch video transcripts (no API key needed)
The lyra-sdk/transcript subpath fetches YouTube captions without a Data API key:
import { transcribeVideo, toPlainText } from 'lyra-sdk/transcript'
const lines = await transcribeVideo('dQw4w9WgXcQ')
console.log(lines[0].text) // "♪ We're no strangers to love ♪"
console.log(lines[0].offset) // 0
console.log(lines[0].lang) // "en"
console.log(toPlainText(lines)) // Full transcript as plain textThe transcript module uses YouTube's internal Innertube API — no quota consumption, no API key.
Batch transcript for playlists
Fetch transcripts for every video in a playlist. Requires an API key for the playlist video list:
import { transcribePlaylist } from 'lyra-sdk'
const result = await transcribePlaylist('PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf', {
apiKey: process.env.YOUTUBE_API_KEY!,
concurrency: 3,
})
console.log(`Succeeded: ${result.succeeded}, Failed: ${result.failed}`)Regions, languages & categories
Discover supported YouTube regions, languages, and video categories:
const regions = await client.regions() // 110+ regions
const languages = await client.languages() // 80+ languages
const categories = await client.videoCategoriesByRegion('US') // 32 US categories
// Get localized category names
const jaCategories = await client.videoCategoriesByRegion('JP', 'ja')
// [{ id: '10', title: '音楽' }, ...]Fetch video comments
Fetch comments, replies, and aggregate stats for any video:
const threads = await client.comments('dQw4w9WgXcQ')
const top5 = await client.topComments('dQw4w9WgXcQ', 5)
const stats = client.commentStats('dQw4w9WgXcQ', threads)
console.log(stats.mostLikedComment?.text) // Most liked comment
console.log(`Unique authors: ${stats.uniqueAuthors}`)