lrclib-api/dist/index.d.mts

The unofficial lrclib.net library for JS and TS

/**
 * Defines the query object used to search for lyrics.
 *
 * This type is a union of two possible structures:
 * 1. Search by track details (e.g., track name and artist).
 * 2. Search by a unique track ID.
 */
type Query = {
    id?: never;
    track_name: string;
    artist_name: string;
    album_name?: string;
    duration?: number;
} | {
    id: number;
    track_name?: never;
    artist_name?: never;
    album_name?: never;
    duration?: never;
};
/**
 * Represents the response returned from the lyrics API.
 */
type FindLyricsResponse = {
    id: number;
    name: string;
    trackName: string;
    artistName: string;
    albumName: string;
    duration: number;
    instrumental: boolean;
    plainLyrics: string | null;
    syncedLyrics: string | null;
} & ErrorResponse;
type ErrorResponse = {
    code: number;
    name: string;
    message: string;
};
/**
 * Defines the parameters for searching lyrics.
 * Combines the {@link SearchType} structure with additional optional parameters.
 */
type Search = SearchType & {
    artist_name?: string;
    duration?: number;
};
/**
 * Defines the parameters for searching lyrics.
 * Combines the {@link SearchType} structure with additional optional parameters.
 */
type SearchType = {
    track_name?: never;
    query: string;
} | {
    track_name: string;
    query?: never;
};

type LyricLine = {
    text: string;
    startTime?: number;
};
/**
 * Represents parsed lyrics in different formats:
 * - `synced`: Array of lyric lines with start times (null if not available)
 * - `unsynced`: Array of lyric lines without timing information
 */
type ParsedLyrics = {
    synced: LyricLine[] | null;
    unsynced: LyricLine[];
};

type ClientOptions = {
    key?: string;
    url?: string;
};

declare class NotFoundError extends Error {
    constructor();
}
declare class NoResultError extends Error {
    constructor();
}

declare class RequestError extends Error {
    constructor(error?: string);
}

declare class Client {
    private _url;
    private _key;
    /**
     * Creates a request client to api
     *
     * Example Usage;
     * ```typescript
     * const client = new Client();
     *
     * client.findLyrics({ track_name: "The Chain", artist_name: "Fleetwood Mac" }).then(console.log);
     * ```
     *
     * @notigorwastaken: I'm still working on it.
     *
     * @param options - An optional object containing Client Options
     *  - `url`: The base URL, e.g. you can set up a custom url that uses another lrclib.net instance
     *  - `key`: The token used to publish lyrics to the api. [click here for more info](https://lrclib.net/docs)
     */
    constructor(options?: ClientOptions);
    private request;
    /**
     * Sends a request to the lyrics search API at https://lrclib.net/api/search.
     *
     * Example Usage:
     * ```typescript
     * const search = await searchLyrics({ query: "The Chain" });
     * ```
     *
     * @param info - An object containing search parameters:
     *  - `query`: The search term (conditional | e.g., song title or lyrics fragment).
     *  - `track_name`: The name of the track (conditional).
     *  - `artist_name`: The artist's name (optional).
     *  - `duration`: The song duration in milliseconds (optional).
     *
     * @returns A promise that resolves to an array of {@link FindLyricsResponse | FindLyricsResponse[]}.
     */
    searchLyrics(info: Search, options?: RequestInit): Promise<FindLyricsResponse[]>;
    /**
     * Finds lyrics for a given track using the API at https://lrclib.net/api/get.
     *
     * Example Usage:
     * ```typescript
     * const lyrics = await findLyrics({ track_name: "The Chain", artist_name: "Fleetwood Mac" });
     * ```
     *
     * @param info - An object containing query parameters:
     *  - `id`: The unique identifier of the track (conditional).
     *  - `track_name`: The name of the track (conditional).
     *  - `artist_name`: The artist's name (conditional).
     *  - `album_name`: The album's name (optional).
     *  - `duration`: The song duration in milliseconds (optional).
     *
     * @returns A promise that resolves to a {@link FindLyricsResponse | FindLyricsResponse} object containing the track's lyrics.
     * @throws Will throw an error if the request fails or the track is not found.
     */
    findLyrics(info: Query, options?: RequestInit): Promise<FindLyricsResponse>;
    /**
     * Retrieves unsynchronized (plain) lyrics for a given track.
     *
     * Example Usage:
     * ```typescript
     * const unsyncedLyrics = await getUnsynced({ track_name: "The Chain", artist_name: "Fleetwood Mac" });
     * ```
     *
     * @param info - An object containing query parameters:
     *  - `id`: The unique identifier of the track (conditional).
     *  - `track_name`: The name of the track (conditional).
     *  - `artist_name`: The artist's name (conditional).
     *  - `album_name`: The album's name (optional).
     *  - `duration`: The song duration in milliseconds (optional).
     *
     * @returns A promise that resolves to an array of {@link LyricLine | LyricLine[]} objects
     *          containing unsynchronized lyrics or `null` if no lyrics are found.
     */
    getUnsynced(info: Query): Promise<LyricLine[] | null>;
    /**
     * Retrieves synchronized (timed) lyrics for a given track.
     *
     * Example Usage:
     * ```typescript
     * const syncedLyrics = await getSynced({ track_name: "The Chain", artist_name: "Fleetwood Mac" });
     * ```
     *
     * @param info - An object containing query parameters:
     *  - `id`: The unique identifier of the track (conditional).
     *  - `track_name`: The name of the track (conditional).
     *  - `artist_name`: The artist's name (conditional).
     *  - `album_name`: The album's name (optional).
     *  - `duration`: The song duration in milliseconds (optional).
     *
     * @returns A promise that resolves to an array of {@link LyricLine | LyricLine[]} objects
     *          containing synchronized lyrics or `null` if no lyrics are found.
     */
    getSynced(info: Query): Promise<LyricLine[] | null>;
}

/**
 * Parses song lyrics into a structured format by removing metadata tags and separating lines.
 *
 * Example Input:
 * ```
 * [00:27.93] Listen to the wind blow
 * [00:30.88] Watch the sun rise
 * ```
 *
 * Example Output:
 * {
 *   synced: [{ text: "Listen to the wind blow", startTime: 27930 }, { text: "Watch the sun rise", startTime: 30880 }],
 *   unsynced: []
 * }
 *
 * @param lyrics - The raw lyrics string with optional tags and timestamps
 * @returns A ParsedLyrics object containing structured lyric data
 */
declare function parseLocalLyrics(lyrics: string): ParsedLyrics;
/**
 * Converts a timestamp string in the format "mm:ss" or "mm:ss.SSS" to a number in seconds.
 *
 * @param time - The timestamp string to parse
 * @returns The time in seconds as a number
 */
declare function parseTime(time: string): number;

export { Client, type ClientOptions, type ErrorResponse, type FindLyricsResponse, type LyricLine, NoResultError, NotFoundError, type ParsedLyrics, type Query, RequestError, type Search, type SearchType, parseLocalLyrics, parseTime };