👉 [[https://github.com/sponsors/xenodium][Support this work via GitHub Sponsors]]
- Ready Player Mode
An Emacs major mode to open media (audio/video) files like any other file (via find-file, dired, etc).
+HTML: 
Previewing videos is also supported.
+HTML: 
Optionally, there are additional features like indexing and searching.
+HTML: 
- Install / Setup
This package is available on MELPA.
If you just want Emacs to recognize and open media files (find-file, dired, etc.), this is all you need:
+begin_src emacs-lisp :lexical no
(use-package ready-player :ensure t :config (ready-player-mode +1))
+end_src
To customize supported media files, set =ready-player-supported-media= before toggling =ready-player-mode=.
- Remember my music collection
+begin_src emacs-lisp :lexical no
(setq ready-player-my-media-collection-location "path/to/my/media/collection")
+end_src
From then onwards, you can directly open your collection via =M-x ready-player= (unless you were last playing something else). If you want to explicitly open your media collection, invoke =M-x ready-player-open-my-media-collection=.
- Ready player buffer key bindings
+BEGIN_SRC emacs-lisp :results table :colnames '("Command" "Description") :exports results
(let ((rows)) (mapatoms (lambda (symbol) (when (and (string-match "^ready-player" (symbol-name symbol)) (commandp symbol)) (push `(,(string-join (seq-filter (lambda (symbol) (not (string-match "menu" symbol))) (mapcar (lambda (keys) (key-description keys)) (seq-filter (lambda (keys) (not (string-match "C-c" (key-description keys))) ) (where-is-internal symbol ready-player-major-mode-map nil nil (command-remapping symbol))))) " or ") ,(symbol-name symbol) ,(car (split-string (or (documentation symbol t) "") "\n"))) rows)))) (seq-filter (lambda (command) (not (string-empty-p (car command)))) rows))
+END_SRC
+RESULTS:
| TAB | ready-player-next-button | Navigate to next button. |
| SPC | ready-player-toggle-play-stop | Toggle play/stop of media. |
| g | ready-player-reload-buffer | Reload media from file. |
| r | ready-player-toggle-repeat | Cycle through repeat settings: file, directory, off. |
| f | ready-player-seek-forward | Seek forward. |
| q | ready-player-quit | Quit ready-player-major-mode' window and kill buffer. | | d | ready-player-view-dired-playback-buffer | View associateddired' playback buffer. |
| s | ready-player-toggle-shuffle | Toggle shuffle setting. |
| b | ready-player-seek-backward | Seek backward. |
| a | ready-player-toggle-autoplay | Toggle autoplay setting. |
| o or e | ready-player-open-externally | Open visited file in default external program. |
| n | ready-player-next | Open the next media file in the same directory. |
| c | ready-player-open-my-media-collection | Open my media collection from ready-player-my-media-collection-location'. | | i | ready-player-show-info | Show playback info in the echo area. | | p | ready-player-previous | Open the previous media file in the same directory. | | m | ready-player-mark-dired-file | Mark the current file in the appropriatedired' buffer(s). |
|
- Global key bindings Global bindinds are under the =C-c m= prefix. If you prefer not to have these bindings disable them with:
+begin_src emacs-lisp :lexical no
(setq ready-player-set-global-bindings nil)
+end_src
+BEGIN_SRC emacs-lisp :results table :colnames '("Command" "Description") :exports results
(let ((rows)) (mapatoms (lambda (symbol) (when (and (string-match "^ready-player" (symbol-name symbol)) (commandp symbol)) (push `(,(key-description (car (where-is-internal symbol nil nil (command-remapping symbol)))) ,(symbol-name symbol) ,(car (split-string (or (documentation symbol t) "") "\n"))) rows)))) (seq-filter (lambda (command) (string-match "C-c m" (car command))) rows))
+END_SRC
+RESULTS:
| C-c m SPC | ready-player-toggle-play-stop | Toggle play/stop of media. |
| C-c m r | ready-player-toggle-repeat | Cycle through repeat settings: file, directory, off. |
| C-c m m | ready-player-view-player | Toggle switching between player buffer and previous buffer. |
| C-c m s | ready-player-toggle-shuffle | Toggle shuffle setting. |
| C-c m a | ready-player-toggle-autoplay | Toggle autoplay setting. |
| C-c m n | ready-player-next | Open the next media file in the same directory. |
| C-c m c | ready-player-open-my-media-collection | Open my media collection from ready-player-my-media-collection-location'. | | C-c m i | ready-player-show-info | Show playback info in the echo area. | | C-c m p | ready-player-previous | Open the previous media file in the same directory. | | C-c m / | ready-player-search | Search thedired' playlist for playback (experimental). |
- Toggle recognition
You can optionally toggle media recognition on and off interactively via =M-x ready-player-mode=.
- External dependencies
** Playback
=ready-player-mode= relies on command line utilities to play media.
By default, =ready-player-mode= will try to use either =mpv=, =vlc=, =ffplay=, or =mplayer= (in that order). Customize =ready-player-open-playback-commands= to your preference.
Install either of these using your favorite method.
On macOS:
+begin_src sh
brew install mpv
+end_src
** Metadata
Metadata is extracted using =ffprobe=, which comes bundled with [[https://www.youtube.com/watch?v=9kaIXkImCAM][ffmpeg]].
Install using your favorite method.
On macOS:
+begin_src sh
brew install ffmpeg
+end_src
** Thumbnails
=ready-player-mode= prefers [[https://github.com/dirkvdb/ffmpegthumbnailer][ffmpegthumbnailer]] to generate thumbnails, but will fallback to =ffmpeg= otherwise.
Install using your favorite method.
On macOS:
+begin_src sh
brew install ffmpegthumbnailer
+end_src
- Customizations
** Video vs audio
If you'd like to use different utilities to play video and audio, you can use =ready-player-open-playback-commands= for this with something like:
+begin_src emacs-lisp :lexical no
(setq ready-player-open-playback-commands '((ready-player-is-audio-p "mpg123") (ready-player-is-video-p "mpv")))
+end_src
** Play all videos as audio
Ready player avoids auto-advancing video files to prevent awkward switching between video window and Emacs.
If you'd like to play all video files as audio (no video stream playback) and auto-advance via repeat, use the following settings:
+begin_src emacs-lisp :lexical no
;; Recognize video files as audio. (setq ready-player-supported-audio (append ready-player-supported-audio ready-player-supported-video)) ;; Don't recognize any file as video. (setq ready-player-supported-video nil)
;; Disable video stream playback (mpv player)
(setq ready-player-open-playback-commands
'(("mpv" "--audio-display=no" "--video=no" "--input-ipc-server=<
+end_src
** Buttons (macOS SF Symbols)
If you have [[https://lmno.lol/alvaro/emacs-insert-and-render-sf-symbols][SF symbol rendering in Emacs]] on macOS, you can use enable usage in buttons by invoking =(ready-player-macos-use-sf-symbols)= prior to =(ready-player-mode +1)=:
+begin_src emacs-lisp :lexical no
(ready-player-macos-use-sf-symbols) (ready-player-mode +1)
+end_src
** Buttons (Linux)
Default icons are =◁◁ ▶ ■ ▷▷ ➦ ⇆=. These can be customized (see all icon variables). I'm happy to take suggestions for improving default icons.
- All customizations
+BEGIN_SRC emacs-lisp :results table :colnames '("Custom variable" "Description") :exports results
(let ((rows)) (mapatoms (lambda (symbol) (when (and (string-match "^ready-player" (symbol-name symbol)) (not (string-match "--" (symbol-name symbol))) (or (custom-variable-p symbol) (boundp symbol))) (push `(,symbol ,(car (split-string (or (get (indirect-variable symbol) 'variable-documentation) (get symbol 'variable-documentation) "") "\n"))) rows)))) rows)
+END_SRC
+RESULTS:
| Custom variable | Description |
|-----------------------------------------------------------+----------------------------------------------------------------------------|
| ready-player-hide-modeline | If non-nil, hides mode line in buffer. |
| ready-player-open-playback-commands | Command line utilities to try for playback. |
| ready-player-show-thumbnail | When non-nil, display file's thumbnail if available. |
| ready-player-mode | Non-nil if Ready-Player mode is enabled. |
| ready-player-supported-audio | Supported audio media. |
| ready-player-open-externally-icon | Open externally button icon string, for example: "➦". |
| ready-player-cache-thumbnails | When non-nil, cache thumbnail. |
| ready-player-open-my-media-collection-icon | Open my collection icon string, for example: "⌂". |
| ready-player-autoplay-icon | Autoplay icon string, for example: "⏻". |
| ready-player-set-global-bindings | When non-nil, bind global keys under ready-player-minor-mode-map-prefix'. | | ready-player-cache-metadata | When non-nil, cache metadata. | | ready-player-multi-buffer | When non-nil, enable opening multiple buffers with parallel playback. | | ready-player-thumbnail-max-pixel-height | Maximum thumbnail pixel height. | | ready-player-repeat | Continue playing if there's more media in directory or playlist. | | ready-player-stop-icon | Stop icon string, for example: "■". | | ready-player-shuffle-icon | Shuffle icon string, for example: "⤮". | | ready-player-always-load-directory-recursively | When non-nil, load directory recursively without prompt. | | ready-player-shuffle | Next media item is selected at random within current directory. | | ready-player-minor-mode-map |ready-player' minor mode map. |
| ready-player-major-mode-syntax-table | Syntax table for ready-player-major-mode'. | | ready-player-autoplay | When non-nil, automatically start playing when media file opens. | | ready-player-display-dired-playback-buffer-display-action | Choose how to display the associated playbackdired' buffer. |
| ready-player-repeat-icon | Repeat icon string, for example: "⇆". |
| ready-player-major-mode-abbrev-table | Abbrev table for ready-player-major-mode'. | | ready-player-mode-hook | Hook run after entering or leavingready-player-mode'. |
| ready-player-supported-media | Supported media types. |
| ready-player-major-mode-map | Keymap for ready-player'. | | ready-player-play-icon | Play button icon string, for example: "▶". | | ready-player-search-icon | Search icon string, for example: "⌕". | | ready-player-supported-video | Supported video media. | | ready-player-major-mode-hook | Hook run after enteringready-player-major-mode'. |
| ready-player-minor-mode-map-prefix | The global bindings prefix used in `ready-player-minor-mode'. |
| ready-player-my-media-collection-location | Path to your media collection. |
| ready-player-help-icon | Search icon string, for example: "⁈". |
| ready-player-previous-icon | Previous button icon string, for example: "◁◁". |
| ready-player-next-icon | Next button icon string, for example: "▷▷". |
- Commands
+BEGIN_SRC emacs-lisp :results table :colnames '("Command" "Description") :exports results
(let ((rows))
(mapatoms
(lambda (symbol)
(when (and (string-match "^ready-player"
(symbol-name symbol))
(commandp symbol))
(push `(,(string-join
(seq-filter
(lambda (symbol)
(not (string-match "menu" symbol)))
(mapcar
(lambda (keys)
(key-description keys))
(or
(where-is-internal
symbol ready-player-major-mode-map nil nil (command-remapping symbol))
(where-is-internal
(symbol-function symbol)
ready-player-major-mode-map nil nil (command-remapping symbol))))) " or ")
,(symbol-name symbol)
,(car
(split-string
(or (documentation symbol t) "")
"\n")))
rows))))
rows)+END_SRC
+RESULTS:
| TAB | ready-player-next-button | Navigate to next button. |
| SPC or C-c m SPC | ready-player-toggle-play-stop | Toggle play/stop of media. |
| | ready-player-mode | Toggle Ready Player mode media file recognition. |
| g | ready-player-reload-buffer | Reload media from file. |
| r or C-c m r | ready-player-toggle-repeat | Cycle through repeat settings: file, directory, off. |
| f | ready-player-seek-forward | Seek forward. |
| | ready-player-set-album-artwork | Select image and set as album artwork. |
| q | ready-player-quit | Quit ready-player-major-mode' window and kill buffer. | | | ready-player-version | Show Ready Player Mode version. | | | ready-player-download-album-artwork | Download album artwork to media directory. | | C-c m m | ready-player-view-player | Toggle switching between player buffer and previous buffer. | | | ready-player-toggle-modeline | Toggle displaying the mode line. | | d | ready-player-view-dired-playback-buffer | View associateddired' playback buffer. |
| | ready-player-load-dired-buffer | Load a dired' buffer. | | s or C-c m s | ready-player-toggle-shuffle | Toggle shuffle setting. | | | ready-player-play | Start media playback. | | b | ready-player-seek-backward | Seek backward. | | a or C-c m a | ready-player-toggle-autoplay | Toggle autoplay setting. | | o or e | ready-player-open-externally | Open visited file in default external program. | | | ready-player-stop | Stop media playback. | | n or C-c m n | ready-player-next | Open the next media file in the same directory. | | | ready-player-download-album-artwork-and-set-metadata | Download album artwork set media metadata. | | c or C-c m c | ready-player-open-my-media-collection | Open my media collection fromready-player-my-media-collection-location'. |
| C-c m m | ready-player | Toggle switching between player buffer and previous buffer. |
| | ready-player-lookup-song | Look up current song on Discogs. |
| | ready-player-major-mode | Major mode to preview and play media files. |
| | ready-player-load-directory | Load all media from directory (experimental). |
| i or C-c m i | ready-player-show-info | Show playback info in the echo area. |
| p or C-c m p | ready-player-previous | Open the previous media file in the same directory. |
| m | ready-player-mark-dired-file | Mark the current file in the appropriate dired' buffer(s). | | <backtab> | ready-player-previous-button | Navigate to previous button. | | u | ready-player-unmark-dired-file | Unmark the current file in the appropriatedired' buffer(s). |
| / or C-c m / | ready-player-search | Search the `dired' playlist for playback (experimental). |
| | ready-player-load-m3u-playlist | Load an .m3u playlist. |
| | ready-player-load-last-known | Attempt to load last known media. |
👉 [[https://github.com/sponsors/xenodium][Support this work via GitHub Sponsors]]