https://github.com/alphapapa/listen.el

Audio/music player for Emacs
https://github.com/alphapapa/listen.el

audio-player emacs music-player

Last synced: 5 days ago
JSON representation

Audio/music player for Emacs

• Host: GitHub
• URL: https://github.com/alphapapa/listen.el
• Owner: alphapapa
• License: gpl-3.0
• Created: 2024-02-17T09:01:11.000Z (11 months ago)
• Default Branch: master
• Last Pushed: 2024-09-24T01:16:59.000Z (4 months ago)
• Last Synced: 2025-01-10T04:09:29.703Z (12 days ago)
• Topics: audio-player, emacs, music-player
• Language: Emacs Lisp
• Homepage:
• Size: 522 KB
• Stars: 65
• Watchers: 5
• Forks: 3
• Open Issues: 5
• Metadata Files:
  • Readme: README.org
  • License: LICENSE

Awesome Lists containing this project

README

        
#+options: broken-links:t *:t num:1 toc:1 author:nil timestamp:nil

#+title: listen.el

#+export_file_name: listen.texi

#+texinfo_dir_category: Emacs

#+texinfo_dir_title: Listen: (listen)

#+texinfo_dir_desc: Audio/Music player

[[https://elpa.gnu.org/packages/listen.html][file:https://elpa.gnu.org/packages/listen.svg]] [[https://elpa.gnu.org/devel/listen.html][file:https://elpa.gnu.org/devel/listen.svg]]

This package aims to provide a simple audio/music player for Emacs.  It should "just work," with little-to-no configuration, have intuitive commands, and be easily extended and customized.  (Contrast to setting up EMMS, or having to configure external players like MPD.)  A Transient menu, under the command ~listen~, is the primary entry point.

The only external dependency is either [[https://mpv.io/][MPV]] or [[https://www.videolan.org/vlc/][VLC]], which are the supported player backends.  Track metadata is read using EMMS's native Elisp metadata library, which has been imported into this package.

Queues are provided as the means to play consecutive tracks, and they are shown in a ~vtable~-based view buffer.  They are persisted between sessions using the ~persist~ library, and they may be bookmarked.

The primary interface to one's music library is through the filesystem, by selecting a file to play, or by adding files and directories to a queue.  Although MPD is not required, support is provided for finding files from a local MPD server's library using MPD's metadata searching.

A simple "library" view is provided that shows a list of files organized into a hierarchy by genre, date, artist, album, etc.  (This will be made more configurable and useful in the future.)

Note a silly limitation: a track may be present in a queue only once (but who would want to have a track more than once in a playlist).

* Contents

:CONTENTS:

- [[#screenshots][Screenshots]]

- [[#installation][Installation]]

- [[#configuration][Configuration]]

- [[#usage][Usage]]

- [[#changelog][Changelog]]

- [[#development][Development]]

:END:

* Screenshots

[[file:images/screenshot-modus-vivendi-tinted.png]]

* Installation

*Requirements:*

- Emacs version 29.1 or later.

- [[https://mpv.io/][MPV]] or [[https://www.videolan.org/vlc/][VLC]]: used to play audio.

- Optional: ~ffprobe~ (part of [[https://ffmpeg.org/ffprobe.html][FFmpeg]]) is used to read tracks' duration when available.

** GNU ELPA

Listen.el is published in [[http://elpa.gnu.org/][GNU ELPA]] as [[https://elpa.gnu.org/packages/listen.html][listen]], so it may be installed in Emacs with the command ~M-x package-install RET listen RET~.  This is the recommended way to install Listen.el, as it will install the current stable release.

The latest development build may be installed from [[https://elpa.gnu.org/devel/listen.html][ELPA-devel]] or from Git (see below).

** Git

The ~master~ branch of the Git repository is intended to be usable at all times; only minor bugs are expected to be found in it before a new stable release is made.

To install from Git, it is recommended to use [[https://github.com/quelpa/quelpa-use-package][quelpa-use-package]], like this (using [[https://github.com/alphapapa/unpackaged.el#upgrade-a-quelpa-use-package-forms-package][this helpful command]] for upgrading versions):

#+begin_src elisp

  ;; Install and load `quelpa-use-package'.

  (package-install 'quelpa-use-package)

  (require 'quelpa-use-package)

  ;; Install Listen.

  (use-package listen

    :quelpa (listen :fetcher github :repo "alphapapa/listen.el"))

#+end_src

One might also use systems like [[https://github.com/progfolio/elpaca][Elpaca]] or [[https://github.com/radian-software/straight.el][Straight]] (which is also used by [[https://github.com/doomemacs/doomemacs][DOOM]]), but the author cannot offer support for them.

* Configuration

Listen is intended to work with little-to-no configuration.  You can set the ~listen-directory~ to the location of your music library if it's not at ~~/Music~.  See ~M-x customize-group RET listen RET~.

* Usage

Use the command ~listen~ to show the Transient menu.  From there, it is--hopefully--self-explanatory.  Please feel free to give feedback if it doesn't seem so.  For more information, see the following sections.

:CONTENTS:

- [[#queues][Queues]]

- [[#library][Library]]

- [[#players][Players]]

- [[#mode][Mode]]

- [[#tips][Tips]]

:END:

** Queues

While ~listen~ can simply play one track and stop, playing multiple tracks sequentially is provided by /queues/ (what other players may call /playlists/).  A queue is a list of tracks, each of which is backed by a file on disk, and which may have associated metadata (provided by reading the file in Emacs with the ~listen-info~ library, or from an external source, like an MPD server).

Queues are automatically persisted to disk in the variable ~listen-queues~.

A new, empty queue may be made with the command ~listen-queue-new~, but it's usually more convenient to use a command that adds tracks to a queue and enter a new queue name.

A queue's tracks may be de-duplicated using the command ~listen-queue-deduplicate~.  Tracks that appear to have the same metadata (artist, album, and title, compared case-insensitively) are de-duplicated.  Also, any tracks no longer backed by a file are removed.

*** Adding tracks to a queue

Tracks can be added to a queue from various sources using these commands:

- Files and directories: ~listen-queue-add-files~.  Individual files may be chosen, or a directory may be, which will be searched recursively for tracks, which are added to the selected queue.

- From an MPD server: ~listen-queue-add-from-mpd~.  An MPD search query will be read with completion, and matching tracks are added to the selected queue.

- From a playlist file: ~listen-queue-add-from-playlist-file~.  The playlist file is read, and its tracks are added to the selected queue.

*** Queue buffer

A queue may be shown in a buffer with the command ~listen-queue~, which shows its tracks in a [[info:vtable#Introduction][vtable]] with columns for metadata and filename.

**** Commands

In the buffer, you can use these commands:

| Listen to track | ~listen-queue-play~ (~RET~) |

| Move point forward/backward   | ~forward-line~ (~n~) / ~previous-line~ (~p~) |

| Move track forward            | ~listen-queue-transpose-forward~ (~N~)       |

| Move track backward           | ~listen-queue-transpose-backward~ (~P~)      |

| Kill track                    | ~listen-queue-kill-track~ (~C-k~)            |

| Yank track                    | ~listen-queue-yank~ (~C-y~)                  |

| Show track's metadata         | ~listen-view-track~ (~m~)                    |

| Jump to track's file in Dired | ~listen-jump~ (~j~)                          |

| Show tracks (at point or selected) in library buffer | ~listen-library-from-queue~ (~l~)  |

| Run shell command on tracks (at point or selected)   | ~listen-queue-shell-command~ (~!~) |

| Order the queue by column at point | ~listen-queue-order-by~ (~o~) |

| Shuffle the queue                  | ~listen-queue-shuffle~ (~s~)  |

| Revert the queue buffer         | ~listen-queue-revert~ (~g~) |

| Revert queue's tracks from disk | ~C-u g~                     |

| Pause the player                | ~listen-pause~ (~SPC~)      |

| Show the menu                   | ~listen-menu~ (~?~)         |

**** Bookmarks

Queue buffers may be bookmarked with ~bookmark-set~ (~C-x r m~).  The bookmark record refers to the queue by name, so if the queue is renamed or discarded, the bookmark will remain.

*** Queue list buffer

The queue list buffer may be shown with the command ~listen-queue-list~.  In the list buffer, you can use these commands:

| Show queue's buffer | ~listen-queue~ (~RET~) |

| Move point forward/backward           | ~forward-line~ (~n~) / ~previous-line~ (~p~) |

| Rename a queue                        | ~listen-queue-rename~ (~R~)                  |

| Discard a queue                       | ~listen-queue-discard~ (~C-k~)               |

| Show queue's tracks in library buffer | ~listen-library-from-queue~ (~l~)            |

| Revert the queue list | ~listen-queue-list~ (~g~) |

| Pause the player      | ~listen-pause~ (~SPC~)    |

| Show the menu         | ~listen-menu~ (~?~)       |

** Library

To help with exploring and managing a music library, ~listen~ provides various "library" features.  Tracks can be passed between library and queue buffers and operated on with similar commands and bindings.

~listen~ does not maintain its own database of audio files; they are simply read from the filesystem as needed.  But if a local MPD server is available, tracks can be loaded from its database (which does a fine job of indexing audio files and their metadata); this is generally much faster, because it avoids having to read tracks' metadata with Emacs Lisp or their durations with ~ffprobe~.

~listen~ does not provide features to modify tracks' metadata, but it provides commands to run shell commands on tracks' filenames, which works well with external tools like [[https://picard.musicbrainz.org/][Picard]].

*** Library buffer

A library buffer provides a hierarchical view of tracks grouped by their metadata using [[info:taxy#Top][Taxy]], rendered with [[info:magit-section#Top][Magit Section]].  Each section can be folded, and it shows the number of tracks in it and its subgroups.

**** Showing a library buffer

Tracks from various sources can be shown in a library using these commands:

- Files and directories: ~listen-library~.  Individual files may be chosen, or a directory may be, which will be searched recursively for tracks.

- From an MPD server: ~listen-library-from-mpd~.  An MPD search query will be read with completion, and matching tracks are read from the MPD server.

- From a playlist file: ~listen-library-from-playlist-file~.  Tracks are read from the given playlist file.

**** Commands

In the library buffer, you can use these commands:

| Listen to tracks    | ~listen-library-play~ (~RET~)   |

| Add tracks to queue | ~listen-library-to-queue~ (~a~) |

| Move point forward/backward   | ~forward-line~ (~n~) / ~previous-line~ (~p~) |

| Show track's metadata         | ~listen-library-view-track~ (~m~)            |

| Jump to track's file in Dired | ~listen-library-jump~ (~j~)                  |

| Run shell command on tracks | ~listen-library-shell-command~ (~!~) |

| Revert the library buffer | ~listen-library-revert~ (~g~) |

| Pause the player          | ~listen-pause~ (~SPC~)        |

| Show the menu             | ~listen-menu~ (~?~)           |

**** Bookmarks

Library buffers may be bookmarked with ~bookmark-set~ (~C-x r m~).  The bookmark record refers to the buffer by the way it was created (e.g. the filename paths, queue name, MPD query, or playlist file the tracks came from), so jumping to the bookmark will show an updated view, as if calling the original command with the same arguments.

** Players

~listen~ supports audio playback via MPV or VLC backends.  Internally, any number of simultaneous player instances could be controlled, but ~listen~'s UI provides the means to control one at a time.

Controlling the player is mainly done through the main [[info:transient#Top][Transient]] menu, through the command ~listen~.  However, all of the commands provided in it are also available as interactive commands, which could be bound by the user in any keymap (see, e.g. [[elisp:(apropos-command "^listen-")][M-x apropos-command RET ^listen- RET]]).

The player is run in a child process, which is started when playback begins.  The ~listen-quit~ command terminates the player process.

*** Volume

The ~listen-volume~ command is used to set the current player's volume.  Its argument should be an integer percentage.  Some players, e.g. VLC, may allow settings above 100% to boost output beyond normal levels.

*** Seeking

The ~listen-seek~ command is used to seek to a position in the current track.  Its argument should be a timestamp in MM:SS format, and it may include a ~-~ or ~+~ prefix to indicate a position relative to the current one.

*** Repeat modes

Three repeat modes are provided, controlled by the option ~listen-queue-repeat-mode~, which may have these values:

- ~nil~ :: No repeating.  When the last track in the current queue finishes playing, playback stops.

- ~queue~ :: The current queue is repeated when its last track finishes playing.

- ~shuffle~ :: When the last track in the current queue finishes playing, the queue is shuffled and played again.

The repeat mode is most easily set using the commands in the ~listen~ menu.

** Mode

The ~listen-mode~ minor mode runs a timer which plays the next track in the current queue when a track finishes playing (when playing a queue).  It is automatically activated when playing a queue.  It also shows the current track in the ~global-mode-string~, which may be displayed in the mode line or tab bar.

** Tips

- When using VLC as a backend, [[https://www.freedesktop.org/wiki/Specifications/mpris-spec/][MPRIS]]-based player info and controls "just work", so you can use things like media hotkeys and various widgets to control ~listen~'s playback.  When using MPV as a backend, see the [[https://github.com/hoyon/mpv-mpris][mpv-mpris]] package.

- Similarly, you might even see an icon in your task switcher indicating that Emacs is playing sound (e.g. with KDE Plasma).

* Changelog

** v0.10-pre

*Additions*

- [[https://mpv.io/][MPV]] support.

- Command ~listen-queue-add-tracks~, when used in a Dired buffer, uses the marked files or the one at point.

- Option ~listen-backend~, which sets the backend to use: MPV or VLC.  (The default is to auto-detect which is available at load time, with MPV being preferred due to more robust IPC support.)

- Faces for parts of mode line lighter.

*Fixes*

- Updating vtables for Emacs versions before 30.

** v0.9

/Released without additional changes due to change in ELPA recipe./

*Fixes*

- Currently playing column in queue list buffer.

- Autoload of ~listen~ / ~listen-menu~ commands (See [[https://github.com/magit/transient/issues/280][Transient issue]].  Thanks to Jonas Bernoulli.).

** v0.8.1

*Fixes*

- Autoload of ~listen~ / ~listen-menu~ commands.

** v0.8

*Additions*

- The ~listen-queue-list~ buffer can be bookmarked.

- Queue buffers showing the currently playing queue indicate so in the mode line.

- Support for ~mood~ metadata tag in MP3 files (added in ID3v2.4; other filetypes need no specific support).

*Changes*

- Truncate track titles for display using option ~listen-lighter-title-max-length~ (because the ~format-spec~ specifier used in ~listen-lighter-format~ does not add an ellipsis where truncation occurs).

*Fixes*

- Command ~listen-queue-add-from-mpd~.

- Indication of currently playing queue in queue list.

- Set metadata slot when reverting track from disk.

- Don't highlight current track in non-playing queues.

- Increase minimum ~ffprobe~ timeout for a single track.

** v0.7

*Additions*

- Info manual.

- Option ~listen-lighter-format~ now allows customizing the mode line lighter.

*Changes*

- Command ~listen-queue~ switches to existing queue buffers without reverting them.

- Transient ~qq~ command exits the transient.

- Optimize updating of individual tracks in queue buffer.

- Improve handling of maximum volume with VLC (allowing boosting over 100%).

- Library buffer name defaults to given path.

- Minor improvements to Transient menu.

*Fixes*

- When reverting a queue's tracks from disk, re-detect the currently playing track by filename.

- Queue bookmark handler.

- Open library buffer with point at beginning.

- In queue buffer, sort track numbers numerically.

** v0.6

*Additions*

- In library buffer, show disc number when available.

*Changes*

- Reverting library buffers shows tracks from the queue or MPD query originally selected.

- Command ~listen-queue-add-files~ no longer plays the queue automatically.

- Command ~listen-library-play-or-add~ renamed to ~listen-library-play~, and it now plays the selected queue when playing multiple tracks.

- Face ~listen-album~ slants italic.

- In library buffer, prefer album-artist over artist tag when available.

- Use half the number of CPUs to read track durations, by default.

*Fixes*

- Reading new queue name when no queue is playing.

** v0.5.1

*Fixes*

- Viewing queues which aren't currently playing.

** v0.5

*Additions*

- Command ~listen-queue-list~ shows a list of queues.

- Command ~listen-jump~ (bound to ~j~ in queue and library buffers) jumps to the track at point in a Dired buffer.

- Command ~listen-track-view~ shows a track's complete metadata in a table view.

- Mode ~listen-queue-delay-mode~ plays a queue with a configurable, random delay between tracks.

- Option ~listen-queue-repeat-mode~ (also settable in ~listen-menu~) allows repeating a queue in-order or shuffled.

- Option ~listen-lighter-extra-functions~ allows displaying extra information in the ~listen-mode~ lighter.

- Option ~listen-track-end-functions~ allows running functions when a track finishes playing.

- Show total queue duration at bottom of track list.

- Show track ratings in library and queue buffers.

*Changes*

- All metadata in MP3 and Ogg files is available for display (not only standard tags).

- For date field in library and queue views, show ~originalyear~ or ~originaldate~ metadata fields in preference to ~date~ (which seems generally more useful, as the ~date~ field may contain a full date, and sometimes of a later release).

*Fixes*

- Increase timeout for reading track durations.

- Command ~listen-queue-deduplicate~ first removes any tracks not backed by a file.

- In queue buffer, mark current track by comparing filename (rather than internal track identity).

** v0.4

*Additions*

- Command ~listen-queue-deduplicate~ removes duplicate tracks from a queue (by comparing artist, album, and title metadata case-insensitively).

- Read track durations with ~ffprobe~ and show in library and queue views.

- Bound key ~?~ to open the ~listen~ Transient menu in library and queue views.

*Fixes*

- Transposing a track in a queue keeps point on the track.

- Autoloading of ~listen~ command.

** v0.3

*Additions*

- Command ~listen-library-from-mpd~ shows tracks selected from MPD in a library view.

- Command ~listen-library-from-queue~ shows tracks selected from a queue buffer in a library view.

- Command ~listen-library-from-playlist-file~ shows tracks from an M3U playlist in a library view.

- Command ~listen-queue-add-from-playlist-file~ adds tracks from an M3U playlist file to a queue.

*Changes*

- Reading tracks from MPD allows multiple selection using ~completing-read-multiple~.

- Various improvements in robustness.

- Command ~listen-queue~ doesn't recreate its buffer when already open.

- Key bindings in ~listen~ Transient menu.

- Function ~listen-queue-complete~ accepts argument ~:allow-new-p~ to return a new queue if the entered name doesn't match an existing one.

*Fixes*

- Completing read of tracks from MPD.

- Unset VLC process's query-on-exit flag.

*Credits*

- Thanks to [[https://amodernist.com/][Philip Kaludercic]] for reviewing.

** v0.2

*Additions*

- Command ~listen-queue-jump~ jumps to the currently playing track in the queue.

- Command ~listen-queue-shell-command~ runs a shell command on the tracks selected in the queue.

- Reverting a queue buffer with universal prefix argument refreshes the tracks' metadata from disk.

*Fixes*

- The queue could sometimes skip tracks when playing.

- Improve handling of tracks that are changed during playback (e.g. metadata).

- Update copyright statements in all libraries.

** v0.1

Initial release.

* Development

Feedback and patches are welcome.

** Copyright assignment

Listen.el is published in GNU ELPA and is considered part of GNU Emacs.  Therefore, cumulative contributions of more than 15 lines of code require that the author assign copyright of such contributions to the FSF.  Authors who are interested in doing so may contact [[mailto:[email protected]][[email protected]]] to request the appropriate form.

** Known issues

- Queue buffers that are not visible during playback are not updated automatically (i.e. to show the currently playing track).  This is due to a limitation of the ~vtable~ library (see [[https://debbugs.gnu.org/cgi/bugreport.cgi?bug=69837][bug #69837]]).