[elpa] externals/emms de0c407 80/80: * emms.info: new info

[Stefan Monnier]

branch: externals/emms
commit de0c4079ccdf3e17b722e3ddf2a275e66703b6bb
Author: Yoni Rabkin <yoni@rabkins.net>
Commit: Yoni Rabkin <yoni@rabkins.net>

    * emms.info: new info
---
 emms.info | 478 ++++++++++++++++++++++++++++++++++++++++++--------------------
 1 file changed, 325 insertions(+), 153 deletions(-)

diff --git a/emms.info b/emms.info
index 93b25ac..4c46802 100644
--- a/emms.info
+++ b/emms.info
@@ -96,9 +96,7 @@ The Core File
 * Core Functions::     Providing the basic functionality of Emms.
 
 Track Information
-* Using tinytag::            Track information via tinytag.
-* Using exiftool::           Track information via exiftool.
-* Using TagLib::             TagLib for track information.
+* Metadata Utilities:: Supported external metadata utilities.
 * Defining Info Methods::    Defining new info methods.
 
 Extending Emms
@@ -790,146 +788,325 @@ File: emms.info,  Node: Track Information,  Next: 
Interactive Playlists,  Prev:
 13 Track Information
 ********************
 
-Without a way to read the embedded track information inside files, Emms
-will only be able to list file names and file locations.  Therefore Emms
-is distributed with support for a number of pieces of software and
-libraries which can be used to provide access to track metadata such as
-the artist's name, track name, album title, etc.
+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::).  Most 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.
 
-   Emms can use a number of different ways to populate the playlist with
-track information.  These methods require the installation some
-additional software, free software of course, that Emms can then call to
-read the metadata from the files.
+   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.
 
-   * Tinytag, a small python utility.  See *Note Using tinytag::.
+   Here is a list of all info methods distributed with Emms and their
+software requirements:
 
-   * Exiftool, written in perl.  See *Note Using exiftool::.
+'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.
 
-   * The TagLib library can be used by compiling a small piece of "shim"
-     software.  See *Note Using TagLib::.
+'emms-info-tinytag'
+     This method utilizes a small Python library 'tinytag'.  It supports
+     MP3, Ogg Vorbis, Opus, MP4, M4A, FLAC, WMA and WAV formats.
 
