Skip to content

xenodium/ready-player

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 

Repository files navigation

👉 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

TABready-player-next-buttonNavigate to next button.
SPCready-player-toggle-play-stopToggle play/stop of media.
gready-player-reload-bufferReload media from file.
rready-player-toggle-repeatCycle through repeat settings: file, directory, off.
fready-player-seek-forwardSeek forward.
qready-player-quitQuit `ready-player-major-mode’ window and kill buffer.
dready-player-view-dired-playback-bufferView associated `dired’ playback buffer.
sready-player-toggle-shuffleToggle shuffle setting.
bready-player-seek-backwardSeek backward.
aready-player-toggle-autoplayToggle autoplay setting.
o or eready-player-open-externallyOpen visited file in default external program.
nready-player-nextOpen the next media file in the same directory.
cready-player-open-my-media-collectionOpen my media collection from `ready-player-my-media-collection-location’.
iready-player-show-infoShow playback info in the echo area.
pready-player-previousOpen the previous media file in the same directory.
mready-player-mark-dired-fileMark the current file in the appropriate `dired’ buffer(s).
<backtab>ready-player-previous-buttonNavigate to previous button.
uready-player-unmark-dired-fileUnmark 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 SPCready-player-toggle-play-stopToggle play/stop of media.
C-c m rready-player-toggle-repeatCycle through repeat settings: file, directory, off.
C-c m mready-player-view-playerToggle switching between player buffer and previous buffer.
C-c m sready-player-toggle-shuffleToggle shuffle setting.
C-c m aready-player-toggle-autoplayToggle autoplay setting.
C-c m nready-player-nextOpen the next media file in the same directory.
C-c m cready-player-open-my-media-collectionOpen my media collection from `ready-player-my-media-collection-location’.
C-c m iready-player-show-infoShow playback info in the echo area.
C-c m pready-player-previousOpen the previous media file in the same directory.
C-c m /ready-player-searchSearch 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 variableDescription
ready-player-hide-modelineIf non-nil, hides mode line in buffer.
ready-player-open-playback-commandsCommand line utilities to try for playback.
ready-player-show-thumbnailWhen non-nil, display file’s thumbnail if available.
ready-player-modeNon-nil if Ready-Player mode is enabled.
ready-player-supported-audioSupported audio media.
ready-player-open-externally-iconOpen externally button icon string, for example: “➦”.
ready-player-cache-thumbnailsWhen non-nil, cache thumbnail.
ready-player-open-my-media-collection-iconOpen my collection icon string, for example: “⌂”.
ready-player-autoplay-iconAutoplay icon string, for example: “⏻”.
ready-player-set-global-bindingsWhen non-nil, bind global keys under `ready-player-minor-mode-map-prefix’.
ready-player-cache-metadataWhen non-nil, cache metadata.
ready-player-multi-bufferWhen non-nil, enable opening multiple buffers with parallel playback.
ready-player-thumbnail-max-pixel-heightMaximum thumbnail pixel height.
ready-player-repeatContinue playing if there’s more media in directory or playlist.
ready-player-stop-iconStop icon string, for example: “■”.
ready-player-shuffle-iconShuffle icon string, for example: “⤮”.
ready-player-always-load-directory-recursivelyWhen non-nil, load directory recursively without prompt.
ready-player-shuffleNext media item is selected at random within current directory.
ready-player-minor-mode-map`ready-player’ minor mode map.
ready-player-major-mode-syntax-tableSyntax table for `ready-player-major-mode’.
ready-player-autoplayWhen non-nil, automatically start playing when media file opens.
ready-player-display-dired-playback-buffer-display-actionChoose how to display the associated playback `dired’ buffer.
ready-player-repeat-iconRepeat icon string, for example: “⇆”.
ready-player-major-mode-abbrev-tableAbbrev table for `ready-player-major-mode’.
ready-player-mode-hookHook run after entering or leaving `ready-player-mode’.
ready-player-supported-mediaSupported media types.
ready-player-major-mode-mapKeymap for `ready-player’.
ready-player-play-iconPlay button icon string, for example: “▶”.
ready-player-search-iconSearch icon string, for example: “⌕”.
ready-player-supported-videoSupported video media.
ready-player-major-mode-hookHook run after entering `ready-player-major-mode’.
ready-player-minor-mode-map-prefixThe global bindings prefix used in `ready-player-minor-mode’.
ready-player-my-media-collection-locationPath to your media collection.
ready-player-help-iconSearch icon string, for example: “⁈”.
ready-player-previous-iconPrevious button icon string, for example: “◁◁”.
ready-player-next-iconNext button icon string, for example: “▷▷”.

