lrclib

README

lrclib-go

Go client for the LRCLIB lyrics API and parser for synchronized LRC text files.

Features

• Fast LRC parser that skips metadata tags and extracts timed lines without regular expressions
• LRCLIB REST client to search tracks, look up by ID, and fetch synchronized or plain lyrics
• Built-in request pacing and automatic backoff on HTTP 429 using Retry-After
• Standard library only, no external dependencies

Installation

go get github.com/fumbledlol/lrclib-go

Usage

Parsing synchronized LRC

package main

import (
	"fmt"

	"github.com/fumbledlol/lrclib-go"
)

func main() {
	rawLRC := `[ti:Song Title]
[00:12.34]First lyric line
[00:15.50]Second lyric line`

	lines, err := lrclib.ParseLRC(rawLRC)
	if err != nil {
		panic(err)
	}

	for _, line := range lines {
		fmt.Printf("[%v] (%.2fs) %s\n", line.Timestamp, line.Seconds, line.Text)
	}
}

Fetching lyrics from LRCLIB

client := lrclib.NewClient()

lyrics, err := client.Get(ctx, "Track Name", "Artist Name", "Album Name", 210.0)
if err != nil {
	// Handle ErrNotFound or request error
}

// Access timed lines
lines, err := lyrics.Lines()

Benchmarks

BenchmarkParseLRC-12    4112946    306.9 ns/op    352 B/op    1 allocs/op

License

MIT

Documentation

Index

• Constants
• Variables
• type Client
  • func NewClient(opts ...ClientOption) *Client
  • func (c *Client) Get(ctx context.Context, trackName, artistName, albumName string, duration float64) (*Lyrics, error)
  • func (c *Client) GetByID(ctx context.Context, id int64) (*Lyrics, error)
  • func (c *Client) Search(ctx context.Context, params SearchParams) ([]Lyrics, error)
• type ClientOption
  • func WithBaseURL(url string) ClientOption
  • func WithHTTPClient(client *http.Client) ClientOption
  • func WithMinInterval(interval time.Duration) ClientOption
  • func WithUserAgent(ua string) ClientOption
• type Line
  • func ParseLRC(syncedLyrics string) ([]Line, error)
• type Lyrics
  • func (l *Lyrics) Lines() ([]Line, error)
• type SearchParams

Constants

const (
	DefaultBaseURL   = "https://lrclib.net/api"
	DefaultUserAgent = "lrclib-go/1.0 (https://github.com/fumbledlol/lrclib-go)"
)

Variables

var (
	// ErrNotFound is returned when LRCLIB returns 404.
	ErrNotFound = errors.New("lrclib: lyrics not found")
	// ErrRateLimited is returned when LRCLIB rate limits the request and backoff could not recover.
	ErrRateLimited = errors.New("lrclib: rate limited")
)

var (
	// ErrInvalidLRC indicates the input is not valid LRC formatted text.
	ErrInvalidLRC = errors.New("lrclib: invalid or empty LRC data")
)

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client interacts with the LRCLIB REST API.

func NewClient

func NewClient(opts ...ClientOption) *Client

NewClient creates a new LRCLIB client.

func (*Client) Get

func (c *Client) Get(ctx context.Context, trackName, artistName, albumName string, duration float64) (*Lyrics, error)

Get fetches lyrics by exact track and artist metadata.

func (*Client) GetByID

func (c *Client) GetByID(ctx context.Context, id int64) (*Lyrics, error)

GetByID fetches lyrics by LRCLIB database ID.

func (*Client) Search

func (c *Client) Search(ctx context.Context, params SearchParams) ([]Lyrics, error)

Search searches for lyrics matching query parameters.

type ClientOption

type ClientOption func(*Client)

ClientOption configures a Client.

func WithBaseURL

func WithBaseURL(url string) ClientOption

WithBaseURL overrides the default API base URL.

func WithHTTPClient

func WithHTTPClient(client *http.Client) ClientOption

WithHTTPClient overrides the default HTTP client.

func WithMinInterval

func WithMinInterval(interval time.Duration) ClientOption

WithMinInterval configures the rate-limiting spacing between requests.

func WithUserAgent

func WithUserAgent(ua string) ClientOption

WithUserAgent overrides the default User-Agent header.

type Line

type Line struct {
	Timestamp time.Duration `json:"timestamp"`
	Seconds   float64       `json:"seconds"`
	TimeStr   string        `json:"time_str"`
	Text      string        `json:"text"`
}

Line represents a single synchronized lyric line.

func ParseLRC

func ParseLRC(syncedLyrics string) ([]Line, error)

ParseLRC parses synchronized LRC text into a slice of timed lines. It skips metadata tags (e.g. [ar:...]) and extracts all valid timestamped lines.

type Lyrics

type Lyrics struct {
	ID           int64   `json:"id"`
	Name         string  `json:"name,omitempty"`
	TrackName    string  `json:"trackName"`
	ArtistName   string  `json:"artistName"`
	AlbumName    string  `json:"albumName,omitempty"`
	Duration     float64 `json:"duration"`
	Instrumental bool    `json:"instrumental"`
	PlainLyrics  string  `json:"plainLyrics,omitempty"`
	SyncedLyrics string  `json:"syncedLyrics,omitempty"`
}

Lyrics represents the response payload from LRCLIB.

func (*Lyrics) Lines

func (l *Lyrics) Lines() ([]Line, error)

Lines parses the SyncedLyrics into timed lines.

type SearchParams

type SearchParams struct {
	Query      string  `json:"q,omitempty"`
	TrackName  string  `json:"track_name,omitempty"`
	ArtistName string  `json:"artist_name,omitempty"`
	AlbumName  string  `json:"album_name,omitempty"`
	Duration   float64 `json:"duration,omitempty"`
}

SearchParams contains query parameters for searching lyrics.