diff options
| -rw-r--r-- | doc/emms.texinfo | 197 | ||||
| -rw-r--r-- | lisp/emms-lastfm-client.el | 46 |
2 files changed, 63 insertions, 180 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 diff --git a/lisp/emms-lastfm-client.el b/lisp/emms-lastfm-client.el index 20ec018..0ad8451 100644 --- a/lisp/emms-lastfm-client.el +++ b/lisp/emms-lastfm-client.el @@ -24,49 +24,9 @@ ;;; Commentary: ;; -;; There are restrictions on the use of this service. Quoting from -;; [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". -;; -;; 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. - -;;; Installation: -;; -;; Here is how to get authorization from Last.fm to stream -;; music. Thankfully this only needs to be done _once_: -;; -;; 1. Complete steps 1 and 2 from -;; [http://www.last.fm/api/authentication] to get an API key and a -;; secret key. Set `emms-lastfm-client-api-key' and -;; `emms-lastfm-client-api-secret-key' accordingly. -;; -;; 2. M-x emms-lastfm-client-user-authorization -;; -;; If this completes successfully a browser window will open asking -;; for confirmation to allow this application to access the Last.fm -;; account. Confirm and close the browser. -;; -;; 3. M-x emms-lastfm-client-get-session -;; -;; After this last step the permanent session key will be stored in -;; `emms-lastfm-client-session-key-file'. As long as this key value -;; is accessible the authentication process need never be repeated. - -;;; Use: -;; -;; M-x emms-lastfm-client-play-similar-artists -;; -;; Call the ...-play- family of interactive functions, such the above, -;; to start streaming music. -;; -;; To show the currently playing track: M-x emms-lastfm-client-show -;; -;; To skip to the next track: M-x emms-lastfm-client-track-advance -;; -;; ...more Last.fm functionality to come, so stay tuned. +;; Definitive information on how to setup and use this package is +;; provided in the wonderful Emms manual, in the /doc directory of the +;; Emms distribution. ;;; Code: |