add emms
[emacs.git] / .emacs.d / elisp / emms / doc / emms.texinfo
1 \input texinfo @c -*-texinfo-*-
2 @c %**start of header
3 @setfilename emms.info
4 @settitle The Emms Manual
5 @c %**end of header
6
7 @c History: The Emms manual was almost entirely rewritten for the
8 @c release of Emms version 2.
9
10 @c As a rule, modules which are stable enough to be included into the
11 @c `emms-all' setup level should be documented. That is, any feature
12 @c which is considered stable should be included.
13
14 @dircategory Emacs
15 @direntry
16 * Emms: (emms). The Emacs Multimedia System
17 @end direntry
18
19 @copying
20 @copyright{} 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011
21 Free Software Foundation, Inc.
22 @quotation
23 Permission is granted to copy, distribute and/or modify this document
24 under the terms of the GNU Free Documentation License, Version 1.1 or
25 any later version published by the Free Software Foundation; with no
26 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
27 copy of the license is included in the section entitled "GNU Free
28 Documentation License".
29 @end quotation
30 @end copying
31
32 @c For printed material
33 @titlepage
34 @title The Emms Manual
35
36 @page
37 @vskip 0pt plus 1filll
38 @insertcopying
39 @end titlepage
40
41 @contents
42 @c END For printed material
43
44 @ifnottex
45 @node Top, Introduction, (dir), (dir)
46 @top Emms Manual
47
48 This is the Manual for the Emacs Multimedia System.
49
50 @insertcopying
51
52 @menu
53 Starting out
54 * Introduction:: Introduction to Emms.
55 * Installation:: How to install Emms on your System.
56 * Simple Setup:: Quick, basic default Emms setup.
57 * Configuration:: More detailed setup and configuration.
58 * Quickstart Guide:: First steps with EMMS for new users.
59 * Getting Help:: Where to get help with Emms and make suggestions.
60 * Formats and Freedom:: File formats without restrictions.
61
62 Emms basics
63 * Basic Commands:: How to control Emms with ease.
64 * The Core File:: The inner core of Emms.
65 * Sources:: Sources for playlists-creation.
66 * Simple Players:: Some simple players.
67 * Playlists:: How Emms organizes media.
68
69 Advanced Features
70 * Track Information:: More narrative track descriptions.
71 * Interactive Playlists:: Interactive Playlists.
72 * Markable Playlists:: Allow tracks to be marked.
73
74 Modules and Extensions
75 * The Browser:: Advanced metadata browsing.
76 * Sorting Playlists:: Sorting the order of the tracks.
77 * Persistent Playlists:: Restoring playlists on emacs startup.
78 * Editing Tracks:: Editing track information from within Emms.
79 * Emms Mode Line:: Emms information on the mode line.
80 * Music Player Daemon:: Interface to Music Player Daemon.
81 * Streaming Audio:: Interface to streaming audio.
82 * Lyrics:: Displaying lyrics synchronously.
83 * Volume:: Changing the volume.
84 * Last.fm:: Interact with the Last.fm service.
85 * APE / FLAC Commands:: How to play next or previous track in these files.
86 * Bookmarks:: Saving a place in a media file.
87 * Extending Emms:: How to define new players and modules.
88
89 Copying and license
90 * Copying:: The GNU General Public License gives you permission to
91 redistribute Emms on certain terms; it also explains
92 that there is no warranty.
93 * The GNU FDL:: The license for this documentation.
94
95 Indices
96 * Concept Index::
97 * Function Index::
98 * Variable Index::
99 * Keybinding Index::
100
101 @detailmenu
102 --- The Detailed Node Listing ---
103
104 Here are some other nodes which are really inferiors of the ones
105 already listed, mentioned here so you can get to them in one step:
106
107 Installation
108 * Compiling Emms:: Compiling Emms into Byte-Code.
109
110 The Core File
111 * User Variables:: Variables for the user to tweak.
112 * Hooks:: Hooks for important Emms functions.
113 * Core Functions:: Providing the basic functionality of Emms.
114
115 Track Information
116 * Defining Info Methods:: Defining new info methods.
117
118 Last.fm
119 * Last.fm Setup:: Configuring Emms to use Last.fm.
120 * Last.fm Radio:: Listening to music through Last.fm.
121 * Last.fm Audioscrobbler:: Submitting music to Last.fm
122
123 Extending Emms
124 * New Player:: How to define a new player.
125 * Simple Player for `play':: Example player using @command{play}.
126 * More Complex Player:: Example of a complex player using @command{mpg321}.
127 @end detailmenu
128 @end menu
129
130 @end ifnottex
131
132
133 @node Introduction
134 @chapter Introduction
135
136 @cindex introduction
137
138 Emms is the Emacs Multi-Media System. It tries to be a clean and small
139 application to play multimedia files from Emacs using external
140 players. Many of its ideas are derived from
141 @uref{http://www.nongnu.org/mp3player, MpthreePlayer}, but it tries to
142 be more general and more clean.
143
144 This manual tries to be the definitive source of information about
145 Emms, an online version of the manual is available at:
146 @uref{http://www.gnu.org/software/emms/manual/}.
147
148 The basic functionality of Emms consists of three parts: The core, the
149 sources, and the players.
150
151 The core resides in @file{emms.el}, and provides a simple playlist and the
152 basic functionality to use all the other features of Emms. It provides
153 the common user commands and interfaces for other parts. It thinks in
154 tracks, where a track is the combination of a type and a name - e.g.
155 the track type 'file has a name that is the file name. Other track
156 types are possible.
157
158 To get to tracks, the core needs sources. The file @file{emms-source-file.el}
159 provides simple sources to interact with the file system.
160
161 When Emms finally has the sources in the playlist, it needs a player
162 to play them. @file{emms-player-simple.el} defines a few useful players, and
163 allows you to define your own in a very simple way.
164
165 The way Emms works is easy to customize with your own code or by using
166 `M-x customize'.
167
168 @node Installation
169 @chapter Installation
170
171 @cindex installation
172
173 You need to put all the .el files of emms in a directory in your
174 load-path. For example, if you put all those files into ~/elisp/emms/,
175 then in your ~/.emacs, you should do:
176
177 @lisp
178 (add-to-list 'load-path "~/elisp/emms/lisp/")
179 @end lisp
180 @noindent
181
182 @menu
183 * Compiling Emms:: Compiling Emms into Byte-Code.
184 @end menu
185
186 @node Compiling Emms
187 @section Compiling Emms
188
189 @cindex compiling
190
191 If you are using XEmacs, you will need to edit @file{Makefile} as
192 follows before continuing.
193
194 @example
195 EMACS=xemacs
196 SITEFLAG=-no-site-file
197 @end example
198
199 You can byte-compile Emms by first entering the directory containing the
200 Emms source code, followed by invoking:
201
202 @command{make}
203
204 Which will byte compile Emms. You can then invoke:
205
206 @command{make install}
207
208 Which will install Emms into your Emacs directories (provided you have
209 the appropriate permissions to do so on your system).
210
211 Note that Emms is a light-weight and agile program, you can therefore
212 run Emms just fine without byte compiling it.
213
214 @node Simple Setup
215 @chapter Simple Setup
216
217 @cindex simple setup
218 @cindex setting up Emms
219 @cindex quick setup
220
221 After adding the location of the Emms code to the @var{load-path}
222 variable, see @xref{Installation}. We invoke the following using the
223 `emms-setup' feature which allows for quick and simple Emms setup.
224
225 @lisp
226 (require 'emms-setup)
227 (emms-standard)
228 (emms-default-players)
229 @end lisp
230
231 After which Emms is set-up and ready to go!
232
233 The above will setup Emms with standard features (interactive
234 playlists, audio track tag reading etc.) and a default list of players
235 (ogg, mp3, mplayer etc.).
236
237 The `emms-setup' feature is provided by the file
238 @file{emms-setup.el}. It is essentially a collection of shortcuts for
239 setting up Emms quickly and simply. Everything you can do with
240 `emms-setup' can also be done manually.
241
242 We use `emms-setup' by calling one of the setup functions. Each of the
243 functions sets up Emms to include a number of features.
244
245 @defun emms-minimalistic
246 An Emms setup script.
247 Invisible playlists and all the basics for playing media.
248 @end defun
249
250 @defun emms-standard
251 An Emms setup script.
252 Everything included in the @code{emms-minimalistic} setup, the Emms
253 interactive playlist mode and reading information from tagged
254 audio files.
255 @end defun
256
257 @defun emms-all
258 An Emms setup script.
259 Everything included in the @code{emms-standard} setup and adds all the
260 stable features which come with the Emms distribution.
261 @end defun
262
263 @defun emms-devel
264 An Emms setup script.
265 Everything included in the @code{emms-all} setup and adds all of the
266 features which come with the Emms distribution regardless of if they
267 are considered stable or not. Use this if you like living on the
268 edge.
269 @end defun
270
271 `emms-setup' also comes with a convenience function to set a default
272 list of media players.
273
274 @defun emms-default-players
275 Set @var{emms-player-list} to @var{emms-setup-default-player-list}.
276 @end defun
277
278 It is also worth noting that you can write your own Emms setup
279 functions like the above by looking at the existing function
280 definitions in @file{emms-setup.el}.
281
282 @node Configuration
283 @chapter Configuration
284
285 @cindex Configuration
286
287 This chapter discusses the configuration of Emms in more detail.
288
289 The following code fragment provides a minimal Emms setup without
290 using the layer of `emms-setup'. It can maybe be used to better
291 understand the internals of Emms. You can see how Emms needs to know
292 about players (these are defined in `emms-player-simple') and about
293 sources for tracks (trivial file system based sources, such as this
294 `emms-directory-tree', are defined in `emms-source-file').
295
296 @lisp
297 (require 'emms-player-simple)
298 (require 'emms-source-file)
299 (require 'emms-source-playlist)
300 (setq emms-player-list '(emms-player-mpg321
301 emms-player-ogg123
302 emms-player-mplayer))
303 @end lisp
304
305 For a discussion on how to define additional players, see @xref{Simple
306 Players}.
307
308 Much of the behaviour of Emms can be changed by setting
309 variables. For example:
310
311 @lisp
312 (setq emms-info-asynchronously nil)
313 (setq emms-playlist-buffer-name "*Music*")
314 @end lisp
315
316 The first @code{setq} turns off the asynchronous updating of info tags. The
317 second sets the default name of the Emms playlist buffer.
318
319 Another way to change Emms variables is to use the M-x
320 @command{customize} mechanism provided by Emacs.
321
322 @menu
323 * Finding files and speed:: Finding files quickly or portably.
324 @end menu
325
326 @node Finding files and speed
327 @section Finding files and speed
328
329 @cindex files
330 @cindex speed
331
332 Emms needs to traverse directories in order to find playable
333 media. The default method Emms uses to achive this is
334 @code{emms-source-file-directory-tree-internal} as defined in
335 @file{emms-source-file.el}. The above method is written portably and
336 will always work, but might be too slow if we want to load several
337 hundred tracks (or more).
338
339 @file{emms-source-file.el} defines another method for finding files,
340 @code{emms-source-file-directory-tree-find} which uses
341 GNU/find. @code{emms-source-file-directory-tree-find} is usually an
342 order of magnitude faster, but of course will not work if you do not
343 have GNU/find installed.
344
345 The method Emms will use is defined in the customisable variable
346 @var{emms-source-file-directory-tree-function}.
347
348 @node Quickstart Guide
349 @chapter Quickstart Guide
350
351 This chapter demonstrates how to setup EMMS so that you can start
352 listening to your music without having to read all of the documentation
353 first.
354
355 The first thing you have to do is telling Emacs where the sources of
356 EMMS are located. Let's say you have them in @file{~/elisp/emms/}. So
357 add this line to your @file{.emacs}.
358
359 @lisp
360 (add-to-list 'load-path "~/elisp/emms/lisp/")
361 @end lisp
362
363 Further informations about installing EMMS can be found in the
364 installation chapter, @xref{Installation}.
365
366 Let's say you want to enable all features which are considered stable by
367 the EMMS developers. To achieve this you invoke the @code{emms-all}
368 setup function by adding the following three lines to your @file{.emacs}.
369
370 @lisp
371 (require 'emms-setup)
372 (emms-all)
373 (emms-default-players)
374 @end lisp
375
376 The function @code{emms-default-players} in the last line sets up the
377 list of default players. The list contains lightweight specialized
378 players like ogg123 or mpg321 and we-play-everything-players like
379 mplayer or xine. To be sure that emms can play all your music you should
380 check that the needed players are installed.
381
382 Further informations about the several setup scripts can be found in the
383 simple setup chapter, @xref{Simple Setup}.
384
385 Of course EMMS tries to display the tags of the music files you listen
386 to. For this to work you have to make sure that the appropriate programs
387 are installed. For mp3 files you need `mp3info', and for ogg files you
388 need `ogginfo'.
389
390 The last thing to do is to tell EMMS the root directory of our music
391 collection. Let's say all your music is in @file{~/Music} or in
392 subdirectories thereof.
393
394 @lisp
395 (setq emms-source-file-default-directory "~/Music/")
396 @end lisp
397
398 OK, now we've set up EMMS. Reload your @file{.emacs} or restart Emacs to
399 let the changes have an effect.
400
401 Now we will add all our music to a playlist by invoking @kbd{M-x
402 emms-add-directory-tree RET ~/Music/ RET}. We do this because then EMMS
403 will read the tags of all your music files and cache them. This is
404 required for the browser, @xref{The Browser}.
405
406 To switch to the playlist buffer, invoke @kbd{M-x emms-playlist-mode-go}
407 or simply @kbd{M-x emms}. You can see that most tracks are displayed
408 with their file name, but track by track the filename gets replaced with
409 the artist and track name of the file's tag.
410
411 Hit @kbd{RET} on a track to start playback.
412
413 Now you can start exploring EMMS. It's probably best to begin with the
414 basic commands (@pxref{Basic Commands}), the interactive playlists
415 (@pxref{Interactive Playlists}), and the browser (@pxref{The Browser}).
416
417 @node Getting Help
418 @chapter Getting Help
419
420 @cindex mailing list
421 @cindex website
422
423 If you have a bug to report, need help, or wish to suggest a feature,
424 please feel free to use the Emms mailing list. The address of the list
425 is emms-help@@gnu.org. To subscribe to it, visit
426 @url{http://lists.gnu.org/mailman/listinfo/emms-help}.
427
428 If you are familiar with the Gmane service, there is a Gmane newsgroup
429 which mirrors this mailing address at gmane.emacs.emms.user.
430
431 Emms also has a website at @url{http://www.gnu.org/software/emms/}.
432
433 @node Formats and Freedom
434 @chapter Formats and Freedom
435
436 @cindex freedom
437 @cindex format
438
439 Emms is free software, but some of the file formats it can play carry
440 restrictions, they are proprietary file formats. Proprietary software
441 companies are pushing out audio and video formats which restrict when,
442 where and how you can play them, and restrict developers from writing
443 free software which interacts with them.
444
445 Restrictive file formats put the corporate bottom-line before the
446 public interest.
447
448 Fortunately there are alternatives like Ogg. Ogg is a professional
449 grade multimedia format. Ogg Vorbis is the compressed audio format
450 (like MP3), and Ogg Theora is the video format. For more information,
451 go to @url{http://www.xiph.org/}.
452
453 If you want to transcode audio into a lossless format, you can try
454 FLAC (Free Lossless Audio Codec). FLAC stands out as the fastest and
455 most widely supported lossless audio codec, and the only one that at
456 once is non-proprietary, is unencumbered by patents and has the source
457 code for a reference implementation freely available. For more
458 information about FLAC, go to @url{http://flac.sourceforge.net/}.
459
460 @node Basic Commands
461 @chapter Basic Commands
462
463 @cindex basic commands
464 @cindex commands, basic
465
466 Before you can use the interface commands, you need a playlist to
467 start with. The following commands allow you to add to the current
468 playlist from different sources:
469
470 Note that the commands with the ``emms-add-'' prefix add the source to
471 the playlist but do not start playing it immediately. Conversely, the
472 commands with the ``emms-play-'' prefix begin playing the track
473 immediately.
474
475 @defun emms-play-file file
476 A source for a single file - either @var{file}, or queried from the
477 user. If called with a prefix the file will be added like
478 @command{emms-add-file}.
479 @end defun
480 @defun emms-add-file file
481 A source for a single file - either @var{file}, or queried from
482 the user. If called with a prefix the file will be played like
483 @command{emms-play-file}.
484 @end defun
485 @defun emms-play-directory dir
486 A source for a whole directory tree - either @var{dir}, or queried
487 from the user.
488 @end defun
489 @defun emms-add-directory dir
490 A source for a whole directory tree - either @var{dir}, or queried
491 from the user.
492 @end defun
493 @defun emms-play-directory-tree dir
494 A source for multiple directory trees - either @var{dir}, or the
495 value of @var{emms-source-file-default-directory}.
496 @end defun
497 @defun emms-add-directory-tree dir
498 A source for multiple directory trees - either @var{dir}, or the
499 value of @var{emms-source-file-default-directory}.
500 @end defun
501 @defun emms-play-url url
502 A source for an @var{url} - for example, for streaming.
503 @end defun
504 @defun emms-add-url url
505 A source for an @var{url} - for example, for streaming.
506 @end defun
507 @defun emms-play-playlist playlist
508 A source for the M3u or PLS playlist format from the file @var{playlist}.
509 @end defun
510 @defun emms-add-playlist playlist
511 A source for the M3u or PLS playlist format from the file @var{playlist}.
512 @end defun
513 @defun emms-play-find dir regexp
514 A source that will find files in @var{dir} or
515 @var{emms-source-file-default-directory} which match @var{regexp}.
516 @end defun
517 @defun emms-add-find dir regexp
518 A source that will find files in @var{dir} or
519 @var{emms-source-file-default-directory} which match @var{regexp}.
520 @end defun
521
522 The basic functionality of Emms is just to play music without being
523 noticed. It provides a few commands to skip the current track and
524 such, but other than that it doesn't show up. Emms provides the
525 following basic user commands (which you might want to bind to
526 keystrokes):
527
528 @defun emms-start
529 Start playing the current playlist
530 @end defun
531 @defun emms-stop
532 Stop playing
533 @end defun
534 @defun emms-next
535 Start playing the next track in the playlist
536 @end defun
537 @defun emms-previous
538 Start playing previous track in the playlist
539 @end defun
540 @defun emms-shuffle
541 Shuffle the current playlist. This uses
542 @var{emms-playlist-shuffle-function}.
543 @end defun
544 @defun emms-sort
545 Sort the current playlist. This uses
546 @var{emms-playlist-sort-function}.
547 @end defun
548 @defun emms-show &optional insertp
549 Describe the current Emms track in the minibuffer. If @var{insertp} is
550 non-nil, insert the description into the current buffer instead. This
551 function uses @var{emms-show-format} to format the current track.
552 @end defun
553
554 @node The Core File
555 @chapter The Core File
556
557 @cindex core file
558 @cindex heart of Emms
559 @cindex primitive functions
560
561 The core file @file{emms.el} provides the all basic functions for
562 playing music, generating playlists and defining players.
563
564 @menu
565 * User Variables:: Variables for the user to tweak.
566 * Hooks:: Hooks for important Emms functions.
567 * Core Functions:: Providing the basic functionality of Emms.
568 @end menu
569
570 @node User Variables
571 @section User Variables
572
573 @cindex user variables
574 @cindex options
575
576 The core file defines a number of user variables.
577
578 @defopt emms-player-list
579 A list of players Emms can use. You need to set this in order to use
580 Emms to play media.
581 @end defopt
582 @defopt emms-show-format
583 The format to use for @command{emms-show}. Any "%s" is replaced by
584 what @var{emms-track-description-function} returns for the currently
585 playing track.
586 @end defopt
587 @defopt emms-repeat-playlist
588 Non-nil if the Emms playlist should automatically repeat the playlist.
589 If nil, playback will stop when the last track finishes playing.
590 @end defopt
591 @defopt emms-track-description-function
592 Function for describing an Emms track in a user-friendly way.
593 @end defopt
594 @defopt emms-sort-lessp-function
595 A function that compares two tracks, and returns non-nil if the first
596 track should be sorted before the second (see also @code{sort}).
597 @end defopt
598
599 @node Hooks
600 @section Hooks
601
602 @cindex hooks
603 @cindex adding functionality
604
605 The core file provides hook variables for the basic functionality of
606 Emms.
607
608 @defopt emms-player-started-hook
609 A hook run when an Emms player started playing.
610 @end defopt
611 @defopt emms-player-stopped-hook
612 A hook run when an Emms player stopped playing. See also
613 @var{emms-player-finished-hook}.
614 @end defopt
615 @defopt emms-playlist-source-inserted-hook
616 Hook run when a source got inserted into the playlist. The buffer is
617 narrowed to the new tracks.
618 @end defopt
619 @defopt emms-playlist-selection-changed-hook
620 Hook run after another track is selected in the Emms playlist.
621 @end defopt
622 @defopt emms-playlist-cleared-hook
623 Hook run after the current Emms playlist is cleared. This happens both
624 when the playlist is cleared and when a new buffer is created for it.
625 @end defopt
626 @defopt emms-player-finished-hook
627 Hook run when an Emms player finishes playing a track. Please pay
628 attention to the differences between @var{emms-player-finished-hook}
629 and @var{emms-player-stopped-hook}. The former is called only when the
630 player is stopped interactively; the latter, only when the player
631 actually finishes playing a track.
632 @end defopt
633 @defopt emms-player-paused-hook
634 Hook run when a player is paused or resumed. Use
635 @var{emms-player-paused-p} to find the current state.
636 @end defopt
637
638 @node Core Functions
639 @section Core Functions
640
641 @cindex core functions
642 @cindex basic functions
643
644 The core file also defines all the functions important to the basic
645 use of Emms.
646
647 There are functions which deal with movement in the playlist.
648
649 @defun emms-next-noerror
650 Start playing the next track in the Emms playlist. Unlike
651 @code{emms-next}, this function doesn't signal an error when called at
652 the end of the playlist. This function should only be called when no
653 player is playing. This is a good function to put in
654 @code{emms-player-finished-hook}.
655 @end defun
656 @defun emms-playlist-next
657 Move to the previous track in the current buffer.
658 @end defun
659 @defun emms-playlist-previous
660 Move to the previous track in the current buffer.
661 @end defun
662 @defun emms-random
663 Jump to a random track.
664 @end defun
665 @defun emms-toggle-repeat-playlist
666 Toggle whether emms repeats the playlist after it is done. See
667 @var{emms-repeat-playlist}.
668 @end defun
669 @defun emms-toggle-repeat-track
670 Toggle whether emms repeats the current track. See
671 @var{emms-repeat-track}.
672 @end defun
673 @defun emms-toggle-random-playlist
674 Toggle whether emms plays the tracks randomly or sequentially. See
675 @var{emms-random-playlist}.
676
677 Some functions deal with the getting and setting track information.
678
679 @defun emms-track type name
680 Create a track with type @var{type} and name @var{name}.
681 @end defun
682 @defun emms-track-type track
683 Return the type of @var{track}.
684 @end defun
685 @defun emms-track-name track
686 Return the name of @var{track}.
687 @end defun
688 @defun emms-track-get name track &optional inexistent
689 Return the value of @var{name} for @var{track}. If there is no value,
690 return @var{default} (or nil, if not given).
691 @end defun
692 @defun emms-track-set track name value
693 Set the value of @var{name} for @var{track} to @var{value}.
694 @end defun
695 @defun emms-track-description track
696 Return a description of @var{track}. This function uses
697 @var{emms-track-description-function}.
698 @end defun
699 @defun emms-player-for track
700 Return an Emms player capable of playing @var{track}. This will be the
701 first player whose PLAYABLEP function returns non-nil, or nil if no
702 such player exists.
703 @end defun
704 @defun emms-playlist-current-selected-track
705 Return the currently selected track in the current playlist.
706 @end defun
707
708 There are also functions which deal with the playing itself.
709
710 @defun emms-player-start track
711 Start playing @var{track}.
712 @end defun
713 @defun emms-player-stop
714 Stop the currently playing player.
715 @end defun
716 @defun emms-player-stopped
717 Declare that the current Emms player is finished.
718 This should only be done by the current player itself.
719 @end defun
720 @defun emms-seek seconds
721 Seek the current player @var{seconds} seconds. This can be a floating
722 point number for sub-second fractions. It can also be negative to
723 seek backwards.
724 @end defun
725 @defun emms-seek-forward
726 Seek ten seconds forward.
727 @end defun
728 @defun emms-seek-backward
729 Seek ten seconds backward.
730 @end defun
731
732 For more basic commands defined in the core file see @xref{Basic
733 Commands}.
734
735 @node Sources
736 @chapter Sources
737
738 @cindex Sources
739
740 Sources allow Emms to add and play tracks. Emms comes with a number of
741 sources of its own. Sources are designed so that creating new ones
742 will be easy.
743
744 For examples of Emms sources for files and directories see
745 @file{emms-source-file.el}.
746
747 @defopt emms-source-file-default-directory
748 The default directory to look for media files.
749 @end defopt
750 @defun emms-play-find
751 Play all files in @var{emms-source-file-default-directory} that match
752 a specific regular expression.
753 @end defun
754 @defun emms-source-file &optional file
755 An Emms source for a single file - either @var{file}, or queried from the
756 user.
757 @end defun
758 @defun emms-source-files files
759 An Emms source for a list of @var{files}.
760 @end defun
761 @defun emms-source-directory &optional dir
762 An Emms source for a whole directory tree - either @var{dir}, or queried
763 from the user
764 @end defun
765 @defun emms-source-directory-tree & optional dir
766 An Emms source for multiple directory trees - either @var{dir}, or the
767 value of @var{emms-source-file-default-directory}.
768 @end defun
769 @defun emms-source-playlist file
770 An EMMS source for playlists. See @var{emms-source-playlist-formats}
771 for a list of supported formats.
772 @end defun
773 @defun emms-source-playlist-native file
774 An EMMS source for a native EMMS playlist file.
775 @end defun
776 @defun emms-source-playlist-m3u file
777 An EMMS source for an m3u playlist file.
778 @end defun
779 @defun emms-source-playlist-pls file
780 An EMMS source for a pls playlist file.
781 @end defun
782 @defun emms-source-find &optional dir regex
783 An Emms source that will find files in @var{dir} or
784 @var{emms-source-file-default-directory} that match @var{regexp}.
785 @end defun
786 @defun emms-source-file-directory-tree &optional dir
787 Return a list of all files under @var{dir} which match @var{regex}.
788 @end defun
789 @defun emms-source-dired
790 Play all marked files of a dired buffer
791 @end defun
792 @defun emms-source-file-regex
793 Return a regexp that matches everything any player (that supports
794 files) can play.
795 @end defun
796 @defun emms-locate regexp
797 Search for @var{regexp} and display the results in a locate buffer
798 @end defun
799
800 @node Simple Players
801 @chapter Simple Players
802
803 @cindex players, simple
804
805 @defmac define-emms-simple-player name types regex command &rest args
806 Define a simple player with the use of `emms-define-player'.
807 @var{name} is used to construct the name of the function like
808 emms-player-@var{name}. @var{types} is a list of track types
809 understood by this player. @var{regex} must be a regexp that matches
810 the filenames the player can play. @var{command} specifies the command
811 line argument to call the player and @var{args} are the command line
812 arguments.
813 @end defmac
814
815 For a discussion on how to define new players see @xref{New Player}.
816
817 @defun emms-player-simple-stop
818 Stop the currently playing process, if indeed there is one.
819 @end defun
820 @defun emms-player-simple-start filename cmdname params
821 Starts a process playing @var{filename} using the specified @var{cmdname} with
822 the specified @var{params}.
823 @end defun
824 @defun emms-player-simple-sentinel proc str
825 Sentinel for determining the end of process for the process @var{proc}
826 and the sentinel string @var{str}.
827 @end defun
828
829 @node Playlists
830 @chapter Playlists
831
832 @cindex organizing tracks and media
833
834 Emms uses Emacs buffers to store the media tracks for playing. We call
835 one such buffer a ``playlist buffer'' or an ``Emms playlist
836 buffer''. Emms then proceeds to play the media tracks in the buffer
837 from top to bottom until the end of the playlist.
838
839 The name of the playlist buffer is defined in the variable
840 @var{emms-playlist-buffer-name} and is set to be an invisible Emacs
841 buffer by default. You can change to any name you want. For an example
842 configuration see @xref{Configuration}.
843
844 You can create any number of playlist buffers you wish. At any time
845 Emms has a single ``current'' buffer through which it proceeds track
846 by track.
847
848 @defun emms-playlist-new &optional name
849 Create a new playlist buffer.
850 The buffer is named @var{name}, but made unique. @var{name} defaults
851 to `emms-playlist-buffer-name'. If called interactively, the new
852 buffer is also selected.
853 @end defun
854
855 @defun emms-playlist-save &optional format file
856 Store the current playlist to FILE as the type FORMAT. The default
857 format is specified by @var{emms-source-playlist-default-format}.
858 @end defun
859
860 The current Emms playlist buffer is stored in the variable
861 @var{emms-playlist-buffer}.
862
863 @node Track Information
864 @chapter Track Information
865
866 @cindex track information
867 @cindex info tags
868
869 Emms is distributed with three predefined methods for retrieving info,
870 provided by @file{emms-info-mp3info.el}, @file{emms-info-ogginfo.el} and
871 @file{emms-cue.el}. The first two packages are front-ends for
872 command-line tools. Ogg track information is retrieved using the
873 @uref{http://directory.fsf.org/audio/ogg/vorbistools.html, ogginfo}
874 software. Likewise, mp3 track information is available using
875 @uref{http://www.ibiblio.org/mp3info/, mp3info}. While,
876 @file{emms-cue.el} retrieves tracks information for ape/flac files by
877 parsing a cue sheet file, which is plain text.
878
879 Automatic track information retrieval is enabled by default in the
880 `emms-standard', `emms-all' and `emms-devel' setup levels provided by
881 @file{emms-setup.el}. For more information about @file{emms-setup.el}
882 see @xref{Simple Setup}.
883
884 If you would like to know how Emms track retreival works and how we
885 can define new methods for track retrieval see @xref{Defining Info
886 Methods}.
887
888 There are a number of user variables which control the behaviour of
889 `emms-info'.
890
891 @defopt emms-info-auto-update
892 Non-nil when Emms should update track information if the file changes.
893 This will cause hard drive activity on track loading. If this is too
894 annoying for you, set this variable to nil.
895 @end defopt
896 @defopt emms-info-asynchronously
897 Non-nil when track information should be loaded asynchronously. This
898 requires the feature `later-do' which is provided by the file
899 @file{later-do.el}, which should come with Emms.
900 @end defopt
901 @defopt emms-info-functions
902 Functions which add information to tracks. Each is called with a
903 track as argument.
904 @end defopt
905
906 @menu
907 * Defining Info Methods:: Defining new info methods.
908 @end menu
909
910 @node Defining Info Methods
911 @section Defining Info Methods
912
913 @cindex defining info methods
914
915 An info method essentially consists of a function which given an Emms
916 track returns the appropriate info for that track.
917
918 We can for example look at the predefined method for retrieving
919 information about audio tracks in the Ogg format.
920
921 The function @command{emms-info-ogginfo} provided by
922 @file{emms-info-ogginfo.el} accepts an Emms track as a single
923 argument and returns the appropriate information string.
924
925 We then register our info function with Emms by adding it to the
926 @var{emms-info-functions} list. The function will then be called at
927 the right time to provide track info.
928
929 @lisp
930 (add-to-list 'emms-info-functions 'emms-info-ogginfo)
931 @end lisp
932
933 @node Interactive Playlists
934 @chapter Interactive Playlists
935
936 @cindex Interactive Playlists
937
938 Emms provides a visual, interactive playlist mode as well as the
939 ability to use playlists without ever looking at then. This visual,
940 interactive mode is called the `emms-playlist-mode' and is defined in
941 @file{emms-playlist-mode.el}.
942
943 The interactive playlist mode is enabled by default in the
944 `emms-standard', `emms-all' and `emms-devel' setup levels. For more
945 information about Emms setup levels see @xref{Simple Setup}.
946
947 @defun emms-playlist-mode-go
948 Switch to the current emms-playlist buffer and use emms-playlist-mode.
949 @end defun
950
951 If you wish to make this the default EMMS playlist mode, add the
952 following to your @file{.emacs}.
953
954 @lisp
955 (setq emms-playlist-default-major-mode 'emms-playlist-mode)
956 @end lisp
957
958 The interactive playlist buffer shows the tracks in the current Emms
959 playlist in the order in which they will be played. The current track
960 will be highlighted.
961
962 When in the interactive playlist mode we can perform different actions
963 on the current playlist.
964
965 @table @kbd
966 @item a
967 @findex emms-playlist-mode-add-contents
968 Add files in the playlist at point to the current playlist buffer.
969 If we are in the current playlist, make a new playlist buffer and
970 set it as current.
971 @item b
972 @findex emms-playlist-set-playlist-buffer
973 Set the current playlist buffer.
974 @item n
975 @findex emms-next
976 Start playing the next track in the playlist.
977 @item p
978 @findex emms-next
979 Start playing the previous track in the playlist.
980 @item s
981 @findex emms-stop
982 Stop playing.
983 @item P
984 @findex emms-pause
985 Pause.
986 @item >
987 @findex emms-seek-forward
988 Seek ten seconds forward.
989 @item <
990 @findex emms-seek-backward
991 Seek ten seconds backward.
992 @item f
993 @findex emms-show
994 Describe the currently playing track in the minibuffer.
995 @item c
996 @findex emms-playlist-mode-center-current
997 Display the current track in the center of the screen.
998 @item RET
999 @findex emms-playlist-mode-play-current-track
1000 Start playing the track under point. Note that this is also available
1001 with @kbd{<mouse-2>}.
1002 @item SPC
1003 @findex scroll-up
1004 Scroll up a near full page.
1005 @item M-<
1006 @findex emms-playlist-mode-first
1007 Go to the first track in the playlist.
1008 @item M->
1009 @findex emms-playlist-mode-last
1010 Go to the last track in the playlist.
1011 @item r
1012 @findex emms-random
1013 Go to a randomly selected track in the playlist.
1014 @item q
1015 @findex bury-buffer
1016 Put the interactive playlist buffer at the end of the list of all
1017 buffers.
1018 @item C-x C-s
1019 @findex emms-playlist-save
1020 Save the current playlist buffer to a file. By default, Emms will ask
1021 you for confirmation before overwriting an existing playlist. You can
1022 silently overwrite existing playlist by setting
1023 @var{emms-source-playlist-ask-before-overwrite} to nil.
1024 @item ?
1025 @findex describe-mode
1026 Describe the mode.
1027 @end table
1028
1029 We can also edit the playlist using familiar GNU/Emacs commands:
1030
1031 @table @kbd
1032 @item C-k
1033 @findex emms-playlist-mode-kill-track
1034 Remove the track under point from the playlist buffer. Also available
1035 using the @kbd{d} key.
1036 @item C-y
1037 @findex emms-playlist-mode-yank
1038 See the command @command{yank}
1039 @item C-w
1040 @findex emms-playlist-mode-kill
1041 See the command @command{kill-region}
1042 @item M-y
1043 @findex emms-playlist-mode-yank-pop
1044 See the command @command{yank-pop}.
1045 @item C-j
1046 @findex emms-playlist-mode-insert-newline
1047 Insert a newline at point.
1048 @end table
1049
1050 We can use the regular GNU/Emacs killing and yanking commands to move
1051 and copy tracks in between playlist buffers. We can use the same
1052 commands to insert arbitrary text into the playlist buffers together
1053 with the playlist tracks. Text which is not a track is ignored by the
1054 program and can therefore be used to include titles and annotations
1055 within the playlist.
1056
1057 @node Markable Playlists
1058 @chapter Markable Playlists
1059
1060 @cindex Markable Playlists
1061
1062 The Markable Playlists provided by the file @file{emms-mark.el} are an
1063 alternative to the default interactive playlists, @xref{Interactive
1064 Playlists}. They allow marking tracks with keybindings familiar to users
1065 of dired.
1066
1067 To enable the Markable Playlists you have to add
1068
1069 @lisp
1070 (require 'emms-mark)
1071 @end lisp
1072
1073 to your @file{.emacs}. Then you can activate @command{emms-mark-mode} by
1074 executing @command{M-x emms-mark-mode} in a playlist buffer. You can
1075 return to the default interactive playlist mode with @command{M-x
1076 emms-mark-mode-disable}.
1077
1078 If you wish to make this the default EMMS playlist mode, add the
1079 following to your @file{.emacs}.
1080
1081 @lisp
1082 (setq emms-playlist-default-major-mode 'emms-mark-mode)
1083 @end lisp
1084
1085 @table @kbd
1086 @item m
1087 @findex emms-mark-forward
1088 Marks the current track and sets point one line forward. If a prefix
1089 argument ARG is given, it will mark the next ARG tracks and set point
1090 accordingly. A negative argument marks backward.
1091 @item U
1092 @findex emms-mark-unmark-all
1093 Unmarks all tracks in the playlist.
1094 @item t
1095 @findex emms-mark-toggle
1096 Toggles mark on the current track.
1097 @item u
1098 @findex emms-mark-unmark-forward
1099 Unmarks same way as @command{emms-mark-forward} marks.
1100 @item % m
1101 @findex emms-mark-regexp
1102 Marks all tracks in the playlist matching the given regular
1103 expression. A prefix argument means to unmark them instead.
1104 @end table
1105
1106 When tracks are marked you can operate on them:
1107
1108 @table @kbd
1109 @item D
1110 @findex emms-mark-delete-marked-tracks
1111 Deletes the marked tracks from the playlist.
1112 @item K
1113 @findex emms-mark-kill-marked-tracks
1114 Deletes the marked tracks from the playlist and places them in the
1115 kill-ring, so that you can @command{yank} in into another playlist.
1116 @item W
1117 @findex emms-mark-copy-marked-tracks
1118 Adds the marked tracks to the kill-ring, so that you can @command{yank}
1119 them into another playlist.
1120 @end table
1121
1122 emms-mark is also intent to provide a way for user to select tracks
1123 for other command to operate on them. Currently,
1124 @file{emms-tag-editor.el} used the emms-mark to edit tags of selected
1125 tracks. Two function is useful for elisp programer to handle marked
1126 tracks.
1127
1128 @defun emms-mark-do-with-marked-track
1129 This function take a function to perform on all marked tracks. A
1130 optional argument `move-flag' to tell the function to move forward
1131 line after calling given function. If the given function didn't change
1132 position, the second argument should set to non-nil.
1133 @end defun
1134
1135 @defun emms-mark-mapcar-marked-track
1136 This function is very similar to `emms-mark-do-with-marked-track'
1137 except it collects result of given function (that's why named with
1138 `mapcar').
1139 @end defun
1140
1141 @node APE / FLAC Commands
1142 @chapter APE / FLAC Commands
1143
1144 Often, a single APE or FLAC file contains a complete ablum. We can still
1145 play next or previous track in the ablum with the help of
1146 @file{emms-cue.el} package, provided there is a corresponding cue sheet
1147 file. This package also defines @code{emms-info-cueinfo} for retreiving
1148 the track information for APE / FLAC itself.
1149
1150 To load @file{emms-cue.el}:
1151
1152 @lisp
1153 (require 'emms-cue)
1154 (add-to-list 'emms-info-functions 'emms-info-cueinfo)
1155 @end lisp
1156
1157 @defun emms-cue-next
1158 Play next track from .cue file
1159 @end defun
1160 @defun emms-cue-previous
1161 Play previous track from .cue file
1162 @end defun
1163
1164 @node Bookmarks
1165 @chapter Bookmarks
1166
1167 Emms can save a ``temporal bookmark'' in a media file via
1168 emms-bookmarks. The file @file{emms-bookmarks.el} provides the package
1169 emms-bookmarks.
1170
1171 While some media is playing, invoking @kbd{M-x emms-bookmarks-add}
1172 will first pause the playback and then prompt for a name describing
1173 the bookmark. Tracks can have multiple bookmarks associated with them.
1174
1175 To jump to the next and previous bookmarks in the current track invoke
1176 @kbd{M-x emms-bookmarks-next} and @kbd{M-x emms-bookmarks-prev}
1177 respectively.
1178
1179 To clear all of the bookmarks for the current track invoke @kbd{M-x
1180 emms-bookmarks-clear}.
1181
1182 @node Extending Emms
1183 @chapter Extending Emms
1184
1185 @cindex new players
1186 @cindex defining players
1187 @cindex new players, defining
1188
1189 Emms introduces a high abstraction layer for playing music so you can
1190 customise it to your needs.
1191
1192 @menu
1193 * New Player:: How to define a new player.
1194 * Simple Player for `play':: An example player using @command{play}.
1195 * More Complex Player:: Example of a complex player using @command{mpg321}.
1196 @end menu
1197
1198 @node New Player
1199 @section New Player
1200
1201 @cindex new player
1202 @cindex defining new players
1203
1204 The file @file{emms-player-simple.el} defines some easy players to
1205 start with, but it shouldn't be hard to provide a function for your
1206 favourite player. We will start with an easy example that shows how
1207 we can use the @command{play} command under Unix to play our WAV files.
1208
1209 @node Simple Player for `play'
1210 @section Simple Player for `play'
1211
1212 @cindex simple player
1213 @cindex primitive player
1214 @cindex basic player
1215
1216 Play is a very easy command line player for various format. If you
1217 want your emms to play WAV files just put the following lines in you
1218 @file{.emacs}:
1219
1220 @lisp
1221 (require 'emms-player-simple)
1222 (define-emms-simple-player play '(file) "\\.wav$" "play")
1223 @end lisp
1224 @noindent
1225
1226 Huh! Wasn't that easy?
1227
1228 The macro function @command{define-emms-simple-player} takes a minimum
1229 of three arguments. The first argument (@emph{play} in our example)
1230 defines the name of the player. It's used to name the player
1231 functions. The second is a regexp, that defines which files to play
1232 with our player. @emph{\\.wav$} matches any filename ending with a dot
1233 and the string wav. The last argument is the actual command line
1234 command we use to play our files. You can also add the path but we
1235 just assume that the command is in your path. All arguments you add to
1236 these three are optional. They define the command line arguments you
1237 want to add to your argument. If you want to hear the wav file of your
1238 favourite artist in the most possible volume use the following line:
1239
1240 @lisp
1241 (require 'emms-player-simple)
1242
1243 (define-emms-simple-player play
1244 '(file)
1245 "\\artist-*.wav$"
1246 "play"
1247 "--volume=100")
1248 @end lisp
1249 @noindent
1250
1251 Please notice that you have to add the arguments as strings!
1252
1253 The command line tool you use for @command{define-emms-simple-player}
1254 has to take one song as argument and stop after playing that
1255 particular song. For any other concept you will need to customise
1256 emms a bit more...
1257
1258 @node More Complex Player
1259 @section More Complex Player
1260
1261 @cindex complex player
1262 @cindex advanced player
1263
1264 The most players you use will be simple players so you don't need to
1265 read this chapter. But if you are curious how you can use (almost) every
1266 player in emms read further...
1267
1268 In this chapter we will use mpg321 to construct a player that
1269 actually can pause a track, restart it and show rest time. We won't
1270 implement all of that, but after that chapter you will know how to
1271 define it.
1272
1273 The command @command{define-emms-simple-player} is just a abstraction
1274 layer for @command{define-emms-player}, which is a little bit more
1275 complicated but much more powerful!
1276
1277 @lisp
1278 (define-emms-player "emms-mpg321-remote"
1279 :start 'emms-mpg321-remote-start
1280 :stop 'emms-mpg321-remote-stop
1281 :playablep 'emms-mpg321-remote-playable-p)
1282 @end lisp
1283 @noindent
1284
1285 So, that is almost all! @command{define-emms-player} takes a minimum
1286 of three arguments. The first is the name of the player. The rest are
1287 methods with functions to call. Three methods are required: start,
1288 stop and playable. Start says Emms how to start a track (sic!), stop
1289 how to stop a player and playablep should return non-nil if the player
1290 can play the track.
1291
1292 So we just need these three functions to get our mpg321-remote:
1293
1294 First we code the start function. We will check if there's a open
1295 process and start one otherwise. Then we send a string to the process
1296 with the filename and set a filter.
1297
1298 @lisp
1299 (defun emms-mpg321-remote-start ()
1300 (unless (get-process ``mpg321-remote'')
1301 (setq emms-mpg321-remote-process
1302 (start-process "mpg321-remote-process"
1303 "*mpg321*" "mpg321" "-R" "abc"))
1304 (process-send-string "mpg321-remote-process"
1305 (concat "l " (emms-track-name track)))
1306 (set-process-filter emms-mpg321-remote-process 'emms-mpg321-remote-filter)))
1307 @end lisp
1308 @noindent
1309
1310 We need the filter, as mpg321-remote won't quit after playing the
1311 track as the simple player do. We wait until the process sends the
1312 output ``(at-sign)P 0'' (the signal of mpg321 that the song ended) to the
1313 filter and call emms-mpg321-remote-stop.
1314
1315 @lisp
1316 (defun emms-mpg321-remote-filter (process output)
1317 (when (string-match "(at-sign)P 0" output)
1318 (emms-mpg321-remote-stop)))
1319 @end lisp
1320 @noindent
1321
1322 @command{emms-mpg321-remote-stop} won't do anything interesting. It
1323 just test if there are other files to play and close the process otherwise.
1324
1325 @lisp
1326 (defun emms-mpg321-remote-stop ()
1327 (unless emms-playlist
1328 (process-send-string "mpg321-remote-process" "Q\n"))
1329 @end lisp
1330 @noindent
1331
1332 And to make that a playable example I also added
1333 @command{emms-mpg321-remote-playablep}, which I really just steal
1334 from @file{emms-player-simple.el}
1335
1336 @lisp
1337 (defun emms-mpg321-remote-playablep (track)
1338 "Return non-nil when we can play this track."
1339 (and (eq 'file (emms-track-type track))
1340 @end lisp
1341 @noindent
1342
1343 Now we have a ready player and we could add commands like
1344 @command{emms-mpg321-remote-pause} for example.
1345
1346 @node The Browser
1347 @chapter The Browser
1348
1349 The Browser allows you to browse the metadata cache and add tracks to
1350 your playlist. It includes a powerful interactive mode.
1351
1352 The Browser is defined in @file{emms-browser.el} and is included in
1353 the @command{emms-all} setup level. For more information about Emms
1354 setup levels see @xref{Simple Setup}.
1355
1356 You can also manually add the Browser to your Emms setup by loading it
1357 explicitly with:
1358
1359 @lisp
1360 (require 'emms-browser)
1361 @end lisp
1362
1363 To be properly useful, you should do M-x
1364 @command{emms-add-directory-tree} to all the files you own at least
1365 once so that the cache is fully populated.
1366
1367 @menu
1368 * Browser Interface:: The interactive browser interface.
1369 * Filtering Tracks:: Displaying a subset of the tracks.
1370 * Displaying Covers:: Displaying album covers in the browser interface.
1371 * Changing Looks:: Changing the tree structure, display format and faces.
1372 @end menu
1373
1374 @node Browser Interface
1375 @section Browser Interface
1376
1377 The browser interface allows you to display and interact with your
1378 tracks in many different ways. There are a number of ways to start the
1379 browser.
1380
1381 @defun emms-smart-browse
1382 Display browser and playlist. Toggle between selecting browser,
1383 playlist or hiding both. Tries to behave sanely if the user has
1384 manually changed the window configuration.
1385 @end defun
1386
1387 @defun emms-browse-by-artist
1388 Display the browser and order the tracks by artist.
1389 @end defun
1390
1391 @defun emms-browse-by-album
1392 Display the browser and order the tracks by album.
1393 @end defun
1394
1395 @defun emms-browse-by-genre
1396 Display the browser and order the tracks by genre.
1397 @end defun
1398
1399 @defun emms-browse-by-year
1400 Display the browser and order the tracks by year.
1401 @end defun
1402
1403 Once the Browser is displayed you can use it to managed your track
1404 collection and playlists. The Browser is interactive and has its own
1405 keybindings.
1406
1407 @table @kbd
1408
1409 @item C-j
1410 @kindex C-j (emms-browser)
1411 @findex emms-browser-add-tracks-and-play
1412 Add all tracks at point, and play the first added track.
1413
1414 @item RET
1415 @kindex RET (emms-browser)
1416 @findex emms-browser-add-tracks
1417 Add all tracks at point.
1418
1419 @item SPC
1420 @kindex SPC (emms-browser)
1421 @findex emms-browser-toggle-subitems
1422 Show or hide (kill) subitems under the current line.
1423
1424 @item 1
1425 @kindex 1 (emms-browser)
1426 @findex emms-browser-collapse-all
1427 Collapse everything.
1428
1429 @item 2
1430 @kindex 2 (emms-browser)
1431 @findex emms-browser-expand-to-level-2
1432 Expand all top level items one level.
1433
1434 @item 3
1435 @kindex 3 (emms-browser)
1436 @findex emms-browser-expand-to-level-3
1437 Expand all top level items two levels.
1438
1439 @item 4
1440 @kindex 4 (emms-browser)
1441 @findex emms-browser-expand-to-level-4
1442 Expand all top level items three levels.
1443
1444 @item C
1445 @kindex C (emms-browser)
1446 @findex emms-browser-clear-playlist
1447 Clear the playlist.
1448
1449 @item E
1450 @kindex E (emms-browser)
1451 @findex emms-browser-expand-all
1452 Expand everything.
1453
1454 @item d
1455 @kindex d (emms-browser)
1456 @findex emms-browser-view-in-dired
1457 View the current directory in dired.
1458
1459 @item q
1460 @kindex q (emms-browser)
1461 @findex emms-browser-bury-buffer
1462 Bury the browser buffer.
1463
1464 @item r
1465 @kindex r (emms-browser)
1466 @findex emms-browser-goto-random
1467 Jump to a random track.
1468
1469 @item /
1470 @kindex / (emms-browser)
1471 @findex emms-isearch-buffer
1472 Isearch through the buffer.
1473
1474 @item <
1475 @kindex < (emms-browser)
1476 @findex emms-browser-previous-filter
1477 Redisplay with the previous filter.
1478
1479 @item >
1480 @kindex > (emms-browser)
1481 @findex emms-browser-next-filter
1482 Redisplay with the next filter.
1483
1484 @item ?
1485 @kindex ? (emms-browser)
1486 @findex describe-mode
1487 See the Emacs documentation for the function.
1488
1489 @item C-/
1490 @kindex C-/ (emms-browser)
1491 @findex emms-playlist-mode-undo
1492 Undo the previous playlist action.
1493
1494 @item <C-return>
1495 @kindex <C-return> (emms-browser)
1496 @findex emms-browser-add-tracks-and-play
1497 Add all tracks at point, and play the first added track.
1498
1499 @item <backtab>
1500 @kindex <backtab> (emms-browser)
1501 @findex emms-browser-prev-non-track
1502 Jump to the previous non-track element.
1503
1504 @item <tab>
1505 @kindex <tab> (emms-browser)
1506 @findex emms-browser-next-non-track
1507 Jump to the next non-track element.
1508
1509 @item s A
1510 @kindex s A (emms-browser)
1511 @findex emms-browser-search-by-album
1512 Search the collection by album.
1513
1514 @item s a
1515 @kindex s a (emms-browser)
1516 @findex emms-browser-search-by-artist
1517 Search the collection by artist.
1518
1519 @item s s
1520 @kindex s s (emms-browser)
1521 @findex emms-browser-search-by-names
1522 Search the collection by names.
1523
1524 @item s t
1525 @kindex s t (emms-browser)
1526 @findex emms-browser-search-by-title
1527 Search the collection by title.
1528
1529 @item b 1
1530 @kindex b 1 (emms-browser)
1531 @findex emms-browse-by-artist
1532 Browse the collection by artist.
1533
1534 @item b 2
1535 @kindex b 2 (emms-browser)
1536 @findex emms-browse-by-album
1537 Browse the collection by album.
1538
1539 @item b 3
1540 @kindex b 3 (emms-browser)
1541 @findex emms-browse-by-genre
1542 Browse the collection by genre.
1543
1544 @item b 4
1545 @kindex b 4 (emms-browser)
1546 @findex emms-browse-by-year
1547 Browse the collection by year.
1548
1549 @item W a p
1550 @kindex W a p (emms-browser)
1551 @findex emms-browser-lookup-album-on-pitchfork
1552 Lookup the album using Pitchfork.
1553
1554 @item W a w
1555 @kindex W a w (emms-browser)
1556 @findex emms-browser-lookup-album-on-wikipedia
1557 Lookup the album using Wikipedia.
1558 @end table
1559
1560 @node Filtering Tracks
1561 @section Filtering Tracks
1562
1563 If you want to display a subset of your collection (such as a
1564 directory of 80s music, only avi files, etc.) then you can extend the
1565 Browser by defining ``filters''.
1566
1567 Show everything:
1568
1569 @lisp
1570 (emms-browser-make-filter "all" 'ignore)
1571 @end lisp
1572
1573 Set "all" as the default filter:
1574
1575 @lisp
1576 (emms-browser-set-filter (assoc "all" emms-browser-filters))
1577 @end lisp
1578
1579 Show all files (no streamlists, etc):
1580
1581 @lisp
1582 (emms-browser-make-filter
1583 "all-files" (emms-browser-filter-only-type 'file))
1584 @end lisp
1585
1586 Show only tracks in one folder:
1587
1588 @lisp
1589 (emms-browser-make-filter
1590 "80s" (emms-browser-filter-only-dir "~/Mp3s/80s"))
1591 @end lisp
1592
1593 Show all tracks played in the last month:
1594
1595 @lisp
1596 (emms-browser-make-filter
1597 "last-month" (emms-browser-filter-only-recent 30))
1598 @end lisp
1599
1600 After executing the above commands, you can use M-x
1601 emms-browser-show-all, emms-browser-show-80s, etc to toggle between
1602 different collections. Alternatively you can use '<' and '>' to cycle
1603 through the available filters.
1604
1605 The second argument to make-filter is a function which returns t if a
1606 single track should be filtered. You can write your own filter
1607 functions to check the type of a file, etc.
1608
1609 Show only tracks not played in the last year:
1610
1611 @lisp
1612 (emms-browser-make-filter "not-played"
1613 (lambda (track)
1614 (not (funcall (emms-browser-filter-only-recent 365) track))))
1615 @end lisp
1616
1617 Show all files that are not in the pending directory:
1618
1619 @lisp
1620 (emms-browser-make-filter
1621 "all"
1622 (lambda (track)
1623 (or
1624 (funcall (emms-browser-filter-only-type 'file) track)
1625 (not (funcall
1626 (emms-browser-filter-only-dir "~/Media/pending") track)))))
1627 @end lisp
1628
1629 @node Displaying Covers
1630 @section Displaying Covers
1631
1632 The browser will attempt to display cover images if they're
1633 available. By default it looks for images cover_small.jpg,
1634 cover_med.jpg, etc. Customize @var{emms-browser-covers} to use your
1635 own covers. Note that you'll probably want to resize your existing
1636 covers to particular sizes. Suggested sizes are 100x100 for small, and
1637 200x200 for medium.
1638
1639 Also, Emacs by default will jump around a lot when scrolling a buffer
1640 with images. In order to prevent that, you can set
1641 @var{scroll-up-aggressively} and @var{scroll-down-aggressively} to the
1642 number ``0.0''.
1643
1644 To show a 'no cover' image for albums which don't have a cover, add
1645 the following code to your .emacs:
1646
1647 @lisp
1648 (setq emms-browser-default-covers
1649 (list "/path/to/cover_small.jpg" nil nil)
1650 @end lisp
1651
1652 The medium and large images can be set as well.
1653
1654 You can download an example @uref{http://repose.cx/cover_small.jpg,
1655 `no cover' image}.
1656
1657 @node Changing Looks
1658 @section Changing Looks
1659
1660 The Browser's look can be customised. You can change the way the tree
1661 structure looks, the display format and display faces.
1662
1663 @subheading Changing Tree Structure
1664
1665 You can change the way the tree is displayed by modifying the function
1666 @command{emms-browser-next-mapping-type}.
1667
1668 The following code displays artist->track instead of
1669 artist->album->track when you switch to the 'singles' filter:
1670
1671 @lisp
1672 (defadvice emms-browser-next-mapping-type
1673 (after no-album (current-mapping))
1674 (when (eq ad-return-value 'info-album)
1675 (setq ad-return-value 'info-title)))
1676 @end lisp
1677
1678 @lisp
1679 (defun toggle-album-display ()
1680 (if (string= emms-browser-current-filter-name "singles")
1681 (ad-activate 'emms-browser-next-mapping-type)
1682 (ad-deactivate 'emms-browser-next-mapping-type)))
1683
1684 (add-hook 'emms-browser-filter-changed-hook 'toggle-album-display)
1685 @end lisp
1686
1687 @subheading Changing Display Format
1688
1689 Format strings govern the way items are displayed in the browser and
1690 playlist. You can customize these if you wish.
1691
1692 @var{emms-browser-default-format} controls the format to use when no
1693 other format has been explicitly defined. By default, only track and
1694 albums deviate from the default.
1695
1696 To customise the format of a particular type, find the name of the
1697 field you want to use (eg `info-artist', `info-title', etc), and
1698 insert that into emms-browser-<type>-format or
1699 emms-browser-playlist-<type>-format. For example, if you wanted to
1700 remove track numbers from tracks in both the browser and playlist, you
1701 could do:
1702
1703 @lisp
1704 (defvar emms-browser-info-title-format "%i%n")
1705 (defvar emms-browser-playlist-info-title-format
1706 emms-browser-info-title-format)
1707 @end lisp
1708
1709 The format specifiers available include:
1710
1711 @itemize @w{}
1712 @item
1713 %i indent relative to the current level
1714 @item
1715 %n the value of the item - eg -info-artist might be ``pink floyd''
1716 @item
1717 %y the album year
1718 @item
1719 %A the album name
1720 @item
1721 %a the artist name of the track
1722 @item
1723 %t the title of the track
1724 @item
1725 %T the track number
1726 @item
1727 %cS a small album cover
1728 @item
1729 %cM a medium album cover
1730 @item
1731 %cL a big album cover
1732 @end itemize
1733
1734 Note that if you use track-related items like %t, it will take the
1735 data from the first track.
1736
1737 @subheading Changing Display Faces
1738
1739 The faces used to display the various fields are also customizable.
1740 They are in the format emms-browser-<type>-face, where type is one of
1741 "year/genre", "artist", "album" or "track". Note that faces lack the
1742 initial "info-" part. For example, to change the artist face, type M-x
1743 @command{customize-face} @command{emms-browser-artist-face}.
1744
1745 @node Sorting Playlists
1746 @chapter Sorting Playlists
1747
1748 @cindex sort
1749 @cindex track order
1750
1751 The `emms-playlist-sort' module, defined in the
1752 @file{emms-playlist-sort.el} package provides functions for sorting
1753 Emms playlists. `emms-playlist-sort' can be loaded by invoking:
1754
1755 @lisp
1756 (require 'emms-playlist-sort)
1757 @end lisp
1758
1759 @defun emms-playlist-sort-by-name
1760 Sort playlist by name in ascending order.
1761 @end defun
1762
1763 @defun emms-playlist-sort-by-info-artist
1764 Sort playlist by artist in ascending order.
1765 @end defun
1766
1767 @defun emms-playlist-sort-by-info-title
1768 Sort playlist by title in ascending order.
1769 @end defun
1770
1771 @defun emms-playlist-sort-by-info-album
1772 Sort playlist by album in ascending order.
1773 @end defun
1774
1775 @defun emms-playlist-sort-by-info-year
1776 Sort playlist by year in ascending order.
1777 @end defun
1778
1779 @defun emms-playlist-sort-by-info-note
1780 Sort playlist by notes in ascending order.
1781 @end defun
1782
1783 @node Persistent Playlists
1784 @chapter Persistent Playlists
1785
1786 The Emms module @file{emms-history.el} makes playlists persistent over
1787 emacs sessions. To make use of this feature put this into your
1788 ~/.emacs.
1789
1790 @lisp
1791 (require 'emms-history)
1792 @end lisp
1793
1794 When you kill emacs all playlists will be saved in the file given by the
1795 variable:
1796
1797 @defopt emms-history-file
1798 The file to save playlists in. It defaults to
1799 "~/.emacs.d/emms-history".
1800 @end defopt
1801
1802 After you started up emacs again, you can restore all saved playlists
1803 with this function.
1804
1805 @defun emms-history-load
1806 Restore all playlists in `emms-history-file'.
1807 @end defun
1808
1809 If that should be done automatically on each startup, put these lines
1810 into your ~/.emacs.
1811
1812 @lisp
1813 (require 'emms-history)
1814 (emms-history-load)
1815 @end lisp
1816
1817 Normally @code{emms-history} only restores playlists. If you want it to
1818 start playback afterwards, you can tweak this variable.
1819
1820 @defopt emms-history-start-playing
1821 If non-nil emms starts playing the current track after
1822 `emms-history-load' was invoked. The default value is nil.
1823 @end defopt
1824
1825 @node Editing Tracks
1826 @chapter Editing Tracks
1827
1828 @cindex track editor
1829
1830 Using @file{emms-tag-editor.el}, emms can set tag informations of tracks
1831 and write them back to the file with the help of external programs, such
1832 as `mp3info', `vorbiscomment'.
1833
1834 Use the keybinding @kbd{E} to edit the tags of track under point in the
1835 playlist or all marked tracks (@pxref{Markable Playlists} for how to
1836 mark tracks). The track's tag informations are listed in a special
1837 buffer `*EMMS-TAGS*' in text format. Field names are marked in bold
1838 face and are not editable. Any tag information is placed behind an
1839 equal sign and is changable. A special field `name' is the track's file
1840 name. If any change is made in this field, the track's file will be
1841 renamed to the new name. When you finished editing the tag infos use
1842 @kbd{C-c C-c} (which calls @code{emms-tag-editor-submit-and-exit}) to
1843 submit the changes and close the `*EMMS-TAGS*' buffer.
1844
1845 There are a few commands to perform changes on all tracks.
1846
1847 @defun emms-tag-editor-set-all tag value
1848 Set TAG to VALUE in all tracks.
1849
1850 If transient-mark-mode is turned on, you can apply the command to a
1851 selected region.
1852
1853 If `transient-mark-mode' is on and the mark is active, the changes will
1854 only take effect on the tracks in the region.
1855 @end defun
1856
1857 @defun emms-tag-editor-replace-in-tag tag from to
1858 Query and replace text in selected TAG.
1859
1860 For example, if the info-title tag is selected, then only perform
1861 replacement in title tags.
1862
1863 If `transient-mark-mode' is on and the mark is active, the changes will
1864 only take effect on the tracks in the region.
1865 @end defun
1866
1867 @defun emms-tag-editor-transpose-tag tag1 tag2
1868 Transpose value of TAG1 and TAG2.
1869
1870 If `transient-mark-mode' is on and the mark is active, the changes will
1871 only take effect on the tracks in the region.
1872 @end defun
1873
1874 @defun emms-tag-editor-submit arg
1875 Make modified tags take affect.
1876
1877 With prefix argument, bury the tag edit buffer.
1878 @end defun
1879
1880 If you want to extend the tag editor to work with file formats other
1881 than `mp3' and `ogg', have a look at these variables.
1882
1883 @defvr {Variable} emms-tag-editor-formats
1884 This variable determine how to insert track fields to
1885 `emms-tag-editor-edit-buffer'. Emms tag info editable fields is usually
1886 determined by the extension of track name. The variable
1887 `emms-tag-editor-tags' contains all tags that emms track may have. A
1888 single charactar is assigned to the tag to make the
1889 `emms-tag-editor-formats' easier to generate.
1890 @end defvr
1891
1892 @defvr {Variable} emms-tag-editor-tagfile-functions
1893 To write tags to track file, an extern program should specified in this
1894 variable.
1895
1896 If the external program has an interface like `mp3info', you don't have
1897 to write a function. Take `mp3' and `ogg' as example.
1898 @end defvr
1899
1900 @heading Renaming Files
1901
1902 The tag editor is also capable to rename the file of the track at point
1903 or all files of the marked tracks according to the value this variable.
1904
1905 @defopt emms-tag-editor-rename-format
1906 When `emms-tag-editor-rename' is invoked the track's file will be
1907 renamed according this format specification. The file extension will be
1908 added automatically.
1909
1910 It uses the format specs defined in @code{emms-tag-editor-tags}.
1911
1912 The default value is "%a - %l - %n - %t", so that files are named
1913
1914 <Artist> - <Album> - <Tracknumber> - <Title>.<extension>
1915
1916 after renaming.
1917 @end defopt
1918
1919 To perform the renaming put point on the track you want to rename or
1920 mark some tracks. Then hit @kbd{R} which calls this function:
1921
1922 @defun emms-tag-editor-rename
1923 Rename the file corresponding to track at point or all marked tracks
1924 according to the value of @code{emms-tag-editor-rename-format}.
1925 @end defun
1926
1927 @node Emms Mode Line
1928 @chapter Emms Mode Line
1929
1930 @cindex mode line
1931 @cindex display emms information
1932
1933 We can display information about the currenty playing track on the
1934 Emacs mode line using the package `emms-mode-line' which is provided
1935 by the file @file{emms-mode-line.el}.
1936
1937 To activate this feature invoke:
1938
1939 @lisp
1940 (require 'emms-mode-line)
1941 (emms-mode-line 1)
1942 @end lisp
1943
1944 It is also possible to display the amount of time a track has been
1945 playing. This feature is defined in the `emms-playing-time' package
1946 which is provided by the file @file{emms-playing-time.el}.
1947
1948 To use this feature invoke:
1949
1950 @lisp
1951 (require 'emms-playing-time)
1952 (emms-playing-time 1)
1953 @end lisp
1954
1955 Note: `(emms-playing-time -1)' will disable emms-playing-time module
1956 completely, and is not recommended. (since some other emms modules may
1957 rely on it, such as `emms-lastfm.el')
1958
1959 Instead, to toggle displaying playing time on mode line, one could call
1960 `emms-playing-time-enable-display' and
1961 `emms-playing-time-disable-display'."
1962
1963 @defun emms-playing-time-enable-display
1964 Display playing time on mode line.
1965 @end defun
1966
1967 @defun emms-playing-time-disable-display
1968 Remove playing time from mode line.
1969 @end defun
1970
1971 @node Music Player Daemon
1972 @chapter Music Player Daemon
1973
1974 @cindex music player daemon
1975 @cindex remote interface
1976 @cindex mpd
1977
1978 Emms provides an interface to the @uref{http://www.musicpd.org/, Music
1979 Player Daemon}(MusicPD) software. The package is called `emms-player-mpd' and
1980 is provided by the file @file{emms-player-mpd.el}.
1981
1982 The advantages of using MusicPD as an EMMS backend include the
1983 following.
1984
1985 @itemize @bullet
1986 @item minimal CPU usage
1987 @item fast access of track information
1988 @item optional crossfade
1989 @end itemize
1990
1991 @subheading Setup
1992
1993 To load `emms-player-mpd' invoke:
1994
1995 @lisp
1996 (require 'emms-player-mpd)
1997 @end lisp
1998
1999 Set the variables @var{emms-player-mpd-server-name} and
2000 @var{emms-player-mpd-server-port} to the location and port
2001 (respectively) of your MusicPD server. For example:
2002
2003 @lisp
2004 (setq emms-player-mpd-server-name "localhost")
2005 (setq emms-player-mpd-server-port "6600")
2006 @end lisp
2007
2008 If your MusicPD setup requires a password, you will to set
2009 @var{emms-player-mpd-server-password} as follows.
2010
2011 @lisp
2012 (setq emms-player-mpd-server-password "mypassword")
2013 @end lisp
2014
2015 To get track information from MusicPD, invoke the following:
2016
2017 @lisp
2018 (add-to-list 'emms-info-functions 'emms-info-mpd)
2019 @end lisp
2020
2021 Adding `emms-player-mpd' to your Emms player list is accomplished by
2022 invoking:
2023
2024 @lisp
2025 (add-to-list 'emms-player-list 'emms-player-mpd)
2026 @end lisp
2027
2028 If you use absolute file names in your m3u playlists (which is most
2029 likely), make sure you set @var{emms-player-mpd-music-directory} to
2030 the value of "music_directory" from your MusicPD config. There are
2031 additional options available as well, but the defaults should be
2032 sufficient for most uses.
2033
2034 You can set @var{emms-player-mpd-sync-playlist} to nil if your master
2035 EMMS playlist contains only stored playlists.
2036
2037 @subheading Commands provided
2038
2039 @defun emms-player-mpd-connect
2040 Connect to MusicPD and retrieve its current playlist. Afterward, the
2041 status of MusicPD will be tracked.
2042 @end defun
2043
2044 @defun emms-player-mpd-disconnect
2045 Terminate the MusicPD client process and disconnect from MusicPD.
2046 @end defun
2047
2048 @defun emms-player-mpd-show &optional insertp
2049 Describe the current EMMS track in the minibuffer. If INSERTP is
2050 non-nil, insert the description into the current buffer instead. This
2051 function uses @var{emms-show-format} to format the current track. It
2052 differs from @command{emms-show} in that it asks MusicPD for the
2053 current track, rather than Emms.
2054 @end defun
2055
2056 @subsubheading Updating the MusicPD database
2057
2058 @defun emms-player-mpd-update-directory dir
2059 Cause the tracks in DIR to be updated in the MusicPD database.
2060 @end defun
2061
2062 @defun emms-player-mpd-update-all
2063 Cause all tracks in the MusicPD music directory to be updated in
2064 the MusicPD database.
2065 @end defun
2066
2067 @subsubheading emms-cache.el integration
2068
2069 @defun emms-cache-set-from-mpd-directory dir
2070 Dump all MusicPD data from DIR into the EMMS cache.
2071 This is useful to do when you have recently acquired new music.
2072 @end defun
2073
2074 @defun emms-cache-set-from-mpd-all
2075 Dump all MusicPD data into the EMMS cache.
2076 This is useful to do once, just before using emms-browser.el, in
2077 order to prime the cache.
2078 @end defun
2079
2080 @subsubheading emms-volume.el integration
2081
2082 To activate this, add the following to your .emacs.
2083
2084 @lisp
2085 (require 'emms-volume)
2086 (setq emms-volume-change-function 'emms-volume-mpd-change)
2087 @end lisp
2088
2089 @node Lyrics
2090 @chapter Lyrics
2091
2092 @cindex lyrics
2093
2094 We can display the lyrics of a song in time with the music using the
2095 `emms-lyrics' package provided by the file @file{emms-lyrics.el}.
2096
2097 The lyrics files should have the extention ``.lrc'', and can be placed
2098 under either the same directory as the music files or
2099 @var{emms-lyrics-dir}.
2100
2101 To add this feature we invoke:
2102
2103 @lisp
2104 (require 'emms-lyrics)
2105 (emms-lyrics 1)
2106 @end lisp
2107
2108 There are a number of variables we can set to define the way that
2109 `emms-lyrics' behaves, we can set these directly or by using the
2110 Customize feature in Emacs.
2111
2112 @defvr {User Option} emms-lyrics-display-on-minibuffer
2113 If non-nil, display lyrics on minibuffer.
2114 @end defvr
2115
2116 @defvr {User Option} emms-lyrics-display-on-modeline
2117 If non-nil, display lyrics on modeline.
2118 @end defvr
2119
2120 @defvr {User Option} emms-lyrics-dir
2121 Local lyrics repository.
2122 @command{emms-lyrics-find-lyric} will look for lyrics in current
2123 directory(i.e., same as the music file) and this directory.
2124 @end defvr
2125
2126 @defvr {User Option} emms-lyrics-display-format
2127 Format for displaying lyrics. "%s" will be replaced by the lyrics
2128 string.
2129 @end defvr
2130
2131 @defvr {User Option} emms-lyrics-coding-system
2132 Coding system used in the output of lyrics.
2133 @end defvr
2134
2135 @defvr {User Option} emms-lyrics-scroll-p
2136 Non-nil value will enable lyrics scrolling.
2137 @end defvr
2138
2139 @defvr {User Option} emms-lyrics-scroll-timer-interval
2140 Interval between scroller timers. The shorter, the faster.
2141 @end defvr
2142
2143 We can control `emms-lyrics' with the help of the following functions:
2144
2145 @defun emms-lyrics-start
2146 Start displaying lyrics.
2147 @end defun
2148
2149 @defun emms-lyrics-stop
2150 Stop displaying lyrics.
2151 @end defun
2152
2153 @defun emms-lyrics-toggle-display-on-minibuffer
2154 Toggle display lyrics on minibufer.
2155 @end defun
2156
2157 @defun emms-lyrics-toggle-display-on-modeline
2158 Toggle display lyrics on mode line.
2159 @end defun
2160
2161 @defun emms-lyrics-enable
2162 Enable displaying Emms lyrics.
2163 @end defun
2164
2165 @defun emms-lyrics-disable
2166 Disable displaying Emms lyrics.
2167 @end defun
2168
2169 @defun emms-lyrics-toggle
2170 Toggle displaying Emms lyrics.
2171 @end defun
2172
2173 @node Volume
2174 @chapter Volume
2175
2176 @cindex volume
2177
2178 We can use the `emms-volume' package, as provided by the
2179 @file{emms-volume.el} file, to manipulate the volume.
2180
2181 @defopt emms-volume-change-amount
2182 The amount to use when raising or lowering the volume using the
2183 emms-volume interface.
2184
2185 This should be a positive integer.
2186 @end defopt
2187
2188 @defun emms-volume-raise
2189 Increase the volume.
2190 @end defun
2191
2192 @defun emms-volume-lower
2193 Decrease the volume.
2194 @end defun
2195
2196 If you feel like binding those two functions to global keys --- don't do
2197 it or you'll miss the convenience of `emms-volume-minor-mode'. Instead,
2198 bind the following two commands to some keys that you like.
2199
2200 @defun emms-volume-mode-plus
2201 Raise volume and enable or extend the `emms-volume-minor-mode' timeout.
2202 @end defun
2203
2204 @defun emms-volume-mode-minus
2205 Lower volume and enable or extend the `emms-volume-minor-mode' timeout.
2206 @end defun
2207
2208 Example:
2209
2210 @lisp
2211 (global-set-key (kbd "C-c +") 'emms-volume-mode-plus)
2212 (global-set-key (kbd "C-c -") 'emms-volume-mode-minus)
2213 @end lisp
2214
2215 Whenever you use one of these keys or call these functions with
2216 @kbd{M-x}, Emms will be put into `emms-volume-minor-mode' for a short
2217 period defined by `emms-volume-mode-timeout'.
2218
2219 @defopt emms-volume-mode-timeout
2220 The timeout in amount of seconds used by `emms-volume-minor-mode'.
2221 @end defopt
2222
2223 In this interval you can raise/lower the volume simply by pressing
2224 @kbd{+} or @kbd{-}, which will also reset the timer to its initial
2225 value. So instead of pressing @kbd{C-c +} six times to increase volume
2226 by six steps of @code{emms-volume-change-amount}, you would simply type
2227 @kbd{C-c + + + + + +}.
2228
2229
2230 @node Last.fm
2231 @chapter Last.fm
2232
2233 @cindex last.fm
2234
2235 Last.fm is a popular commercial music streaming service. Last.fm
2236 allows a subscriber to listen to streaming music. Last.fm can also
2237 accept data as to what music is played locally. This information can
2238 be used by the Last.fm service. As usual the responsibility is on the
2239 user to decide how much information to share with third-parties.
2240
2241 The emms-lastfm-client package, provided the file
2242 @file{emms-lastfm-client.el} provides native Last.fm support from
2243 within Emms.
2244
2245 Emms does not provide a subscription to the Last.fm service, nor is it
2246 affiliated with the service in any way. There are restrictions on the
2247 use of this service. Quoting from @uref{http://www.last.fm/api/radio}:
2248 ``Who can I stream radio to? Any API account can only stream radio to
2249 Last.fm's paid subscribers''.
2250
2251 @menu
2252 * Last.fm Setup:: Configuring Emms to use Last.fm.
2253 * Last.fm Radio:: Listening to music through Last.fm
2254 * Last.fm Audioscrobbler:: Submitting music to Last.fm
2255 @end menu
2256
2257 @node Last.fm Setup
2258 @section Last.fm Setup
2259
2260 We've spoken to representatives from Last.fm and arrived at the
2261 following agreement: In order to be able to use the service while
2262 preserving the essential freedoms of the GPL each client must apply
2263 for their own API key from Last.fm.
2264
2265 Here are the steps for getting authorization from Last.fm to stream
2266 music. Thankfully this only needs to be done once:
2267
2268 @enumerate
2269
2270 @item
2271 Complete steps 1 and 2 from
2272 @uref{http://www.last.fm/api/authentication} to get an API key and a
2273 secret key. Set the variables @var{emms-lastfm-client-api-key} and
2274 @var{emms-lastfm-client-api-secret-key} respectively.
2275
2276 @item
2277 Invoke @kbd{M-x emms-lastfm-client-user-authorization}. On successful
2278 completion a browser window will open asking for confirmation to allow
2279 this application access to your Last.fm account. Confirm and close the
2280 browser.
2281
2282 @item
2283 Invoke @kbd{M-x emms-lastfm-client-get-session}. On successful
2284 completion your permanent session key will be stored in
2285 @var{emms-lastfm-client-session-key-file}. As long as this value is
2286 accessible the authentication process need not be repeated.
2287
2288 @end enumerate
2289
2290 After successfully completing the above Emms should be authorized to
2291 access your Last.fm account.
2292
2293 @node Last.fm Radio
2294 @section Last.fm Radio
2295
2296 To show the currently streaming track invoke:
2297 @kbd{M-x emms-lastfm-client-show}.
2298
2299 To display information and a photo of currently streaming artist:
2300 @kbd{M-x emms-lastfm-client-info}.
2301
2302 There are three ratings you can submit while streaming audio from
2303 Last.fm: ``love''-ing a track, skipping to the next song (simply
2304 skipping also counts as a form of ``scrobbing'') and ``ban''-ing
2305 (which also skips).
2306
2307 @kbd{M-x emms-lastfm-client-love-track}: ``love'' the currently
2308 streaming track.
2309
2310 @kbd{M-x emms-lastfm-client-track-advance}: Skip to the next streaming
2311 track.
2312
2313 @kbd{M-x emms-lastfm-client-ban-track}: ``ban'' the currently
2314 streaming track.
2315
2316 Note that Last.fm streams cannot be paused or replayed. Doing so may
2317 cause Last.fm to suspend your account.
2318
2319 There are a number of stations you can tune into:
2320
2321 @kbd{M-x emms-lastfm-client-play-similar-artists}: Play
2322 Similar-Artists stream. You will be prompted to enter the name of the
2323 artist. The input will auto-complete from the Emms cache. If an artist
2324 is not in the Emms cache and has a name with spaces, use @kbd{C-q
2325 Space} to enter literal spaces.
2326
2327 There are personal streams you can tune into:
2328
2329 (at the time of writing these are in a state of flux as Last.fm
2330 depreciate old stations and bring in new ones; If a station which used
2331 to work doesn't anymore that is probably the reason. As Last.fm add
2332 and remove stations emms-lastfm-client will be updated accordingly)
2333
2334 @kbd{M-x emms-lastfm-client-play-library}: Your Last.fm Library.
2335
2336 @kbd{M-x emms-lastfm-client-play-loved}: Your ``loved'' tracks.
2337
2338 @kbd{M-x emms-lastfm-client-play-recommended}: Your ``recommended'' tracks.
2339
2340 @kbd{M-x emms-lastfm-client-play-mix}: Your ``mix'' radio.
2341
2342 @kbd{M-x emms-lastfm-client-play-neighborhood}: Your ``neighborhood''.
2343
2344 You can use similar commands to tune into other people's streams. For
2345 each of these commands you will be prompted for the Last.fm username
2346 of the person whose radio you wish to hear.
2347
2348 @kbd{M-x emms-lastfm-client-play-user-library}: A Last.fm user's
2349 Library.
2350
2351 @kbd{M-x emms-lastfm-client-play-user-loved}: A Last.fm user's
2352 ``loved'' tracks.
2353
2354 @kbd{M-x emms-lastfm-client-play-user-neighborhood}: A Last.fm user's
2355 ``neighborhood''.
2356
2357 @node Last.fm Audioscrobbler
2358 @section Last.fm Audioscrobbler
2359
2360 Emms can submit the tracks you play to your Last.fm profile. Assuming
2361 you have obtained a Last.fm api key, as explained in the chapter
2362 @xref{Last.fm Setup}, all the audioscrobbler needs is your username in
2363 @var{emms-lastfm-client-username}. You can enter it with @kbd{M-x
2364 customize-group RET emms-lastfm}.
2365
2366 @kbd{M-x emms-lastfm-scrobbler-enable} turns on audioscrobbling.
2367
2368 To turn it off use @kbd{M-x emms-lastfm-scrobbler-disable}.
2369
2370 To turn on Emms' audioscrobber in your .emacs file add:
2371 @lisp
2372 (require 'emms-lastfm-client)
2373
2374 (setq emms-lastfm-client-username "your-lastfm-username")
2375 (setq emms-lastfm-client-api-key "your-lastfm-api-key")
2376 (setq emms-lastfm-client-api-secret-key "your-lastfm-api-secret-key")
2377
2378 (emms-lastfm-scrobbler-enable)
2379 @end lisp
2380
2381
2382 @node Streaming Audio
2383 @chapter Streaming Audio
2384
2385 @cindex streaming audio
2386 @cindex internet radio
2387
2388 Emms provides a friendly interface for managing and playing streaming
2389 audio in addition to the Emms playlist interface. The interface is
2390 defined in the @file{emms-streams.el} package and can be loaded by
2391 invoking:
2392
2393 @lisp
2394 (require 'emms-streams)
2395 @end lisp
2396
2397 The Emms interface for streaming audio is enabled by default in the
2398 `emms-all' and `emms-devel' setup levels. For more information about
2399 Emms setup levels see @xref{Simple Setup}.
2400
2401 Enter the emms-streams interface by invoking @kbd{M-x}
2402 @command{emms-streams}. The emms-streams interface comes with a
2403 built-in, eclectic list of streaming audio channels from throughout the
2404 Web. Emms can of-course play other streams than the ones listed by
2405 default, you are free to remove any or all of them and add your
2406 own.@footnote{If you enjoy a particular streaming audio station on the
2407 Web and think that it belongs in the default list, please send us a
2408 link and we will gladly add it!}
2409
2410 If you want to play Last.fm streams, invoke the following and use the
2411 ``lastfm'' type when adding a bookmark to a Last.fm stream.
2412
2413 @lisp
2414 (require 'emms-lastfm)
2415 @end lisp
2416
2417 The following is a list of the key-bindings for the emms-streams
2418 interface:
2419
2420 @table @kbd
2421 @item RET
2422 @kindex RET (emms-streams)
2423 @vindex emms-stream-default-action
2424 Perform the default action when you press RET in the Emms Stream
2425 interface. Can be either ``add'' or ``play''. The default is ``add'',
2426 which adds the station under point to the Emms playlist. When
2427 @var{emms-stream-default-action} is ``play'' then Emms will play the
2428 streaming audio channel under point.
2429 @item q
2430 @kindex q (emms-streams)
2431 @findex emms-stream-quit
2432 Quit the emms-streams interface.
2433 @item a
2434 @kindex a (emms-streams)
2435 @findex emms-stream-add-bookmark
2436 Add a bookmark to a streaming audio URL to the list.
2437 @item d
2438 @kindex d (emms-streams)
2439 @findex emms-stream-delete-bookmark
2440 Remove a bookmark to a streaming audio URL from the list.
2441 @item e
2442 @kindex e (emms-streams)
2443 @findex emms-stream-edit-bookmark
2444 Edit the details of the bookmark under point.
2445 @item h
2446 @kindex h (emms-streams)
2447 @findex describe-mode
2448 Describe the emms-streams mode.
2449 @item n
2450 @kindex n (emms-streams)
2451 @findex emms-stream-next-line
2452 Move to the next line in the emms-streams buffer (same as C-n).
2453 @item p
2454 @kindex p (emms-streams)
2455 @findex emms-stream-previous-line
2456 Move to the previous line in the emms-streams buffer (same as C-p).
2457 @item s
2458 @kindex s (emms-streams)
2459 @findex emms-stream-save-bookmarks-file
2460 Save the bookmarks in the emms-streams interface to disk. The
2461 bookmarks will be to the location designated in the variable
2462 @var{emms-stream-bookmarks-file}.
2463 @item i
2464 @kindex i (emms-streams)
2465 @findex emms-stream-info-bookmark
2466 Return information about the streaming audio at the URL of the
2467 bookmark under point. Note that this will only work if the
2468 `emms-stream-info' has already been loaded.
2469 @end table
2470
2471 @c including the relevant licenses
2472 @include gpl.texi
2473 @include fdl.texi
2474
2475 @node Concept Index
2476 @unnumbered Concept Index
2477 @printindex cp
2478
2479 @node Function Index
2480 @unnumbered Function Index
2481 @printindex fn
2482
2483 @node Variable Index
2484 @unnumbered Variable Index
2485 @printindex vr
2486
2487 @node Keybinding Index
2488 @unnumbered Keybinding Index
2489 @printindex ky
2490
2491 @bye