pub struct Scrobbler { /* private fields */ }Expand description
A Last.fm Scrobbler client. Submits song play information to Last.fm.
This is a client for the Scrobble and Now Playing endpoints on the Last.fm API. It handles API client and user auth, as well as providing Scrobble and Now Playing methods, plus support for sending batches of songs to Last.fm.
See the official scrobbling API documentation for more information.
High-level example usage:
let username = "last-fm-username";
let password = "last-fm-password";
let api_key = "client-api-key";
let api_secret = "client-api-secret";
let mut scrobbler = Scrobbler.new(api_key, api_secret);
scrobbler.authenticate_with_password(username, password);
let song = Scrobble::new("Example Artist", "Example Song", "Example Album");
scrobbler.scrobble(song);Implementations§
Source§impl Scrobbler
impl Scrobbler
Sourcepub fn new(api_key: &str, api_secret: &str) -> Self
pub fn new(api_key: &str, api_secret: &str) -> Self
Creates a new Scrobbler instance with the given Last.fm API Key and API Secret
§Usage
let api_secret = "xxx";
let api_key = "123abc";
let mut scrobbler = Scrobbler::new(api_key, api_secret);
...
// Authenticate user with one of the available auth methods§API Credentials
All clients require the base API credentials: An API key and an API secret. These are obtained from Last.fm, and are specific to each client. These are credentials are totally separate from user authentication.
More information on authentication and API clients can be found in the Last.fm API documentation:
Sourcepub fn authenticate_with_password(
&mut self,
username: &str,
password: &str,
) -> Result<SessionResponse, ScrobblerError>
pub fn authenticate_with_password( &mut self, username: &str, password: &str, ) -> Result<SessionResponse, ScrobblerError>
Authenticates a Last.fm user with the given username and password.
This authentication path is known as the ‘Mobile auth flow’, but is valid for any platform. This is often the simplest method of authenticating a user with the API, requiring just username & password. Other Last.fm auth flows are available and might be better suited to your application, check the official Last.fm API docs for further information.
§Usage
let mut scrobbler = Scrobbler::new(...)
let username = "last-fm-user";
let password = "hunter2";
let response = scrobbler.authenticate_with_password(username, password);
...§Last.fm API Documentation
Sourcepub fn authenticate_with_token(
&mut self,
token: &str,
) -> Result<SessionResponse, ScrobblerError>
pub fn authenticate_with_token( &mut self, token: &str, ) -> Result<SessionResponse, ScrobblerError>
Authenticates a Last.fm user with an authentication token. This method supports both the ‘Web’ and ‘Desktop’ Last.fm auth flows (check the API documentation to ensure you are using the correct authentication method for your needs).
§Usage
let mut scrobbler = Scrobbler.new(...);
let auth_token = "token-from-last-fm";
let response = scrobbler.authenticate_with_token(auth_token);§Last.fm API Documentation
Sourcepub fn authenticate_with_session_key(&mut self, session_key: &str)
pub fn authenticate_with_session_key(&mut self, session_key: &str)
Authenticates a Last.fm user with a session key.
§Usage
let mut scrobbler = Scrobbler::new(...);
let session_key = "securely-saved-old-session-key";
let response = scrobbler.authenticate_with_session_key(session_key);§Response
This method has no response: the crate expects a valid session key to be provided here and has no way to indicate if an invalidated key has been used. Clients will need to manually detect any authentication issues via API call error responses.
§A Note on Session Keys
When authenticating successfully with username/password or with an authentication token (
authenticate_with_password or authenticate_with_token), the Last.fm API will provide a Session Key.
The Session Key is used internally to authenticate all subsequent requests to the Last.fm API.
Session keys are valid indefinitely. Thus, they can be stored and used for authentication at a later time.
A common pattern would be to authenticate initially via a username/password (or any other authentication flow)
but store ONLY the session key (avoiding difficulties of securely storing usernames/passwords that can change
etc.) and use this method to authenticate all further sessions. The current session key can be fetched for
later use via Scrobbler::session_key.
Sourcepub fn now_playing(
&self,
scrobble: &Scrobble,
) -> Result<NowPlayingResponse, ScrobblerError>
pub fn now_playing( &self, scrobble: &Scrobble, ) -> Result<NowPlayingResponse, ScrobblerError>
Registers the given Scrobble/track as the currently authenticated user’s “now playing” track.
Most scrobbling clients will set the now-playing track as soon as the user starts playing it; this makes it appear temporarily as the ‘now listening’ track on the user’s profile. However use of this endpoint/method is entirely optional and can be skipped if you want.
§Usage
This method behaves largely identically to the Scrobbler::scrobble method, just pointing to a different
endpoint on the Last.fm API.
let scrobbler = Scrobbler::new(...);
// Scrobbler authentication ...
let now_playing_track = Scrobble::new("Example Artist", "Example Track", "Example Album");
match scrobbler.now_playing(now_playing_track) {
Ok(_) => println!("Now playing succeeded!"),
Err(err) => println("Now playing failed: {}", err)
};§Response
On success a NowPlayingResponse is returned. This can often be ignored (as in the example code), but it
contains information that may be of use to some clients.
§Last.fm API Documentation
Sourcepub fn scrobble(
&self,
scrobble: &Scrobble,
) -> Result<ScrobbleResponse, ScrobblerError>
pub fn scrobble( &self, scrobble: &Scrobble, ) -> Result<ScrobbleResponse, ScrobblerError>
Registers a scrobble (play) of the given Scrobble/track.
§Usage
Your Scrobbler must be fully authenticated before using Scrobbler::scrobble.
let scrobbler = Scrobbler::new(...);
// Scrobbler authentication ...
let scrobble_track = Scrobble::new("Example Artist", "Example Track", "Example Album");
match scrobbler.scrobble(scrobble_track) {
Ok(_) => println!("Scrobble succeeded!"),
Err(err) => println("Scrobble failed: {}", err)
};§Response
On success a ScrobbleResponse is returned. This can often be ignored (as in the example code), but it
contains information that may be of use to some clients.
§Last.fm API Documentation
track.scrobble API Method Documention Scrobble Request Documentation
Sourcepub fn scrobble_batch(
&self,
batch: &ScrobbleBatch,
) -> Result<BatchScrobbleResponse, ScrobblerError>
pub fn scrobble_batch( &self, batch: &ScrobbleBatch, ) -> Result<BatchScrobbleResponse, ScrobblerError>
Registers a scrobble (play) of a collection of tracks.
Takes a ScrobbleBatch, effectively a wrapped Vec<Scrobble>, containing one or more Scrobble objects
which are be submitted to the Scrobble endpoint in a single batch.
§Usage
Each ScrobbleBatch must contain 50 or fewer tracks. If a ScrobbleBatch containing more than 50
Scrobbles is submitted an error will be returned. An error will similarly be returned if the batch contains
no Scrobbles. An example batch scrobbling client is in the examples directory:
examples/example_batch.rs.
let tracks = vec![
("Artist 1", "Track 1", "Album 1"),
("Artist 2", "Track 2", "Album 2"),
];
let batch = ScrobbleBatch::from(tracks);
let response = scrobbler.scrobble_batch(&batch);§Response
On success, returns a ScrobbleBatchResponse. This can be ignored by most clients, but contains some data
that may be of interest.
§Last.fm API Documentation
Sourcepub fn session_key(&self) -> Option<&str>
pub fn session_key(&self) -> Option<&str>
Gets the session key the client is currently authenticated with. Returns None if not authenticated. Valid
session keys can be stored and used to authenticate with authenticate_with_session_key.
See authenticate_with_session_key for more information on Last.fm API Session Keys