lfm_api

README

lfm-api

lfm-api is a Go package that provides an interface to interact with the Last.fm API, allowing you to retrieve information about a users recent scrobbles, without the need for an API key.

Installation

Install the package using go get:

go get github.com/twangodev/lfm-api

Usage

The primary function of the package is to retrieve a users recent scrobbles. To do this, you can use the GetActiveScrobble function:

func main() {
    // Get the most recent scrobble
    scrobble, err := lfm.GetActiveScrobble("twangodev")
    if err != nil {
        fmt.Println(err)
        return
    }

    fmt.Println(scrobble)
}

The GetActiveScrobble function returns a Scrobble struct, which contains the following fields:

type Scrobble struct {
	Active        bool      // Whether the user is actively scrobbling
	Name          string    // The name of the track
	Artist        string    // The artist of the track
	Album         string    // The album of the track
	Loved         bool      // Whether the user loves the track
	DataId        string    // A unique ID used to identify the scrobble, generated by Last.FM
	DataTimestamp time.Time // When the user began scrobbling
	DataLink      string    // A link to the track (YouTube, etc.)
	DataLinkTitle string    // A description for the dataLink
	CoverArtUrl   string    // A URL to the album cover art
}

[!TIP] The GetActiveScrobble function will return EmptyScrobble if the user is not actively scrobbling.

EmptyScrobble is a Scrobble struct with all fields set to their zero values, and Active set to false.

var EmptyScrobble = Scrobble{
Active: false,
}

[!IMPORTANT] The underlying implementation used by lfm-api utilizes an unofficial endpoint of the Last.fm API, which allows the package to obtain information without an API key. As such, the API may change or be removed at any time. The package is provided as-is, with no guarantees of support or functionality.

When building applications that rely on the Last.fm API, it is recommended to use the official API and obtain an API key. However, for simple applications or personal use, lfm-api provides a quick and easy way to retrieve scrobble information.

It is recommended to use this package on the client-side only, as it may not scale well for server-side applications, and could potentially be rate-limited by Last.fm.

For more information about lfm-api, you can view the source code on GitHub.

Fetching and tests

The client automatically completes the supported Fastly SHA-256 proof-of-work challenge and keeps verification cookies in memory between calls. Cookies are renewed when challenged again. Unsupported challenges, unexpected HTML, and failed requests return errors; callers should retain their previous state and retry later. Requests have timeouts, response size limits, and bounded challenge retries. No browser or API key is required for the supported challenge.

Run offline tests with go test -race ./.... To also check the live endpoint:

LFM_LIVE_TEST_USER=your_username go test -run '^TestGetActiveScrobble$' -count=1 -v

Releases

Conventional Commits on main update a Release Please PR containing the next version and changelog. Merging that PR creates the version tag and GitHub release. Go consumers install the tagged module directly; the same workflow verifies its availability from proxy.golang.org.

CHANGELOG.md includes the original published notes for v1.0.0 through v1.1.1. Release Please maintains subsequent entries automatically.

The pipeline uses the repository's built-in GITHUB_TOKEN; no additional secrets or OIDC setup are needed. GitHub Actions must be allowed to create pull requests. PRs created with that token do not trigger PR workflows automatically; tests run on main before release creation. Ordinary pushes and pull requests run tests too, using both Go 1.20 and the current stable Go release.

To retry the Go proxy availability check, run the CI workflow manually with the existing release tag (for example v1.1.2). Leave the tag empty to run normal CI and rebuild documentation. Tag verification runs do not deploy documentation.

All automation lives in .github/workflows/ci.yml: Go tests, Release Please, module availability checks, and documentation build/deployment. Documentation builds on pushes and normal manual runs, and deploys to GitHub Pages from main. The Pages deployment uses its existing OIDC permissions; releases use GITHUB_TOKEN.

Roadmap

The following features are planned for future releases of lfm-api, if the unofficial endpoint remains available, and there is interest in the features

• Retrieving more than the most recent scrobble
• Retrieving a users top tracks
• Retrieving a users top artists
• Retrieving a users top albums

If you would like to see any of these features implemented, or have any other suggestions, feel free to open an issue on the GitHub repository.

Documentation

Index

• Constants
• Variables
• type Scrobble
  • func GetActiveScrobble(username string) (Scrobble, error)
  • func (s Scrobble) String() string

Constants

const LastFmUrl = "https://www.last.fm/"

Variables

var EmptyScrobble = Scrobble{
	Active: false,
}

Types

type Scrobble

type Scrobble struct {
	Active        bool      // Whether the user is actively scrobbling
	Name          string    // The name of the track
	Artist        string    // The artist of the track
	Album         string    // The album of the track
	Loved         bool      // Whether the user loves the track
	DataId        string    // A unique ID used to identify the scrobble, generated by Last.FM
	DataTimestamp time.Time // When the user began scrobbling
	DataLink      string    // A link to the track (YouTube, etc.)
	DataLinkTitle string    // A description for the dataLink
	CoverArtUrl   string    // A URL to the album cover art
}

Scrobble represents a scrobble on Last.FM.

func GetActiveScrobble

func GetActiveScrobble(username string) (Scrobble, error)

GetActiveScrobble returns the active scrobble for the given user.

func (Scrobble) String

func (s Scrobble) String() string