-   You can also use a combination of format-specific tools if needed,
-such as 'emms-info-mp3info.el', 'emms-info-ogginfo.el',
-'emms-info-opusinfo.el', and 'emms-cue.el'.  These three packages are
-front-ends for command-line tools.  Ogg track information is retrieved
-using the ogginfo (http://directory.fsf.org/audio/ogg/vorbistools.html)
-and the <https://www.opus-codec.org/ opusinfo> software.  Likewise, mp3
-track information is available using mp3info
-(http://www.ibiblio.org/mp3info/).  'emms-cue.el' retrieves tracks
-information for ape/flac files by parsing a cue sheet file, which is
-plain text.
+'emms-info-exiftool'
+     This method calls 'exiftool' utility written in Perl.  It supports
+     dozens of media file formats, far too many to list here.
 
-   Automatic track information retrieval is enabled by default in the
-'emms-all' setup level provided by 'emms-setup.el'.  For more
-information about 'emms-setup.el' see *Note Setup::.
+'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:
 
-   If you would like to know how Emms track retreival works and how we
-can define new methods for track retrieval see *Note Defining Info
-Methods::.
+     (require 'emms-info-native)
+     (add-to-list 'emms-info-functions 'emms-info-native)
 
-   There are a number of user variables which control the behaviour of
-'emms-info'.
+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 LATER-DO-BATCH for
-     performance tweaking.
+     'later-do.el', which comes with Emms.  See variable
+     'emms-later-do-batch' for performance tweaking.
+
  -- User Option: emms-info-functions
-     Functions which add information to tracks.  Each is called with a
-     track as argument.
+     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:
 
-* Using tinytag::            Track information via tinytag.
-* Using exiftool::           Track information via exiftool.
-* Using TagLib::        TagLib for track information.
-* Defining Info Methods::    Defining new info methods.
+* Metadata Utilities::       Supported external metadata utilities.
+* Defining Info Methods::    How to define new info methods.
 
 
-File: emms.info,  Node: Using tinytag,  Next: Using exiftool,  Up: Track 
Information
+File: emms.info,  Node: Metadata Utilities,  Next: Defining Info Methods,  Up: 
Track Information
 
-13.1 Using tinytag
-==================
+13.1 Metadata Utilities
+=======================
 
-Make sure that the python program tinytag is installed on your system.
-It is available at tinytag (https://pypi.org/project/tinytag/).
+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.
 
-   Configure tinytag as the sole info method (competing and overlapping
-methods can cause confusion) for Emms:
+tinytag
+.......
 
-     (setq emms-info-functions '(emms-info-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'.
 
-
-File: emms.info,  Node: Using exiftool,  Next: Using TagLib,  Prev: Using 
tinytag,  Up: Track Information
+   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:
 
-13.2 Using exiftool
-===================
+     (require 'emms-info-tinytag)
+     (setq emms-info-functions '(emms-info-tinytag))
 
-Make sure that the perl program exiftool is installed on your system.
-It is available at <https://exiftool.org/>.
+ExifTool
+........
 
-   Then set exiftool as the sole info method with:
+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
+corresponding Emms info method is 'emms-info-exiftool'.
 
-     (setq emms-info-functions '(emms-info-exiftool))
+   It is best to configure 'emms-info-exiftool' 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:
 
-
-File: emms.info,  Node: Using TagLib,  Next: Defining Info Methods,  Prev: 
Using exiftool,  Up: Track Information
+     (require 'emms-info-exiftool)
+     (setq emms-info-functions '(emms-info-exiftool))
 
-13.3 Using TagLib
-=================
+TagLib
+......
 
-'emms-info-libtag.el' uses a tiny C shim (included in the src/
-directory) program to take advantage of TagLib
-(http://taglib.github.io/).
+TagLib is a library for reading and editing metadata of several popular
+audio formats.  It is available at <http://taglib.github.io/>.  Because
+TagLib is a C++ library instead of an executable program, you have to
+build and install a small "shim" executable 'emms-print-metadata' around
+it.  'emms-info-libtag' will then call this executable to read metadata
+from media files.
 
-   The communication with the TagLib library is done via a tiny program
-written in C++ 'emms-print-metadata.cpp', which comes with Emms.  To
-compile 'emms-print-metadata' invoke:
+   To compile 'emms-print-metadata' invoke
 
    'make emms-print-metadata'
 
-   The resultant binary will be installed when you invoke:
+in Emms directory.  For this to succeed you need to have a working C++
+compiler and TagLib development libraries installed on your system.  The
+resultant binary executable will be installed when you invoke
 
    'make install' as in *Note Compiling Emms::.
 
-   It is of course also possible to install only the
-'emms-print-metadata' binary where your system can find and execute it
-without installing all of Emms via the make command.
+It is of course also possible to install only the 'emms-print-metadata'
+binary where your system can find and execute it without installing all
+of Emms via the make command.
 
-   Once the binary is available load 'emms-info-libtag' and make it the
-_only_ info function with (note that if you have caching enabled you may
-have to delete the existing cache and repopulate it in order to see the
-TagLib data):
+   Once 'emms-print-metadata' is available, it is best to configure
+'emms-info-libtag' 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-libtag)
      (setq emms-info-functions '(emms-info-libtag))
 
+metaflac
+........
+
+'metaflac' is the command-line FLAC file metadata editor.  It is
+included in FLAC source distribution available at
+<https://github.com/xiph/flac>.  The corresponding info method is
+'emms-info-metaflac'.  To use it, add the following into your Emacs
+initialization file:
+
+     (require 'emms-info-metaflac)
+     (add-to-list 'emms-info-functions 'emms-info-libtag)
+
+MP3info
+.......
+
+MP3info is a small utility for reading and modifying id3v1 tags from MP3
+files.  Note that more recent id3v2 tags are not supported; for those
+you need to use another info method, for example 'emms-info-native'.
+MP3info is available at <https://ibiblio.org/mp3info/>.
+
+   The corresponding info method is 'emms-info-mp3info'.  To use it, add
+the following into your Emacs initialization file:
+
+     (require 'emms-info-mp3info)
+     (add-to-list 'emms-info-functions 'emms-info-mp3info)
+
+ogginfo
+.......
+
+'ogginfo' is a small utility for extracting information about Ogg Vorbis
+and Theora files.  It is part of Vorbis Tools source distribution
+available at <https://github.com/xiph/vorbis-tools>.  The corresponding
+info method is 'emms-info-ogginfo'.  To use it, add the following into
+your Emacs initialization file:
+
+     (require 'emms-info-ogginfo)
+     (add-to-list 'emms-info-functions 'emms-info-ogginfo)
+
+opusinfo
+........
+
+'opusinfo' is a small utility for extracting information about Opus
+files.  It is part of Opus Tools source distribution available at
+<https://github.com/xiph/opus-tools>.  The corresponding info method is
+'emms-info-opusinfo'.  To use it, add the following into your Emacs
+initialization file:
+
+     (require 'emms-info-opusinfo)
+     (add-to-list 'emms-info-functions 'emms-info-opusinfo)
+
 
-File: emms.info,  Node: Defining Info Methods,  Prev: Using TagLib,  Up: Track 
Information
+File: emms.info,  Node: Defining Info Methods,  Prev: Metadata Utilities,  Up: 
Track Information
 
-13.4 Defining Info Methods
+13.2 Defining Info Methods
 ==========================
 
-An info method essentially consists of a function which given an Emms
-track returns the appropriate info for that track.
+An info method essentially consists of a function which, given an Emms
+track, sets the appropriate "info-symbols" for that track.  Info symbols
+are keys that have an associated value stored in the "metadata cache".
+While info symbols can have arbitrary names, the following symbols are
+recognized by Emms:
 
-   We can for example look at the predefined method for retrieving
-information about audio tracks in the Ogg format.
+'info-album'
+     Album title.
 
-   The function 'emms-info-ogginfo' provided by 'emms-info-ogginfo.el'
-accepts an Emms track as a single argument and returns the appropriate
-information string.
+'info-albumsort'
+     Album title for collation.
 
-   We then register our info function with Emms by adding it to the
-EMMS-INFO-FUNCTIONS list.  The function will then be called at the right
-time to provide track info.
+'info-artist'
+     Artist name.
 
-     (add-to-list 'emms-info-functions 'emms-info-ogginfo)
+'info-artistsort'
+     Artist name for collation.
+
+'info-albumartist'
+     Album artist name.
+
+'info-albumartistsort'
+     Album artist name for collation.
+
+'info-composer'
+     Composer name.
+
+'info-composersort'
+     Composer name for collation.
+
+'info-date'
+     Release date.
+
+'info-originaldate'
+     Original release date.
+
+'info-performer'
+     Performer name.
+
+'info-title'
+     Track title.
+
+'info-titlesort'
+     Track title for collation.
+
+'info-tracknumber'
+     Track number.
+
+'info-discnumber'
+     Disc number.
+
+'info-year'
+     Release year.
+
+'info-originalyear'
+     Original release year.
+
+'info-note'
+     Free-form note.
+
+'info-genre'
+     Genre.
+
+'info-label'
+     Record label.
+
+'info-playing-time'
+     Playing time in seconds.
+
+An info method does not need to add all of these symbols into the given
+track.  It can also add other symbols, but those extra symbols won't be
+used by Emms.
+
+   We can for example look at the predefined method for retrieving
+information about audio tracks in the Ogg format.  The function
+'emms-info-ogginfo' provided by 'emms-info-ogginfo.el' accepts an Emms
+track TRACK as a single argument.  It uses 'ogginfo' utility to extract
+a list of key-value metadata pairs from the file represented by TRACK.
+Next, it sets the appropriate info symbols for TRACK by calling
+'emms-track-set'.  Info symbols are interned from the extracted keys.
+Those keys can be arbitrary strings, but they typically coincide with
+the keys listed above; for example "album" and "artist" form info
+symbols 'info-album' and 'info-artist'.
 
 
 File: emms.info,  Node: Interactive Playlists,  Next: Markable Playlists,  
Prev: Track Information,  Up: Top
@@ -2109,8 +2286,8 @@ File: emms.info,  Node: APE / FLAC Commands,  Next: 
Bookmarks,  Prev: Streaming
 27 APE / FLAC Commands
 **********************
 
-Often, a single APE or FLAC file contains a complete ablum.  We can
-still play next or previous track in the ablum with the help of
+Often, a single APE or FLAC file contains a complete album.  We can
+still play next or previous track in the album with the help of
 'emms-cue.el' package, provided there is a corresponding cue sheet file.
 This package also defines 'emms-info-cueinfo' for retreiving the track
 information for APE / FLAC itself.
@@ -3476,9 +3653,6 @@ Concept Index
 * track information:                     Track Information.     (line 6)
 * track order:                           Sorting Playlists.     (line 6)
 * user variables:                        User Variables.        (line 6)
-* Using exiftool:                        Using exiftool.        (line 6)
-* using taglib:                          Using TagLib.          (line 6)
-* Using tinytag:                         Using tinytag.         (line 6)
 * volume:                                Volume.                (line 6)
 * website:                               Getting Help.          (line 6)
 
@@ -3719,9 +3893,9 @@ Variable Index
 
 * emms-history-file:                     Persistent Playlists. (line 14)
 * emms-history-start-playing:            Persistent Playlists. (line 33)
-* emms-info-asynchronously:              Track Information.    (line 50)
-* emms-info-auto-update:                 Track Information.    (line 46)
-* emms-info-functions:                   Track Information.    (line 55)
+* emms-info-asynchronously:              Track Information.    (line 93)
+* emms-info-auto-update:                 Track Information.    (line 88)
+* emms-info-functions:                   Track Information.    (line 99)
 * emms-lyrics-coding-system:             Lyrics.               (line 36)
 * emms-lyrics-dir:                       Lyrics.               (line 27)
 * emms-lyrics-display-format:            Lyrics.               (line 32)
@@ -3811,61 +3985,59 @@ Keybinding Index
 
 Tag Table:
 Node: Top701
-Node: Introduction4454
-Node: Quickstart Guide5922
-Node: Installation8790
-Node: Compiling Emms9339
-Node: Setup10027
-Node: Configuration11013
-Node: Finding files and speed12488
-Node: Setup Examples13357
-Node: Getting Help15290
-Node: Formats and Freedom15868
-Node: Basic Commands17073
-Node: The Core File20454
-Node: User Variables20888
-Node: Hooks21864
-Node: Core Functions23290
-Node: Sources26290
-Node: Simple Players28423
-Node: Playlists29480
-Node: Track Information30761
-Node: Using tinytag33648
-Node: Using exiftool34077
-Node: Using TagLib34449
-Node: Defining Info Methods35558
-Node: Interactive Playlists36340
-Node: Markable Playlists39382
-Node: Extending Emms41853
-Node: New Player42289
-Node: Simple Player for `play'42678
-Node: More Complex Player44406
-Node: The Browser47413
-Node: Browser Interface48389
-Node: Filtering Tracks50803
-Node: Displaying Covers52581
-Node: Changing Looks54595
-Node: Sorting Playlists57573
-Node: Persistent Playlists59042
-Node: Editing Tracks60201
-Node: Emms Mode Line63875
-Node: Limiting65043
-Node: Music Player Daemon67382
-Node: Lyrics70895
-Node: Volume72943
-Node: Streaming Audio74731
-Ref: Streaming Audio-Footnote-175323
-Node: APE / FLAC Commands75674
-Node: Bookmarks76381
-Node: Managing Playlists77092
-Node: GNU FM78115
-Node: Uploading Track Information79469
-Node: GNU FM Streaming80351
-Node: Copying80851
-Node: The GNU FDL118368
-Node: Concept Index140756
-Node: Function Index145833
-Node: Variable Index161525
-Node: Keybinding Index163868
+Node: Introduction4336
+Node: Quickstart Guide5804
+Node: Installation8672
+Node: Compiling Emms9221
+Node: Setup9909
+Node: Configuration10895
+Node: Finding files and speed12370
+Node: Setup Examples13239
+Node: Getting Help15172
+Node: Formats and Freedom15750
+Node: Basic Commands16955
+Node: The Core File20336
+Node: User Variables20770
+Node: Hooks21746
+Node: Core Functions23172
+Node: Sources26172
+Node: Simple Players28305
+Node: Playlists29362
+Node: Track Information30643
+Node: Metadata Utilities35022
+Node: Defining Info Methods39694
+Node: Interactive Playlists41838
+Node: Markable Playlists44880
+Node: Extending Emms47351
+Node: New Player47787
+Node: Simple Player for `play'48176
+Node: More Complex Player49904
+Node: The Browser52911
+Node: Browser Interface53887
+Node: Filtering Tracks56301
+Node: Displaying Covers58079
+Node: Changing Looks60093
+Node: Sorting Playlists63071
+Node: Persistent Playlists64540
+Node: Editing Tracks65699
+Node: Emms Mode Line69373
+Node: Limiting70541
+Node: Music Player Daemon72880
+Node: Lyrics76393
+Node: Volume78441
+Node: Streaming Audio80229
+Ref: Streaming Audio-Footnote-180821
+Node: APE / FLAC Commands81172
+Node: Bookmarks81879
+Node: Managing Playlists82590
+Node: GNU FM83613
+Node: Uploading Track Information84967
+Node: GNU FM Streaming85849
+Node: Copying86349
+Node: The GNU FDL123866
+Node: Concept Index146254
+Node: Function Index151112
+Node: Variable Index166804
+Node: Keybinding Index169147
 
 End Tag Table