Document emms-lastfm-client.el

1 files changed, 60 insertions, 137 deletions

diff --git a/doc/emms.texinfo b/doc/emms.texinfo
index 1fca86c..c34f7d7 100644
--- a/doc/emms.texinfo
+++ b/doc/emms.texinfo
@@ -81,7 +81,7 @@ Modules and Extensions
 * Streaming Audio::      Interface to streaming audio.
 * Lyrics::               Displaying lyrics synchronously.
 * Volume::               Changing the volume.
-* Last.fm::              Interact with http://www.last.fm's services.
+* Last.fm::              Interact with the Last.fm service.
 * APE / FLAC Commands::  How to play next or previous track in these files.  
 * Extending Emms::       How to define new players and modules.
 
@@ -115,8 +115,8 @@ Track Information
 * Defining Info Methods::    Defining new info methods.
 
 Last.fm
-* Submitting track informations:: How to submit track information to last.fm.
-* Last.fm radio::                 How to listen to last.fm radio.
+* Last.fm Setup::            Configuring Emms to use Last.fm.
+* Last.fm Radio::            Listening to music through Last.fm.
 
 Extending Emms
 * New Player::               How to define a new player.
@@ -2212,160 +2212,83 @@ by six steps of @code{emms-volume-change-amount}, you would simply type
 
 @cindex last.fm
 
