-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathemms.info
4307 lines (3392 loc) · 180 KB
/
emms.info
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
This is docgCYtAI.info, produced by makeinfo version 6.8 from
emms.texinfo.
(C) 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2014, 2015, 2016,
2020, 2021, 2022, 2023, 2024 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.1 or any later version published by the Free Software
Foundation; with no Invariant Sections, no Front-Cover Texts, and
no Back-Cover Texts. A copy of the license is included in the
section entitled "GNU Free Documentation License".
INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Emms: (emms). The Emacs Multimedia System
END-INFO-DIR-ENTRY
File: docgCYtAI.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
Emms Manual
***********
This is the Manual for the Emacs Multimedia System.
(C) 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2014, 2015, 2016,
2020, 2021, 2022, 2023, 2024 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.1 or any later version published by the Free Software
Foundation; with no Invariant Sections, no Front-Cover Texts, and
no Back-Cover Texts. A copy of the license is included in the
section entitled "GNU Free Documentation License".
* Menu:
Starting out
* Introduction:: Introduction to Emms.
* Quickstart Guide:: First steps with Emms for new users.
* Installation:: How to install Emms on your System.
* Setup:: How to setup Emms.
* Configuration:: More detailed setup and configuration.
* Getting Help:: Where to get help with Emms and make suggestions.
* Formats and Freedom:: File formats without restrictions.
Emms basics
* Basic Commands:: How to control Emms with ease.
* The Core File:: The inner core of Emms.
* Sources:: Sources for playlists-creation.
* Simple Players:: Some simple players.
* Playlists:: How Emms organizes media.
Advanced Features
* Track Information:: More narrative track descriptions.
* Interactive Playlists:: Interactive Playlists.
* Markable Playlists:: Allow tracks to be marked.
* Extending Emms:: How to define new players and modules.
Modules and Extensions
* The Browser:: Advanced metadata browsing.
* Sorting Playlists:: Sorting the order of the tracks.
* Persistent Playlists:: Restoring playlists on emacs startup.
* Editing Tracks:: Editing track information from within Emms.
* Emms Mode Line:: Emms information on the mode line.
* Limiting:: Derive a new playlist from the current.
* Music Player Daemon:: Interface to Music Player Daemon.
* Lyrics:: Displaying lyrics synchronously.
* Volume:: Changing the volume.
* Streaming Audio:: Interface to streaming audio.
* APE / FLAC Commands:: How to play next or previous track in these files.
* Bookmarks:: Saving a place in a media file.
* Managing Playlists:: Managing multiple playlists.
* GNU FM:: Connect to music community websites.
* Listenbrainz:: Notify listenbrainz of tracks played.
* D-Bus:: Control Emms over D-Bus.
Copying and license
* Copying:: The GNU General Public License gives you permission to
redistribute Emms on certain terms; it also explains
that there is no warranty.
* The GNU FDL:: The license for this documentation.
Indices
* Concept Index::
* Function Index::
* Variable Index::
* Keybinding Index::
-- The Detailed Node Listing --
Here are some other nodes which are really inferiors of the ones
already listed, mentioned here so you can get to them in one step:
Installation
* Compiling Emms:: Compiling Emms into Byte-Code.
The Core File
* User Variables:: Variables for the user to tweak.
* Hooks:: Hooks for important Emms functions.
* Core Functions:: Providing the basic functionality of Emms.
Track Information
* Metadata Utilities:: Supported external metadata utilities.
* Defining Info Methods:: Defining new info methods.
Extending Emms
* New Player:: How to define a new player.
* Simple Player for `play':: Example player using 'play'.
* More Complex Player:: Example of a complex player using 'mpg321'.
File: docgCYtAI.info, Node: Introduction, Next: Quickstart Guide, Up: Top
1 Introduction
**************
Emms is the Emacs Multi-Media System. Emms organizes playlists, allows
browsing through track and album metadata, and plays files by calling
external players.
This manual tries to be the definitive source of information about
Emms, an online version of the manual is available at:
<http://www.gnu.org/software/emms/manual/>.
The basic functionality of Emms consists of three parts: The core,
the sources, and the players.
The core resides in 'emms.el', provides a simple playlist, and the
basic functionality to use all the other features of Emms. It provides
the common user commands and interfaces for other parts. It thinks in
tracks, where a track is the combination of a type and a name - e.g.
the track type 'file has a name that is the file name. Other track
types are possible.
To get to tracks, the core needs sources. The file
'emms-source-file.el' provides simple sources to interact with the file
system.
When Emms finally has the sources in the playlist, it needs a player
to play them. 'emms-player-simple.el' defines a few useful players and
provides a straightforward way of providing your own.
The Emms comes with many additional features to extend the
functionality beyond the core.
The way Emms works is easy to customize with your own code or by
using 'M-x customize' or by changing the variables directly.
File: docgCYtAI.info, Node: Quickstart Guide, Next: Installation, Prev: Introduction, Up: Top
2 Quickstart Guide
******************
This chapter demonstrates how to setup Emms so that you can start
listening to your music without having to read all of the documentation
first. This is the tl;dr version of the manual.
The first thing to do is to load Emms via GNU ELPA. Invoke 'M-x
list-packages' and choose to install Emms.
If you are installing Emms manually, then start by telling Emacs
where your copy of Emms is located. Let's say you have it in
'~/elisp/emms/'. So add this line to your '.emacs':
(add-to-list 'load-path "~/elisp/emms/lisp/")
(require 'emms-setup)
(More detailed information about installing Emms can be found in the
installation chapter, *Note Installation::.)
Either way, you are now ready to configure Emms. Your Emms config
can be as simple as three lines. For example:
(emms-all)
(setq emms-player-list '(emms-player-vlc)
emms-info-functions '(emms-info-native))
The function 'emms-all' loads all of the stable features in Emms.
Emms can automatically generate that 'setq' statement for you based
on which players and metadata readers you have installed on your system.
Just invoke 'emms-setup-discover' and answer a few questions.
The variable EMMS-PLAYER-LIST is a list of players that Emms should
call to play your media. In this example we assume that you have VLC
installed on your system. But if you use mpv or mplayer instead, just
change 'emms-player-vlc' to 'emms-player-mpv' or 'emms-player-mplayer';
you get the idea.
The variable EMMS-INFO-FUNCTIONS is a list of ways for Emms to read
the metadata in your media files, so that Emms can display the song
title, artist name, etc. 'emms-info-native' is a metadata reader
written entirely in Emacs Lisp, but there are also other backends which
call external programs such as TinyTag, Taglib, Exiftool, and etc.
Reload your Emacs initialization file, or restart Emacs to let the
changes have an effect.
Add all your music to a playlist by invoking 'M-x
emms-add-directory-tree RET ~/my_music_directory/ RET'. When you do
this Emms will start reading metadata from the files and populating the
cache. This may take a while.
When you are done, you can load the browser with 'M-x emms-browser',
or view your playlist directly with 'M-x emms-playlist-mode-go' (when in
the playlist you can hit 'RET' on a track to start playing it.)
Now you can start exploring Emms. It's probably best to begin with
the basic commands (*note Basic Commands::), the interactive playlists
(*note Interactive Playlists::), and the browser (*note The Browser::).
More detail about setting up Emms can be found in the setup chapter,
*Note Setup::.
Need help? There are knowledgeable people on the #emacs channel on
irc (irc.libera.chat), and Emms has a mailing list at [email protected].
File: docgCYtAI.info, Node: Installation, Next: Setup, Prev: Quickstart Guide, Up: Top
3 Installation
**************
Emms is available via GNU ELPA, which takes care of all of the following
steps automatically.
If you are installing Emms manually, you need to put all the .el
files of emms in a directory in your load-path. For example, if you put
all those files into ~/elisp/emms/, then in your ~/.emacs, you should
add:
(add-to-list 'load-path "~/elisp/emms/lisp/")
* Menu:
* Compiling Emms:: Compiling Emms into Byte-Code.
File: docgCYtAI.info, Node: Compiling Emms, Up: Installation
3.1 Compiling Emms
==================
If you are using XEmacs, you will need to edit 'Makefile' as follows
before continuing.
EMACS=xemacs
SITEFLAG=-no-site-file
You can byte-compile Emms by first entering the directory containing
the Emms source code, followed by invoking:
'make'
Which will byte compile Emms. You can then invoke:
'make install'
Which will install Emms into your Emacs directories (provided you
have the appropriate permissions to do so on your system).
Note that Emms is a light-weight and agile program, you can therefore
run Emms just fine without byte compiling it.
File: docgCYtAI.info, Node: Setup, Next: Configuration, Prev: Installation, Up: Top
4 Setup
*******
The 'emms-setup' feature is provided by the file 'emms-setup.el'. It is
essentially a collection of shortcuts for loading different Emms
features quickly, but everything you can do with 'emms-setup' can also
be done manually.
We use 'emms-setup' by calling one of the setup functions.
-- Function: emms-minimalistic
An Emms setup script. Playlists and all the basics for playing
media, but nothing else.
-- Function: emms-all
An Emms setup script. Loads all the stable features which come
with the Emms distribution.
'emms-setup' also comes with a convenience function to set a default
list of media players.
-- Function: emms-default-players
Set EMMS-PLAYER-LIST to EMMS-SETUP-DEFAULT-PLAYER-LIST.
You can of course write your own Emms setup functions like the above
by looking at the existing function definitions in 'emms-setup.el'.
File: docgCYtAI.info, Node: Configuration, Next: Getting Help, Prev: Setup, Up: Top
5 Configuration
***************
This chapter discusses the configuration of Emms in more detail.
The following code fragment provides a minimal Emms setup without
using the layer of 'emms-setup'. It can maybe be used to better
understand the internals of Emms. You can see how Emms needs to know
about players (these are defined in 'emms-player-simple') and about
sources for tracks (trivial file system based sources, such as this
'emms-directory-tree', are defined in 'emms-source-file').
(require 'emms-player-simple)
(require 'emms-source-file)
(require 'emms-source-playlist)
(setq emms-player-list '(emms-player-mpg321
emms-player-ogg123
emms-player-mplayer))
For a discussion on how to define additional players, see *Note
Simple Players::.
Much of the behaviour of Emms can be changed by setting variables.
For example:
(setq emms-info-asynchronously nil)
(setq emms-playlist-buffer-name "*Music*")
The first 'setq' turns off the asynchronous updating of info tags.
The second sets the default name of the Emms playlist buffer.
Another way to change Emms variables is to use the M-x 'customize'
mechanism provided by Emacs.
* Menu:
* Finding files and speed:: Finding files quickly or portably.
* Setup Examples:: Examples of ways to setup Emms.
File: docgCYtAI.info, Node: Finding files and speed, Next: Setup Examples, Up: Configuration
5.1 Finding files and speed
===========================
Emms needs to traverse directories in order to find playable media. The
default method Emms uses to achive this is
'emms-source-file-directory-tree-internal' as defined in
'emms-source-file.el'. The above method is written portably and will
always work, but might be too slow if we want to load several hundred
tracks (or more).
'emms-source-file.el' defines another method for finding files,
'emms-source-file-directory-tree-find' which uses GNU/find.
'emms-source-file-directory-tree-find' is usually an order of magnitude
faster, but of course will not work if you do not have GNU/find
installed.
The method Emms will use is defined in the customisable variable
EMMS-SOURCE-FILE-DIRECTORY-TREE-FUNCTION.
File: docgCYtAI.info, Node: Setup Examples, Prev: Finding files and speed, Up: Configuration
5.2 Setup Examples
==================
What follow are samples from real-world Emms configurations which show
some of the variety and breadth of modifications people make to the
default Emms setup.
The following excerpt includes dbus integration, defining a "recent"
filter for the *Note The Browser::, persistent playlist via
'emms-history.el', and enabling sending track information with
'emms-librefm-stream.el':
;; notifications
(require 'emms-dbus)
(emms-dbus-enable)
;; covers
(setq emms-browser-covers #'emms-browser-cache-thumbnail-async)
(setq emms-browser-thumbnail-small-size 64)
(setq emms-browser-thumbnail-medium-size 128)
;; filters
(emms-browser-make-filter "all" #'ignore)
(emms-browser-make-filter "recent"
(lambda (track) (< 30
(time-to-number-of-days
(time-subtract (current-time)
(emms-info-track-file-mtime track))))))
(emms-browser-set-filter (assoc "all" emms-browser-filters))
;; history
(emms-history-load)
;; libre-fm
(emms-librefm-scrobbler-enable)
In the following it is possible to see how some of defaults are set
regarding saving playlists, playlist interaction, as well as adding
special arguments to a specific player backend.
(setq-default
emms-source-file-default-directory "/mnt/db/mediaCore/sound_music/"
emms-source-playlist-default-format 'm3u
emms-playlist-mode-center-when-go t
emms-playlist-default-major-mode 'emms-playlist-mode
emms-show-format "NP: %s"
emms-player-list '(emms-player-mpv)
emms-player-mpv-environment '("PULSE_PROP_media.role=music")
emms-player-mpv-parameters '("--quiet" "--really-quiet" "--no-audio-display" "--force-window=no" "--vo=null"))
File: docgCYtAI.info, Node: Getting Help, Next: Formats and Freedom, Prev: Configuration, Up: Top
6 Getting Help
**************
If you have a bug to report, need help, or wish to suggest a feature,
please feel free to use the Emms mailing list. The address of the list
is [email protected]. To subscribe to it, visit
<http://lists.gnu.org/mailman/listinfo/emms-help>.
If you are familiar with the Gmane service, there is a Gmane
newsgroup which mirrors this mailing address at gmane.emacs.emms.user.
Emms also has a website at <http://www.gnu.org/software/emms/>.
File: docgCYtAI.info, Node: Formats and Freedom, Next: Basic Commands, Prev: Getting Help, Up: Top
7 Formats and Freedom
*********************
Emms is free software, but some of the file formats it can play carry
restrictions, they are proprietary file formats. Proprietary software
companies are pushing out audio and video formats which restrict when,
where and how you can play them, and restrict developers from writing
free software which interacts with them.
Restrictive file formats put the corporate bottom-line before the
public interest.
Fortunately there are alternatives like Ogg. Ogg is a professional
grade multimedia format. Ogg Vorbis is the compressed audio format
(like MP3), and Ogg Theora is the video format. For more information,
go to <http://www.xiph.org/>.
If you want to transcode audio into a lossless format, you can try
FLAC (Free Lossless Audio Codec). FLAC stands out as the fastest and
most widely supported lossless audio codec, and the only one that at
once is non-proprietary, is unencumbered by patents and has the source
code for a reference implementation freely available. For more
information about FLAC, go to <http://flac.sourceforge.net/>.
File: docgCYtAI.info, Node: Basic Commands, Next: The Core File, Prev: Formats and Freedom, Up: Top
8 Basic Commands
****************
Before you can use the interface commands, you need a playlist to start
with. The following commands allow you to add to the current playlist
from different sources:
Note that the commands with the "emms-add-" prefix add the source to
the playlist but do not start playing it immediately. Conversely, the
commands with the "emms-play-" prefix begin playing the track
immediately.
This creates the active playlist and queue as needed. The active
queue will automatically switch to any playlists that are browsed to
such that the next song played will come from the currently viewed
playlist.
Locking the active playlist queue to its playlist will prevent it
from changing, allowing for browsing other playlists and sending songs
to the current active playlist from them.
Locking the queue to its playlist allows for live creation of a
curated playlist by browsing other playlists as well as the music
database and files.
-- Function: emms-play-file file
A source for a single file - either FILE, or queried from the user.
If called with a prefix the file will be added like
'emms-add-file'.
-- Function: emms-add-file file
A source for a single file - either FILE, or queried from the user.
If called with a prefix the file will be played like
'emms-play-file'.
-- Function: emms-play-directory dir
A source for a whole directory tree - either DIR, or queried from
the user.
-- Function: emms-add-directory dir
A source for a whole directory tree - either DIR, or queried from
the user.
-- Function: emms-play-directory-tree dir
A source for multiple directory trees - either DIR, or the value of
EMMS-SOURCE-FILE-DEFAULT-DIRECTORY.
-- Function: emms-add-directory-tree dir
A source for multiple directory trees - either DIR, or the value of
EMMS-SOURCE-FILE-DEFAULT-DIRECTORY.
-- Function: emms-play-url url
A source for an URL - for example, for streaming over http, playing
over sftp, or playing local files (with the "file://" scheme).
-- Function: emms-add-url url
A source for an URL - for example, for streaming over http, playing
over sftp, or playing local files (with the "file://" scheme).
-- Function: emms-play-playlist playlist
A source for the M3u or PLS playlist format from the file PLAYLIST.
-- Function: emms-add-playlist playlist
A source for the M3u or PLS playlist format from the file PLAYLIST.
-- Function: emms-play-find dir regexp
A source that will find files in DIR or
EMMS-SOURCE-FILE-DEFAULT-DIRECTORY which match REGEXP.
-- Function: emms-add-find dir regexp
A source that will find files in DIR or
EMMS-SOURCE-FILE-DEFAULT-DIRECTORY which match REGEXP.
The basic functionality of Emms is just to play music without being
noticed. It provides a few commands to skip the current track and such,
but other than that it doesn't show up. Emms provides the following
basic user commands (which you might want to bind to keystrokes):
-- Function: emms-start
Start playing the current playlist
-- Function: emms-stop
Stop playing
-- Function: emms-next
Start playing the next track in the playlist
-- Function: emms-previous
Start playing previous track in the playlist
-- Function: emms-shuffle
Shuffle the current playlist. This uses
EMMS-PLAYLIST-SHUFFLE-FUNCTION.
-- Function: emms-sort
Sort the current playlist. This uses EMMS-PLAYLIST-SORT-FUNCTION.
-- Function: emms-lock-queue
Lock the current active playlist queue to its playlist.
EMMS-PLAYLIST-SORT-FUNCTION.
-- Function: emms-unlock-queue
Unlock the current active playlist queue from its playlist.
EMMS-PLAYLIST-SORT-FUNCTION.
-- Function: emms-show &optional insertp
Describe the current Emms track in the minibuffer. If INSERTP is
non-nil, insert the description into the current buffer instead.
This function uses EMMS-SHOW-FORMAT to format the current track.
The command 'emms-show-all' will pop up a window with the complete
information about the track being played. 'emms-show-all' is provided
by 'emms-show-all.el', which is included in the 'emms-all' setup level.
See *Note Setup::.
File: docgCYtAI.info, Node: The Core File, Next: Sources, Prev: Basic Commands, Up: Top
9 The Core File
***************
The core file 'emms.el' provides the all basic functions for playing
music, generating playlists and defining players.
* Menu:
* User Variables:: Variables for the user to tweak.
* Hooks:: Hooks for important Emms functions.
* Core Functions:: Providing the basic functionality of Emms.
File: docgCYtAI.info, Node: User Variables, Next: Hooks, Up: The Core File
9.1 User Variables
==================
The core file defines a number of user variables.
-- User Option: emms-player-list
A list of players Emms can use. You need to set this in order to
use Emms to play media.
-- User Option: emms-show-format
The format to use for 'emms-show'. Any "%s" is replaced by what
EMMS-TRACK-DESCRIPTION-FUNCTION returns for the currently playing
track.
-- User Option: emms-repeat-playlist
Non-nil if the Emms playlist should automatically repeat the
playlist. If nil, playback will stop when the last track finishes
playing.
-- User Option: emms-track-description-function
Function for describing an Emms track in a user-friendly way.
-- User Option: emms-sort-lessp-function
A function that compares two tracks, and returns non-nil if the
first track should be sorted before the second (see also 'sort').
File: docgCYtAI.info, Node: Hooks, Next: Core Functions, Prev: User Variables, Up: The Core File
9.2 Hooks
=========
The core file provides hook variables for the basic functionality of
Emms.
-- User Option: emms-player-started-hook
A hook run when an Emms player started playing.
-- User Option: emms-player-stopped-hook
A hook run when an Emms player stopped playing. See also
EMMS-PLAYER-FINISHED-HOOK.
-- User Option: emms-playlist-source-inserted-hook
Hook run when a source got inserted into the playlist. The buffer
is narrowed to the new tracks.
-- User Option: emms-playlist-selection-changed-hook
Hook run after another track is selected in the Emms playlist.
-- User Option: emms-playlist-cleared-hook
Hook run after the current Emms playlist is cleared. This happens
both when the playlist is cleared and when a new buffer is created
for it.
-- User Option: emms-player-finished-hook
Hook run when an Emms player finishes playing a track. Please pay
attention to the differences between EMMS-PLAYER-FINISHED-HOOK and
EMMS-PLAYER-STOPPED-HOOK. The former is called only when the
player is stopped interactively; the latter, only when the player
actually finishes playing a track.
-- User Option: emms-player-paused-hook
Hook run when a player is paused or resumed. Use
EMMS-PLAYER-PAUSED-P to find the current state.
File: docgCYtAI.info, Node: Core Functions, Prev: Hooks, Up: The Core File
9.3 Core Functions
==================
The core file also defines all the functions important to the basic use
of Emms.
There are functions which deal with movement in the playlist.
-- Function: emms-next-noerror
Start playing the next track in the Emms playlist. Unlike
'emms-next', this function doesn't signal an error when called at
the end of the playlist. This function should only be called when
no player is playing. This is a good function to put in
'emms-player-finished-hook'.
-- Function: emms-playlist-next
Move to the next track in the current buffer.
-- Function: emms-playlist-previous
Move to the previous track in the current buffer.
-- Function: emms-random
Jump to a random track.
-- Function: emms-toggle-repeat-playlist
Toggle whether emms repeats the playlist after it is done. See
EMMS-REPEAT-PLAYLIST.
-- Function: emms-toggle-repeat-track
Toggle whether emms repeats the current track. See
EMMS-REPEAT-TRACK.
-- Function: emms-toggle-random-playlist
Toggle whether emms plays the tracks randomly or sequentially. See
EMMS-RANDOM-PLAYLIST.
Some functions deal with the getting and setting track information.
-- Function: emms-track type name
Create a track with type TYPE and name NAME.
-- Function: emms-track-type track
Return the type of TRACK.
-- Function: emms-track-name track
Return the name of TRACK.
-- Function: emms-track-get name track &optional inexistent
Return the value of NAME for TRACK. If there is no value, return
DEFAULT (or nil, if not given).
-- Function: emms-track-set track name value
Set the value of NAME for TRACK to VALUE.
-- Function: emms-track-description track
Return a description of TRACK. This function uses
EMMS-TRACK-DESCRIPTION-FUNCTION.
-- Function: emms-player-for track
Return an Emms player capable of playing TRACK. This will be the
first player whose PLAYABLEP function returns non-nil, or nil if no
such player exists.
-- Function: emms-playlist-current-selected-track
Return the currently selected track in the current playlist.
There are also functions which deal with the playing itself.
-- Function: emms-player-start track
Start playing TRACK.
-- Function: emms-player-stop
Stop the currently playing player.
-- Function: emms-player-stopped
Declare that the current Emms player is finished. This should only
be done by the current player itself.
-- Function: emms-seek duration
Seek the current player by DURATION from its current position. The
argument DURATION can be:
- A single number, in which case it is interpreted as seconds.
- A string of form [-][HH:]MM:SS.m, where HH is hours, MM is
minutes, and SS is seconds.
In both forms seconds can be a floating point number. A negative
value seeks backwards.
-- Function: emms-seek-to timestamp
Seek the current player to TIMESTAMP. Acceptable forms for
TIMESTAMP are the same as time duration in 'emms-seek', except that
timestamps cannot be negative.
-- Function: emms-seek-forward
Seek ten seconds forward.
-- Function: emms-seek-backward
Seek ten seconds backward.
For more basic commands defined in the core file see *Note Basic
Commands::.
File: docgCYtAI.info, Node: Sources, Next: Simple Players, Prev: The Core File, Up: Top
10 Sources
**********
Sources allow Emms to add and play tracks. Emms comes with a number of
sources of its own. Sources are designed so that creating new ones will
be easy.
For examples of Emms sources for files and directories see
'emms-source-file.el'.
-- User Option: emms-source-file-default-directory
The default directory to look for media files.
-- Function: emms-play-find
Play all files in EMMS-SOURCE-FILE-DEFAULT-DIRECTORY that match a
specific regular expression.
-- Function: emms-source-file &optional file
An Emms source for a single file - either FILE, or queried from the
user.
-- Function: emms-source-files files
An Emms source for a list of FILES.
-- Function: emms-source-directory &optional dir
An Emms source for a whole directory tree - either DIR, or queried
from the user
-- Function: emms-source-directory-tree & optional dir
An Emms source for multiple directory trees - either DIR, or the
value of EMMS-SOURCE-FILE-DEFAULT-DIRECTORY.
-- Function: emms-source-playlist file
An Emms source for playlists. See EMMS-SOURCE-PLAYLIST-FORMATS for
a list of supported formats.
-- Function: emms-source-playlist-native file
An Emms source for a native Emms playlist file.
-- Function: emms-source-playlist-m3u file
An Emms source for an m3u playlist file.
-- Function: emms-source-playlist-pls file
An Emms source for a pls playlist file.
-- Function: emms-source-find &optional dir regex
An Emms source that will find files in DIR or
EMMS-SOURCE-FILE-DEFAULT-DIRECTORY that match REGEXP.
-- Function: emms-source-beets database filter sort
An Emms source that will read a 'beets' library database (requires
Emacs to be built with SQLite support). With prefix argument
FILTER, interactively filter the database. With a double (or more)
prefix argument, also set SORT interactively; otherwise use
EMMS-SOURCE-BEETS-SORT-COLUMNS. If DATABASE is omitted or nil,
EMMS-SOURCE-BEETS-DATABASE is used.
-- Function: emms-source-file-directory-tree &optional dir
Return a list of all files under DIR which match REGEX.
-- Function: emms-play-dired
Play all marked files of a dired buffer
-- Function: emms-add-dired
Add all marked files of a dired buffer
-- Function: emms-source-file-regex
Return a regexp that matches everything any player (that supports
files) can play.
-- Function: emms-locate regexp
Search for REGEXP and display the results in a locate buffer
File: docgCYtAI.info, Node: Simple Players, Next: Playlists, Prev: Sources, Up: Top
11 Simple Players
*****************
-- Macro: define-emms-simple-player name types regex command &rest args
Define a simple player. NAME is used to construct the name of the
function like emms-player-NAME. TYPES is a list of track types
understood by this player. REGEX must be a regexp that matches the
filenames the player can play. COMMAND specifies the command line
argument to call the player and ARGS are the command line
arguments.
For a discussion on how to define new players see *Note New Player::.
-- Function: emms-player-simple-stop
Stop the currently playing process, if indeed there is one.
-- Function: emms-player-simple-start filename cmdname params
Starts a process playing FILENAME using the specified CMDNAME with
the specified PARAMS.
-- Function: emms-player-simple-sentinel proc str
Sentinel for determining the end of process for the process PROC
and the sentinel string STR.
File: docgCYtAI.info, Node: Playlists, Next: Track Information, Prev: Simple Players, Up: Top
12 Playlists
************
Emms uses Emacs buffers to store the media tracks for playing. We call
one such buffer a "playlist buffer" or an "Emms playlist buffer". Emms
then proceeds to play the media tracks in the buffer from top to bottom
until the end of the playlist.
The name of the playlist buffer is defined in the variable
EMMS-PLAYLIST-BUFFER-NAME and is set to be an invisible Emacs buffer by
default. You can change to any name you want. For an example
configuration see *Note Configuration::.
You can create any number of playlist buffers you wish. At any time
Emms has a single "current" buffer through which it proceeds track by
track. A saved playlist can be added to the current buffer by calling
'M-x emms-add-playlist' or 'M-x emms-play-playlist', which also plays
the tracks immediately.
The current Emms playlist buffer is stored in the variable
EMMS-PLAYLIST-BUFFER.
-- Function: emms-playlist-new &optional name
Create a new playlist buffer. The buffer is named NAME, but made
unique. NAME defaults to 'emms-playlist-buffer-name'. If called
interactively, the new buffer is also selected.
-- Function: emms-playlist-save &optional format file
Store the current playlist to FILE as the type FORMAT. The default
format is specified by EMMS-SOURCE-PLAYLIST-DEFAULT-FORMAT.
-- Function: emms-playlist-clear
Clears the playlist buffer.
-- Function: emms-playlist-current-clear
Clear the current playlist. If no current playlist exists, a new
one is generated.
-- Function: emms-playlist-current-kill
Kill the current EMMS playlist buffer and switch to the next one.
-- Function: emms-playlist-length
Display the total playing time of the current playlist.
-- Function: emms-playlist-total-playing-time
Alias for 'emms-playlist-length'.
File: docgCYtAI.info, Node: Track Information, Next: Interactive Playlists, Prev: Playlists, Up: Top
13 Track Information
********************
By default Emms will only list tracks as file names or URLs in playlists
(*note Playlists::) and the browser (*note The Browser::). However,
Emms can be configured to utilize so-called "info methods" to augment
tracks with metadata information, such as artist name, track name, album
title, and the like. We describe these methods and their use in this
chapter.
Fundamentally, info methods are Emacs Lisp functions that are called
for each track to provide information for that track. Current info
methods in Emms are restricted to tracks that are files; they do not
work with stream URLs (*note Streaming Audio::). Some of the methods
require installation of some additional software that Emms can then call
to read metadata from disk (*note Metadata Utilities::). Finally, some
methods work only with a limited set of media file formats such as Ogg
or MP3, while some methods support a wide variety of formats.
If caching is enabled (it is by default) then the metadata for each
track will be stored in the cache for faster retrieval. That means if
you change info method and want updated tracks, you will have to reset
the cache 'M-x emms-cache-reset' and then repopulate with 'M-x
emms-add-directory-tree RET ~/Music/ RET' or similar.
Automatic track information retrieval is enabled by default in the
'emms-all' setup level (*note Setup::). That setup level configures
Emms to use 'emms-info-native' and 'emms-info-cueinfo' methods, as they
are the only methods that do not rely on additional software.
Here is a list of all info methods distributed with Emms and their
software requirements:
'emms-info-native'
This method is implemented completely in Emacs Lisp and hence does
not require any external software. It supports Ogg Vorbis, Opus,
FLAC and MP3 files.
'emms-info-tinytag'
This method utilizes a small Python library 'tinytag'. It supports
MP3, Ogg Vorbis, Opus, MP4, M4A, FLAC, WMA and WAV formats.
'emms-info-exiftool'
This method calls 'exiftool' utility written in Perl. It supports
dozens of media file formats, far too many to list here.
'emms-info-libtag'
This method calls a small "shim" executable 'emms-print-metadata'
built around TagLib library. It supports MP3, Ogg Vorbis, Opus,
FLAC, MPC, Speex, WavPack, TrueAudio, WAV, AIFF, MP4 and ASF
formats.
'emms-info-metaflac'
This method calls 'metaflac' utility. It works only with FLAC
files.
'emms-info-mp3info'
This method calls 'mp3info' utility. It works only with MP3 files
that have older id3v1 tags.
'emms-info-ogginfo'
This method calls 'ogginfo' utility. It supports Ogg Vorbis and
Theora formats.
'emms-info-opusinfo'
This method calls 'opusinfo' utility. It works only with Opus
files.
'emms-info-cueinfo'
This is a special method that parses track information from an
accompanying cue file for FLAC and APE files (*note APE / FLAC
Commands::). It does not require any additional software.
To use any of the methods, add the method to 'emms-info-functions'
list. For example:
(require 'emms-info-native)
(add-to-list 'emms-info-functions 'emms-info-native)
You can also use a combination of format-specific tools if needed:
(require 'emms-info-mp3info)
(require 'emms-info-ogginfo)
(add-to-list 'emms-info-functions 'emms-info-mp3info 'emms-info-ogginfo)
In this case both 'emms-info-mp3info' and 'emms-info-ogginfo' will be
called for each track.
There are a number of user variables which control the behavior of
'emms-info':
-- User Option: emms-info-auto-update
Non-nil when Emms should update track information if the file
changes. This will cause hard drive activity on track loading. If
this is too annoying for you, set this variable to nil.
-- User Option: emms-info-asynchronously
Non-nil when track information should be loaded asynchronously.
This requires the feature 'later-do' which is provided by the file
'later-do.el', which comes with Emms. See variable
'emms-later-do-batch' for performance tweaking.
-- User Option: emms-info-functions
A list of functions (info methods) which add information to tracks.
Each function is called with a track as argument. If two info
methods produce the same information (for example album name), the
latter one takes precedence.
* Menu:
* Metadata Utilities:: Supported external metadata utilities.
* Defining Info Methods:: How to define new info methods.
File: docgCYtAI.info, Node: Metadata Utilities, Next: Defining Info Methods, Up: Track Information
13.1 Metadata Utilities
=======================
With the exception of 'emms-info-native' and 'emms-info-cueinfo', Emms
info methods require external metadata utilities to read metadata from
media files. If you plan to use a certain info method, make sure you
have the corresponding utility installed. All of these utilities are
free software, and most of them are included in free GNU/Linux
distributions.
tinytag
.......
tinytag is a Python library for reading metadata from music files. It
is available at <https://pypi.org/project/tinytag/>. Naturally a
working Python interpreter is also required. The corresponding Emms
info method is 'emms-info-tinytag'.
It is best to configure 'emms-info-tinytag' as the sole info method
for Emms, because competing and overlapping methods can cause confusion.
To use it, add the following into your Emacs initialization file:
(require 'emms-info-tinytag)
(setq emms-info-functions '(emms-info-tinytag))
ExifTool
........
ExifTool is a platform-independent Perl library and a command-line
application for reading, writing and editing meta information in a wide
variety of files. It is available at <https://exiftool.org/>.
Naturally a working Perl interpreter is also required. The