Commands

TABready-player-next-buttonNavigate to next button.
SPC or C-c m SPCready-player-toggle-play-stopToggle play/stop of media.
ready-player-modeToggle Ready Player mode media file recognition.
gready-player-reload-bufferReload media from file.
r or C-c m rready-player-toggle-repeatCycle through repeat settings: file, directory, off.
fready-player-seek-forwardSeek forward.
ready-player-set-album-artworkSelect image and set as album artwork.
qready-player-quitQuit `ready-player-major-mode’ window and kill buffer.
ready-player-versionShow Ready Player Mode version.
ready-player-download-album-artworkDownload album artwork to media directory.
C-c m mready-player-view-playerToggle switching between player buffer and previous buffer.
ready-player-toggle-modelineToggle displaying the mode line.
dready-player-view-dired-playback-bufferView associated `dired’ playback buffer.
ready-player-load-dired-bufferLoad a `dired’ buffer.
s or C-c m sready-player-toggle-shuffleToggle shuffle setting.
ready-player-playStart media playback.
bready-player-seek-backwardSeek backward.
a or C-c m aready-player-toggle-autoplayToggle autoplay setting.
o or eready-player-open-externallyOpen visited file in default external program.
ready-player-stopStop media playback.
n or C-c m nready-player-nextOpen the next media file in the same directory.
ready-player-download-album-artwork-and-set-metadataDownload album artwork set media metadata.
c or C-c m cready-player-open-my-media-collectionOpen my media collection from `ready-player-my-media-collection-location’.
C-c m mready-playerToggle switching between player buffer and previous buffer.
ready-player-lookup-songLook up current song on Discogs.
ready-player-major-modeMajor mode to preview and play media files.
ready-player-load-directoryLoad all media from directory (experimental).
i or C-c m iready-player-show-infoShow playback info in the echo area.
p or C-c m pready-player-previousOpen the previous media file in the same directory.
mready-player-mark-dired-fileMark the current file in the appropriate `dired’ buffer(s).
<backtab>ready-player-previous-buttonNavigate to previous button.
uready-player-unmark-dired-fileUnmark the current file in the appropriate `dired’ buffer(s).
/ or C-c m /ready-player-searchSearch the `dired’ playlist for playback (experimental).
ready-player-load-m3u-playlistLoad an .m3u playlist.
ready-player-load-last-knownAttempt to load last known media.

👉 Support this work via GitHub Sponsors

Tips and Tricks

Centering the Buffer with Olivetti Mode

If you prefer to center the buffer content, especially when working with large screens, you can use olivetti-mode to achieve this. olivetti-mode is a lightweight Emacs package that centers text in the buffer, making it more readable and visually appealing.

Note that olivetti-mode does not perform “true centering” (i.e., centering each line individually). Instead, it centers the entire buffer content by adding padding to the left and right, effectively creating a centered column of text. This approach ensures consistent alignment and avoids visual distractions caused by uneven line lengths.

To enable centering for ready-player, add the following configuration to your Emacs setup:

(use-package olivetti
  :defer t
  :ensure t
  :init
  (defun my-center-ready-player-on ()
    "Enable olivetti-mode and visual-line-mode for ready-player."
    (setq olivetti-body-width 0) ; Or a number to control the amount of chars to be centered
    (olivetti-mode 1)            ; Enable olivetti-mode
    (visual-line-mode 1))        ; Enable/Disable visual-line-mode for text wrapping of your liking

  ;; Hook into ready-player's major mode
  (add-hook 'ready-player-major-mode-hook #'my-center-ready-player-on))

This configuration will automatically center the buffer content whenever ready-player is active. You can adjust the olivetti-body-width value to control the width of the centered text.

Note:

Although olivetti-mode handles edge cases well and is a robust solution for centering text, if you prefer not to use olivetti-mode, there are alternatives like perfect-margin, centered-window-mode, or darkroom, which you can configure similarly.

About

No description, website, or topics provided.

Resources

License

Stars

Watchers

Forks

Packages

No packages published