Scrobblenaut

Installation

Add Scrobblenaut to your project:

dart pub add scrobblenaut

Or manually in pubspec.yaml:

dependencies:
  scrobblenaut: ^3.0.1

Usage

1. Unauthenticated Requests (Search & Metadata)

For methods that do not require user authorization (e.g. searching artists, albums, tracks, fetching tags or charts):

import 'package:scrobblenaut/scrobblenaut.dart';

void main() async {
  final lastFM = LastFM.noAuth(apiKey: 'YOUR_API_KEY');
  final scrobblenaut = Scrobblenaut(lastFM: lastFM);

  // Fetch track metadata
  final track = await scrobblenaut.track.getInfo(
    artist: 'Daft Punk',
    track: 'One More Time',
  );

  print('Track listeners: ${track.listeners}');
}

2. Authenticated Requests (Scrobbling & Now Playing)

You can authenticate using a pre-existing session key, user credentials, or an authorized web/desktop token:

import 'package:scrobblenaut/scrobblenaut.dart';

void main() async {
  // Option A: Using an existing session key (recommended for apps after first login)
  final lastFM = LastFM.withSessionKey(
    apiKey: 'YOUR_API_KEY',
    apiSecret: 'YOUR_API_SECRET',
    sessionKey: 'YOUR_SESSION_KEY',
  );

  // Option B: Authenticating with credentials via mobile session
  // final lastFM = await LastFM.authenticate(
  //   apiKey: 'YOUR_API_KEY',
  //   apiSecret: 'YOUR_API_SECRET',
  //   username: 'YOUR_USERNAME',
  //   password: 'YOUR_PASSWORD',
  // );

  final scrobblenaut = Scrobblenaut(lastFM: lastFM);

  // Update Now Playing
  await scrobblenaut.track.updateNowPlaying(
    artist: 'Daft Punk',
    track: 'One More Time',
    album: 'Discovery',
  );

  // Scrobble a track
  final response = await scrobblenaut.track.scrobble(
    artist: 'Daft Punk',
    track: 'One More Time',
    album: 'Discovery',
    timestamp: DateTime.now(),
  );

  print('Scrobble accepted: ${response.accepted}');
}

Authentication Options:

• LastFM.withSessionKey(...): Instantiate with an already stored session key (best practice for persisted sessions).
• LastFM.authenticateWithToken(...): Exchange an authorized web/desktop token (auth.getSession).
• LastFM.authenticate(...): Authenticate directly with username and password (auth.getMobileSession).

Development

If you are cloning this repository to contribute:

dart run build_runner build

Run tests and analyzer:

dart test
dart analyze

Documentation

Full API documentation is available at pub.dev/documentation/scrobblenaut.

Please file bug reports and feature requests on GitHub Issues.