README.org

👉 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).

Previewing videos is also supported.

Optionally, there are additional features like indexing and searching.

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:

(use-package ready-player
  :ensure t
  :config
  (ready-player-mode +1))

To customize supported media files, set ready-player-supported-media before toggling ready-player-mode.

Remember my music collection

(setq ready-player-my-media-collection-location "path/to/my/media/collection")

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

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 associated `dired’ 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 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 appropriate `dired’ 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:

(setq ready-player-set-global-bindings nil)

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 the `dired’ 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:

brew install mpv

Metadata

Metadata is extracted using ffprobe, which comes bundled with ffmpeg.

Install using your favorite method.

On macOS:

brew install ffmpeg

Thumbnails

ready-player-mode prefers ffmpegthumbnailer to generate thumbnails, but will fallback to ffmpeg otherwise.

Install using your favorite method.

On macOS:

brew install ffmpegthumbnailer

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:

(setq ready-player-open-playback-commands
      '((ready-player-is-audio-p "mpg123")
        (ready-player-is-video-p "mpv")))

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:

;; 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=<<socket>>")))

Buttons (macOS SF Symbols)

If you have 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):

(ready-player-macos-use-sf-symbols)
(ready-player-mode +1)

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

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 playback `dired’ 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 leaving `ready-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 entering `ready-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

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 associated `dired’ 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 from `ready-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 appropriate `dired’ 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.

👉 Support this work via GitHub Sponsors