branch: externals/listen
commit 9c82a5528934bd6b1f91fafe467c21c9a9a0e5bd
Author: Adam Porter <[email protected]>
Commit: Adam Porter <[email protected]>
WIP: Info manual
---
.gitignore | 1 +
README.org | 157 ++++++++++++++++++++++++++++++++++++++++++++++--
listen.info | 195 ------------------------------------------------------------
3 files changed, 153 insertions(+), 200 deletions(-)
diff --git a/.gitignore b/.gitignore
index 8a23f1d45f..e64ebee329 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,3 +4,4 @@
/.sandbox/
/.NOTES/
*.texi
+*.info
diff --git a/README.org b/README.org
index a076f88c48..6f8d378f75 100644
--- a/README.org
+++ b/README.org
@@ -23,10 +23,9 @@ Note a silly limitation: a track may be present in a queue
only once (but who wo
* Contents :noexport:
:PROPERTIES:
-:TOC: :include siblings :depth 0 :force (nothing) :ignore (this) :local
(nothing)
+:TOC: :include siblings :depth 0 :force (depth) :ignore (this) :local
(nothing)
:END:
:CONTENTS:
-- [[#screenshots][Screenshots]]
- [[#installation][Installation]]
- [[#configuration][Configuration]]
- [[#usage][Usage]]
@@ -34,7 +33,7 @@ Note a silly limitation: a track may be present in a queue
only once (but who wo
- [[#development][Development]]
:END:
-* Screenshots
+* Screenshots :noexport:
[[file:images/screenshot-modus-vivendi-tinted.png]]
@@ -74,14 +73,158 @@ One might also use systems like
[[https://github.com/progfolio/elpaca][Elpaca]]
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
+:PROPERTIES:
+:TOC: :include descendants :depth 1 :force (nothing) :ignore (nothing)
:local (nothing)
+:END:
+
+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 | {{{command-binding(listen-queue-play,RET)}}} |
+
+| Move point forward/backward | {{{command-binding(forward-line,n)}}} /
{{{command-binding(previous-line,p)}}} |
+| Move track forward |
{{{command-binding(listen-queue-transpose-forward,N)}}} |
+| Move track backward |
{{{command-binding(listen-queue-transpose-backward,P)}}} |
+| Kill track |
{{{command-binding(listen-queue-kill-track,C-k)}}} |
+| Yank track |
{{{command-binding(listen-queue-yank,C-y)}}} |
+| Show track's metadata | {{{command-binding(listen-view-track,m)}}}
|
+| Jump to track's file in Dired | {{{command-binding(listen-jump,j)}}}
|
+
+| Show tracks (at point or selected) in library buffer |
{{{command-binding(listen-library-from-queue,l)}}} |
+| Run shell command on tracks (at point or selected) |
{{{command-binding(listen-queue-shell-command,!)}}} |
+
+| Order the queue by column at point |
{{{command-binding(listen-queue-order-by,o)}}} |
+| Shuffle the queue |
{{{command-binding(listen-queue-shuffle,s)}}} |
+
+| Revert the queue buffer |
{{{command-binding(listen-queue-revert,g)}}} |
+| Revert queue's tracks from disk | ~C-u g~
|
+| Pause the player | {{{command-binding(listen-pause,SPC)}}}
|
+| Show the menu | {{{command-binding(listen-menu,?)}}}
|
+
+**** Bookmarks
+
+Queue buffers may be bookmarked with {{{command-binding(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 | {{{command-binding(listen-queue,RET)}}} |
+
+| Move point forward/backward |
{{{command-binding(forward-line,n)}}} / {{{command-binding(previous-line,p)}}} |
+| Rename a queue |
{{{command-binding(listen-queue-rename,R)}}} |
+| Discard a queue |
{{{command-binding(listen-queue-discard,C-k)}}} |
+| Show queue's tracks in library buffer |
{{{command-binding(listen-library-from-queue,l)}}} |
+
+| Revert the queue list | {{{command-binding(listen-queue-list,g)}}} |
+| Pause the player | {{{command-binding(listen-pause,SPC)}}}
|
+| Show the menu | {{{command-binding(listen-menu,?)}}}
|
+
+** Library
-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.
+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.
+
+*** 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 | {{{command-binding(listen-library-play,RET)}}} |
+| Add tracks to queue | {{{command-binding(listen-library-to-queue,a)}}} |
+
+| Move point forward/backward | {{{command-binding(forward-line,n)}}} /
{{{command-binding(previous-line,p)}}} |
+| Show track's metadata |
{{{command-binding(listen-library-view-track,m)}}} |
+| Jump to track's file in Dired | {{{command-binding(listen-library-jump,j)}}}
|
+
+| Run shell command on tracks |
{{{command-binding(listen-library-shell-command,!)}}} |
+
+| Revert the library buffer |
{{{command-binding(listen-library-revert,g)}}} |
+| Pause the player | {{{command-binding(listen-pause,SPC)}}}
|
+| Show the menu | {{{command-binding(listen-menu,?)}}}
|
+
+**** Bookmarks
+
+Library buffers may be bookmarked with {{{command-binding(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~ currently supports audio playback via the VLC backend. 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
+ Since VLC is used 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.
+ Similarly, you might even see an icon in your task switcher indicating that
Emacs is playing sound (e.g. with KDE Plasma).
-
+
* Changelog
** v0.7-pre
@@ -209,6 +352,10 @@ Listen.el is published in GNU ELPA and is considered part
of GNU Emacs. Therefo
#+OPTIONS: broken-links:t *:t num:1 toc:1
+** Macros
+
+#+MACRO: command-binding ~$1~ (~$2~)
+
** Info export options
# NOTE: See note at top of file.
diff --git a/listen.info b/listen.info
deleted file mode 100644
index db68dd8a57..0000000000
--- a/listen.info
+++ /dev/null
@@ -1,195 +0,0 @@
-This is README.info, produced by makeinfo version 6.7 from README.texi.
-
-INFO-DIR-SECTION Emacs
-START-INFO-DIR-ENTRY
-* Listen: (listen). Audio/Music player.
-END-INFO-DIR-ENTRY
-
-
-File: README.info, Node: Top, Next: Installation, Up: (dir)
-
-listen.el
-*********
-
-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 VLC, which is currently the only
-player backend that is supported. (Other backends may easily be added;
-see library ‘listen-vlc’ for example.) 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).
-
-* Menu:
-
-* Installation::
-* Configuration::
-* Usage::
-* Changelog::
-* Development::
-
-— The Detailed Node Listing —
-
-Changelog
-
-* v0.3-pre: v03-pre.
-* v0.2: v02.
-* v0.1: v01.
-
-
-
-File: README.info, Node: Installation, Next: Configuration, Prev: Top, Up:
Top
-
-1 Installation
-**************
-
-Until it’s added to a repository, the easiest way to install this
-package is with this Elisp code (removing the line that’s inappropriate
-for your Emacs version):
-
- (use-package listen
- ;; For Emacs 29:
- :init (unless (package-installed-p 'listen)
- (package-vc-install '(listen :url
"https://github.com/alphapapa/listen.el.git";)))
- ;; For Emacs 30+:
- :vc (:url "https://github.com/alphapapa/listen.el";))
-
- You also need to have VLC installed.
-
-
-File: README.info, Node: Configuration, Next: Usage, Prev: Installation,
Up: Top
-
-2 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’.
-
-
-File: README.info, Node: Usage, Next: Changelog, Prev: Configuration, Up:
Top
-
-3 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.
-
-
-File: README.info, Node: Changelog, Next: Development, Prev: Usage, Up: Top
-
-4 Changelog
-***********
-
-* Menu:
-
-* v0.3-pre: v03-pre.
-* v0.2: v02.
-* v0.1: v01.
-
-
-File: README.info, Node: v03-pre, Next: v02, Up: Changelog
-
-4.1 v0.3-pre
-============
-
-*Additions*
- • Command ‘listen-library-from-mpd’ shows tracks selected from MPD in
- a library view.
- • Command ‘listen-queue-library’ shows tracks selected from a queue
- buffer in a library view.
-
- *Changes*
- • Reading tracks from MPD allows multiple selection using
- ‘completing-read-multiple’.
- • Various improvements in robustness.
-
- *Fixes*
- • Completing read of tracks from MPD.
- • Unset VLC process’s query-on-exit flag.
-
- *Credits*
- • Thanks to Philip Kaludercic (https://amodernist.com/) for
- reviewing.
-
-
-File: README.info, Node: v02, Next: v01, Prev: v03-pre, Up: Changelog
-
-4.2 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.
-
-
-File: README.info, Node: v01, Prev: v02, Up: Changelog
-
-4.3 v0.1
-========
-
-Initial release.
-
-
-File: README.info, Node: Development, Prev: Changelog, Up: Top
-
-5 Development
-*************
-
-Feedback is welcome.
-
- This package might be submitted to GNU ELPA in the future, so any
-contributions should meet the same criteria for GNU Emacs (i.e.
-cumulative contributions of 15 lines or more must have copyright
-assigned to the FSF).
-
-
-
-Tag Table:
-Node: Top181
-Node: Installation1943
-Node: Configuration2552
-Node: Usage2891
-Node: Changelog3162
-Node: v03-pre3327
-Node: v023996
-Node: v014636
-Node: Development4734
-
-End Tag Table
-
-
-Local Variables:
-coding: utf-8
-End:
