lrclib-sdk

TypeScript-first SDK for the LRCLIB API — fetch, search, and publish synchronised lyrics. Works in Node.js, Bun, and the browser.

npm install lrclib-sdk

Quick Start

import { LRCLibClient } from "lrclib-sdk";

const client = new LRCLibClient({
  userAgent: "MyApp (https://github.com/me/myapp)",
});

const lyrics = await client.get({
  trackName: "I Want to Live",
  artistName: "Borislav Slavov",
  albumName: "Baldur's Gate 3 (Original Game Soundtrack)",
  duration: 233,
});

console.log(lyrics.syncedLyrics);

const results = await client.search({ q: "Still Alive" });
const byId = await client.getById(3396226);

await client.publish({
  trackName: "My Song",
  artistName: "My Artist",
  albumName: "My Album",
  duration: 200,
  plainLyrics: "la la la",
  syncedLyrics: "[00:00.00] la la la",
});

API

Methods

| Method | Params | HTTP | | --------------------------------------- | ---------------- | --------------------- | | client.get(params) | TrackSignature | GET /api/get | | client.getCached(params) | TrackSignature | GET /api/get-cached | | client.getById(id) | number | GET /api/get/{id} | | client.search(params) | SearchParams | GET /api/search | | client.publish(params, solveOptions?) | PublishParams | POST /api/publish |

publish auto-solves a SHA-256 proof-of-work challenge and supports progress reporting and abort signals:

await client.publish(
  { trackName, artistName, albumName, duration, plainLyrics, syncedLyrics },
  {
    onProgress: (p) => console.log(`${p.hashRate.toLocaleString()} h/s`),
    signal: AbortSignal.timeout(120_000),
  },
);

Constructor

new LRCLibClient(options?: LRCLibOptions)

| Option | Type | Default | Description | | ----------- | -------- | ---------------------- | --------------------------------- | | baseUrl | string | "https://lrclib.net" | Custom LRCLIB instance URL | | userAgent | string | — | User-Agent header (recommended) |

Types

interface LyricsRecord {
  id: number;
  trackName: string;
  artistName: string;
  albumName: string;
  duration: number;
  instrumental: boolean;
  plainLyrics: string | null;
  syncedLyrics: string | null;
}

interface TrackSignature {
  trackName: string;
  artistName: string;
  albumName: string;
  duration: number;
}

interface SearchParams {
  q?: string;
  trackName?: string;
  artistName?: string;
  albumName?: string;
}

interface PublishParams {
  trackName: string;
  artistName: string;
  albumName: string;
  duration: number;
  plainLyrics: string;
  syncedLyrics: string;
}

All types use camelCase. The SDK converts to snake_case for the API. search requires at least one of q or trackName.

Errors

import { LRCLibError } from "lrclib-sdk";

try {
  await client.get({ ... });
} catch (err) {
  if (err instanceof LRCLibError) {
    console.log(err.statusCode);
    console.log(err.body?.name);
  }
}

Requirements

• Node.js ≥ 18 / Bun ≥ 1.2
• Browser: Web Worker + WASM

License

MIT