lrclib-api is a TypeScript-based wrapper for the lrclib.net API, designed to fetch song lyrics and metadata. It supports both plain and synchronized lyrics, providing a simple and efficient way to access lyrics data.

Features

• Retrieve song lyrics by track name, artist name, and album name.
• Supports both plain (unsynced) and synchronized (timed) lyrics.
• Handles instrumental tracks gracefully.
• Provides metadata such as track name, artist, album, and duration.
• Fully type-safe with TypeScript.

Installation

Install the package via npm:

npm install lrclib-api

Usage

Basic Example

JavaScript

const { findLyrics, getSynced, getUnsynced } = require("lrclib-api");

(async () => {
  const query = {
    track_name: "The Chain",
    artist_name: "Fleetwood Mac",
  };

  const lyrics = await findLyrics(query);
  console.log("Metadata:", lyrics);

  const unsyncedLyrics = await getUnsynced(query);
  console.log("Unsynced Lyrics:", unsyncedLyrics);

  const syncedLyrics = await getSynced(query);
  console.log("Synced Lyrics:", syncedLyrics);
})();

ES Module

import { findLyrics, getSynced, getUnsynced } from "lrclib-api";

const query = {
  track_name: "The Chain",
  artist_name: "Fleetwood Mac",
};

const lyrics = await findLyrics(query);
console.log("Metadata:", lyrics);

const unsyncedLyrics = await getUnsynced(query);
console.log("Unsynced Lyrics:", unsyncedLyrics);

const syncedLyrics = await getSynced(query);
console.log("Synced Lyrics:", syncedLyrics);

Example Response

findLyrics Response

{
  "id": 151738,
  "name": "The Chain",
  "trackName": "The Chain",
  "artistName": "Fleetwood Mac",
  "albumName": "Rumours",
  "duration": 271,
  "instrumental": false,
  "plainLyrics": "Listen to the wind blow\nWatch the sun rise...",
  "syncedLyrics": "[00:27.93] Listen to the wind blow\n[00:30.88] Watch the sun rise..."
}

Unsynced Lyrics Example

[{ "text": "Listen to the wind blow" }, { "text": "Watch the sun rise" }]

Synced Lyrics Example

[
  { "text": "Listen to the wind blow", "startTime": 27930 },
  { "text": "Watch the sun rise", "startTime": 30880 }
]

Running Tests

To run the test suite:

1. Clone the repository:

   git clone https://github.com/igorwastaken/lrclib-api.git
   cd lrclib-api

2. Install dependencies:

   npm install

3. Run tests:

   npm test

Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository.
2. Create a new branch:

   git checkout -b my-feature

3. Commit your changes:

   git commit -m "Add my feature"

4. Push to your branch:

   git push origin my-feature

5. Open a pull request.

License

This project is licensed under the ISC License.

Links

• GitHub Repository: https://github.com/igorwastaken/lrclib-api
• NPM Package: lrclib-api
• lrclib.net: https://lrclib.net