-Currently the `emms-lastfm' package provided by the file
-@file{emms-lastfm.el} offers the two most important last.fm services.
+Last.fm is a popular commercial music streaming service. Last.fm
+allows a subscriber to listen to streaming music. Last.fm can also
+accept data as to what music is played locally. This information can
+be used by the Last.fm service. As usual the responsibility is on the
+user to decide how much information to share with third-parties.
 
-@enumerate
-@item
-It can submit informations of tracks (artist, title, album) you listen
-to to last.fm to enhance your music profile.
-
-@item
-You can listen to the Last.fm radio. Those are the streams beginning
-with lastfm://.
-@end enumerate
-
-For both services you need a last.fm account and you have to set up
-two variables.
-
-@defopt emms-lastfm-username
-Your last.fm username.
-@end defopt
-
-@defopt emms-lastfm-password
-Your last.fm password.
-@end defopt
-
-To set them in your @file{.emacs} add something like this.
-
-@lisp
-(setq emms-lastfm-username "my-user-name"
-      emms-lastfm-password "very-secret!")
-@end lisp
+The emms-lastfm-client package, provided the file
+@file{emms-lastfm-client.el} provides native Last.fm support from
+within Emms.
 
-You can edit them with the `customize' interface, too.
+Emms does not provide a subscription to the Last.fm service, nor is it
+affiliated with the service in any way. There are restrictions on the
+use of this service. Quoting from @uref{http://www.last.fm/api/radio}:
+``Who can I stream radio to? Any API account can only stream radio to
+Last.fm's paid subscribers''.
 
 @menu
-* Submitting track informations:: How to submit track information to last.fm.
-* Last.fm radio::                 How to listen to last.fm radio.
+* Last.fm Setup::            Configuring Emms to use Last.fm.
+* Last.fm Radio::            Listening to music through Last.fm
 @end menu
 
-@node Submitting track informations
-@section Submitting track informations
-
-These functions enable/disable submission of track informations to
-last.fm.
-
-@defun emms-lastfm-enable
-Start submitting to last.fm. Note that submission will start with the
-next track, not the current one.
-@end defun
-
-@defun emms-lastfm-disable
-Stop submission of track informations.
-@end defun
-
-If you want to enable submission of tracks by default, put this into
-your @file{.emacs}.
-
-@lisp
-(emms-lastfm-activate)
-@end lisp
-
-@node Last.fm radio
-@section Last.fm radio
-
-On http://www.last.fm you'll find lots of links referencing last.fm
-radio stations like lastfm://artist/Metallica/fans. You can listen to
-them using these functions.
-
-@defun emms-lastfm-radio lastfm-url
-Starts playing the stream referenced by @var{lastfm-url}. When run
-interactively you will be prompted for a last.fm URL.
-@end defun
-
-You can also insert Last.fm streams into playlists (or use
-emms-streams.el to listen to them) by activating the player as follows.
-
-@lisp
-(add-to-list 'emms-player-list 'emms-player-lastfm-radio)
-@end lisp
-
-To add a Last.fm stream into the current playlist, do the following:
-@kbd{M-x emms-add-lastfm RET lastfm://rest-of-url RET}. To directly
-start playing use @command{emms-play-lastfm}.
-
-To read more about the concept of the ``current'' playlist
-@xref{Playlists}. To add a last.fm stream to the playlist buffer that's
-currently browsed (which might not be the ``current'' playlist), use
-@command{emms-insert-lastfm} instead.
-
-For your convenience there are some functions which let you choose a
-common radio station without having to remember or type its last.fm URL.
-
-@defun emms-play-lastfm-similar-artists artist
-Starts playing the similar artist radio of @var{artist}. When run
-interactively you will be prompted for an artist name.
-@end defun
-
-@defun emms-play-lastfm-global-tag tag
-Starts playing the global tag radio of @var{tag}. When run interactively
-you will be prompted for a tag name.
-@end defun
-
-@defun emms-play-lastfm-artist-fan artist
-Starts playing the artist fan radio of @var{artist}. When run
-interactively you will be prompted for an artist name.
-@end defun
+@node Last.fm Setup
+@section Last.fm Setup
 
-While listening to a last.fm radio station `emms-lastfm' will try to
-fetch some meta-informations (artist and title) of the currently playing
-song. That's controlled by the following variable:
+We've spoken to representatives from Last.fm and arrived at the
+following agreement: In order to be able to use the service while
+preserving the essential freedoms of the GPL each client must apply
+for their own API key from Last.fm.
 
-@defopt emms-lastfm-radio-metadata-period
-When listening to Last.fm Radio every how many seconds should
-emms-lastfm poll for metadata? If set to nil, there won't be any
-polling at all.
+Here are the steps for getting authorization from Last.fm to stream
+music. Thankfully this only needs to be done once:
 
-The default is 15: That means that the mode line will display the
-wrong (last) track's data for a maximum of 15 seconds. If your
-network connection has a big latency this value may be too
-high. (But then streaming a 128KHz mp3 won't be fun anyway.)
-@end defopt
+@enumerate
 
-Even if you set this variable to nil (no polling) you can fetch the
-meta-informations with one of the following functions.
+@item
+Complete steps 1 and 2 from
+@uref{http://www.last.fm/api/authentication} to get an API key and a
+secret key. Set the variables @var{emms-lastfm-client-api-key} and
+@var{emms-lastfm-client-api-secret-key} respectively.
 
-@defun emms-lastfm-radio-request-metadata
-Request the metadata of the current song and display it in the
-mode-line if the `emms-mode-line' package is enabled.
-@end defun
+@item
+Invoke @kbd{M-x emms-lastfm-client-user-authorization}. On successful
+completion a browser window will open asking for confirmation to allow
+this application access to your Last.fm account. Confirm and close the
+browser.
 
-@defun emms-lastfm-np
-Show the currently-playing lastfm radio tune.
+@item
+Invoke @kbd{M-x emms-lastfm-client-get-session}. On successful
+completion your permanent session key will be stored in
+@var{emms-lastfm-client-session-key-file}. As long as this value is
+accessible the authentication process need not be repeated.
 
-If you prefixed the command with @kbd{C-u}, the current song information
-is inserted at point.
+@end enumerate
 
-Otherwise, display a message with the current song information.
-@end defun
+After successfully completing the above Emms should be authorized to
+access your Last.fm account.
 
-When you listen to last.fm radio you can rate or skip the current song.
+@node Last.fm Radio
+@section Last.fm Radio
 
-@defun emms-lastfm-radio-love
-Inform Last.fm that you love the currently playing song.
-@end defun
+Currently the only music streaming service provided by
+emms-lastfm-client is Last.fm's "play similar artists". More services
+will be implemented Real Soon Now.
 
-@defun emms-lastfm-radio-skip
-Inform Last.fm that you want to skip the currently playing song.
-@end defun
+Note that Last.fm streams cannot be paused or replayed. Doing so may
+cause Last.fm to suspend your account.
 
-@defun emms-lastfm-radio-ban
-Inform Last.fm that you want to ban the currently playing song.
-@end defun
+To play the Similar-Artists stream invoke @kbd{M-x
+emms-lastfm-client-play-similar-artists}. Then enter the name of the
+artist. The input will auto-complete from the Emms cache. If an artist
+is not in the Emms cache and has a name with spaces, use @kbd{C-q
+Space} to enter literal spaces.
 
-Ok, that's all.
+To show information about the currently playing track invoke @kbd{M-x
+emms-lastfm-client-show}.
 
+To skip a track invoke @kbd{M-x emms-lastfm-client-track-advance}.
 
 @node Streaming Audio
 @chapter Streaming Audio