NAME

    Mojo::WebService::LastFM - Non-blocking recent tracks information from
    Last.FM

SYNOPSIS

        use Mojo::WebService::LastFM;
        use Data::Dumper;
    
        my $user = 'vsTerminus';
        my $last = Mojo::WebService::LastFM->new('api_key' => 'abc123');
    
        # Get currently playing or last played track using a callback, passing username as a scalar,
        # and dump the resulting hashref to screen using Data::Dumper
        $last->nowplaying($user, sub { say Dumper(shift) });
        
        # Get currently playing or last played track using a promise, passing username in a hashref
        $last->nowplaying_p({
            'username' => $user
        })->then(sub
        {
            my $np = shift;
            if ( exists $np->{'date'} )
            {
                say $user . ' last listened to ' . $np->{'title'} . ' by ' . $np->{'artist'} . ' from ' . $np->{'album'} . ' at ' . $np->{'date'};
            }
            else
            {
                say $user . ' is currently listening to ' . $np->{'title'} . ' by ' . $np->{'artist'} . ' from ' . $np->{'album'};
            }
        })->catch(sub
        {
            my $err = shift;
            die $err->message;
        });
        
        # Get a complete recent tracks payload using a callback
        # Print a formatted string of values
        $last->recenttracks({ 'username' => $user }, sub
        {
            my $json = shift;
            my $track = $json->{'recenttracks'}{'track'}[0];
            my $artist = $track->{'artist'}{'#text'};
            my $album = $track->{'album'}{'#text'};
            my $title = $track->{'name'};
            my $date = $track->{'date'};
            my $img = $track->{'image'};
    
            my $when = ( defined $date ? 'Last played' : 'Now playing' );
            say "$when $artist - $album - $title";
        });
        
        # Get a complete recent tracks payload using a promise
        # Dump the hashref to screen with Data::Dumper
        $last->recenttracks_p({ 'username' => $user })->then(sub{ say Dumper(shift) });

DESCRIPTION

    Mojo::WebService::LastFM is a way to request currently playing or
    recently played song information from Last.FM. Support exists for
    blocking calls or non-blocking with callbacks or promises - your
    choice.

    It also provides the option to either fetch the entire JSON return
    object as a hashref, or to fetch a simplified hashref which contains
    only the currently playing or last played song info. The latter is
    easier to work with if you just want to display the currently playing
    song.

ATTRIBUTES

 api_key

    You will need an API Key for Last.FM, which you can get from the
    Last.FM API page <https://www.last.fm/api/account/create>.

    You will receive an API Key and an API Secret. Each will be a string of
    base-16 numbers (0-9a-f).

    You don't need the API Secret for anything in this module (currently),
    but make sure when you get it you record it somewhere (eg your password
    vault) because LastFM won't show it to you again and you may need it in
    the future.

 ua

    A Mojo::UserAgent object is used to make all of the HTTP calls
    asynchronously.

 base_url

    This is the base URL for the Last.FM API site. It defaults to
    'http://ws.audioscrobbler.com/2.0'.

    API call URLs are made by appending endpoints to this base string.

METHODS

    Mojo::WebService::LastFM implements the following methods

 recenttracks

    Request the complete 'recenttracks' JSON structure from Last.FM

    Non-Blocking: Takes a hashref and a callback, returns nothing.
    Blocking: Takes a hashref, returns a hashref

    The parameters must contain at least a 'username' value, but may also
    specify a 'limit' value for the number of recent tracks to retrieve.

    The callback, if defined, should be a sub. recenttracks will call this
    sub and pass it the json object it got from the API.

        $lastfm->recenttracks({'username' => $some_user, 'limit' => 1}, sub { my $json = shift; ... }); # Non-Blocking
    
        my $json = $lastfm->recenttracks({'username' => $some_user, 'limit' => 2}); # Blocking

 recenttracks_p

    Version of recenttracks which accepts a params hashref and returns a
    Mojo::Promise

        $lastfm->recenttracks_p({'username' => $another_user})->then(sub{ say Dumper(shift) })->catch(sub{ say Dumper(shift) });

 nowplaying

    Return only the currently playing track or the last played track in a
    simplified object structure.

    Takes a username either as a scalar or as a hashref with the 'username'
    key and a callback sub. Sends the resulting JSON payload as a hashref
    to the callback.

    Alternatively takes just a username, makes a blocking call, and returns
    the JSON payload as a hashref.

    The response includes the Artist, Album, Title, and Album Art URL. If
    it is not the currently playing track it will also include the
    date/time of when the last track was played. Checking for the existence
    of the date key is the simplest way to determine if the song is
    currently playing or not.

        # As scalar
        $lastfm->nowplaying('SomeUser1234', sub { my $json = shift; say "Now Playing: " . $json->{'artist'} . " - " . $json->{'title'} ; });
    
        # As hashref
        $lastfm->nowplaying({'username' => 'SomeUser1234'}, sub { exists shift->{'date'} ? say "Last Played" : say "Currently Playing" });
    
        # Blocking
        my $json = $lastfm->nowplaying('SomeUser5678');

 nowplaying_p

    Promise version of nowplaying.

    Takes a username as a scalar or as a hashref, returns a Mojo::Promise

        $lastfm->nowplaying_p('SomeUser5678')->then(sub{ say Dumper(shift) });

 info

    Returns user profile info for the specified user.

    Accepts a username as a string and a callback sub. Sends the resulting
    JSON payload as a hashref to the callback.

    Alternatively accepts just a username and returns the JSON payload
    after making a blocking call.

        $lastfm->info($username, sub { say Dumper(shift) }); # Non-Blocking
    
        my $json = $lastfm->info($username); # Blocking

 info_p

    Promise version of info. Takes a username as a string, returns a
    Mojo::Promise

        $lastfm->info_p($user)->then(sub{ say Dumper(shift) });

BUGS

    Report any issues on the public bug tracker.

AUTHOR

    Travis Smith <tesmith@cpan.org>

COPYRIGHT AND LICENSE

    This software is Copyright (c) 2020 by Travis Smith.

    This is free software, licensed under:

      The MIT (X11) License

SEE ALSO

    Mojolicious, Mojolicious::Guides, https://mojolicious.org.

